@querykitjs/web 3.1.0 → 4.0.0

package/dist/{registry-B1WohYab.d.cts → registry-DOVi_zCU.d.cts}

@@ -46,6 +46,8 @@ interface Params<T = Record<string, unknown>> {
 interface ListParams<T = Record<string, unknown>> extends Params<T> {
     page?: number;
     perPage?: number;
+    /** `false` — the server runs no count; the meta totals come back `null` (sent only when given). */
+    withTotal?: boolean;
 }
 /** Infinite-scroll (limit + offset) paginatsiya kirishi. */
 interface InfiniteParams<T = Record<string, unknown>> extends Params<T> {
@@ -72,6 +74,8 @@ interface QueryPayload {
 interface ListPayload extends QueryPayload {
     page: number;
     perPage: number;
+    /** Only present when given in the input. */
+    withTotal?: boolean;
 }
 interface InfinitePayload extends QueryPayload {
     limit: number;
@@ -99,8 +103,10 @@ type RawInfiniteMeta = Partial<Core.InfiniteMeta>;
 type RawCursorMeta = Partial<Core.CursorMeta>;
 /** Offset (list) — normalizatsiya qilingan meta (camelCase). */
 interface Meta {
-    totalPages: number;
-    totalCount: number;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalPages: number | null;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalCount: number | null;
     currentPage: number;
     perPage: number;
     hasNext: boolean;
@@ -262,10 +268,37 @@ declare function encodeSort(sort: SortInput): string;
  * present (`{ and: [orGroup, …conditions] }`).
  */
 declare function schemaToFilter(schema: ListSchema, searchParams: URLSearchParams): Filter;
-/** searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage). */
-declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListParams;
-/** searchParams → to'liq, yuborishga tayyor {@link ListPayload}. */
-declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListPayload;
+/**
+ * The bounds the URL readers clamp to — the builder's own (`createRegistry`
+ * `defaults`); an absent one is the core default.
+ */
+interface UrlLimits {
+    perPage?: number;
+    maxPerPage?: number;
+    maxOffset?: number;
+    maxSortFields?: number;
+}
+/** {@link ListParams} read from a URL. `clamped` — the URL's page or sort was cut to the limits. */
+type UrlListParams = ListParams & {
+    clamped: boolean;
+};
+/**
+ * A list payload built from a URL. `clamped` is non-enumerable: readable in code,
+ * never serialized, so the wire payload is unchanged.
+ */
+type UrlListPayload = ListPayload & {
+    readonly clamped?: boolean;
+};
+/**
+ * searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage).
+ * The URL is user input: a page past `maxOffset` becomes the last allowed page and a
+ * sort past `maxSortFields` keeps its first fields, with `clamped: true` — so a
+ * hand-edited `?page=9999` never throws during render. The builders still throw
+ * for a direct call (task 008).
+ */
+declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig, limits?: UrlLimits): UrlListParams;
+/** searchParams → to'liq, yuborishga tayyor {@link ListPayload} (core default limits; clamped like {@link readListParams}). */
+declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): UrlListPayload;
 /** Filter param'ini o'rnatadi/o'chiradi va `page`ni reset qiladi. */
 declare function setParam(searchParams: URLSearchParams, name: string, value: string | null | undefined, url?: UrlConfig): URLSearchParams;
 /** Sahifani o'rnatadi (`page` reset qilinmaydi). */
@@ -331,6 +364,11 @@ type ResourceCursorParams<T, A extends AdapterName> = Omit<CursorParams<T>, "wit
 type ResourceParams<T, A extends AdapterName> = Omit<Params<T>, "with"> & {
     with?: WithFor<A>;
 };
+/** `resource.search` options. */
+interface SearchOptions {
+    /** The string operator per field (default `"contains"`). */
+    operation?: "contains" | "startsWith" | "endsWith";
+}
 interface RawResponse<T, M> {
     data?: T[];
     meta?: M | null;
@@ -365,16 +403,22 @@ interface Resource<T, A extends AdapterName> {
     params(input?: ResourceParams<T, A>): QueryPayload;
     /** Filter builder typed to `T`'s fields. */
     f: ReturnType<typeof createFilters<T>>;
-    /** Search preset — OR of `contains` across `fields` (e.g. one input → many columns). */
-    search(term: string, fields: FieldKey<T>[]): Filter<T>;
+    /**
+     * Search preset — OR of `operation` (default `contains`) across `fields` (one input → many columns).
+     * Each field must be `filterable` with that operator on the server.
+     */
+    search(term: string, fields: FieldKey<T>[], options?: SearchOptions): Filter<T>;
     /** Declare a URL↔filter schema (identity helper). */
     schema<S extends ListSchema>(s: S): S;
-    /** Build a list payload from URL search params (SSR — the non-hook `useListParams`). */
+    /**
+     * Build a list payload from URL search params (SSR — the non-hook `useListParams`).
+     * A page or sort past the registry limits is clamped (`clamped`, non-enumerable — never sent).
+     */
     fromSearchParams(searchParams: URLSearchParams, options: {
         schema: ListSchema;
         url?: UrlConfig;
         with?: WithFor<A>;
-    }): ListPayload;
+    }): UrlListPayload;
     /** Stable query keys for TanStack/SWR caches. */
     keys: ResourceKeys;
     /** Map a list response's meta to camelCase (`data` typed to `T`). */
@@ -395,6 +439,10 @@ interface RegistryDefaults {
     maxPerPage?: number;
     /** `limit` upper bound (core `DEFAULT_MAX_LIMIT` = 200). */
     maxLimit?: number;
+    /** Page depth bound (core `DEFAULT_MAX_OFFSET` = 10 000) — a deeper `list`/`infinite` request throws. */
+    maxOffset?: number;
+    /** Sort field count bound (core `DEFAULT_MAX_SORT_FIELDS` = 3) — more fields throw. */
+    maxSortFields?: number;
     /** `list`/`infinite` sort — `[{key,direction}]` or `["-createdAt", "id"]` shorthand. */
     sort?: SortInput;
     /** Cursor-only defaults. */
@@ -402,9 +450,16 @@ interface RegistryDefaults {
         order?: SortDirection;
     };
 }
+/** The backend registry's `timestamps` field names, so the web default sort names the same field. */
+interface RegistryTimestamps {
+    /** The createdAt field (default `"createdAt"`) — the default `list`/`infinite` sort is `[{ key: createdAt, direction: "desc" }]`. */
+    createdAt?: string;
+}
 interface RegistryConfig<A extends AdapterName> {
     adapter: A;
     defaults?: RegistryDefaults;
+    /** Same as the backend registry's `timestamps`; `defaults.sort` wins over it. */
+    timestamps?: RegistryTimestamps;
     /** Drop empty filter values built from form inputs (default `true`). */
     pruneEmpty?: boolean;
 }
@@ -431,4 +486,5 @@ interface Registry<A extends AdapterName> {
  */
 declare function createRegistry<A extends AdapterName>(config: RegistryConfig<A>): Registry<A>;
 
-export { readListParams as $, type AdapterName as A, type ResourceCursorParams as B, type CursorParams as C, type DrizzleWith as D, type ResourceInfiniteParams as E, type Filter as F, type ResourceKeys as G, type ResourceListParams as H, type InfiniteParams as I, type ResourceParams as J, type SortDirection as K, type ListParams as L, type Meta as M, type NotGroup as N, type OrGroup as O, type Params as P, type QueryPayload as Q, type RawCursorMeta as R, type Sort as S, type SortItem as T, type UrlConfig as U, createFilters as V, type WithFor as W, createRegistry as X, decodeSort as Y, defineListSchema as Z, encodeSort as _, type CursorPayload as a, resetParams as a0, schemaToFilter as a1, searchParamsToPayload as a2, setPage as a3, setParam as a4, setSize as a5, setSort as a6, type InfinitePayload as b, type ListPayload as c, type FieldCondition as d, type FilterNode as e, type SortInput as f, type AndGroup as g, type CursorMeta as h, type CursorResult as i, type FieldDescriptor as j, type FieldKey as k, type FilterOperator as l, type FilterScalar as m, type FilterValue as n, type InfiniteMeta as o, type InfiniteResult as p, type ListResult as q, type ListSchema as r, type MongoosePopulate as s, type PrismaInclude as t, type RawInfiniteMeta as u, type RawMeta as v, type Registry as w, type RegistryConfig as x, type RegistryDefaults as y, type Resource as z };
+export { createFilters as $, createRegistry as a0, decodeSort as a1, defineListSchema as a2, encodeSort as a3, readListParams as a4, resetParams as a5, schemaToFilter as a6, searchParamsToPayload as a7, setPage as a8, setParam as a9, setSize as aa, setSort as ab };
+export type { AdapterName as A, Resource as B, CursorParams as C, DrizzleWith as D, ResourceCursorParams as E, Filter as F, ResourceInfiniteParams as G, ResourceKeys as H, InfiniteParams as I, ResourceListParams as J, ResourceParams as K, ListParams as L, Meta as M, NotGroup as N, OrGroup as O, Params as P, QueryPayload as Q, RawCursorMeta as R, Sort as S, SearchOptions as T, SortDirection as U, SortItem as V, UrlConfig as W, UrlLimits as X, UrlListParams as Y, UrlListPayload as Z, WithFor as _, CursorPayload as a, InfinitePayload as b, ListPayload as c, FieldCondition as d, FilterNode as e, SortInput as f, AndGroup as g, CursorMeta as h, CursorResult as i, FieldDescriptor as j, FieldKey as k, FilterOperator as l, FilterScalar as m, FilterValue as n, InfiniteMeta as o, InfiniteResult as p, ListResult as q, ListSchema as r, MongoosePopulate as s, PrismaInclude as t, RawInfiniteMeta as u, RawMeta as v, Registry as w, RegistryConfig as x, RegistryDefaults as y, RegistryTimestamps as z };

package/dist/{registry-B1WohYab.d.ts → registry-DOVi_zCU.d.ts}

@@ -46,6 +46,8 @@ interface Params<T = Record<string, unknown>> {
 interface ListParams<T = Record<string, unknown>> extends Params<T> {
     page?: number;
     perPage?: number;
+    /** `false` — the server runs no count; the meta totals come back `null` (sent only when given). */
+    withTotal?: boolean;
 }
 /** Infinite-scroll (limit + offset) paginatsiya kirishi. */
 interface InfiniteParams<T = Record<string, unknown>> extends Params<T> {
@@ -72,6 +74,8 @@ interface QueryPayload {
 interface ListPayload extends QueryPayload {
     page: number;
     perPage: number;
+    /** Only present when given in the input. */
+    withTotal?: boolean;
 }
 interface InfinitePayload extends QueryPayload {
     limit: number;
@@ -99,8 +103,10 @@ type RawInfiniteMeta = Partial<Core.InfiniteMeta>;
 type RawCursorMeta = Partial<Core.CursorMeta>;
 /** Offset (list) — normalizatsiya qilingan meta (camelCase). */
 interface Meta {
-    totalPages: number;
-    totalCount: number;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalPages: number | null;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalCount: number | null;
     currentPage: number;
     perPage: number;
     hasNext: boolean;
@@ -262,10 +268,37 @@ declare function encodeSort(sort: SortInput): string;
  * present (`{ and: [orGroup, …conditions] }`).
  */
 declare function schemaToFilter(schema: ListSchema, searchParams: URLSearchParams): Filter;
-/** searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage). */
-declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListParams;
-/** searchParams → to'liq, yuborishga tayyor {@link ListPayload}. */
-declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListPayload;
+/**
+ * The bounds the URL readers clamp to — the builder's own (`createRegistry`
+ * `defaults`); an absent one is the core default.
+ */
+interface UrlLimits {
+    perPage?: number;
+    maxPerPage?: number;
+    maxOffset?: number;
+    maxSortFields?: number;
+}
+/** {@link ListParams} read from a URL. `clamped` — the URL's page or sort was cut to the limits. */
+type UrlListParams = ListParams & {
+    clamped: boolean;
+};
+/**
+ * A list payload built from a URL. `clamped` is non-enumerable: readable in code,
+ * never serialized, so the wire payload is unchanged.
+ */
+type UrlListPayload = ListPayload & {
+    readonly clamped?: boolean;
+};
+/**
+ * searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage).
+ * The URL is user input: a page past `maxOffset` becomes the last allowed page and a
+ * sort past `maxSortFields` keeps its first fields, with `clamped: true` — so a
+ * hand-edited `?page=9999` never throws during render. The builders still throw
+ * for a direct call (task 008).
+ */
+declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig, limits?: UrlLimits): UrlListParams;
+/** searchParams → to'liq, yuborishga tayyor {@link ListPayload} (core default limits; clamped like {@link readListParams}). */
+declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): UrlListPayload;
 /** Filter param'ini o'rnatadi/o'chiradi va `page`ni reset qiladi. */
 declare function setParam(searchParams: URLSearchParams, name: string, value: string | null | undefined, url?: UrlConfig): URLSearchParams;
 /** Sahifani o'rnatadi (`page` reset qilinmaydi). */
@@ -331,6 +364,11 @@ type ResourceCursorParams<T, A extends AdapterName> = Omit<CursorParams<T>, "wit
 type ResourceParams<T, A extends AdapterName> = Omit<Params<T>, "with"> & {
     with?: WithFor<A>;
 };
+/** `resource.search` options. */
+interface SearchOptions {
+    /** The string operator per field (default `"contains"`). */
+    operation?: "contains" | "startsWith" | "endsWith";
+}
 interface RawResponse<T, M> {
     data?: T[];
     meta?: M | null;
@@ -365,16 +403,22 @@ interface Resource<T, A extends AdapterName> {
     params(input?: ResourceParams<T, A>): QueryPayload;
     /** Filter builder typed to `T`'s fields. */
     f: ReturnType<typeof createFilters<T>>;
-    /** Search preset — OR of `contains` across `fields` (e.g. one input → many columns). */
-    search(term: string, fields: FieldKey<T>[]): Filter<T>;
+    /**
+     * Search preset — OR of `operation` (default `contains`) across `fields` (one input → many columns).
+     * Each field must be `filterable` with that operator on the server.
+     */
+    search(term: string, fields: FieldKey<T>[], options?: SearchOptions): Filter<T>;
     /** Declare a URL↔filter schema (identity helper). */
     schema<S extends ListSchema>(s: S): S;
-    /** Build a list payload from URL search params (SSR — the non-hook `useListParams`). */
+    /**
+     * Build a list payload from URL search params (SSR — the non-hook `useListParams`).
+     * A page or sort past the registry limits is clamped (`clamped`, non-enumerable — never sent).
+     */
     fromSearchParams(searchParams: URLSearchParams, options: {
         schema: ListSchema;
         url?: UrlConfig;
         with?: WithFor<A>;
-    }): ListPayload;
+    }): UrlListPayload;
     /** Stable query keys for TanStack/SWR caches. */
     keys: ResourceKeys;
     /** Map a list response's meta to camelCase (`data` typed to `T`). */
@@ -395,6 +439,10 @@ interface RegistryDefaults {
     maxPerPage?: number;
     /** `limit` upper bound (core `DEFAULT_MAX_LIMIT` = 200). */
     maxLimit?: number;
+    /** Page depth bound (core `DEFAULT_MAX_OFFSET` = 10 000) — a deeper `list`/`infinite` request throws. */
+    maxOffset?: number;
+    /** Sort field count bound (core `DEFAULT_MAX_SORT_FIELDS` = 3) — more fields throw. */
+    maxSortFields?: number;
     /** `list`/`infinite` sort — `[{key,direction}]` or `["-createdAt", "id"]` shorthand. */
     sort?: SortInput;
     /** Cursor-only defaults. */
@@ -402,9 +450,16 @@ interface RegistryDefaults {
         order?: SortDirection;
     };
 }
+/** The backend registry's `timestamps` field names, so the web default sort names the same field. */
+interface RegistryTimestamps {
+    /** The createdAt field (default `"createdAt"`) — the default `list`/`infinite` sort is `[{ key: createdAt, direction: "desc" }]`. */
+    createdAt?: string;
+}
 interface RegistryConfig<A extends AdapterName> {
     adapter: A;
     defaults?: RegistryDefaults;
+    /** Same as the backend registry's `timestamps`; `defaults.sort` wins over it. */
+    timestamps?: RegistryTimestamps;
     /** Drop empty filter values built from form inputs (default `true`). */
     pruneEmpty?: boolean;
 }
@@ -431,4 +486,5 @@ interface Registry<A extends AdapterName> {
  */
 declare function createRegistry<A extends AdapterName>(config: RegistryConfig<A>): Registry<A>;
 
-export { readListParams as $, type AdapterName as A, type ResourceCursorParams as B, type CursorParams as C, type DrizzleWith as D, type ResourceInfiniteParams as E, type Filter as F, type ResourceKeys as G, type ResourceListParams as H, type InfiniteParams as I, type ResourceParams as J, type SortDirection as K, type ListParams as L, type Meta as M, type NotGroup as N, type OrGroup as O, type Params as P, type QueryPayload as Q, type RawCursorMeta as R, type Sort as S, type SortItem as T, type UrlConfig as U, createFilters as V, type WithFor as W, createRegistry as X, decodeSort as Y, defineListSchema as Z, encodeSort as _, type CursorPayload as a, resetParams as a0, schemaToFilter as a1, searchParamsToPayload as a2, setPage as a3, setParam as a4, setSize as a5, setSort as a6, type InfinitePayload as b, type ListPayload as c, type FieldCondition as d, type FilterNode as e, type SortInput as f, type AndGroup as g, type CursorMeta as h, type CursorResult as i, type FieldDescriptor as j, type FieldKey as k, type FilterOperator as l, type FilterScalar as m, type FilterValue as n, type InfiniteMeta as o, type InfiniteResult as p, type ListResult as q, type ListSchema as r, type MongoosePopulate as s, type PrismaInclude as t, type RawInfiniteMeta as u, type RawMeta as v, type Registry as w, type RegistryConfig as x, type RegistryDefaults as y, type Resource as z };
+export { createFilters as $, createRegistry as a0, decodeSort as a1, defineListSchema as a2, encodeSort as a3, readListParams as a4, resetParams as a5, schemaToFilter as a6, searchParamsToPayload as a7, setPage as a8, setParam as a9, setSize as aa, setSort as ab };
+export type { AdapterName as A, Resource as B, CursorParams as C, DrizzleWith as D, ResourceCursorParams as E, Filter as F, ResourceInfiniteParams as G, ResourceKeys as H, InfiniteParams as I, ResourceListParams as J, ResourceParams as K, ListParams as L, Meta as M, NotGroup as N, OrGroup as O, Params as P, QueryPayload as Q, RawCursorMeta as R, Sort as S, SearchOptions as T, SortDirection as U, SortItem as V, UrlConfig as W, UrlLimits as X, UrlListParams as Y, UrlListPayload as Z, WithFor as _, CursorPayload as a, InfinitePayload as b, ListPayload as c, FieldCondition as d, FilterNode as e, SortInput as f, AndGroup as g, CursorMeta as h, CursorResult as i, FieldDescriptor as j, FieldKey as k, FilterOperator as l, FilterScalar as m, FilterValue as n, InfiniteMeta as o, InfiniteResult as p, ListResult as q, ListSchema as r, MongoosePopulate as s, PrismaInclude as t, RawInfiniteMeta as u, RawMeta as v, Registry as w, RegistryConfig as x, RegistryDefaults as y, RegistryTimestamps as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@querykitjs/web",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "Frontend query-building for querykit — typed filters, pagination params & URL sync. Zero-dependency; you send the request.",
   "type": "module",
   "author": {
@@ -23,18 +23,36 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js",
-      "require": "./dist/react/index.cjs"
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": {
+        "types": "./dist/react/index.d.cts",
+        "default": "./dist/react/index.cjs"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "./dist/react/index.d.ts"
+      ]
     }
   },
   "files": [
     "dist",
+    "skills/querykit-web",
     "README.md",
     "README.en.md",
     "LICENSE"
@@ -43,31 +61,37 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=22.12"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test:smoke": "bun run test/smoke.ts"
+    "test:smoke": "bun run test/smoke.ts",
+    "test:hook": "bun run test/hook.ts"
   },
   "dependencies": {
-    "@querykitjs/core": "^1.2.0"
+    "@querykitjs/core": "^2.0.0"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "react-router-dom": ">=6"
+    "react": "^18.3 || ^19.2.7",
+    "react-router": "^7.0 || ^8.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
     },
-    "react-router-dom": {
+    "react-router": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
-    "react": "^19.0.0",
-    "react-router-dom": "^7.0.0"
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-router": "8.5.1"
   },
   "keywords": [
     "querykit",

package/skills/querykit-web/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: querykit-web
+description: Use when frontend code builds or reads a querykit list request (@querykitjs/web, @querykitjs/web/react) - createRegistry({ adapter }), qk.resource<T>(name), f filters, sort, list / infinite / cursor payloads, withTotal, parseList / parseInfinite / parseCursor, search, adapter-aware with, defineListSchema and URL helpers (readListParams, setPage, setSort), useListParams / useListParamsBase (clamped), fromSearchParams for SSR, query keys, or reading a 400 with isQueryKitError.
+---
+
+## Safety rules
+
+- DO treat the server as the authority: `filterable`, `sortable` and the filter limits live in the backend repository and its validator. The web package does not repeat them, so a refused filter comes back as a 400.
+- DON'T write `page` / `perPage` / `limit` math by hand. Build every payload with `resource.list` / `infinite` / `cursor` (or `buildListParams` …): `perPage` and `limit` are clamped to `200`, and an offset past `maxOffset` (`10000`) or more than `maxSortFields` (`3`) sort fields throws an `Error`. Use a cursor for deep pages.
+- DO read list state from the URL with `readListParams`, `fromSearchParams` or `useListParams`: they never throw, they clamp a too-deep `page` or too-long `sort` and report it as `clamped: true` (`clamped` is not sent to the server).
+- DON'T send `columns`, `with` or `withDeleted` unless the backend opened them on purpose (validator `allow`, repository `relations`). In `with`, name only the relations and columns the backend lists in `relations`; anything else is `forbidden-key`.
+- DO send dates as ISO strings: the wire is JSON.
+- DO read a 400 body with `isQueryKitError(body)` and use its `reason`, `site` and `key` (for example, mark the field named by `key`).
+- DO handle `withTotal: false`: `meta.totalCount` and `meta.totalPages` are then `null`, so show "next" / "previous" from `hasNext` / `hasPrev` instead of a page count.
+
+## When to use
+
+- A browser or SSR frontend (React, Next.js, any fetch client) that talks to a querykit backend.
+- Building list, infinite-scroll or cursor request bodies, keeping filters in the URL, and caching with TanStack Query or SWR.
+
+The package builds the payload only. You send the request yourself.
+
+## Setup
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+interface User {
+  id: number;
+  name: string;
+  status: "active" | "blocked";
+  createdAt: string;
+}
+
+export const qk = createRegistry({
+  adapter: "drizzle-pg", // "mongoose" | "drizzle-pg" | "drizzle-sqlite" | "prisma-pg" — types `with` only
+  defaults: { perPage: 20, limit: 20 },
+  timestamps: { createdAt: "createdAt" }, // same name as the backend; the default sort is this field, desc
+});
+export const users = qk.resource<User>("users"); // the name is the cache-key namespace
+```
+
+## Common tasks
+
+### Filter, sort and an offset page
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const users = createRegistry({ adapter: "prisma-pg" }).resource<{ id: number; name: string; age: number; createdAt: string }>("users");
+const { f } = users;
+
+const body = users.list({
+  filter: f.and(f.gte("age", 18), f.or(f.contains("name", "ali"), f.isNull("age"))),
+  sort: [
+    { key: "name", direction: "asc" },
+    { key: "createdAt", direction: "desc" },
+  ],
+  page: 2,
+  perPage: 20,
+  withTotal: false, // the server skips the count
+});
+const res = await fetch("/api/users/list", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+const { data, meta } = users.parseList(await res.json());
+console.log(data.length, meta.totalCount ?? "unknown", meta.hasNext);
+```
+
+### Infinite scroll and cursor payloads
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const posts = createRegistry({ adapter: "mongoose" }).resource<{ _id: string; title: string; createdAt: string }>("posts");
+
+const feedBody = posts.infinite({ limit: 20, offset: 40 });
+const firstPage = posts.cursor({ limit: 20, order: "desc", cursorKey: "createdAt" }); // no sort on a cursor
+declare const raw: unknown;
+const feed = posts.parseInfinite(raw as Parameters<typeof posts.parseInfinite>[0]);
+const page = posts.parseCursor(raw as Parameters<typeof posts.parseCursor>[0]);
+const nextBody = posts.cursor({ limit: 20, order: "desc", cursorKey: "createdAt", cursor: page.meta.nextCursor });
+console.log(feedBody, firstPage, feed.meta.hasMore, feed.meta.nextOffset, nextBody);
+```
+
+### Search box across several fields
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const users = createRegistry({ adapter: "drizzle-pg" }).resource<{ id: number; name: string; email: string }>("users");
+
+const filter = users.search("ali", ["name", "email"], { operation: "startsWith" }); // OR of startsWith
+const body = users.list({ filter, page: 1 });
+console.log(body);
+```
+
+### Relations with an adapter-aware `with`
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const posts = createRegistry({ adapter: "drizzle-pg" }).resource<{ id: number; title: string }>("posts");
+
+// only relations and columns the backend lists in `relations`
+const body = posts.list({ with: { author: { columns: { name: true } } }, page: 1 });
+console.log(body.with);
+```
+
+### Filters in the URL
+
+```ts
+import { defineListSchema, readListParams, setPage, setSort } from "@querykitjs/web";
+
+const schema = defineListSchema({
+  status: { operation: "=", default: "active" },
+  q: { search: ["name", "email"] },
+  createdAt: { range: ["fromDate", "toDate"] },
+});
+
+const read = readListParams(schema, new URLSearchParams("page=9999&size=20&q=ali"));
+console.log(read.page, read.clamped); // 501 true — clamped, never thrown
+
+let sp = new URLSearchParams(location.search);
+sp = setPage(sp, 2);
+sp = setSort(sp, [{ key: "name", direction: "asc" }]); // resets the page
+history.replaceState(null, "", `?${sp.toString()}`);
+```
+
+### React list page with `useListParams`
+
+```tsx
+import { createRegistry } from "@querykitjs/web";
+import { useListParams } from "@querykitjs/web/react";
+
+const users = createRegistry({ adapter: "mongoose" }).resource<{ _id: string; name: string; status: string }>("users");
+const usersSchema = users.schema({ name: { operation: "%_%", trim: true }, status: { operation: "=" } });
+
+export function UsersListPage() {
+  const { params, clamped, setParam, setPage } = useListParams(users, { schema: usersSchema });
+  if (clamped) setPage(params.page ?? 1); // fix a hand-edited URL
+  return (
+    <div>
+      <input placeholder="Name" onChange={event => setParam("name", event.target.value)} />
+      <pre>{JSON.stringify(users.keys.list(params))}</pre>
+    </div>
+  );
+}
+```
+
+### SSR payload and a refused request
+
+```ts
+import { createRegistry, isQueryKitError } from "@querykitjs/web";
+
+const users = createRegistry({ adapter: "prisma-pg" }).resource<{ id: number; name: string }>("users");
+const usersSchema = users.schema({ name: { operation: "%_%", trim: true } });
+
+export async function loadUsers(searchParams: URLSearchParams) {
+  const body = users.fromSearchParams(searchParams, { schema: usersSchema });
+  const res = await fetch("https://api.example.com/users/list", { method: "POST", body: JSON.stringify(body) });
+  const json: unknown = await res.json();
+  if (res.status === 400) {
+    const error = (json as { error?: unknown }).error;
+    if (isQueryKitError(error)) return { fieldError: { key: error.key, reason: error.reason, site: error.site } };
+  }
+  return users.parseList(json as Parameters<typeof users.parseList>[0]);
+}
+```
+
+## Request contract
+
+The same JSON shape as every querykit package (`@querykitjs/core`): conditions `{ key, operation?, value? }`, groups `{ and }` / `{ or }` / `{ not }` (a flat array = AND), `sort` always `[{ key, direction? }]`, offset `page` / `perPage` / `withTotal`, infinite `limit` / `offset`, cursor `limit` / `cursor` / `cursorKey` / `order` / `direction` (no `sort`). Meta is snake_case: `total_items`, `total_pages`, `has_next`, `has_more`, `next_offset`, `next_cursor`, `prev_cursor`. The body types are `WireOffsetParams`, `WireInfiniteParams` and `WireCursorParams`; validate with `@querykitjs/zod` or `@querykitjs/class-validator`, then pass the body as is. Refusals are `QueryKitError` with `{ source, site, key, operation?, reason }`.
+
+`parseList` / `parseInfinite` / `parseCursor` map that meta to camelCase: `totalCount`, `totalPages`, `currentPage`, `perPage`, `hasNext`, `hasPrev`; `limit`, `offset`, `count`, `hasMore`, `nextOffset`; `nextCursor`, `prevCursor`.
+
+## Mistakes to avoid
+
+- Expecting `list` / `infinite` / `cursor` to fetch: they return a plain payload object, synchronously.
+- Passing `sort` to `cursor`: cursor pages order by `cursorKey` with `order` and `direction`.
+- Computing `meta.totalCount + 1` without a `null` check: it is `null` after `withTotal: false`.
+- Validating filter size in the browser: depth, condition count and string length are checked by the server only.
+- Using `useListParams` outside react-router: use `useListParamsBase` with your own `searchParams` and `setSearchParams`.