chore: Cleanup & testing

Author: franky47

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

@@ -87,9 +87,23 @@ describe('debounce: DebouncedPromiseQueue', () => {
     expect(queue.queuedValue).toBeUndefined()
     await expect(p).rejects.toThrowError('error')
   })
+  it('returns a new Promise when an update is pushed while the callback is pending', async () => {
+    vi.useFakeTimers()
+    const queue = new DebouncedPromiseQueue(async input => {
+      await setTimeout(100)
+      return input
+    })
+    const p1 = queue.push('a', 100)
+    vi.advanceTimersByTime(150) // 100ms debounce + half the callback settle time
+    const p2 = queue.push('b', 100)
+    expect(p1).not.toBe(p2)
+    vi.advanceTimersToNextTimer()
+    await expect(p1).resolves.toBe('a')
+    await expect(p2).resolves.toBe('b')
+  })
 })
 
-describe.only('debounce: DebounceController', () => {
+describe('debounce: DebounceController', () => {
   it('schedules an update and calls the adapter with it', async () => {
     vi.useFakeTimers()
     const fakeAdapter: UpdateQueueAdapterContext = {

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

@@ -18,26 +18,28 @@ export class DebouncedPromiseQueue<ValueType, OutputType> {
     this.callback = callback
   }
 
-  public push(value: ValueType, timeMs: number) {
+  push(value: ValueType, timeMs: number) {
     this.queuedValue = value
     this.controller.abort()
     this.controller = new AbortController()
     timeout(
       () => {
+        // Keep the resolvers in a separate variable to reset the queue
+        // while the callback is pending, so that the next push can be
+        // assigned to a new Promise (and not dropped).
+        const outputResolvers = this.resolvers
         try {
           debug('[nuqs queue] Flushing debounce queue', value)
-          const p = this.callback(value)
+          const callbackPromise = this.callback(value)
           debug('[nuqs queue] Reset debounced queue %O', this.queuedValue)
           this.queuedValue = undefined
-          p.then(output => this.resolvers.resolve(output))
-            .catch(error => this.resolvers.reject(error))
-            .finally(() => {
-              // Reset Promise for next use
-              this.resolvers = withResolvers<OutputType>()
-            })
+          this.resolvers = withResolvers<OutputType>()
+          callbackPromise
+            .then(output => outputResolvers.resolve(output))
+            .catch(error => outputResolvers.reject(error))
         } catch (error) {
           this.queuedValue = undefined
-          this.resolvers.reject(error)
+          outputResolvers.reject(error)
         }
       },
       timeMs,
@@ -62,7 +64,7 @@ export class DebounceController {
     this.throttleQueue = throttleQueue
   }
 
-  public push(
+  push(
     update: Omit<UpdateQueuePushArgs, 'throttleMs'>,
     timeMs: number,
     adapter: UpdateQueueAdapterContext
@@ -73,19 +75,21 @@ export class DebounceController {
         URLSearchParams
       >(update => {
         this.throttleQueue.push(update)
-        return this.throttleQueue.flush(adapter)
-        // todo: Figure out cleanup strategy
-        // .finally(() => {
-        //   this.queues.delete(update.key)
-        // })
+        return this.throttleQueue.flush(adapter).finally(() => {
+          const queuedValue = this.queues.get(update.key)?.queuedValue
+          if (queuedValue === undefined) {
+            // Cleanup empty queues
+            this.queues.delete(update.key)
+          }
+        })
       })
       this.queues.set(update.key, queue)
     }
     const queue = this.queues.get(update.key)!
     return queue.push(update, timeMs)
   }
 
-  public getQueuedQuery(key: string) {
+  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
     // in the update chain.

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

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import { ThrottledQueue } from './throttle'
+
+describe('throttle: ThrottleQueue value queueing', () => {
+  it('should enqueue key & values', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'key', query: 'value', options: {} })
+    expect(queue.getQueuedQuery('key')).toEqual('value')
+  })
+  it('should replace more recent values with the same key', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'key', query: 'a', options: {} })
+    queue.push({ key: 'key', query: 'b', options: {} })
+    expect(queue.getQueuedQuery('key')).toEqual('b')
+  })
+  it('should enqueue multiple keys', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'key1', query: 'a', options: {} })
+    queue.push({ key: 'key2', query: 'b', options: {} })
+    expect(queue.getQueuedQuery('key1')).toEqual('a')
+    expect(queue.getQueuedQuery('key2')).toEqual('b')
+  })
+  it('should enqueue null values (to clear a key from the URL)', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'key', query: 'a', options: {} })
+    queue.push({ key: 'key', query: null, options: {} })
+    expect(queue.getQueuedQuery('key')).toBeNull()
+  })
+  it('should return an undefined queued value if no push occurred', () => {
+    const queue = new ThrottledQueue()
+    expect(queue.getQueuedQuery('key')).toBeUndefined()
+  })
+})
+
+describe('throttle: ThrottleQueue option combination logic', () => {
+  it('should resolve with the default options', () => {
+    const queue = new ThrottledQueue()
+    expect(queue.options).toEqual({
+      history: 'replace',
+      scroll: false,
+      shallow: true
+    })
+  })
+  it('should combine history options (push takes precedence)', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'a', query: null, options: { history: 'replace' } })
+    queue.push({ key: 'b', query: null, options: { history: 'push' } })
+    queue.push({ key: 'c', query: null, options: { history: 'replace' } })
+    expect(queue.options.history).toEqual('push')
+  })
+  it('should combine scroll options (true takes precedence)', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'a', query: null, options: { scroll: false } })
+    queue.push({ key: 'b', query: null, options: { scroll: true } })
+    queue.push({ key: 'c', query: null, options: { scroll: false } })
+    expect(queue.options.scroll).toEqual(true)
+  })
+  it('should combine shallow options (false takes precedence)', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'a', query: null, options: { shallow: true } })
+    queue.push({ key: 'b', query: null, options: { shallow: false } })
+    queue.push({ key: 'c', query: null, options: { shallow: true } })
+    expect(queue.options.shallow).toEqual(false)
+  })
+})

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

