feat: multi-parsers

packages/nuqs/package.json

@@ -207,7 +207,7 @@
     {
       "name": "Server",
       "path": "dist/server.js",
-      "limit": "3 kB"
+      "limit": "3.1 kB"
     }
   ]
 }

packages/nuqs/src/api.test.ts

@@ -8,6 +8,7 @@ const exports = `
 {
   ".": {
     "createLoader": "function",
+    "createMultiParser": "function",
     "createParser": "function",
     "createSerializer": "function",
     "createStandardSchemaV1": "function",
@@ -22,6 +23,7 @@ const exports = `
     "parseAsIsoDate": "object",
     "parseAsIsoDateTime": "object",
     "parseAsJson": "function",
+    "parseAsNativeArrayOf": "function",
     "parseAsNumberLiteral": "function",
     "parseAsString": "object",
     "parseAsStringEnum": "function",
@@ -73,6 +75,7 @@ const exports = `
   },
   "./server": {
     "createLoader": "function",
+    "createMultiParser": "function",
     "createParser": "function",
     "createSearchParamsCache": "function",
     "createSerializer": "function",
@@ -88,6 +91,7 @@ const exports = `
     "parseAsIsoDate": "object",
     "parseAsIsoDateTime": "object",
     "parseAsJson": "function",
+    "parseAsNativeArrayOf": "function",
     "parseAsNumberLiteral": "function",
     "parseAsString": "object",
     "parseAsStringEnum": "function",

packages/nuqs/src/lib/queues/debounce.ts

@@ -73,7 +73,9 @@ export class DebounceController {
     this.throttleQueue = throttleQueue
   }
 
-  useQueuedQueries(keys: string[]): Record<string, string | null | undefined> {
+  useQueuedQueries(
+    keys: string[]
+  ): Record<string, Iterable<string> | null | undefined> {
     return useSyncExternalStores(
       keys,
       (key, callback) => this.queuedQuerySync.on(key, callback),
@@ -153,7 +155,7 @@ export class DebounceController {
     this.queues.clear()
   }
 
-  getQueuedQuery(key: string): string | null | undefined {
+  getQueuedQuery(key: string): Iterable<string> | null | undefined {
     // The debounced queued values are more likely to be up-to-date
     // than any updates pending in the throttle queue, which comes last
     // in the update chain.

packages/nuqs/src/lib/queues/throttle.ts

@@ -6,8 +6,9 @@ import { error } from '../errors'
 import { timeout } from '../timeout'
 import { withResolvers, type Resolvers } from '../with-resolvers'
 import { defaultRateLimit } from './rate-limiting'
+import { write } from '../search-params'
 
-type UpdateMap = Map<string, string | null>
+type UpdateMap = Map<string, Iterable<string> | null>
 type TransitionSet = Set<React.TransitionStartFunction>
 export type UpdateQueueAdapterContext = Pick<
   AdapterInterface,
@@ -19,7 +20,7 @@ export type UpdateQueueAdapterContext = Pick<
 
 export type UpdateQueuePushArgs = {
   key: string
-  query: string | null
+  query: Iterable<string> | null
   options: AdapterOptions & Pick<Options, 'startTransition'>
 }
 
@@ -65,7 +66,7 @@ export class ThrottledQueue {
     }
   }
 
-  getQueuedQuery(key: string): string | null | undefined {
+  getQueuedQuery(key: string): Iterable<string> | null | undefined {
     return this.updateMap.get(key)
   }
 
@@ -185,7 +186,7 @@ export class ThrottledQueue {
       if (value === null) {
         search.delete(key)
       } else {
-        search.set(key, value)
+        search = write(value, key, search)
       }
     }
     if (processUrlSearchParams) {

packages/nuqs/src/lib/safe-parse.ts

@@ -1,11 +1,10 @@
-import type { Parser } from '../parsers'
 import { warn } from './debug'
 
-export function safeParse<T>(
-  parser: Parser<T>['parse'],
-  value: string,
+export function safeParse<I, R>(
+  parser: (arg: I) => R,
+  value: I,
   key?: string
-): T | null {
+): R | null {
   try {
     return parser(value)
   } catch (error) {

packages/nuqs/src/lib/search-params.ts

@@ -0,0 +1,19 @@
+export function isEmpty(query: string | Iterable<string> | null): boolean {
+  return query === null || (Array.isArray(query) && query.length === 0)
+}
+
+export function write(
+  serialized: Iterable<string>,
+  key: string,
+  searchParams: URLSearchParams
+): URLSearchParams {
+  if (typeof serialized === 'string') {
+    searchParams.set(key, serialized)
+  } else {
+    searchParams.delete(key)
+    for (const v of serialized) {
+      searchParams.append(key, v)
+    }
+  }
+  return searchParams
+}

packages/nuqs/src/lib/sync.ts

@@ -2,7 +2,7 @@ import { createEmitter, type Emitter } from './emitter'
 
 export type CrossHookSyncPayload = {
   state: any
-  query: string | null
+  query: Iterable<string> | null
 }
 
 type EventMap = {

packages/nuqs/src/loader.ts

@@ -1,5 +1,6 @@
 import type { UrlKeys } from './defs'
-import type { inferParserType, ParserMap } from './parsers'
+import { type inferParserType, type ParserMap } from './parsers'
+import { isEmpty } from './lib/search-params'
 
 export type LoaderInput =
   | URL
@@ -96,14 +97,18 @@ export function createLoader<Parsers extends ParserMap>(
     const result = {} as any
     for (const [key, parser] of Object.entries(parsers)) {
       const urlKey = urlKeys[key] ?? key
-      const query = searchParams.get(urlKey)
-      if (query === null) {
+      const query =
+        parser.type === 'multi'
+          ? searchParams.getAll(urlKey)
+          : searchParams.get(urlKey)
+      if (isEmpty(query)) {
         result[key] = parser.defaultValue ?? null
         continue
       }
       let parsedValue
       try {
-        parsedValue = parser.parse(query)
+        // we have properly narrowed `query` here, but TS doesn't keep track of that
+        parsedValue = parser.parse(query as string & readonly string[])
       } catch (error) {
         if (strict) {
           throw new Error(