feat: process url search params middleware

Author: Multiply

packages/nuqs/src/adapters/lib/context.ts

@@ -16,6 +16,7 @@ export type AdapterProps = {
   defaultOptions?: Partial<
     Pick<Options, 'shallow' | 'clearOnDefault' | 'scroll' | 'limitUrlUpdates'>
   >
+  processUrlSearchParams?: (search: URLSearchParams) => URLSearchParams
 }
 
 export type AdapterContext = AdapterProps & {
@@ -59,10 +60,10 @@ export type AdapterProvider = (
 export function createAdapterProvider(
   useAdapter: UseAdapterHook
 ): AdapterProvider {
-  return ({ children, defaultOptions, ...props }) =>
+  return ({ children, defaultOptions, processUrlSearchParams, ...props }) =>
     createElement(
       context.Provider,
-      { ...props, value: { useAdapter, defaultOptions } },
+      { ...props, value: { useAdapter, defaultOptions, processUrlSearchParams } },
       children
     )
 }
@@ -77,3 +78,6 @@ export function useAdapter(watchKeys: string[]): AdapterInterface {
 
 export const useAdapterDefaultOptions = (): AdapterProps['defaultOptions'] =>
   useContext(context).defaultOptions
+
+export const useAdapterProcessUrlSearchParams = (): AdapterProps['processUrlSearchParams'] =>
+  useContext(context).processUrlSearchParams

packages/nuqs/src/adapters/testing.ts

@@ -29,6 +29,7 @@ type TestingAdapterProps = {
 export function NuqsTestingAdapter({
   resetUrlUpdateQueueOnMount = true,
   defaultOptions,
+  processUrlSearchParams,
   ...props
 }: TestingAdapterProps): ReactElement {
   if (resetUrlUpdateQueueOnMount) {
@@ -59,7 +60,7 @@ export function NuqsTestingAdapter({
   })
   return createElement(
     context.Provider,
-    { value: { useAdapter, defaultOptions } },
+    { value: { useAdapter, defaultOptions, processUrlSearchParams } },
     props.children
   )
 }

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

@@ -305,4 +305,62 @@ describe('throttle: flush', () => {
       new Error('updateUrl error')
     )
   })
+  it('should process url search params', async () => {
+    const mockAdapter = createMockAdapter()
+    const queue = new ThrottledQueue()
+    queue.push({
+      key: 'a',
+      query: 'a',
+      options: {},
+    })
+    const promise = queue.flush(mockAdapter, function (search) {
+      const params = new URLSearchParams(search)
+      params.set('b', 'b')
+      return params
+    })
+    expect(queue.controller).not.toBeNull()
+    vi.runAllTimers()
+    await expect(promise).resolves.toEqual(new URLSearchParams('?a=a&b=b'))
+  })
+  describe('should process url search params', () => {
+    it('should add new params', async () => {
+      const mockAdapter = createMockAdapter()
+      const queue = new ThrottledQueue()
+      queue.push({
+        key: 'a',
+        query: 'a',
+        options: {},
+      })
+      const promise = queue.flush(mockAdapter, (search) => {
+        const params = new URLSearchParams(search)
+        params.set('b', 'b')
+        return params
+      })
+      expect(queue.controller).not.toBeNull()
+      vi.runAllTimers()
+      await expect(promise).resolves.toEqual(new URLSearchParams('?a=a&b=b'))
+    })
+    it('should sort params', async () => {
+      const mockAdapter = createMockAdapter()
+      const queue = new ThrottledQueue()
+      queue.push({
+        key: 'b',
+        query: 'b',
+        options: {},
+      })
+      queue.push({
+        key: 'a',
+        query: 'a',
+        options: {},
+      })
+      const promise = queue.flush(mockAdapter, (search) => {
+        const entries = Array.from(search.entries())
+        entries.sort(([a], [b]) => a.localeCompare(b))
+        return new URLSearchParams(entries)
+      })
+      expect(queue.controller).not.toBeNull()
+      vi.runAllTimers()
+      await expect(promise).resolves.toEqual(new URLSearchParams('?a=a&b=b'))
+    })
+  })
 })

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

@@ -69,11 +69,14 @@ export class ThrottledQueue {
     return this.updateMap.get(key)
   }
 
-  flush({
-    getSearchParamsSnapshot = getSearchParamsSnapshotFromLocation,
-    rateLimitFactor = 1,
-    ...adapter
-  }: UpdateQueueAdapterContext): Promise<URLSearchParams> {
+  flush(
+    {
+      getSearchParamsSnapshot = getSearchParamsSnapshotFromLocation,
+      rateLimitFactor = 1,
+      ...adapter
+    }: UpdateQueueAdapterContext,
+    processUrlSearchParams?: (search: URLSearchParams) => URLSearchParams
+  ): Promise<URLSearchParams> {
     this.controller ??= new AbortController()
     if (!Number.isFinite(this.timeMs)) {
       debug('[nuqs gtq] Skipping flush due to throttleMs=Infinity')
@@ -90,7 +93,7 @@ export class ThrottledQueue {
         ...adapter,
         autoResetQueueOnUpdate: adapter.autoResetQueueOnUpdate ?? true,
         getSearchParamsSnapshot
-      })
+      }, processUrlSearchParams)
       if (error === null) {
         this.resolvers!.resolve(search)
       } else {
@@ -152,10 +155,11 @@ export class ThrottledQueue {
   }
 
   applyPendingUpdates(
-    adapter: Required<Omit<UpdateQueueAdapterContext, 'rateLimitFactor'>>
+    adapter: Required<Omit<UpdateQueueAdapterContext, 'rateLimitFactor'>>,
+    processUrlSearchParams?: (search: URLSearchParams) => URLSearchParams
   ): [URLSearchParams, null | unknown] {
     const { updateUrl, getSearchParamsSnapshot } = adapter
-    const search = getSearchParamsSnapshot()
+    let search = getSearchParamsSnapshot()
     debug(
       `[nuqs gtq] Applying %d pending update(s) on top of %s`,
       this.updateMap.size,
@@ -181,6 +185,9 @@ export class ThrottledQueue {
         search.set(key, value)
       }
     }
+    if (processUrlSearchParams) {
+      search = processUrlSearchParams(search)
+    }
     try {
       compose(transitions, () => {
         updateUrl(search, options)

packages/nuqs/src/useQueryStates.test.ts

@@ -748,3 +748,23 @@ describe('useQueryStates: adapter defaults', () => {
     expect(onUrlUpdate.mock.calls[0]![0].queryString).toBe('?test=pass')
   })
 })
+
+describe('useQueryStates: process url search params', () => {
+  it('should use adapter processUrlSearchParams when provided', async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
+    const useTestHook = () => useQueryStates({ test: parseAsString })
+    const { result } = renderHook(useTestHook, {
+      wrapper: withNuqsTestingAdapter({
+        processUrlSearchParams: (search) => {
+          const params = new URLSearchParams(search)
+          params.set('test', 'processed')
+          return params
+        },
+        onUrlUpdate
+      })
+    })
+    await act(() => result.current[1]({ test: 'update' }))
+    expect(onUrlUpdate).toHaveBeenCalledOnce()
+    expect(onUrlUpdate.mock.calls[0]![0].queryString).toBe('?test=processed')
+  })
+})

packages/nuqs/src/useQueryStates.ts

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
-import { useAdapter, useAdapterDefaultOptions } from './adapters/lib/context'
+import { useAdapter, useAdapterDefaultOptions, useAdapterProcessUrlSearchParams } from './adapters/lib/context'
 import type { Nullable, Options, UrlKeys } from './defs'
 import { debug } from './lib/debug'
 import { error } from './lib/errors'
@@ -69,6 +69,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
 ): UseQueryStatesReturn<KeyMap> {
   const hookId = useId()
   const defaultOptions = useAdapterDefaultOptions()
+  const processUrlSearchParams = useAdapterProcessUrlSearchParams()
 
   const {
     history = 'replace',
@@ -333,7 +334,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       // debounced update that will resolve afterwards.
       const globalPromise = debounceAborts.reduce(
         (previous, fn) => fn(previous),
-        globalThrottleQueue.flush(adapter)
+        globalThrottleQueue.flush(adapter, processUrlSearchParams)
       )
       return returnedPromise ?? globalPromise
     },