ref: Reorganise lib code

- Move shared code into src/lib, leaving only features at the top level
- Move the throttle queue into a class to help with testing &
  multi-storage support later
- Add stubs for debounce queue

Author: franky47

packages/nuqs/src/adapters/custom.ts

@@ -1,4 +1,4 @@
-export { renderQueryString } from '../url-encoding'
+export { renderQueryString } from '../lib/url-encoding'
 export {
   createAdapterProvider as unstable_createAdapterProvider,
   type AdapterContext as unstable_AdapterContext

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

@@ -1,5 +1,5 @@
 import { createContext, createElement, useContext, type ReactNode } from 'react'
-import { error } from '../../errors'
+import { error } from '../../lib/errors'
 import type { UseAdapterHook } from './defs'
 
 export type AdapterContext = {

packages/nuqs/src/adapters/lib/patch-history.ts

@@ -1,6 +1,6 @@
 import type { Emitter } from 'mitt'
-import { debug } from '../../debug'
-import { error } from '../../errors'
+import { debug } from '../../lib/debug'
+import { error } from '../../lib/errors'
 
 export type SearchParamsSyncEmitter = Emitter<{ update: URLSearchParams }>
 

packages/nuqs/src/adapters/lib/react-router.ts

@@ -1,6 +1,6 @@
 import mitt from 'mitt'
 import { startTransition, useCallback, useEffect, useState } from 'react'
-import { renderQueryString } from '../../url-encoding'
+import { renderQueryString } from '../../lib/url-encoding'
 import { createAdapterProvider } from './context'
 import type { AdapterInterface, AdapterOptions } from './defs'
 import {

packages/nuqs/src/adapters/next/impl.app.ts

@@ -1,6 +1,6 @@
 import { useRouter, useSearchParams } from 'next/navigation'
 import { startTransition, useCallback, useOptimistic } from 'react'
-import { debug } from '../../debug'
+import { debug } from '../../lib/debug'
 import type { AdapterInterface, UpdateUrlFunction } from '../lib/defs'
 import { renderURL } from './shared'
 

packages/nuqs/src/adapters/next/impl.pages.ts

@@ -1,7 +1,7 @@
 import { useSearchParams } from 'next/navigation.js'
 import type { NextRouter } from 'next/router'
 import { useCallback } from 'react'
-import { debug } from '../../debug'
+import { debug } from '../../lib/debug'
 import { createAdapterProvider } from '../lib/context'
 import type { AdapterInterface, UpdateUrlFunction } from '../lib/defs'
 import { renderURL } from './shared'

packages/nuqs/src/adapters/next/shared.ts

@@ -1,4 +1,4 @@
-import { renderQueryString } from '../../url-encoding'
+import { renderQueryString } from '../../lib/url-encoding'
 
 export function renderURL(base: string, search: URLSearchParams) {
   const hashlessBase = base.split('#')[0] ?? ''

packages/nuqs/src/adapters/react.ts

@@ -1,8 +1,8 @@
 import mitt from 'mitt'
 import { useEffect, useState } from 'react'
-import { renderQueryString } from '../url-encoding'
+import { renderQueryString } from '../lib/url-encoding'
 import { createAdapterProvider } from './lib/context'
-import type { AdapterOptions } from './lib/defs'
+import type { AdapterInterface, AdapterOptions } from './lib/defs'
 import { patchHistory, type SearchParamsSyncEmitter } from './lib/patch-history'
 
 const emitter: SearchParamsSyncEmitter = mitt()
@@ -16,7 +16,7 @@ function updateUrl(search: URLSearchParams, options: AdapterOptions) {
   emitter.emit('update', search)
 }
 
-function useNuqsReactAdapter() {
+function useNuqsReactAdapter(): AdapterInterface {
   const [searchParams, setSearchParams] = useState(() => {
     if (typeof location === 'undefined') {
       return new URLSearchParams()

packages/nuqs/src/adapters/testing.ts

@@ -1,6 +1,6 @@
 import { createElement, type ReactNode } from 'react'
-import { resetQueue } from '../update-queue'
-import { renderQueryString } from '../url-encoding'
+import { globalThrottleQueue } from '../lib/queues/throttle'
+import { renderQueryString } from '../lib/url-encoding'
 import { context } from './lib/context'
 import type { AdapterInterface, AdapterOptions } from './lib/defs'
 
@@ -25,7 +25,7 @@ export function NuqsTestingAdapter({
   ...props
 }: TestingAdapterProps) {
   if (resetUrlUpdateQueueOnMount) {
-    resetQueue()
+    globalThrottleQueue.reset()
   }
   const useAdapter = (): AdapterInterface => ({
     searchParams: new URLSearchParams(props.searchParams),

packages/nuqs/src/cache.ts

@@ -1,7 +1,7 @@
 // @ts-ignore
 import { cache } from 'react'
 import type { SearchParams, UrlKeys } from './defs'
-import { error } from './errors'
+import { error } from './lib/errors'
 import { createLoader } from './loader'
 import type { inferParserType, ParserMap } from './parsers'
 

packages/nuqs/src/update-queue.test.ts packages/nuqs/src/lib/compose.test.ts

@@ -1,13 +1,13 @@
-import { describe, expect, test, vi } from 'vitest'
-import { compose } from './update-queue'
+import { describe, expect, it, vi } from 'vitest'
+import { compose } from './compose'
 
-describe('update-queue/compose', () => {
-  test('empty array', () => {
+describe('queues: compose', () => {
+  it('handles an empty array', () => {
     const final = vi.fn()
     compose([], final)
     expect(final).toHaveBeenCalledOnce()
   })
-  test('one item', () => {
+  it('handles one item, calling it before the final', () => {
     const a = vi
       .fn()
       .mockImplementation(x => x())
@@ -20,7 +20,7 @@ describe('update-queue/compose', () => {
       final.mock.invocationCallOrder[0]!
     )
   })
-  test('several items', () => {
+  it('composes several items, calling them in order', () => {
     const a = vi.fn().mockImplementation(x => x())
     const b = vi.fn().mockImplementation(x => x())
     const c = vi.fn().mockImplementation(x => x())

packages/nuqs/src/lib/compose.ts

@@ -0,0 +1,16 @@
+export function compose(
+  fns: React.TransitionStartFunction[],
+  final: () => void
+) {
+  const recursiveCompose = (index: number) => {
+    if (index === fns.length) {
+      return final()
+    }
+    const fn = fns[index]
+    if (!fn) {
+      throw new Error('Invalid transition function')
+    }
+    fn(() => recursiveCompose(index + 1))
+  }
+  recursiveCompose(0)
+}

packages/nuqs/src/debug.test.ts packages/nuqs/src/lib/debug.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from 'vitest'
+import { DebouncedPromiseQueue } from './debounce'
+
+describe('queues: DebouncedPromiseQueue', () => {
+  it('creates a queue for a given key', () => {
+    vi.useFakeTimers()
+    const spy = vi.fn()
+    const queue = new DebouncedPromiseQueue('key', spy)
+    queue.push('value', 100)
+    vi.advanceTimersToNextTimer()
+    expect(spy).toHaveBeenCalledExactlyOnceWith('key', 'value')
+  })
+  it('debounces the queue', () => {
+    vi.useFakeTimers()
+    const spy = vi.fn()
+    const queue = new DebouncedPromiseQueue('key', spy)
+    queue.push('a', 100)
+    queue.push('b', 100)
+    queue.push('c', 100)
+    vi.advanceTimersToNextTimer()
+    expect(spy).toHaveBeenCalledExactlyOnceWith('key', 'c')
+  })
+  it('returns a stable promise to the next time the callback is called', async () => {
+    vi.useFakeTimers()
+    const queue = new DebouncedPromiseQueue('key', () => 'output')
+    const p1 = queue.push('value', 100)
+    const p2 = queue.push('value', 100)
+    expect(p1).toBe(p2)
+    vi.advanceTimersToNextTimer()
+    await expect(p1).resolves.toBe('output')
+  })
+  it('returns a new Promise once the callback is called', async () => {
+    vi.useFakeTimers()
+    let count = 0
+    const queue = new DebouncedPromiseQueue('key', () => count++)
+    const p1 = queue.push('value', 100)
+    vi.advanceTimersToNextTimer()
+    await expect(p1).resolves.toBe(0)
+    const p2 = queue.push('value', 100)
+    expect(p2).not.toBe(p1)
+    vi.advanceTimersToNextTimer()
+    await expect(p2).resolves.toBe(1)
+  })
+})

packages/nuqs/src/debug.ts packages/nuqs/src/lib/debug.ts

@@ -0,0 +1,37 @@
+import { timeout } from '../timeout'
+import { withResolvers } from '../with-resolvers'
+
+export class DebouncedPromiseQueue<ValueType, OutputType> {
+  key: string
+  callback: (key: string, value: ValueType) => OutputType
+  resolvers = withResolvers<OutputType>()
+  controller = new AbortController()
+
+  constructor(
+    key: string,
+    callback: (key: string, value: ValueType) => OutputType
+  ) {
+    this.key = key
+    this.callback = callback
+  }
+
+  public push(value: ValueType, timeMs: number) {
+    this.controller.abort()
+    this.controller = new AbortController()
+    timeout(
+      () => {
+        try {
+          const output = this.callback(this.key, value)
+          this.resolvers.resolve(output)
+        } catch (error) {
+          this.resolvers.reject(error)
+        } finally {
+          this.resolvers = withResolvers<OutputType>()
+        }
+      },
+      timeMs,
+      this.controller.signal
+    )
+    return this.resolvers.promise
+  }
+}