Data Table nuqs Store Adapter

1/**
2 * nuqs Adapter for BYOS
3 *
4 * This adapter uses nuqs for URL-based state management.
5 * It supports SSR and URL synchronization.
6 */
7 
8"use client";
9 
10import { useQueryStates, type ParserBuilder } from "nuqs";
11import { useEffect, useMemo, useRef } from "react";
12import type { InternalStoreAdapter } from "../../adapter/types";
13import { getSchemaDefaults, validateState } from "../../schema/serialization";
14import type { SchemaDefinition, StoreSnapshot } from "../../schema/types";
15import { schemaToNuqsParsers } from "./parser-bridge";
16import type { NuqsAdapterOptions } from "./types";
17 
18export type { NuqsAdapterOptions } from "./types";
19 
20/**
21 * Create a nuqs adapter for URL-based state management
22 *
23 * @example
24 * ```typescript
25 * const schema = createSchema({
26 *   regions: field.array(field.string()).default([]),
27 *   host: field.string(),
28 * });
29 *
30 * function MyComponent() {
31 *   const adapter = useNuqsAdapter(schema.definition, { id: 'my-table' });
32 *   return (
33 *     <DataTableStoreProvider adapter={adapter}>
34 *       <DataTable />
35 *     </DataTableStoreProvider>
36 *   );
37 * }
38 * ```
39 */
40export function useNuqsAdapter<T extends Record<string, unknown>>(
41  schema: SchemaDefinition,
42  options: NuqsAdapterOptions<T>,
43): InternalStoreAdapter<T> {
44  const {
45    id,
46    initialState,
47    shallow = true,
48    history = "push",
49    scroll = false,
50    throttleMs = 50,
51  } = options;
52 
53  const parsers = useMemo(() => schemaToNuqsParsers(schema), [schema]);
54  const defaults = useMemo(() => getSchemaDefaults(schema) as T, [schema]);
55 
56  // Use nuqs hook
57  const [nuqsState, setNuqsState] = useQueryStates(
58    parsers as Record<string, ParserBuilder<unknown>>,
59    {
60      shallow,
61      history,
62      scroll,
63      throttleMs,
64    },
65  );
66 
67  // Store state and version
68  const stateRef = useRef<T>(defaults);
69  const versionRef = useRef(0);
70  const listenersRef = useRef(new Set<() => void>());
71  const pausedRef = useRef(false);
72  const pendingStateRef = useRef<Partial<T> | null>(null);
73 
74  // Cache server snapshot to avoid infinite loop with useSyncExternalStore
75  const serverSnapshotRef = useRef<StoreSnapshot<T>>({
76    state: { ...defaults, ...initialState } as T,
77    version: 0,
78  });
79 
80  // Compute merged state once per render so validateState isn't called twice
81  const currentState = useMemo(() => {
82    const validated = validateState(schema, nuqsState) as T;
83    return { ...defaults, ...initialState, ...validated } as T;
84// … truncated