feat: Abstract reading from location.search in adapters interface (#800)

This is mainly for the testing adapter to only work on the provided set
of initial search params without needing to stub/mock location.search.

But it also opens the door for adapters to define new storage locations,
like hash/fragment or even localStorage.

packages/nuqs/src/adapters/defs.ts

@@ -12,5 +12,6 @@ export type UseAdapterHook = () => AdapterInterface
 export type AdapterInterface = {
   searchParams: URLSearchParams
   updateUrl: UpdateUrlFunction
+  getSearchParamsSnapshot?: () => URLSearchParams
   rateLimitFactor?: number
 }

packages/nuqs/src/adapters/testing.ts

@@ -36,6 +36,9 @@ export function NuqsTestingAdapter({
         options
       })
     },
+    getSearchParamsSnapshot() {
+      return new URLSearchParams(props.searchParams)
+    },
     rateLimitFactor: props.rateLimitFactor ?? 0
   })
   return createElement(

packages/nuqs/src/update-queue.ts

@@ -1,4 +1,4 @@
-import type { UpdateUrlFunction } from './adapters/defs'
+import type { AdapterInterface } from './adapters/defs'
 import { debug } from './debug'
 import type { Options } from './defs'
 import { error } from './errors'
@@ -76,15 +76,19 @@ export function enqueueQueryStringUpdate<Value>(
  *
  * @returns a Promise to the URLSearchParams that have been applied.
  */
-export function scheduleFlushToURL(
-  updateUrl: UpdateUrlFunction,
-  rateLimitFactor: number
-) {
+export function scheduleFlushToURL({
+  getSearchParamsSnapshot = () => new URLSearchParams(location.search),
+  updateUrl,
+  rateLimitFactor = 1
+}: Pick<
+  AdapterInterface,
+  'updateUrl' | 'getSearchParamsSnapshot' | 'rateLimitFactor'
+>) {
   if (flushPromiseCache === null) {
     flushPromiseCache = new Promise<URLSearchParams>((resolve, reject) => {
       if (!Number.isFinite(queueOptions.throttleMs)) {
         debug('[nuqs queue] Skipping flush due to throttleMs=Infinity')
-        resolve(new URLSearchParams(location.search))
+        resolve(getSearchParamsSnapshot())
         // Let the promise be returned before clearing the cached value
         setTimeout(() => {
           flushPromiseCache = null
@@ -93,7 +97,10 @@ export function scheduleFlushToURL(
       }
       function flushNow() {
         lastFlushTimestamp = performance.now()
-        const [search, error] = flushUpdateQueue(updateUrl)
+        const [search, error] = flushUpdateQueue({
+          updateUrl,
+          getSearchParamsSnapshot
+        })
         if (error === null) {
           resolve(search)
         } else {
@@ -129,10 +136,14 @@ export function scheduleFlushToURL(
   return flushPromiseCache
 }
 
-function flushUpdateQueue(
-  updateUrl: UpdateUrlFunction
-): [URLSearchParams, null | unknown] {
-  const search = new URLSearchParams(location.search)
+function flushUpdateQueue({
+  updateUrl,
+  getSearchParamsSnapshot
+}: Pick<Required<AdapterInterface>, 'updateUrl' | 'getSearchParamsSnapshot'>): [
+  URLSearchParams,
+  null | unknown
+] {
+  const search = getSearchParamsSnapshot()
   if (updateQueue.size === 0) {
     return [search, null]
   }

packages/nuqs/src/useQueryState.ts

@@ -228,12 +228,8 @@ export function useQueryState<T = string>(
     defaultValue: undefined
   }
 ) {
-  // Not reactive, but available on the server and on page load
-  const {
-    searchParams: initialSearchParams,
-    updateUrl,
-    rateLimitFactor = 1
-  } = useAdapter()
+  const adapter = useAdapter()
+  const initialSearchParams = adapter.searchParams
   const queryRef = useRef<string | null>(initialSearchParams?.get(key) ?? null)
   const [internalState, setInternalState] = useState<T | null>(() => {
     const queuedQuery = getQueuedValue(key)
@@ -302,18 +298,9 @@ export function useQueryState<T = string>(
       })
       // Sync all hooks state (including this one)
       emitter.emit(key, { state: newValue, query: queryRef.current })
-      return scheduleFlushToURL(updateUrl, rateLimitFactor)
+      return scheduleFlushToURL(adapter)
     },
-    [
-      key,
-      history,
-      shallow,
-      scroll,
-      throttleMs,
-      startTransition,
-      updateUrl,
-      rateLimitFactor
-    ]
+    [key, history, shallow, scroll, throttleMs, startTransition, adapter]
   )
   return [internalState ?? defaultValue ?? null, update]
 }

packages/nuqs/src/useQueryStates.ts

@@ -90,11 +90,8 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       ),
     [stateKeys, urlKeys]
   )
-  const {
-    searchParams: initialSearchParams,
-    updateUrl,
-    rateLimitFactor = 1
-  } = useAdapter()
+  const adapter = useAdapter()
+  const initialSearchParams = adapter.searchParams
   const queryRef = useRef<Record<string, string | null>>({})
   // Initialise the queryRef with the initial values
   if (Object.keys(queryRef.current).length !== Object.keys(keyMap).length) {
@@ -243,7 +240,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
           query: queryRef.current[urlKey] ?? null
         })
       }
-      return scheduleFlushToURL(updateUrl, rateLimitFactor)
+      return scheduleFlushToURL(adapter)
     },
     [
       keyMap,
@@ -253,8 +250,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       throttleMs,
       startTransition,
       resolvedUrlKeys,
-      updateUrl,
-      rateLimitFactor,
+      adapter,
       defaultValues
     ]
   )