fix: forward processUrlSearchParams through the debounce queue (#1250)

Author: franky47

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

@@ -85,7 +85,8 @@ export class DebounceController {
   push(
     update: Omit<UpdateQueuePushArgs, 'timeMs'>,
     timeMs: number,
-    adapter: UpdateQueueAdapterContext
+    adapter: UpdateQueueAdapterContext,
+    processUrlSearchParams?: (search: URLSearchParams) => URLSearchParams
   ): Promise<URLSearchParams> {
     if (!Number.isFinite(timeMs)) {
       const getSnapshot =
@@ -100,14 +101,16 @@ export class DebounceController {
         URLSearchParams
       >(update => {
         this.throttleQueue.push(update)
-        return this.throttleQueue.flush(adapter).finally(() => {
-          const queuedValue = this.queues.get(update.key)?.queuedValue
-          if (queuedValue === undefined) {
-            debug('[nuqs dqc] Cleaning up empty queue for `%s`', update.key)
-            this.queues.delete(update.key)
-          }
-          this.queuedQuerySync.emit(update.key)
-        })
+        return this.throttleQueue
+          .flush(adapter, processUrlSearchParams)
+          .finally(() => {
+            const queuedValue = this.queues.get(update.key)?.queuedValue
+            if (queuedValue === undefined) {
+              debug('[nuqs dqc] Cleaning up empty queue for `%s`', update.key)
+              this.queues.delete(update.key)
+            }
+            this.queuedQuerySync.emit(update.key)
+          })
       })
       this.queues.set(key, queue)
     }

packages/nuqs/src/useQueryStates.test.tsx

@@ -935,6 +935,28 @@ describe('useQueryStates: process url search params', () => {
     expect(onUrlUpdate).toHaveBeenCalledOnce()
     expect(onUrlUpdate.mock.calls[0]![0].queryString).toBe('?test=processed')
   })
+  it('should call processUrlSearchParams after a debounced update', async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
+    const useTestHook = () => useQueryStates({ test: parseAsString })
+    const { result } = renderHook(useTestHook, {
+      wrapper: withNuqsTestingAdapter({
+        processUrlSearchParams: search => {
+          expect(search.get('test')).toBe('fail')
+          search.set('test', 'pass')
+          return search
+        },
+        onUrlUpdate
+      })
+    })
+    await act(async () => {
+      await result.current[1](
+        { test: 'fail' },
+        { limitUrlUpdates: debounce(50) }
+      )
+    })
+    expect(onUrlUpdate).toHaveBeenCalledOnce()
+    expect(onUrlUpdate.mock.calls[0]![0].queryString).toBe('?test=pass')
+  })
 })
 
 describe('useQueryStates: edge cases & repros', () => {

packages/nuqs/src/useQueryStates.ts

@@ -335,7 +335,8 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
           const debouncedPromise = debounceController.push(
             update,
             timeMs,
-            adapter
+            adapter,
+            processUrlSearchParams
           )
           if (maxDebounceTime < timeMs) {
             // The largest debounce is likely to be the last URL update,