feat: Auto-abort debounced updates when pushing a non-debounced one

Author: franky47

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

@@ -202,4 +202,34 @@ describe('debounce: DebounceController', () => {
     const controller = new DebounceController(throttleQueue)
     expect(controller.getQueuedQuery('key')).toEqual('value')
   })
+  it('aborts an update and chains the Promise onto another one that overrides it', async () => {
+    vi.useFakeTimers()
+    const fakeAdapter: UpdateQueueAdapterContext = {
+      updateUrl: vi.fn<UpdateUrlFunction>(),
+      getSearchParamsSnapshot() {
+        return new URLSearchParams()
+      }
+    }
+    const controller = new DebounceController()
+    const debouncedPromise = controller.push(
+      {
+        key: 'key',
+        query: 'value',
+        options: {}
+      },
+      100,
+      fakeAdapter
+    )
+    const attach = controller.abort('key')
+    expect(attach).toBeInstanceOf(Function)
+    vi.runAllTimers()
+    const resolvedPromise = Promise.resolve(
+      new URLSearchParams('?key=override')
+    )
+    const attachedPromise = attach(resolvedPromise)
+    expect(attachedPromise).toBe(resolvedPromise) // Referential equality
+    await expect(debouncedPromise).resolves.toEqual(
+      new URLSearchParams('?key=override')
+    )
+  })
 })

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

@@ -89,6 +89,32 @@ export class DebounceController {
     return queue.push(update, timeMs)
   }
 
+  abort(
+    key: string
+  ): (promise: Promise<URLSearchParams>) => Promise<URLSearchParams> {
+    const queue = this.queues.get(key)
+    if (!queue) {
+      return passThrough => passThrough
+    }
+    debug(
+      '[nuqs queue] Aborting debounced queue %s=%s',
+      key,
+      queue.queuedValue?.query
+    )
+    this.queues.delete(key)
+    queue.controller.abort() // Don't run to completion
+    return function attachAbortedDebouncedResolvers(
+      promise: Promise<URLSearchParams>
+    ) {
+      promise.then(
+        value => queue.resolvers.resolve(value),
+        error => queue.resolvers.reject(error)
+      )
+      // Don't chain: keep reference equality
+      return promise
+    }
+  }
+
   getQueuedQuery(key: string) {
     // The debounced queued values are more likely to be up-to-date
     // than any updates pending in the throttle queue, which comes last

packages/nuqs/src/useQueryState.test.ts

@@ -301,4 +301,27 @@ describe('useQueryState: update sequencing', () => {
     expect(onUrlUpdate.mock.calls[0]![0].queryString).toEqual('?b=b')
     expect(onUrlUpdate.mock.calls[1]![0].queryString).toEqual('?a=a')
   })
+  it('aborts a debounced update when pushing a throttled one', async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
+    const { result } = renderHook(() => useQueryState('test'), {
+      wrapper: withNuqsTestingAdapter({
+        onUrlUpdate,
+        rateLimitFactor: 1
+      })
+    })
+    let p1: Promise<URLSearchParams> | undefined = undefined
+    let p2: Promise<URLSearchParams> | undefined = undefined
+    await act(async () => {
+      p1 = result.current[1]('a', { limitUrlUpdates: debounce(100) })
+      p2 = result.current[1]('b')
+      return Promise.allSettled([p1, p2])
+    })
+    expect(p1).toBeInstanceOf(Promise)
+    expect(p2).toBeInstanceOf(Promise)
+    expect(p1).not.toBe(p2)
+    await expect(p1).resolves.toEqual(new URLSearchParams('?test=b'))
+    await expect(p2).resolves.toEqual(new URLSearchParams('?test=b'))
+    expect(onUrlUpdate).toHaveBeenCalledTimes(1)
+    expect(onUrlUpdate.mock.calls[0]![0].queryString).toEqual('?test=b')
+  })
 })

packages/nuqs/src/useQueryState.ts

