feat: multi-parsers

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,37 @@ 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:
+
+```
+/products?tag=books&tag=tech&tag=design
+```
+
+you can now use `MultiParsers` like `parseAsNativeArrayOf` 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="Empty Array Default">
+  Note that `parseAsNativeArrayOf` has a built-in default value of empty array (`.withDefault([])`) so that you don't have to handle `null` cases.
+</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

@@ -19,6 +19,7 @@ import { ChevronDown, ChevronUp, Minus, Star } from 'lucide-react'
 import {
   ParserBuilder,
   createParser,
+  createMultiParser,
   parseAsBoolean,
   parseAsFloat,
   parseAsHex,
@@ -27,8 +28,12 @@ import {
   parseAsIsoDate,
   parseAsIsoDateTime,
   parseAsJson,
+  parseAsArrayOf,
+  parseAsNativeArrayOf,
+  parseAsString,
   parseAsStringLiteral,
   parseAsTimestamp,
+  SingleParser,
   useQueryState
 } from 'nuqs'
 import React from 'react'
@@ -465,6 +470,210 @@ 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))}
+      >
+        Add random number
+      </Button>
+      <Button
+        onClick={() => setValue(prev => prev.slice(0, -1))}
+      >
+        Remove last number
+      </Button>
+      <Button
+        variant="secondary"
+        onClick={() => setValue([])}
+        className="ml-auto"
+      >
+        Clear
+      </Button>
+      <div className="w-full text-sm text-zinc-500">
+        Current value: [{value.join(', ') || ''}]
+      </div>
+    </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 ?? ''}
+          onChange={e => {
+            setFilters(prev => ({...prev, rating: { eq: 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}
+          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}
+          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="ml-auto mt-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

packages/docs/content/docs/parsers/making-your-own.mdx

@@ -4,7 +4,8 @@ description: Making your own parsers for custom data types & pretty URLs
 ---
 
 import {
-  CustomParserDemo
+  CustomParserDemo,
+  CustomMultiParserDemo
 } from '@/content/docs/parsers/demos'
 
 You may wish to customise the rendered query string for your data type.
@@ -35,6 +36,70 @@ const parseAsStarRating = createParser({
   <CustomParserDemo/>
 </Suspense>
 
+## Custom Multi Parsers
+
+`MultiParsers` work similar to `SingleParsers`, except that they operate on Arrays. That means:
+
+1. `parse` takes an `Array<string>`. It receives all matching values of the key it operates on, and returns the parsed value, or `null{:ts}` if invalid.
+2. `serialize` takes the parsed value and returns an `Array<string>`, where each item will be separately added to the URL.
+
+```tsx
+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({})
+)
+```
+
+<Suspense>
+  <CustomMultiParserDemo/>
+</Suspense>
+
 ## Caveat: lossy serializers
 
 If your serializer loses precision or doesn't accurately represent

packages/docs/src/components/querystring.tsx

@@ -63,7 +63,7 @@ function filterQueryKeys(query: string | URLSearchParams, keys?: string[]) {
   const destination = new URLSearchParams()
   for (const [key, value] of source.entries()) {
     if (keys.includes(key)) {
-      destination.set(key, value)
+      destination.append(key, value)
     }
   }
   return destination

packages/e2e/next/src/app/app/(shared)/native-array/page.tsx

@@ -0,0 +1,10 @@
+import { NativeArray } from 'e2e-shared/specs/native-array'
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <Suspense>
+      <NativeArray />
+    </Suspense>
+  )
+}

packages/e2e/next/src/pages/pages/native-array.tsx

@@ -0,0 +1,3 @@
+import { NativeArray } from 'e2e-shared/specs/native-array'
+
+export default NativeArray

packages/e2e/react-router/v6/src/react-router.tsx

@@ -34,6 +34,7 @@ const router = createBrowserRouter(
       <Route path="linking/useQueryState/other"               lazy={load(import('./routes/linking.useQueryState.other'))} />
       <Route path="linking/useQueryStates"                    lazy={load(import('./routes/linking.useQueryStates'))} />
       <Route path="linking/useQueryStates/other"              lazy={load(import('./routes/linking.useQueryStates.other'))} />
+      <Route path="native-array"                              lazy={load(import('./routes/native-array'))} />
       <Route path="pretty-urls"                               lazy={load(import('./routes/pretty-urls'))} />
       <Route path="referential-stability/useQueryState"       lazy={load(import('./routes/referential-stability.useQueryState'))} />
       <Route path="referential-stability/useQueryStates"      lazy={load(import('./routes/referential-stability.useQueryStates'))} />

packages/e2e/react-router/v6/src/routes/native-array.tsx

@@ -0,0 +1,3 @@
+import { NativeArray } from 'e2e-shared/specs/native-array'
+
+export default NativeArray