@@ -62,7 +62,7 @@ export class ThrottledQueue {
   resolvers: Resolvers<URLSearchParams> | null = null
   lastFlushedAt = 0
 
-  public push({
+  push({
     key,
     query,
     options,
@@ -89,11 +89,11 @@ export class ThrottledQueue {
     )
   }
 
-  public getQueuedQuery(key: string): string | null | undefined {
+  getQueuedQuery(key: string): string | null | undefined {
     return this.updateMap.get(key)
   }
 
-  public flush({
+  flush({
     getSearchParamsSnapshot = getSearchParamsSnapshotFromLocation,
     rateLimitFactor = 1,
     ...adapter
@@ -152,7 +152,7 @@ export class ThrottledQueue {
     return this.resolvers.promise
   }
 
-  public reset() {
+  reset() {
     this.updateMap.clear()
     this.transitions.clear()
     this.options.history = 'replace'
@@ -161,9 +161,7 @@ export class ThrottledQueue {
     this.throttleMs = defaultRateLimit.timeMs
   }
 
-  // --
-
-  private applyPendingUpdates(
+  applyPendingUpdates(
     adapter: Required<Omit<UpdateQueueAdapterContext, 'rateLimitFactor'>>
   ): [URLSearchParams, null | unknown] {
     const { updateUrl, getSearchParamsSnapshot } = adapter

packages/nuqs/src/lib/timeout.ts

@@ -1,4 +1,15 @@
+// Source:
+// https://www.bennadel.com/blog/4195-using-abortcontroller-to-debounce-settimeout-calls-in-javascript.htm
+
 export function timeout(callback: () => void, ms: number, signal: AbortSignal) {
-  const id = setTimeout(callback, ms)
-  signal.addEventListener('abort', () => clearTimeout(id))
+  function onTick() {
+    callback()
+    signal.removeEventListener('abort', onAbort)
+  }
+  const id = setTimeout(onTick, ms)
+  function onAbort() {
+    clearTimeout(id)
+    signal.removeEventListener('abort', onAbort)
+  }
+  signal.addEventListener('abort', onAbort)
 }