feat: Add adapter level options (#27)

* feat(adapters): add adapter level options

* fix(adapters/sveltekit): update options in SvelteKit adapter to be a getter

Author: Isaque

packages/nuqs-svelte/src/lib/adapters/svelte-kit/adapter.svelte

@@ -3,21 +3,28 @@
   import { goto, pushState, replaceState } from "$app/navigation";
   import { page } from "$app/state";
   import type { Snippet } from "svelte";
-  import type { AdapterInterface } from "../types";
+  import type { AdapterInterface, AdapterOptions } from "../types";
   import NuqsContext from "../NuqsContext.svelte";
   import { renderQueryString } from "$lib/url-encoding";
   import { SvelteURL } from "svelte/reactivity";
 
   type Props = {
     children?: Snippet;
+    /**
+     * Options defined at adapter level take precedence over options setted at hook (`useQueryState`) level.
+     */
+    options?: AdapterOptions;
   };
 
-  let { children }: Props = $props();
+  let { children, options }: Props = $props();
 
   // Using page.url directly will update the URL without invalidating the loaders dependent on it.
   let url = $derived(new SvelteURL(page.url));
 
   const adapter: AdapterInterface = {
+    get options() {
+      return options;
+    },
     updateUrl: (search, options) => {
       const { history, scroll, shallow } = options;
 

packages/nuqs-svelte/src/lib/adapters/types.ts

@@ -1,6 +1,6 @@
 import type { Options } from "$lib/types";
 
-export type AdapterOptions = Pick<Options, "history" | "scroll" | "shallow">;
+export type AdapterOptions = Pick<Options, "history" | "scroll" | "shallow" | "throttleMs">;
 
 export type UpdateUrlFunction = (
   search: URLSearchParams,
@@ -18,4 +18,5 @@ export type AdapterInterface = {
   updateUrl: UpdateUrlFunction;
   getSearchParamsSnapshot?: () => URLSearchParams;
   rateLimitFactor?: number;
+  options?: AdapterOptions;
 };

packages/nuqs-svelte/src/lib/update-queue.ts

@@ -152,6 +152,7 @@ function flushUpdateQueue({
         history: options.history,
         scroll: options.scroll,
         shallow: options.shallow,
+        throttleMs: options.throttleMs,
       });
     });
     return [search, null];

packages/nuqs-svelte/src/lib/use-query-state.svelte.ts

@@ -202,10 +202,10 @@ export function useQueryState(key: string): UseQueryStateReturn<string, undefine
 export function useQueryState<T = string>(
   key: string,
   {
-    history = "replace",
-    shallow = true,
-    scroll = false,
-    throttleMs = FLUSH_RATE_LIMIT_MS,
+    history,
+    shallow,
+    scroll,
+    throttleMs,
     parse = (x) => x as unknown as T,
     serialize = String,
     eq = (a, b) => a === b,
@@ -214,10 +214,6 @@ export function useQueryState<T = string>(
   }: Partial<UseQueryStateOptions<T>> & {
     defaultValue?: T;
   } = {
-    history: "replace",
-    scroll: false,
-    shallow: true,
-    throttleMs: 50,
     parse: (x) => x as unknown as T,
     serialize: String,
     eq: (a, b) => a === b,
@@ -306,12 +302,15 @@ export function useQueryState<T = string>(
       newValue = null;
     }
 
+    const adapterOptions = adapter.options;
+
     const query = 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,
+      // Call-level options take precedence over hook declaration options that take precedence over adapter-level options
+      history: options.history ?? history ?? adapterOptions?.history ?? "replace",
+      shallow: options.shallow ?? shallow ?? adapterOptions?.shallow ?? true,
+      scroll: options.scroll ?? scroll ?? adapterOptions?.scroll ?? false,
+      throttleMs:
+        options.throttleMs ?? throttleMs ?? adapterOptions?.throttleMs ?? FLUSH_RATE_LIMIT_MS,
     });
 
     emitter.emit(key, { state: newValue, query });

packages/nuqs-svelte/src/lib/use-query-states.svelte.ts

@@ -89,10 +89,10 @@ const defaultUrlKeys = {};
 export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
   keyMap: KeyMap,
   {
-    history = "replace",
-    scroll = false,
-    shallow = true,
-    throttleMs = FLUSH_RATE_LIMIT_MS,
+    history,
+    scroll,
+    shallow,
+    throttleMs,
     clearOnDefault = true,
     urlKeys = defaultUrlKeys,
   }: Partial<UseQueryStatesOptions<KeyMap>> = {},
@@ -228,13 +228,26 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       ) {
         value = null;
       }
+
+      const adapterOptions = adapter.options;
+
       const query = enqueueQueryStringUpdate(urlKey, value, parser.serialize ?? String, {
         // Call-level options take precedence over individual parser options
-        // which take precedence over global options
-        history: callOptions.history ?? parser.history ?? history,
-        shallow: callOptions.shallow ?? parser.shallow ?? shallow,
-        scroll: callOptions.scroll ?? parser.scroll ?? scroll,
-        throttleMs: callOptions.throttleMs ?? parser.throttleMs ?? throttleMs,
+        // which take precedence over global options that take precedence over adapter options
+        history:
+          callOptions.history ?? parser.history ?? history ?? adapterOptions?.history ?? "replace",
+
+        shallow:
+          callOptions.shallow ?? parser.shallow ?? shallow ?? adapterOptions?.shallow ?? true,
+
+        scroll: callOptions.scroll ?? parser.scroll ?? scroll ?? adapterOptions?.scroll ?? false,
+
+        throttleMs:
+          callOptions.throttleMs ??
+          parser.throttleMs ??
+          throttleMs ??
+          adapterOptions?.throttleMs ??
+          FLUSH_RATE_LIMIT_MS,
       });
       emitter.emit(urlKey, { state: value, query });
     }