feat: multi-parsers (#1134)

Co-authored-by: Valerii Sidorenko <[email protected]>
Co-authored-by: François Best <[email protected]>

Author: 3 people

packages/docs/content/docs/parsers/built-in.mdx

@@ -15,7 +15,8 @@ import {
   DateISOParserDemo,
   DatetimeISOParserDemo,
   DateTimestampParserDemo,
-  JsonParserDemo
+  JsonParserDemo,
+  NativeArrayParserDemo
 } from '@/content/docs/parsers/demos'
 
 Search params are strings by default, but chances are your state is more complex than that.
@@ -322,6 +323,39 @@ parseAsJson(userSchema.validateSync)
   return `null{:ts}` for invalid data. Only **synchronous** validation is supported.
 </Callout>
 
+## Native Arrays
+
+<FeatureSupportMatrix introducedInVersion='2.7.0' />
+
+If you want to use the native URL format for arrays, repeating the same key multiple times like:
+
+import { Querystring } from '@/src/components/querystring'
+
+<Querystring path="/products" value='?tag=books&tag=tech&tag=design' />
+
+you can now use `MultiParsers{:ts}` like `parseAsNativeArrayOf{:ts}` to read and write those values in a fully type-safe way.
+
+```tsx
+import { useQueryState, parseAsNativeArrayOf, parseAsInteger } from 'nuqs'
+
+const [projectIds, setProjectIds] = useQueryState(
+  'project',
+  parseAsNativeArrayOf(parseAsInteger)
+)
+
+// ?project=123&project=456 → [123, 456]
+```
+
+<Suspense fallback={<DemoFallback />}>
+  <NativeArrayParserDemo />
+</Suspense>
+
+<Callout title="Note: empty array default">
+  `parseAsNativeArrayOf{:ts}` has a built-in default value of empty array (`.withDefault([]){:ts}`) so that you don't have to handle `null{:ts}` cases.
+
+  Calls to `.withDefault(){:ts}` can be chained, so you can use it to set a custom default.
+</Callout>
+
 ## Using parsers server-side
 
 For shared code that may be imported in the Next.js app router, you should import

packages/docs/content/docs/parsers/demos.tsx

@@ -15,9 +15,16 @@ import {
 } from '@/src/components/ui/pagination'
 import { Slider } from '@/src/components/ui/slider'
 import { cn } from '@/src/lib/utils'
-import { ChevronDown, ChevronUp, Minus, Star } from 'lucide-react'
 import {
-  ParserBuilder,
+  ChevronDown,
+  ChevronUp,
+  Dices,
+  Minus,
+  Star,
+  Trash2
+} from 'lucide-react'
+import {
+  createMultiParser,
   createParser,
   parseAsBoolean,
   parseAsFloat,
@@ -27,8 +34,11 @@ import {
   parseAsIsoDate,
   parseAsIsoDateTime,
   parseAsJson,
+  parseAsNativeArrayOf,
   parseAsStringLiteral,
   parseAsTimestamp,
+  ParserBuilder,
+  SingleParser,
   useQueryState
 } from 'nuqs'
 import React from 'react'
@@ -465,6 +475,244 @@ export function CustomParserDemo() {
   )
 }
 
+export function NativeArrayParserDemo() {
+  const [value, setValue] = useQueryState(
+    'nativeArray',
+    parseAsNativeArrayOf(parseAsInteger)
+  )
+  return (
+    <DemoContainer demoKey="nativeArray">
+      <Button
+        onClick={() =>
+          setValue(prev => prev.concat(Math.floor(Math.random() * 500) + 1))
+        }
+      >
+        <Dices size={18} className="mr-2 inline-block" role="presentation" />
+        Add random number
+      </Button>
+      <Button
+        onClick={() => setValue(prev => prev.slice(0, -1))}
+        disabled={value.length === 0}
+      >
+        <Trash2 size={16} className="mr-2 inline-block" role="presentation" />
+        Remove last number
+      </Button>
+      <Button
+        variant="secondary"
+        onClick={() => setValue([])}
+        className="ml-auto"
+      >
+        Clear
+      </Button>
+      <CodeBlock
+        lang="json"
+        code={JSON.stringify(value)}
+        allowCopy={false}
+        className="my-0 w-full"
+      />
+    </DemoContainer>
+  )
+}
+
+export function CustomMultiParserDemo() {
+  const parseAsFromTo = createParser({
+    parse: value => {
+      const [min = null, max = null] = value
+        .split('~')
+        .map(parseAsInteger.parse)
+      if (min === null) return null
+      if (max === null) return { eq: min }
+      return { gte: min, lte: max }
+    },
+    serialize: value => {
+      return value.eq !== undefined
+        ? String(value.eq)
+        : `${value.gte}~${value.lte}`
+    }
+  })
+
+  const parseAsKeyValue = createParser({
+    parse: value => {
+      const [key, val] = value.split(':')
+      if (!key || !val) return null
+      return { key, value: val }
+    },
+    serialize: value => {
+      return `${value.key}:${value.value}`
+    }
+  })
+
+  const parseAsFilters = <TItem extends {}>(
+    itemParser: SingleParser<TItem>
+  ) => {
+    return createMultiParser({
+      parse: values => {
+        const keyValue = values
+          .map(parseAsKeyValue.parse)
+          .filter(v => v !== null)
+
+        const result = Object.fromEntries(
+          keyValue.flatMap(({ key, value }) => {
+            const parsedValue: TItem | null = itemParser.parse(value)
+            return parsedValue === null ? [] : [[key, parsedValue]]
+          })
+        )
+
+        return Object.keys(result).length === 0 ? null : result
+      },
+      serialize: values => {
+        return Object.entries(values)
+          .map(([key, value]) => {
+            if (!itemParser.serialize) return null
+            return parseAsKeyValue.serialize({
+              key,
+              value: itemParser.serialize(value)
+            })
+          })
+          .filter(v => v !== null)
+      }
+    })
+  }
+
+  const [filters, setFilters] = useQueryState(
+    'filters',
+    parseAsFilters(parseAsFromTo).withDefault({})
+  )
+
+  return (
+    <DemoContainer demoKey="filters">
+      <div>
+        <label className="text-sm leading-none font-medium select-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">
+          Rating:
+        </label>
+        <input
+          type="number"
+          className="border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:ring-ring flex h-10 flex-1 rounded-md border px-3 py-2 text-sm file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+          value={filters.rating?.eq ?? ''}
+          min={0}
+          max={5}
+          onChange={e => {
+            setFilters(prev => ({
+              ...prev,
+              rating: { eq: e.target.value === '' ? 0 : e.target.valueAsNumber }
+            }))
+          }}
+          autoComplete="off"
+        />
+      </div>
+      <div>
+        <label className="text-sm leading-none font-medium select-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">
+          Price From:
+        </label>
+        <input
+          type="number"
+          className="border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:ring-ring flex h-10 flex-1 rounded-md border px-3 py-2 text-sm file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+          value={filters.price?.gte ?? 0}
+          step={10}
+          max={1000}
+          onChange={e => {
+            setFilters(prev => ({
+              ...prev,
+              price: {
+                lte: prev.price?.lte ?? 0,
+                gte: e.target.value === '' ? 0 : e.target.valueAsNumber
+              }
+            }))
+          }}
+          autoComplete="off"
+        />
+      </div>
+      <div>
+        <label className="text-sm leading-none font-medium select-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">
+          Price To:
+        </label>
+        <input
+          type="number"
+          className="border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:ring-ring flex h-10 flex-1 rounded-md border px-3 py-2 text-sm file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+          value={filters.price?.lte ?? 0}
+          step={10}
+          max={1000}
+          onChange={e => {
+            setFilters(prev => ({
+              ...prev,
+              price: {
+                gte: prev.price?.gte ?? 0,
+                lte: e.target.value === '' ? 0 : e.target.valueAsNumber
+              }
+            }))
+          }}
+          autoComplete="off"
+        />
+      </div>
+      <Button
+        variant="secondary"
+        onClick={() => setFilters(null)}
+        className="mt-auto ml-auto"
+      >
+        Clear
+      </Button>
+    </DemoContainer>
+  )
+
+  return (
+    <DemoContainer demoKey="filters">
+      {Object.entries(filters).map(([key, value]) => {
+        if (value.eq !== undefined) {
+          return (
+            <div key={key}>
+              <label className="text-sm leading-none font-medium select-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">
+                {key}:{' '}
+              </label>
+              <input
+                key={key}
+                type="number"
+                className="border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:ring-ring flex h-10 flex-1 rounded-md border px-3 py-2 text-sm file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+                value={value.eq}
+                onChange={e => {
+                  setFilters(prev => ({
+                    ...prev,
+                    [key]: { eq: e.target.valueAsNumber }
+                  }))
+                }}
+                placeholder="What's your favourite number?"
+                autoComplete="off"
+              />
+            </div>
+          )
+        }
+        return (
+          <div key={key}>
+            <label className="text-sm leading-none font-medium select-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">
+              {key}:{' '}
+            </label>
+            <input
+              key={key}
+              type="number"
+              className="border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:ring-ring flex h-10 flex-1 rounded-md border px-3 py-2 text-sm file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+              value={value.eq}
+              onChange={e => {
+                setFilters(prev => ({
+                  ...prev,
+                  [key]: { eq: e.target.valueAsNumber }
+                }))
+              }}
+              placeholder="What's your favourite number?"
+              autoComplete="off"
+            />
+          </div>
+        )
+      })}
+      <Button
+        variant="secondary"
+        onClick={() => setFilters(null)}
+        className="ml-auto"
+      >
+        Clear
+      </Button>
+    </DemoContainer>
+  )
+}
+
 type StarButtonProps = Omit<React.ComponentProps<typeof Button>, 'value'> & {
   index: Rating
   value: Rating | null