feat: global default value store

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

@@ -2,6 +2,7 @@ import {
   createContext,
   createElement,
   useContext,
+  useRef,
   type Context,
   type ProviderProps,
   type ReactElement,
@@ -30,6 +31,10 @@ export const context: Context<AdapterContext> = createContext<AdapterContext>({
 })
 context.displayName = 'NuqsAdapterContext'
 
+export type DefaultValueStore = Record<string, unknown>
+export const defaultValueContext: Context<DefaultValueStore | null> =
+  createContext<DefaultValueStore | null>(null)
+
 declare global {
   interface Window {
     __NuqsAdapterContext?: typeof context
@@ -60,15 +65,34 @@ export type AdapterProvider = (
 export function createAdapterProvider(
   useAdapter: UseAdapterHook
 ): AdapterProvider {
-  return ({ children, defaultOptions, processUrlSearchParams, ...props }) =>
-    createElement(
+  return function NuqsAdapterProvider({
+    children,
+    defaultOptions,
+    processUrlSearchParams,
+    ...props
+  }) {
+    const defaultValueStore = useRef({})
+    return createElement(
       context.Provider,
       {
         ...props,
         value: { useAdapter, defaultOptions, processUrlSearchParams }
       },
-      children
+      createElement(
+        defaultValueContext.Provider,
+        { value: defaultValueStore.current },
+        children
+      )
     )
+  }
+}
+
+export function useDefaultValueStore(): DefaultValueStore {
+  const context = useContext(defaultValueContext)
+  if (!context) {
+    throw new Error('[nuqs] No DefaultValueContext found')
+  }
+  return context
 }
 
 export function useAdapter(watchKeys: string[]): AdapterInterface {

packages/nuqs/src/adapters/testing.ts

@@ -9,7 +9,7 @@ import {
 } from 'react'
 import { resetQueues } from '../lib/queues/reset'
 import { renderQueryString } from './custom'
-import { context, type AdapterProps } from './lib/context'
+import { context, type AdapterProps, defaultValueContext } from './lib/context'
 import type { AdapterInterface, AdapterOptions } from './lib/defs'
 
 export type UrlUpdateEvent = {
@@ -131,10 +131,15 @@ export function NuqsTestingAdapter({
     getSearchParamsSnapshot,
     rateLimitFactor
   })
+  const defaultValueStore = useRef({})
   return createElement(
     context.Provider,
     { value: { useAdapter, defaultOptions, processUrlSearchParams } },
-    children
+    createElement(
+      defaultValueContext.Provider,
+      { value: defaultValueStore.current },
+      children
+    )
   )
 }
 

packages/nuqs/src/useQueryState.test.tsx

@@ -19,6 +19,7 @@ import {
   parseAsString
 } from './parsers'
 import { useQueryState } from './useQueryState'
+import { useQueryStates } from './useQueryStates'
 
 describe('useQueryState: referential equality', () => {
   const defaults = {
@@ -109,7 +110,7 @@ describe('useQueryState: referential equality', () => {
     expect(result.current.str[0]).toBe('foo')
     rerender({ defaultValue: 'b' })
     const { str, obj, arr } = result.current
-    expect(str[0]).toBe('b')
+    expect(str[0]).toBe('foo')
     expect(obj[0]).toBe(defaults.obj)
     expect(arr[0]).toBe(defaults.arr)
     expect(arr[0][0]).toBe(defaults.arr[0])
@@ -129,6 +130,40 @@ describe('useQueryState: referential equality', () => {
   })
 })
 
+describe('useQueryState: defaultValue', () => {
+  it('should read the same default value for multiple usages of the same parser', () => {
+    function TestComponent({
+      id,
+      defaultValue
+    }: {
+      id: string
+      defaultValue: number
+    }) {
+      const [value] = useQueryState(
+        'a',
+        parseAsInteger.withDefault(defaultValue)
+      )
+
+      return (
+        <div>
+          {id} value: {value}
+        </div>
+      )
+    }
+    const result = render(
+      <div>
+        <TestComponent id="first" defaultValue={5} />
+        <TestComponent id="second" defaultValue={23} />
+      </div>,
+      {
+        wrapper: withNuqsTestingAdapter()
+      }
+    )
+    expect(result.getByText('first value: 5')).toBeInTheDocument()
+    expect(result.getByText('second value: 5')).toBeInTheDocument()
+  })
+})
+
 describe('useQueryState: clearOnDefault', () => {
   it('honors clearOnDefault: true by default', async () => {
     const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()

packages/nuqs/src/useQueryStates.test.tsx

@@ -192,7 +192,7 @@ describe('useQueryStates: referential equality', () => {
     expect(result.current[0].str).toBe('foo')
     rerender({ defaultValue: 'b' })
     const [state] = result.current
-    expect(state.str).toBe('b')
+    expect(state.str).toBe('foo')
     expect(state.obj).toBe(defaults.obj)
     expect(state.arr).toBe(defaults.arr)
     expect(state.arr[0]).toBe(defaults.arr[0])
@@ -266,6 +266,39 @@ describe('useQueryStates: urlKeys remapping', () => {
   })
 })
 
+describe('useQueryStates: defaultValue', () => {
+  it('should read the same default value for multiple usages of the same parser', () => {
+    function TestComponent({
+      id,
+      defaultValue
+    }: {
+      id: string
+      defaultValue: number
+    }) {
+      const [value] = useQueryStates({
+        a: parseAsInteger.withDefault(defaultValue)
+      })
+
+      return (
+        <div>
+          {id} value: {value.a}
+        </div>
+      )
+    }
+    const result = render(
+      <div>
+        <TestComponent id="first" defaultValue={5} />
+        <TestComponent id="second" defaultValue={23} />
+      </div>,
+      {
+        wrapper: withNuqsTestingAdapter()
+      }
+    )
+    expect(result.getByText('first value: 5')).toBeInTheDocument()
+    expect(result.getByText('second value: 5')).toBeInTheDocument()
+  })
+})
+
 describe('useQueryStates: clearOnDefault', () => {
   it('honors clearOnDefault: true by default', async () => {
     const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()

packages/nuqs/src/useQueryStates.ts

@@ -1,8 +1,10 @@
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
 import {
+  type DefaultValueStore,
   useAdapter,
   useAdapterDefaultOptions,
-  useAdapterProcessUrlSearchParams
+  useAdapterProcessUrlSearchParams,
+  useDefaultValueStore
 } from './adapters/lib/context'
 import type { Nullable, Options, UrlKeys } from './defs'
 import { compareQuery } from './lib/compare'
@@ -76,6 +78,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
   const hookId = useId()
   const defaultOptions = useAdapterDefaultOptions()
   const processUrlSearchParams = useAdapterProcessUrlSearchParams()
+  const defaultValueStore = useDefaultValueStore()
 
   const {
     history = 'replace',
@@ -100,17 +103,14 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
   const adapter = useAdapter(Object.values(resolvedUrlKeys))
   const initialSearchParams = adapter.searchParams
   const queryRef = useRef<Record<string, Query | null>>({})
-  const defaultValues = useMemo(
-    () =>
-      Object.fromEntries(
-        Object.keys(keyMap).map(key => [key, keyMap[key]!.defaultValue ?? null])
-      ) as Values<KeyMap>,
-    [
-      Object.values(keyMap)
-        .map(({ defaultValue }) => defaultValue)
-        .join(',')
-    ]
-  )
+
+  // lazily initialize defaultValues in store
+  for (const [stateKey, { defaultValue }] of Object.entries(keyMap)) {
+    if (!(stateKey in defaultValueStore)) {
+      defaultValueStore[stateKey] = defaultValue ?? null
+    }
+  }
+
   const queuedQueries = debounceController.useQueuedQueries(
     Object.values(resolvedUrlKeys)
   )
@@ -191,7 +191,6 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
   useEffect(() => {
     function updateInternalState(state: V) {
       debug('[nuq+ %s `%s`] updateInternalState %O', hookId, stateKeys, state)
-      stateRef.current = state
       setInternalState(state)
     }
     const handlers = Object.keys(keyMap).reduce(
@@ -200,7 +199,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
           state,
           query
         }: CrossHookSyncPayload) => {
-          const { defaultValue } = keyMap[stateKey]!
+          const defaultValue = defaultValueStore[stateKey]
           const urlKey = resolvedUrlKeys[stateKey]!
           // Note: cannot mutate in-place, the object ref must change
           // for the subsequent setState to pick it up.
@@ -257,7 +256,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       const newState: Partial<Nullable<KeyMap>> =
         typeof stateUpdater === 'function'
           ? (stateUpdater(
-              applyDefaultValues(stateRef.current, defaultValues)
+              applyDefaultValues(stateRef.current, defaultValueStore)
             ) ?? nullMap)
           : (stateUpdater ?? nullMap)
       debug('[nuq+ %s `%s`] setState: %O', hookId, stateKeys, newState)
@@ -358,13 +357,17 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       adapter.getSearchParamsSnapshot,
       adapter.rateLimitFactor,
       processUrlSearchParams,
-      defaultValues
+      defaultValueStore
     ]
   )
 
   const outputState = useMemo(
-    () => applyDefaultValues(internalState, defaultValues),
-    [internalState, defaultValues]
+    () =>
+      applyDefaultValues(
+        internalState,
+        defaultValueStore as Partial<Values<KeyMap>>
+      ),
+    [internalState, defaultValueStore]
   )
   return [outputState, update]
 }
@@ -430,7 +433,7 @@ function parseMap<KeyMap extends UseQueryStatesKeysMap>(
 
 function applyDefaultValues<KeyMap extends UseQueryStatesKeysMap>(
   state: NullableValues<KeyMap>,
-  defaults: Partial<Values<KeyMap>>
+  defaults: DefaultValueStore
 ) {
   return Object.fromEntries(
     Object.keys(state).map(key => [key, state[key] ?? defaults[key] ?? null])