fix: Initial value for throttle queue timeMs

Also renamed the property to avoid clashes with the throttleMs option.

Author: franky47

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

@@ -52,7 +52,7 @@ export class DebouncedPromiseQueue<ValueType, OutputType> {
 // --
 
 type DebouncedUpdateQueue = DebouncedPromiseQueue<
-  Omit<UpdateQueuePushArgs, 'throttleMs'>,
+  Omit<UpdateQueuePushArgs, 'timeMs'>,
   URLSearchParams
 >
 
@@ -65,13 +65,13 @@ export class DebounceController {
   }
 
   push(
-    update: Omit<UpdateQueuePushArgs, 'throttleMs'>,
+    update: Omit<UpdateQueuePushArgs, 'timeMs'>,
     timeMs: number,
     adapter: UpdateQueueAdapterContext
   ): Promise<URLSearchParams> {
     if (!this.queues.has(update.key)) {
       const queue = new DebouncedPromiseQueue<
-        Omit<UpdateQueuePushArgs, 'throttleMs'>,
+        Omit<UpdateQueuePushArgs, 'timeMs'>,
         URLSearchParams
       >(update => {
         this.throttleQueue.push(update)

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

@@ -1,5 +1,7 @@
-import { describe, expect, it } from 'vitest'
-import { ThrottledQueue } from './throttle'
+import { describe, expect, it, vi } from 'vitest'
+import type { UpdateUrlFunction } from '../../adapters/lib/defs'
+import { defaultRateLimit } from './rate-limiting'
+import { ThrottledQueue, type UpdateQueueAdapterContext } from './throttle'
 
 describe('throttle: ThrottleQueue value queueing', () => {
   it('should enqueue key & values', () => {
@@ -62,4 +64,52 @@ describe('throttle: ThrottleQueue option combination logic', () => {
     queue.push({ key: 'c', query: null, options: { shallow: true } })
     expect(queue.options.shallow).toEqual(false)
   })
+  it('should compose transitions', async () => {
+    const mockStartTransition = (callback: () => void) => {
+      callback()
+    }
+    const startTransitionA = vi.fn().mockImplementation(mockStartTransition)
+    const startTransitionB = vi.fn().mockImplementation(mockStartTransition)
+    const mockAdapter: UpdateQueueAdapterContext = {
+      updateUrl: vi.fn<UpdateUrlFunction>(),
+      getSearchParamsSnapshot() {
+        return new URLSearchParams()
+      }
+    }
+    const queue = new ThrottledQueue()
+    queue.push({
+      key: 'a',
+      query: null,
+      options: { startTransition: startTransitionA }
+    })
+    queue.push({
+      key: 'b',
+      query: null,
+      options: { startTransition: startTransitionB }
+    })
+    await queue.flush(mockAdapter)
+    expect(startTransitionA).toHaveBeenCalledOnce()
+    expect(startTransitionB).toHaveBeenCalledOnce()
+    expect(startTransitionA).toHaveBeenCalledBefore(startTransitionB)
+  })
+  it('keeps the maximum value for timeMs', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'a', query: null, options: {}, timeMs: 100 })
+    queue.push({ key: 'b', query: null, options: {}, timeMs: 200 })
+    queue.push({ key: 'c', query: null, options: {}, timeMs: 300 })
+    expect(queue.timeMs).toEqual(300)
+  })
+  it('clamps the minimum value for timeMs to the default rate limit', () => {
+    expect(defaultRateLimit.timeMs).toBeGreaterThan(10) // precondition
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'a', query: null, options: {}, timeMs: 10 })
+    expect(queue.timeMs).toEqual(defaultRateLimit.timeMs)
+  })
+  it('supports passing Infinity to the timeMs option (but can be cleared)', () => {
+    const queue = new ThrottledQueue()
+    queue.push({ key: 'a', query: null, options: {}, timeMs: Infinity })
+    expect(queue.timeMs).toBe(Infinity)
+    queue.push({ key: 'b', query: null, options: {}, timeMs: 100 })
+    expect(queue.timeMs).toBe(100)
+  })
 })

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

@@ -20,7 +20,7 @@ export type UpdateQueuePushArgs = {
   key: string
   query: string | null
   options: AdapterOptions & Pick<Options, 'startTransition'>
-  throttleMs?: number
+  timeMs?: number
 }
 
 function getSearchParamsSnapshotFromLocation() {
@@ -34,7 +34,7 @@ export class ThrottledQueue {
     scroll: false,
     shallow: true
   }
-  throttleMs = 0
+  timeMs = defaultRateLimit.timeMs
   transitions: TransitionSet = new Set()
   resolvers: Resolvers<URLSearchParams> | null = null
   lastFlushedAt = 0
@@ -43,7 +43,7 @@ export class ThrottledQueue {
     key,
     query,
     options,
-    throttleMs = defaultRateLimit.timeMs
+    timeMs = defaultRateLimit.timeMs
   }: UpdateQueuePushArgs) {
     debug('[nuqs queue] Enqueueing %s=%s %O', key, query, options)
     // Enqueue update
@@ -60,9 +60,9 @@ export class ThrottledQueue {
     if (options.startTransition) {
       this.transitions.add(options.startTransition)
     }
-    this.throttleMs = Math.max(
-      throttleMs,
-      Number.isFinite(this.throttleMs) ? this.throttleMs : 0
+    this.timeMs = Math.max(
+      timeMs,
+      Number.isFinite(this.timeMs) ? this.timeMs : 0
     )
   }
 
@@ -75,7 +75,7 @@ export class ThrottledQueue {
     rateLimitFactor = 1,
     ...adapter
   }: UpdateQueueAdapterContext): Promise<URLSearchParams> {
-    if (!Number.isFinite(this.throttleMs)) {
+    if (!Number.isFinite(this.timeMs)) {
       debug('[nuqs queue] Skipping flush due to throttleMs=Infinity')
       return Promise.resolve(getSearchParamsSnapshot())
     }
@@ -107,14 +107,14 @@ export class ThrottledQueue {
     const runOnNextTick = () => {
       const now = performance.now()
       const timeSinceLastFlush = now - this.lastFlushedAt
-      const throttleMs = this.throttleMs
+      const timeMs = this.timeMs
       const flushInMs =
         rateLimitFactor *
-        Math.max(0, Math.min(throttleMs, throttleMs - timeSinceLastFlush))
+        Math.max(0, Math.min(timeMs, timeMs - timeSinceLastFlush))
       debug(
         `[nuqs queue] Scheduling flush in %f ms. Throttled at %f ms (x%f)`,
         flushInMs,
-        throttleMs,
+        timeMs,
         rateLimitFactor
       )
       if (flushInMs === 0) {
@@ -135,7 +135,7 @@ export class ThrottledQueue {
     this.options.history = 'replace'
     this.options.scroll = false
     this.options.shallow = true
-    this.throttleMs = defaultRateLimit.timeMs
+    this.timeMs = defaultRateLimit.timeMs
   }
 
   applyPendingUpdates(