tanstack-url-state 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 B0redDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# tanstack-url-state
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+URL search params as React state for [TanStack Router](https://tanstack.com/router), in the style of [nuqs](https://nuqs.dev). The route's own `validateSearch` is the parser, so every key is typed once, links stay type-safe, and there is no second set of parsers to keep in sync.
+
+```sh
+bun add tanstack-url-state
+```
+
+Peer dependencies: `@tanstack/react-router` ^1.170, `react` ≥ 18, `zod` ^4.
+
+## Declare the params on the route
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { searchParams } from "tanstack-url-state";
+import { z } from "zod";
+
+export const Route = createFileRoute("/settings")({
+  ...searchParams({
+    section: z.enum(["models", "services"]).default("models").catch("models"),
+    q: z.string().optional().catch(undefined),
+  }),
+  component: SettingsRoute,
+});
+```
+
+`searchParams` returns `validateSearch` plus a middleware that keeps values equal to their default out of the URL (`/settings`, not `/settings?section=models`). Every key must be optional or have a `.default()`; `.catch()` turns a hand-edited bad value into the fallback instead of an error.
+
+## Read and write
+
+```tsx
+import { useSearchState, useSearchStates } from "tanstack-url-state";
+
+function SettingsRoute() {
+  const [section, setSection] = useSearchState(Route, "section");
+  const [filters, setFilters] = useSearchStates(Route, ["q", "section"]);
+
+  setSection("services");
+  setFilters({ q: "rome" }, { debounce: 300 });
+  setFilters((prev) => ({ q: prev.q ? null : "rome" }));
+}
+```
+
+- **Optimistic:** every hook reading a key sees the new value at once, before the URL changes.
+- **Batched:** updates in the same tick (or inside a `debounce` window) become one navigation.
+- **Removal:** `null`, `undefined`, `""` and `[]` remove the key, which then reads as its default.
+- **Setters return a promise** that resolves once the URL holds the update.
+
+Options, per hook or per call:
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `history` | `"replace"` | `"push"` adds a history entry: use it for real navigation steps. |
+| `scroll` | `false` | Scroll to the top after the update. |
+| `debounce` | `0` | Milliseconds to wait before writing the URL; the state updates immediately. |
+
+`searchDefaults(schema)` returns the defaulted keys of a zod object schema, if you need them elsewhere.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { searchDefaults, searchParams } from "./search-params.js";
+export { useSearchState, useSearchStates } from "./use-search-state.js";
+export type { SearchRoute, SearchStateOptions } from "./use-search-state.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { searchDefaults, searchParams } from "./search-params.js";
+export { useSearchState, useSearchStates } from "./use-search-state.js";

package/dist/search-params.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/** Values a route search schema falls back to when a key is missing from the URL. */
+export declare function searchDefaults(schema: unknown): Record<string, unknown>;
+/**
+ * Route search options from a zod shape: `validateSearch` (parsing + types) and a middleware
+ * that drops values equal to their default from the URL. Spread into `createFileRoute(...)({ ... })`.
+ * Every key must be optional or defaulted. Bad URL values should `.catch()` to a fallback.
+ */
+export declare function searchParams<T extends z.core.$ZodLooseShape>(shape: T): {
+    validateSearch: z.ZodObject<{ -readonly [P in keyof T]: T[P]; }, z.core.$strip>;
+    search: {
+        middlewares: import("@tanstack/react-router").SearchMiddleware<z.core.$InferObjectOutput<{ -readonly [P in keyof T]: T[P]; }, {}>>[];
+    };
+};

package/dist/search-params.js

@@ -0,0 +1,30 @@
+import { stripSearchParams } from "@tanstack/react-router";
+import { z } from "zod";
+const defaultsCache = new WeakMap();
+/** Values a route search schema falls back to when a key is missing from the URL. */
+export function searchDefaults(schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        return {};
+    }
+    let defaults = defaultsCache.get(schema);
+    if (!defaults) {
+        // zod 4 `.partial()` keeps `.default()`s, so this yields exactly the defaulted keys.
+        defaults = Object.fromEntries(Object.entries(schema.partial().parse({})).filter(([, value]) => value !== undefined));
+        defaultsCache.set(schema, defaults);
+    }
+    return defaults;
+}
+/**
+ * Route search options from a zod shape: `validateSearch` (parsing + types) and a middleware
+ * that drops values equal to their default from the URL. Spread into `createFileRoute(...)({ ... })`.
+ * Every key must be optional or defaulted. Bad URL values should `.catch()` to a fallback.
+ */
+export function searchParams(shape) {
+    const schema = z.object(shape);
+    return {
+        validateSearch: schema,
+        search: {
+            middlewares: [stripSearchParams(searchDefaults(schema))],
+        },
+    };
+}

package/dist/use-search-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * nuqs-style URL state on top of TanStack Router: the route's `validateSearch` is the parser,
+ * these hooks are `useQueryState`/`useQueryStates`.
+ *
+ * - Updates are optimistic: every hook reading a key sees the new value immediately.
+ * - Updates in the same tick (or within a `debounce` window) are merged into one navigation.
+ * - `null`, `undefined`, `""` and `[]` remove the key, so it reads as the schema default.
+ * - Defaults are kept out of the URL by `searchParams()`' middleware.
+ */
+/** A file route (`Route`) whose `validateSearch` types the keys. */
+export interface SearchRoute {
+    id: string;
+    options: {
+        validateSearch?: unknown;
+    };
+    types: {
+        fullSearchSchema: object;
+    };
+}
+type SearchOf<R extends SearchRoute> = R["types"]["fullSearchSchema"];
+type Patch<S, K extends keyof S> = {
+    [P in K]?: S[P] | null;
+};
+export interface SearchStateOptions {
+    /** `push` adds a history entry; default `replace`. */
+    history?: "push" | "replace";
+    /** Scroll to top after the update; default `false`. */
+    scroll?: boolean;
+    /** Delay the URL write (ms) while still updating state immediately; restarts on each update. */
+    debounce?: number;
+}
+/** Several search params as one state object; one navigation per update. */
+export declare function useSearchStates<R extends SearchRoute, const K extends keyof SearchOf<R> & string>(route: R, keys: readonly K[], options?: SearchStateOptions): readonly [Pick<SearchOf<R>, K>, (update: Patch<SearchOf<R>, K> | ((prev: Pick<SearchOf<R>, K>) => Patch<SearchOf<R>, K>), callOptions?: SearchStateOptions) => Promise<void>];
+/** One search param as `[value, setValue]`, like `useState`. */
+export declare function useSearchState<R extends SearchRoute, const K extends keyof SearchOf<R> & string>(route: R, key: K, options?: SearchStateOptions): readonly [Pick<SearchOf<R>, K>[K], (update: SearchOf<R>[K] | null | ((prev: SearchOf<R>[K]) => SearchOf<R>[K] | null), callOptions?: SearchStateOptions) => Promise<void>];
+export {};

package/dist/use-search-state.js

@@ -0,0 +1,129 @@
+import { useRouter, useSearch } from "@tanstack/react-router";
+import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+import { searchDefaults } from "./search-params.js";
+// One queue per app: search params are global to the URL. Only written by client events, never during SSR.
+const EMPTY = {};
+let pending = EMPTY;
+let queued = null;
+let timer;
+let nextFlush = null;
+let resolveFlush;
+const listeners = new Set();
+const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+};
+const emit = () => {
+    for (const listener of listeners) {
+        listener();
+    }
+};
+const isEmpty = (value) => value === null || value === undefined || value === "" || (Array.isArray(value) && value.length === 0);
+async function flush() {
+    timer = undefined;
+    const sent = pending;
+    const job = queued;
+    const resolve = resolveFlush;
+    queued = null;
+    nextFlush = null;
+    try {
+        if (job) {
+            const patch = Object.fromEntries(Object.entries(sent).map(([key, value]) => [key, isEmpty(value) ? undefined : value]));
+            await job.router.navigate({
+                to: ".",
+                replace: !job.push,
+                resetScroll: job.scroll,
+                search: (prev) => ({ ...prev, ...patch }),
+            });
+        }
+    }
+    finally {
+        // The URL now owns what was sent; keep only values set again while navigating.
+        const rest = Object.fromEntries(Object.entries(pending).filter(([key, value]) => sent[key] !== value));
+        pending = Object.keys(rest).length > 0 ? rest : EMPTY;
+        emit();
+        resolve?.();
+    }
+}
+function enqueue(router, patch, options) {
+    pending = { ...pending, ...patch };
+    queued = {
+        router,
+        push: queued?.push === true || options.history === "push",
+        scroll: queued?.scroll === true || options.scroll === true,
+    };
+    nextFlush ??= new Promise((resolve) => {
+        resolveFlush = resolve;
+    });
+    emit();
+    clearTimeout(timer);
+    // An immediate update also writes any debounced one still waiting.
+    timer = setTimeout(flush, options.debounce ?? 0);
+    return nextFlush;
+}
+function pick(source, keys) {
+    const out = {};
+    for (const key of keys) {
+        if (key in source) {
+            out[key] = source[key];
+        }
+    }
+    return out;
+}
+/** Pending removals read as the schema default, like a missing URL key. */
+function withDefaults(values, defaults) {
+    const out = {};
+    for (const [key, value] of Object.entries(values)) {
+        out[key] = isEmpty(value) ? defaults[key] : value;
+    }
+    return out;
+}
+/** Several search params as one state object; one navigation per update. */
+export function useSearchStates(route, keys, options = {}) {
+    const router = useRouter();
+    const defaults = searchDefaults(route.options.validateSearch);
+    // Callers pass inline arrays; key the memos on the names, not the array identity.
+    const keysKey = keys.join("\0");
+    const stableKeys = useMemo(() => keysKey.split("\0"), [keysKey]);
+    // Re-renders only when one of these keys changes in the URL…
+    const fromUrl = useSearch({
+        strict: false,
+        structuralSharing: true,
+        select: (search) => pick(search, stableKeys),
+    });
+    // …or in the pending queue (only the keys that have a pending value).
+    const lastPending = useRef(EMPTY);
+    const pendingValues = useSyncExternalStore(subscribe, () => {
+        const last = lastPending.current;
+        const next = pick(pending, stableKeys);
+        const names = Object.keys(next);
+        const same = names.length === Object.keys(last).length && names.every((key) => key in last && last[key] === next[key]);
+        if (!same) {
+            lastPending.current = next;
+        }
+        return lastPending.current;
+    }, () => EMPTY);
+    const values = useMemo(() => ({ ...fromUrl, ...withDefaults(pendingValues, defaults) }), [fromUrl, pendingValues, defaults]);
+    const { history, scroll, debounce } = options;
+    const set = useCallback((update, callOptions) => {
+        // Functional updates chain on values queued earlier in the same tick.
+        const prev = { ...values, ...withDefaults(pick(pending, stableKeys), defaults) };
+        return enqueue(router, typeof update === "function" ? update(prev) : update, {
+            history,
+            scroll,
+            debounce,
+            ...callOptions,
+        });
+    }, [router, values, stableKeys, defaults, history, scroll, debounce]);
+    return [values, set];
+}
+/** One search param as `[value, setValue]`, like `useState`. */
+export function useSearchState(route, key, options) {
+    const [values, setValues] = useSearchStates(route, [key], options);
+    const set = useCallback((update, callOptions) => setValues((prev) => ({
+        [key]: typeof update === "function" ? update(prev[key]) : update,
+    }), callOptions), [key, setValues]);
+    return [values[key], set];
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "tanstack-url-state",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "nuqs-style URL search state for TanStack Router, typed by each route's validateSearch",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/B0redDev/tanstack-url-state.git"
+  },
+  "keywords": ["tanstack-router", "search-params", "url-state", "react", "zod"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": "^1.170.0",
+    "react": ">=18",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.14.6",
+    "@tanstack/react-router": "^1.170.41",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2",
+    "zod": "^4.6.5"
+  }
+}