ref: Carry state & serialized query across hook sync

So that internal refs can be synced together without calling the serializer
on each reception site.

Author: franky47

Diff for: packages/nuqs/src/sync.ts

@@ -12,11 +12,15 @@ export type QueryUpdateNotificationArgs = {
   search: URLSearchParams
   source: QueryUpdateSource
 }
+export type CrossHookSyncPayload = {
+  state: any
+  query: string | null
+}
 
 type EventMap = {
   [SYNC_EVENT_KEY]: URLSearchParams
   [NOTIFY_EVENT_KEY]: QueryUpdateNotificationArgs
-  [key: string]: any
+  [key: string]: CrossHookSyncPayload
 }
 
 export const emitter = Mitt<EventMap>()

Diff for: packages/nuqs/src/useQueryState.ts

@@ -3,7 +3,7 @@ import React from 'react'
 import { debug } from './debug'
 import type { Options } from './defs'
 import type { Parser } from './parsers'
-import { SYNC_EVENT_KEY, emitter } from './sync'
+import { SYNC_EVENT_KEY, emitter, type CrossHookSyncPayload } from './sync'
 import {
   FLUSH_RATE_LIMIT_MS,
   enqueueQueryStringUpdate,
@@ -225,12 +225,12 @@ export function useQueryState<T = string>(
   const router = useRouter()
   // Not reactive, but available on the server and on page load
   const initialSearchParams = useSearchParams()
-  const valueRef = React.useRef<string | null>(null)
+  const queryRef = React.useRef<string | null>(null)
   const [internalState, setInternalState] = React.useState<T | null>(() => {
     const queueValue = getQueuedValue(key)
     const urlValue = initialSearchParams?.get(key) ?? null
     const value = queueValue ?? urlValue
-    valueRef.current = value
+    queryRef.current = value
     return value === null ? null : safeParse(parse, value, key)
   })
   const stateRef = React.useRef(internalState)
@@ -247,34 +247,33 @@ export function useQueryState<T = string>(
     if (window.next?.version !== '14.0.3') {
       return
     }
-    const value = initialSearchParams.get(key) ?? null
-    if (value === valueRef.current) {
+    const query = initialSearchParams.get(key) ?? null
+    if (query === queryRef.current) {
       return
     }
-    const state = value === null ? null : safeParse(parse, value, key)
+    const state = query === null ? null : safeParse(parse, query, key)
     debug('[nuqs `%s`] syncFromUseSearchParams %O', key, state)
     stateRef.current = state
-    valueRef.current = value
+    queryRef.current = query
     setInternalState(state)
   }, [initialSearchParams?.get(key), key])
 
   // Sync all hooks together & with external URL changes
   React.useInsertionEffect(() => {
-    function updateInternalState(state: T | null) {
+    function updateInternalState({ state, query }: CrossHookSyncPayload) {
       debug('[nuqs `%s`] updateInternalState %O', key, state)
       stateRef.current = state
-      valueRef.current = state === null ? null : serialize(state)
+      queryRef.current = query
       setInternalState(state)
     }
     function syncFromURL(search: URLSearchParams) {
-      const value = search.get(key) ?? null
-      if (value === valueRef.current) {
+      const query = search.get(key)
+      if (query === queryRef.current) {
         return
       }
-      const state = value === null ? null : safeParse(parse, value, key)
+      const state = query === null ? null : safeParse(parse, query, key)
       debug('[nuqs `%s`] syncFromURL %O', key, state)
-      updateInternalState(state)
-      valueRef.current = value
+      updateInternalState({ state, query })
     }
     debug('[nuqs `%s`] subscribing to sync', key)
     emitter.on(SYNC_EVENT_KEY, syncFromURL)
@@ -299,16 +298,16 @@ export function useQueryState<T = string>(
       ) {
         newValue = null
       }
-      // Sync all hooks state (including this one)
-      emitter.emit(key, newValue)
-      valueRef.current = enqueueQueryStringUpdate(key, newValue, serialize, {
+      queryRef.current = enqueueQueryStringUpdate(key, newValue, serialize, {
         // Call-level options take precedence over hook declaration options.
         history: options.history ?? history,
         shallow: options.shallow ?? shallow,
         scroll: options.scroll ?? scroll,
         throttleMs: options.throttleMs ?? throttleMs,
         startTransition: options.startTransition ?? startTransition
       })
+      // Sync all hooks state (including this one)
+      emitter.emit(key, { state: newValue, query: queryRef.current })
       return scheduleFlushToURL(router)
     },
     [key, history, shallow, scroll, throttleMs, startTransition]

Diff for: packages/nuqs/src/useQueryStates.ts

@@ -7,7 +7,7 @@ import React from 'react'
 import { debug } from './debug'
 import type { Nullable, Options } from './defs'
 import type { Parser } from './parsers'
-import { SYNC_EVENT_KEY, emitter } from './sync'
+import { SYNC_EVENT_KEY, emitter, type CrossHookSyncPayload } from './sync'
 import {
   FLUSH_RATE_LIMIT_MS,
   enqueueQueryStringUpdate,
@@ -101,34 +101,34 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
     }
     const handlers = Object.keys(keyMap).reduce(
       (handlers, key) => {
-        handlers[key as keyof V] = (value: any) => {
-          const { defaultValue, serialize = String } = keyMap[key]!
+        handlers[key as keyof V] = ({ state, query }: CrossHookSyncPayload) => {
+          const { defaultValue } = keyMap[key]!
           // Note: cannot mutate in-place, the object ref must change
           // for the subsequent setState to pick it up.
           stateRef.current = {
             ...stateRef.current,
-            [key as keyof V]: value ?? defaultValue ?? null
+            [key as keyof V]: state ?? defaultValue ?? null
           }
-          queryRef.current[key] = value === null ? null : serialize(value)
+          queryRef.current[key] = query
           debug(
             '[nuq+ `%s`] Cross-hook key sync %s: %O (default: %O). Resolved: %O',
             keys,
             key,
-            value,
+            state,
             defaultValue,
             stateRef.current
           )
           updateInternalState(stateRef.current)
         }
         return handlers
       },
-      {} as Record<keyof V, any>
+      {} as Record<keyof V, (payload: CrossHookSyncPayload) => void>
     )
 
     emitter.on(SYNC_EVENT_KEY, syncFromURL)
     for (const key of Object.keys(keyMap)) {
       debug('[nuq+ `%s`] Subscribing to sync for `%s`', keys, key)
-      emitter.on(key, handlers[key])
+      emitter.on(key, handlers[key]!)
     }
     return () => {
       emitter.off(SYNC_EVENT_KEY, syncFromURL)
@@ -159,7 +159,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
         ) {
           value = null
         }
-        emitter.emit(key, value)
+
         queryRef.current[key] = enqueueQueryStringUpdate(
           key,
           value,
@@ -173,6 +173,10 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
             startTransition: options.startTransition ?? startTransition
           }
         )
+        emitter.emit(key, {
+          state: value,
+          query: queryRef.current[key] ?? null
+        })
       }
       return scheduleFlushToURL(router)
     },