tanstack-url-state 0.1.1 → 0.2.0

package/README.md

@@ -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,6 +1,6 @@
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanstack-url-state",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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",