@@ -311,8 +311,9 @@ export function useQueryState<T = string>(
           limitUrlUpdates?.timeMs ??
           options.throttleMs ??
           throttleMs
+        const handleAbortedDebounce = debounceController.abort(key)
         globalThrottleQueue.push(update, timeMs)
-        return globalThrottleQueue.flush(adapter)
+        return handleAbortedDebounce(globalThrottleQueue.flush(adapter))
       }
     },
     [

packages/nuqs/src/useQueryStates.test.ts

@@ -615,4 +615,71 @@ describe('useQueryStates: update sequencing', () => {
     expect(onUrlUpdate.mock.calls[0]![0].queryString).toEqual('?b=b')
     expect(onUrlUpdate.mock.calls[1]![0].queryString).toEqual('?a=a')
   })
+
+  it('aborts a debounced update when pushing a throttled one', async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
+    const { result } = renderHook(
+      () =>
+        useQueryStates({
+          test: parseAsString
+        }),
+      {
+        wrapper: withNuqsTestingAdapter({
+          onUrlUpdate,
+          rateLimitFactor: 1
+        })
+      }
+    )
+    let p1: Promise<URLSearchParams> | undefined = undefined
+    let p2: Promise<URLSearchParams> | undefined = undefined
+    await act(async () => {
+      p1 = result.current[1](
+        { test: 'init' },
+        { limitUrlUpdates: debounce(100) }
+      )
+      p2 = result.current[1]({ test: 'pass' })
+      return Promise.allSettled([p1, p2])
+    })
+    expect(p1).toBeInstanceOf(Promise)
+    expect(p2).toBeInstanceOf(Promise)
+    expect(p1).not.toBe(p2)
+    // Note: our mock adapter does not save search params, so there is no merge
+    await expect(p1).resolves.toEqual(new URLSearchParams('?test=pass'))
+    await expect(p2).resolves.toEqual(new URLSearchParams('?test=pass'))
+    expect(onUrlUpdate).toHaveBeenCalledTimes(1)
+    expect(onUrlUpdate.mock.calls[0]![0].queryString).toEqual('?test=pass')
+  })
+
+  it('does not abort when pushing another key', async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
+    const { result } = renderHook(
+      () =>
+        useQueryStates({
+          a: parseAsString.withOptions({ limitUrlUpdates: debounce(100) }),
+          b: parseAsString
+        }),
+      {
+        wrapper: withNuqsTestingAdapter({
+          onUrlUpdate,
+          rateLimitFactor: 1
+        })
+      }
+    )
+    let p1: Promise<URLSearchParams> | undefined = undefined
+    let p2: Promise<URLSearchParams> | undefined = undefined
+    await act(async () => {
+      p1 = result.current[1]({ a: 'debounced' })
+      p2 = result.current[1]({ b: 'pass' })
+      return Promise.allSettled([p1, p2])
+    })
+    expect(p1).toBeInstanceOf(Promise)
+    expect(p2).toBeInstanceOf(Promise)
+    expect(p1).not.toBe(p2)
+    // Note: our mock adapter does not save search params, so there is no merge
+    await expect(p1).resolves.toEqual(new URLSearchParams('?a=debounced'))
+    await expect(p2).resolves.toEqual(new URLSearchParams('?b=pass'))
+    expect(onUrlUpdate).toHaveBeenCalledTimes(2)
+    expect(onUrlUpdate.mock.calls[0]![0].queryString).toEqual('?b=pass')
+    expect(onUrlUpdate.mock.calls[1]![0].queryString).toEqual('?a=debounced')
+  })
 })

packages/nuqs/src/useQueryStates.ts

@@ -218,6 +218,9 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       debug('[nuq+ `%s`] setState: %O', stateKeys, newState)
       let returnedPromise: Promise<URLSearchParams> | undefined = undefined
       let maxDebounceTime = 0
+      const debounceAborts: Array<
+        (p: Promise<URLSearchParams>) => Promise<URLSearchParams>
+      > = []
       for (let [stateKey, value] of Object.entries(newState)) {
         const parser = keyMap[stateKey]
         const urlKey = resolvedUrlKeys[stateKey]!
@@ -281,12 +284,16 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
             callOptions.throttleMs ??
             parser.throttleMs ??
             throttleMs
+          debounceAborts.push(debounceController.abort(urlKey))
           globalThrottleQueue.push(update, timeMs)
         }
       }
       // We need to flush the throttle queue, but we may have a pending
       // debounced update that will resolve afterwards.
-      const globalPromise = globalThrottleQueue.flush(adapter)
+      const globalPromise = debounceAborts.reduce(
+        (previous, fn) => fn(previous),
+        globalThrottleQueue.flush(adapter)
+      )
       return returnedPromise ?? globalPromise
     },
     [