tanstack-url-state 0.1.1 → 0.2.1

package/README.md

@@ -44,7 +44,7 @@ function SettingsRoute() {
 - **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.
+- **Setters return a promise** that resolves once the URL holds the update, or rejects with the router's error if the navigation fails (the state then reads the URL again).
 
 Options, per hook or per call:
 
@@ -54,8 +54,28 @@ Options, per hook or per call:
 | `scroll` | `false` | Scroll to the top after the update. |
 | `debounce` | `0` | Milliseconds to wait before writing the URL; the state updates immediately. |
 
+## Lists: pagination and sort
+
+```tsx
+import { pagination, searchParams, sortParam } from "tanstack-url-state";
+
+export const Route = createFileRoute("/videos")({
+  ...searchParams({
+    ...pagination(), // page (default 1), perPage (default 20, at most 100)
+    sort: sortParam(["title", "publishDate"], "-publishDate"), // "title" | "-title" | …
+  }),
+});
+```
+
+- `pagination({ perPage, maxPerPage })` gives `page` and `perPage` with defaults (kept out of the URL) and a fallback for junk such as `?page=abc`.
+- `sortParam(sorts, fallback?)` accepts `field` and `-field` (descending) for every field in `sorts`, which may list bare or signed names; anything else reads as `fallback`, or as no sort.
+
 `searchDefaults(schema)` returns the defaulted keys of a zod object schema, if you need them elsewhere.
 
+## Bundle size
+
+ESM only, one module per concern, `"sideEffects": false`: you ship what you import. The schema helpers (`pagination`, `sortParam`, `searchDefaults`) need only `zod`; `searchParams` adds the router's `stripSearchParams`; the hooks need React and the router and never pull the route helpers. A test bundles each group to keep it that way.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,3 +1,5 @@
-export { searchDefaults, searchParams } from "./search-params.js";
+export { pagination, searchDefaults, sortParam } from "./schema.js";
+export type { PaginationOptions, SortValue } from "./schema.js";
+export { 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

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

package/dist/schema.d.ts

@@ -0,0 +1,29 @@
+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>;
+export interface PaginationOptions {
+    /** Default page size, kept out of the URL; default 20. */
+    perPage?: number;
+    /** Largest page size a URL may ask for; default 100. */
+    maxPerPage?: number;
+}
+/**
+ * `page` (1-based) and `perPage` for a list route: spread into `searchParams({ ... })`.
+ * Both have defaults (so they stay out of the URL) and fall back to them on junk input.
+ */
+export declare function pagination({ perPage, maxPerPage }?: PaginationOptions): {
+    page: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    perPage: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+};
+/** `field` and `-field` for every field, whichever form `sorts` lists them in. */
+export type SortValue<S extends string> = S extends `-${infer F}` ? S | F : S | `-${S}`;
+/**
+ * `sort=field` / `sort=-field` (descending). Unknown fields fall back to `fallback`, or to no
+ * sort when there is none. `sorts` may list bare fields, signed ones, or both.
+ */
+export declare function sortParam<const S extends string>(sorts: readonly S[]): z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+    [K in SortValue<S>]: K;
+}>>>;
+export declare function sortParam<const S extends string>(sorts: readonly S[], fallback: SortValue<S>): z.ZodCatch<z.ZodDefault<z.ZodEnum<{
+    [K in SortValue<S>]: K;
+}>>>;

package/dist/schema.js

@@ -0,0 +1,33 @@
+// zod-only building blocks; no router or React import, so they bundle on their own.
+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;
+}
+/**
+ * `page` (1-based) and `perPage` for a list route: spread into `searchParams({ ... })`.
+ * Both have defaults (so they stay out of the URL) and fall back to them on junk input.
+ */
+export function pagination({ perPage = 20, maxPerPage = 100 } = {}) {
+    return {
+        page: z.number().int().positive().default(1).catch(1),
+        perPage: z.number().int().min(1).max(maxPerPage).default(perPage).catch(perPage),
+    };
+}
+export function sortParam(sorts, fallback) {
+    const fields = [...new Set(sorts.map((sort) => sort.replace(/^-/, "")))];
+    const sort = z.enum(fields.flatMap((field) => [field, `-${field}`]));
+    return fallback === undefined
+        ? sort.optional().catch(undefined)
+        : sort.default(fallback).catch(fallback);
+}

package/dist/search-params.d.ts

@@ -1,6 +1,4 @@
 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(...)({ ... })`.

package/dist/search-params.js

@@ -1,19 +1,6 @@
 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;
-}
+import { searchDefaults } from "./schema.js";
 /**
  * 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(...)({ ... })`.

package/dist/use-search-state.js

@@ -1,13 +1,13 @@
 import { useRouter, useSearch } from "@tanstack/react-router";
 import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
-import { searchDefaults } from "./search-params.js";
+import { searchDefaults } from "./schema.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;
+let settleFlush;
 const listeners = new Set();
 const subscribe = (listener) => {
     listeners.add(listener);
@@ -21,13 +21,15 @@ const emit = () => {
     }
 };
 const isEmpty = (value) => value === null || value === undefined || value === "" || (Array.isArray(value) && value.length === 0);
+// Runs from a timer, so it never throws: a failed navigation rejects the setters' promise instead.
 async function flush() {
     timer = undefined;
     const sent = pending;
     const job = queued;
-    const resolve = resolveFlush;
+    const settle = settleFlush;
     queued = null;
     nextFlush = null;
+    let failure;
     try {
         if (job) {
             const patch = Object.fromEntries(Object.entries(sent).map(([key, value]) => [key, isEmpty(value) ? undefined : value]));
@@ -39,12 +41,21 @@ async function flush() {
             });
         }
     }
+    catch (error) {
+        failure = { error };
+    }
     finally {
-        // The URL now owns what was sent; keep only values set again while navigating.
+        // The URL now owns what was sent (or kept its old values if navigating failed);
+        // 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?.();
+        if (failure) {
+            settle?.reject(failure.error);
+        }
+        else {
+            settle?.resolve();
+        }
     }
 }
 function enqueue(router, patch, options) {
@@ -54,8 +65,8 @@ function enqueue(router, patch, options) {
         push: queued?.push === true || options.history === "push",
         scroll: queued?.scroll === true || options.scroll === true,
     };
-    nextFlush ??= new Promise((resolve) => {
-        resolveFlush = resolve;
+    nextFlush ??= new Promise((resolve, reject) => {
+        settleFlush = { resolve, reject };
     });
     emit();
     clearTimeout(timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanstack-url-state",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "nuqs-style URL search state for TanStack Router, typed by each route's validateSearch",
   "license": "MIT",
   "type": "module",
@@ -8,14 +8,22 @@
     "type": "git",
     "url": "git+https://github.com/B0redDev/tanstack-url-state.git"
   },
-  "keywords": ["tanstack-router", "search-params", "url-state", "react", "zod"],
+  "keywords": [
+    "tanstack-router",
+    "search-params",
+    "url-state",
+    "react",
+    "zod"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",