@querykitjs/web 3.1.0 → 4.0.0

package/README.en.md

@@ -48,19 +48,31 @@ function UsersPage() {
 - **3 pagination modes** — offset (`list`), infinite (`infinite`), cursor/keyset (`cursor`); each has its own `parse*` to camelCase the meta.
 - **Adapter-aware `with`** — only **wire-safe** (JSON) per-relation options are suggested for `mongoose`/`drizzle-pg`/`drizzle-sqlite`/`prisma-pg`; function/SQL forms are never offered.
 - **Declarative schema** — `resource.schema` / `defineListSchema` maps URL params → filter; kills the per-page hand-building.
-- **React hooks** — `useListParams` (react-router-dom inside), `useListParamsBase` (router-agnostic). Framework-agnostic core — Vue can bind the same core.
+- **React hooks** — `useListParams` (react-router inside), `useListParamsBase` (router-agnostic). Framework-agnostic core — Vue can bind the same core.
 - **SSR** — `resource.fromSearchParams(sp, {schema})` builds a payload straight from `URLSearchParams`, no hook.
 - **Query keys** — `resource.keys` gives stable keys for TanStack/SWR.
-- **Zero dependency** — no axios/react-query/dayjs. `react` (+ `react-router-dom` for the hook) are optional peers.
+- **Zero dependency** — no axios/react-query/dayjs. `react` (+ `react-router` for the hook) are optional peers.
 
 ## Install
 
 ```bash
 bun add @querykitjs/web
-# React hook: react (peer). `useListParams` also peers react-router-dom.
-# The router-agnostic `useListParamsBase` needs no react-router-dom.
+# React hook: react (peer). `useListParams` also peers react-router.
+# The router-agnostic `useListParamsBase` needs no react-router.
 ```
 
+### Requirements
+
+|                                                      | Version              | Tested (`bun run test:matrix`) |
+| ---------------------------------------------------- | -------------------- | ------------------------------ |
+| Node.js                                              | `>=22.12`            | 24                             |
+| `react` (optional peer)                              | `^18.3 \|\| ^19.2.7` | 18.3.1, 19.3.1                 |
+| `react-router` (optional peer, `useListParams` only) | `^7.0 \|\| ^8.0`     | 7.18.5, 8.5.1                  |
+
+Node 20 is no longer supported (`engines`: `>=22.12`). Peer ranges cover the last two majors; both ends are tested.
+
+**`react-router-dom` → `react-router`.** `useListParams` now imports from `react-router` (v7 and v8 both export `useSearchParams`). A project that has `react-router-dom` installs `react-router` too — on v7 it is already a dependency of `react-router-dom`: `npm i react-router`.
+
 ## Two ways to use it
 
 ```ts
@@ -84,18 +96,20 @@ export const qk = createRegistry({
     sort: ["-createdAt"], // list + infinite ordering (leading "-" = desc)
     cursor: { order: "asc" }, // cursor-only key traversal order
   },
+  timestamps: { createdAt: "created_at" }, // same as the backend registry; the default sort is this field, desc
   pruneEmpty: true, // drop empty filter values (""/null/undefined/[]); keep 0/false
 });
 ```
 
-| Config                  | Meaning                                                                             |
-| ----------------------- | ----------------------------------------------------------------------------------- |
-| `adapter`               | Target backend — tailors `with` typing (intellisense only).                         |
-| `defaults.perPage`      | Default `perPage` for `list`.                                                       |
-| `defaults.limit`        | Default `limit` for `infinite` and `cursor`.                                        |
-| `defaults.sort`         | Default sort for `list`/`infinite` — `[{key,direction}]` or `["-field"]` shorthand. |
-| `defaults.cursor.order` | Default cursor traversal order (`"asc"`/`"desc"`).                                  |
-| `pruneEmpty`            | Auto-drop empty filter conditions built from form inputs (default `true`).          |
+| Config                  | Meaning                                                                                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `adapter`               | Target backend — tailors `with` typing (intellisense only).                                                                                                |
+| `defaults.perPage`      | Default `perPage` for `list`.                                                                                                                              |
+| `defaults.limit`        | Default `limit` for `infinite` and `cursor`.                                                                                                               |
+| `defaults.sort`         | Default sort for `list`/`infinite` — `[{key,direction}]` or `["-field"]` shorthand.                                                                        |
+| `defaults.cursor.order` | Default cursor traversal order (`"asc"`/`"desc"`).                                                                                                         |
+| `timestamps.createdAt`  | Same as the backend `timestamps.createdAt`; without `defaults.sort` the default sort is `[{ key: createdAt, direction: "desc" }]` (default `"createdAt"`). |
+| `pruneEmpty`            | Auto-drop empty filter conditions built from form inputs (default `true`).                                                                                 |
 
 Every default is overridable per call.
 
@@ -106,19 +120,19 @@ import type { IUser } from "@my/api-types";
 export const users = qk.resource<IUser>("users"); // "users" = cache-key namespace (required, unique)
 ```
 
-| Member                                                        | What it is                                                           |
-| ------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `users.list(input)`                                           | build an offset (page) payload                                       |
-| `users.infinite(input)`                                       | build an infinite (limit/offset) payload                             |
-| `users.cursor(input)`                                         | build a cursor (keyset) payload                                      |
-| `users.params(input)`                                         | build a paginationless payload (filter/sort/columns/with)            |
-| `users.f`                                                     | `createFilters<IUser>()` — field-typed builder                       |
-| `users.search(term, fields)`                                  | OR-of-`contains` preset across `fields`                              |
-| `users.schema(desc)`                                          | `defineListSchema` bound (URL ↔ filter)                              |
-| `users.fromSearchParams(sp, {schema})`                        | build a list payload straight from `URLSearchParams` (SSR / no hook) |
-| `users.keys`                                                  | stable query keys for TanStack/SWR                                   |
-| `users.parseList / parseInfinite / parseCursor`               | map response meta snake→camel                                        |
-| `ListResult<T> / InfiniteResult<T> / CursorResult<T>` (types) | `parse*` return types                                                |
+| Member                                                        | What it is                                                                  |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `users.list(input)`                                           | build an offset (page) payload                                              |
+| `users.infinite(input)`                                       | build an infinite (limit/offset) payload                                    |
+| `users.cursor(input)`                                         | build a cursor (keyset) payload                                             |
+| `users.params(input)`                                         | build a paginationless payload (filter/sort/columns/with)                   |
+| `users.f`                                                     | `createFilters<IUser>()` — field-typed builder                              |
+| `users.search(term, fields, { operation? })`                  | OR preset across `fields` (`contains` by default, `startsWith`, `endsWith`) |
+| `users.schema(desc)`                                          | `defineListSchema` bound (URL ↔ filter)                                     |
+| `users.fromSearchParams(sp, {schema})`                        | build a list payload straight from `URLSearchParams` (SSR / no hook)        |
+| `users.keys`                                                  | stable query keys for TanStack/SWR                                          |
+| `users.parseList / parseInfinite / parseCursor`               | map response meta snake→camel                                               |
+| `ListResult<T> / InfiniteResult<T> / CursorResult<T>` (types) | `parse*` return types                                                       |
 
 All builders inherit the registry's `defaults` + `pruneEmpty`; all types are driven by `IUser` and the `adapter`.
 
@@ -155,8 +169,13 @@ f.contains("age", "x"); // ✗ compile error — `contains` is string-only
 ```ts
 users.search("ali", ["buyerName", "email"]);
 // → or(contains("buyerName","ali"), contains("email","ali"))
+users.search("ali", ["buyerName"], { operation: "startsWith" });
+// → or(startsWith("buyerName","ali")) — can use an index
 ```
 
+- `contains` is expensive: `%ali%` cannot use a B-tree index (a full scan on Postgres, a regex on MongoDB). On a large table prefer `startsWith` (`ali%`) or full-text search.
+- Every field must be `filterable` on the server with that operator (`{ buyerName: ["%_%"] }` or `["%_"]`); otherwise the server answers 400 with `forbidden-key` / `forbidden-operator`.
+
 An untyped `f` is also exported: `import { f } from "@querykitjs/web"` (no field-type checks, quick use).
 
 ## Sort — always `[{ key, direction }]` (multi-field)
@@ -219,6 +238,15 @@ users.parseInfinite(res.data); // { data, meta: { hasMore, nextOffset, … } }
 users.parseCursor(res.data); // { data, meta: { nextCursor, hasNext, … } }
 ```
 
+**`withTotal: false`** — when you do not need the total (an infinite-like list, a "next" button), the server skips the count query:
+
+```ts
+const body = users.list({ page, perPage: 20, withTotal: false }); // the payload carries withTotal: false (absent when not given)
+const { meta } = users.parseList(res.data); // meta.totalCount === null, meta.totalPages === null; hasNext still works
+```
+
+`Meta.totalCount` / `Meta.totalPages` are typed `number | null`: `null` means no count ran; a field the server did not send at all is `0` as before. zod (`makeOffsetParamsSchema`) and class-validator (`makeOffsetParamsDto`) accept `withTotal`.
+
 `parse*` exists at two levels (one shared implementation — meta is entity-agnostic):
 `qk.parseList/...` (registry, `data: unknown[]`) when you don't have a `resource`; `users.parseList/...` (entity-typed).
 
@@ -276,7 +304,7 @@ Empty/**absent** params are pruned; `default` fills only when the param is **abs
 ## React hook
 
 ```tsx
-import { useListParams } from "@querykitjs/web/react"; // uses react-router-dom internally
+import { useListParams } from "@querykitjs/web/react"; // uses react-router internally
 import { qk } from "@/lib/query";
 
 const users = qk.resource<IUser>("users");
@@ -299,9 +327,11 @@ function UsersListPage() {
 }
 ```
 
+The hook also returns `clamped: boolean` — the URL's `page` or `sort` was past a limit and was cut (see «Limits» below). To fix the URL: `if (clamped) setPage(params.page)`.
+
 An input/sort/page change mutates the URL → `params` changes → `queryKey` changes → TanStack refetches (and caches each combo).
 
-**Router-agnostic** (Next.js, TanStack Router) — pass `searchParams` to the base hook (no react-router-dom):
+**Router-agnostic** (Next.js, TanStack Router) — pass `searchParams` to the base hook (no react-router):
 
 ```tsx
 import { useListParamsBase } from "@querykitjs/web/react";
@@ -465,6 +495,59 @@ createRegistry({ adapter: "drizzle-pg", defaults: { maxPerPage: 50, maxLimit: 25
 createQuery({ maxPerPage: Infinity });
 ```
 
+## Limits
+
+`perPage`/`limit` are clamped (above), but **page depth** and the **number of sort fields** are not — the builder throws an `Error`, because silently cutting them would change what the request means (another page, another order). The values come from `@querykitjs/core`, the same as in zod and class-validator.
+
+| Limit           | Default  | What counts                                          | Past it                                                               |
+| --------------- | -------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
+| `maxOffset`     | `10 000` | `list`: `(page - 1) × perPage`; `infinite`: `offset` | `Error: querykit: page 502 × perPage 20 exceeds maxOffset (10000); …` |
+| `maxSortFields` | `3`      | `sort` fields after normalization                    | `Error: querykit: sort with 4 fields exceeds maxSortFields (3)`       |
+
+```ts
+buildListParams({ page: 501, perPage: 20 }); // ✅ offset 10 000
+buildListParams({ page: 502, perPage: 20 }); // ❌ Error — use buildCursorParams for deeper pages
+
+createQuery({ maxOffset: 50_000, maxSortFields: 4 });
+createRegistry({ adapter: "drizzle-pg", defaults: { maxOffset: 50_000 } });
+```
+
+- Filter limits (depth, conditions, `in` items, string length) are **not** checked in web — the server (zod / class-validator) rejects them with a 400.
+- **The URL readers clamp.** The URL is in the user's hands, so `readListParams`, `searchParamsToPayload`, `resource.fromSearchParams` and the hooks (`useListParams`, `useListParamsBase`) never throw: `page` becomes the last allowed page (`floor(maxOffset / perPage) + 1`), `sort` keeps its first `maxSortFields` fields, and the result has `clamped: true`. `?page=9999&size=20` → `page: 501`, `clamped: true`; `?sortType=a,b,c,d` → 3 fields, `clamped: true`. Through a registry, the registry's `defaults` limits apply.
+
+```ts
+const read = readListParams(schema, new URLSearchParams("page=9999&size=20")); // { page: 501, perPage: 20, clamped: true, … }
+const body = users.fromSearchParams(sp, { schema }); // body.clamped === true
+JSON.stringify(body); // no clamped — it is non-enumerable on the payload and never reaches the server
+const { params, clamped } = useListParams(users, { schema }); // no error during render
+```
+
+Builders the developer calls directly (`buildListParams`, `resource.list`, …) still throw an `Error`.
+
+## Migrating (limits)
+
+- `buildListParams` / `buildInfiniteParams` / `createQuery` / registry `list`/`infinite` now throw for an offset deeper than 10 000 or more than 3 sort fields (they used to build the payload and the server accepted it). Use a cursor for deep pages; raise `maxOffset` / `maxSortFields` where you must (and raise the same limit on the server).
+
+- `Meta.totalCount` / `Meta.totalPages` are now `number | null` (`null` in a `withTotal: false` response). Code like `meta.totalCount + 1` needs a `null` check in TS; in an app that never sends `withTotal` the value is a number as before.
+- A deep `page` read from the URL is now clamped (`clamped: true`), not an error — no error boundary or manual check needed.
+
+## Errors — `isQueryKitError`
+
+When the server rejects a request (`forbidden-key`, `forbidden-operator`, `limit-exceeded`, `empty-filter`, …), the backend may return `QueryKitError.info` in its 400 response. The envelope is the project's own; web only types the `info` shape:
+
+```ts
+import { isQueryKitError, type QueryKitErrorBody } from "@querykitjs/web";
+
+// backend: catch (e) { if (e instanceof QueryKitError) return res.status(400).json({ error: e.info }); }
+const body = error.response?.data?.error;
+if (isQueryKitError(body)) {
+  // body: { reason, site, key, source?, operation? }
+  if (body.reason === "forbidden-key" && body.site === "filter") showFieldError(body.key);
+}
+```
+
+`isQueryKitError` checks `reason` and `site` against the core lists and `key` is a string; any other object (e.g. `{ statusCode: 400, message }`) → `false`.
+
 ## You send the request yourself
 
 The library works only **up to the request**. No transport:
@@ -486,7 +569,7 @@ const { data, meta } = users.parseList(await res.json());
 | `registry.resource<T>(name)`                                                      | entity-typed builders/filters/schema/keys/parsers       |
 | `resource.list/infinite/cursor/params(input)`                                     | build a payload (offset/infinite/cursor/paginationless) |
 | `resource.f` / `createFilters<T>()` / `f`                                         | typed filter builder / typed / untyped                  |
-| `resource.search(term, fields)`                                                   | OR-of-contains preset                                   |
+| `resource.search(term, fields, { operation? })`                                   | OR preset (`contains` / `startsWith` / `endsWith`)      |
 | `resource.schema(desc)` / `defineListSchema(desc)`                                | URL param → filter descriptor                           |
 | `resource.fromSearchParams(sp, {schema})`                                         | searchParams → list payload (SSR)                       |
 | `resource.keys`                                                                   | TanStack/SWR query keys                                 |
@@ -495,11 +578,12 @@ const { data, meta } = users.parseList(await res.json());
 | `buildParams / buildListParams / buildInfiniteParams / buildCursorParams`         | standalone builders                                     |
 | `createQuery(config)`                                                             | builder without a registry (defaults/pruneEmpty)        |
 | `schemaToFilter(schema, sp)`                                                      | searchParams → `FieldCondition[]`                       |
-| `searchParamsToPayload(schema, sp)`                                               | searchParams → full payload                             |
-| `readListParams(schema, sp)`                                                      | searchParams → `ListParams`                             |
+| `searchParamsToPayload(schema, sp)`                                               | searchParams → full payload (clamped, `clamped`)        |
+| `readListParams(schema, sp, url?, limits?)`                                       | searchParams → `ListParams` + `clamped`                 |
+| `isQueryKitError(body)` / `QueryKitErrorBody`                                     | recognise a querykit error in a 400 response            |
 | `setParam/setPage/setSize/setSort/resetParams`                                    | write URL (immutable, page-reset)                       |
 | `encodeSort/decodeSort`                                                           | `[{key,direction}]` ↔ `"-createdAt,id"` (multi-field)   |
-| `useListParams(resource, {schema})` (`/react`)                                    | URL-sync hook (react-router-dom)                        |
+| `useListParams(resource, {schema})` (`/react`)                                    | URL-sync hook (react-router)                            |
 | `useListParamsBase(resource, {schema, searchParams, setSearchParams})` (`/react`) | router-agnostic hook                                    |
 
 ## Development

package/README.md

@@ -48,19 +48,31 @@ function UsersPage() {
 - **3 pagination** — offset (`list`), infinite (`infinite`), cursor/keyset (`cursor`); har birining meta'si alohida `parse*` bilan camelCase'ga o'giriladi.
 - **Adapter-aware `with`** — `mongoose`/`drizzle-pg`/`drizzle-sqlite`/`prisma-pg` uchun faqat **wire-safe** (JSON) relation opsiyalari intellisense'да; funksiya/SQL formalarи ko'rsatilmaydi.
 - **Declarative schema** — `resource.schema` / `defineListSchema` bilan URL param → filter; har sahifadagi qo'lda qurishni yo'q qiladi.
-- **React hook** — `useListParams` (`react-router-dom` ichida), `useListParamsBase` (router-agnostik). Core framework'siz — Vue ham shu core'ga bog'lanadi.
+- **React hook** — `useListParams` (`react-router` ichida), `useListParamsBase` (router-agnostik). Core framework'siz — Vue ham shu core'ga bog'lanadi.
 - **SSR** — `resource.fromSearchParams(sp, {schema})` hook'siz, `URLSearchParams`'dan to'g'ridan-to'g'ri payload.
 - **Query keys** — `resource.keys` TanStack/SWR uchun barqaror kalitlar.
-- **Zero dependency** — axios/react-query/dayjs YO'Q. `react` (+ hook uchun `react-router-dom`) ixtiyoriy peer.
+- **Zero dependency** — axios/react-query/dayjs YO'Q. `react` (+ hook uchun `react-router`) ixtiyoriy peer.
 
 ## O'rnatish
 
 ```bash
 bun add @querykitjs/web
-# React hook uchun: react (peer). `useListParams` uchun qo'shimcha: react-router-dom (peer).
-# Router-agnostik `useListParamsBase` react-router-dom talab qilmaydi.
+# React hook uchun: react (peer). `useListParams` uchun qo'shimcha: react-router (peer).
+# Router-agnostik `useListParamsBase` react-router talab qilmaydi.
 ```
 
+### Talablar
+
+|                                                        | Versiya              | Tekshiriladi (`bun run test:matrix`) |
+| ------------------------------------------------------ | -------------------- | ------------------------------------ |
+| Node.js                                                | `>=22.12`            | 24                                   |
+| `react` (ixtiyoriy peer)                               | `^18.3 \|\| ^19.2.7` | 18.3.1, 19.3.1                       |
+| `react-router` (ixtiyoriy peer, faqat `useListParams`) | `^7.0 \|\| ^8.0`     | 7.18.5, 8.5.1                        |
+
+Node 20 endi qo'llab-quvvatlanmaydi (`engines`: `>=22.12`). Peer diapazoni — oxirgi ikki major; ikkala cheti testda.
+
+**`react-router-dom` → `react-router`.** `useListParams` endi `react-router`dan import qiladi (v7 va v8 ikkalasi ham `useSearchParams` eksport qiladi). `react-router-dom` o'rnatilgan loyiha `react-router` ni ham o'rnatadi — v7 da u allaqachon `react-router-dom`ning bog'liqligi: `npm i react-router`.
+
 ## Ikki xil ishlatish
 
 ```ts
@@ -84,18 +96,20 @@ export const qk = createRegistry({
     sort: ["-createdAt"], // list + infinite tartibi (boshidagi "-" = desc)
     cursor: { order: "asc" }, // faqat cursor: kalit bo'ylab yurish tartibi
   },
+  timestamps: { createdAt: "created_at" }, // backend registry'dagi bilan bir xil; default sort shu maydon bo'yicha desc
   pruneEmpty: true, // bo'sh filterlarni tashlash (""/null/undefined/[]); 0/false qoladi
 });
 ```
 
-| Config                  | Vazifasi                                                                          |
-| ----------------------- | --------------------------------------------------------------------------------- |
-| `adapter`               | Backend turi — `with` tipini moslaydi (faqat intellisense).                       |
-| `defaults.perPage`      | `list` uchun default `perPage`.                                                   |
-| `defaults.limit`        | `infinite` va `cursor` uchun default `limit`.                                     |
-| `defaults.sort`         | `list`/`infinite` default sort — `[{key,direction}]` yoki `["-field"]` shorthand. |
-| `defaults.cursor.order` | Default cursor tartibi (`"asc"`/`"desc"`).                                        |
-| `pruneEmpty`            | Form input'lardan qurilgan bo'sh filterlarni avtomatik tashlash (default `true`). |
+| Config                  | Vazifasi                                                                                                                                                  |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `adapter`               | Backend turi — `with` tipini moslaydi (faqat intellisense).                                                                                               |
+| `defaults.perPage`      | `list` uchun default `perPage`.                                                                                                                           |
+| `defaults.limit`        | `infinite` va `cursor` uchun default `limit`.                                                                                                             |
+| `defaults.sort`         | `list`/`infinite` default sort — `[{key,direction}]` yoki `["-field"]` shorthand.                                                                         |
+| `defaults.cursor.order` | Default cursor tartibi (`"asc"`/`"desc"`).                                                                                                                |
+| `timestamps.createdAt`  | Backend `timestamps.createdAt` bilan bir xil; `defaults.sort` yo'q bo'lsa default sort `[{ key: createdAt, direction: "desc" }]` (default `"createdAt"`). |
+| `pruneEmpty`            | Form input'lardan qurilgan bo'sh filterlarni avtomatik tashlash (default `true`).                                                                         |
 
 Har bir default har chaqiriqда override qilinadi.
 
@@ -106,19 +120,19 @@ import type { IUser } from "@my/api-types";
 export const users = qk.resource<IUser>("users"); // "users" = cache-key namespace (majburiy, unikal)
 ```
 
-| A'zo                                                           | Nima                                                                   |
-| -------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `users.list(input)`                                            | offset (page) payload quradi                                           |
-| `users.infinite(input)`                                        | infinite (limit/offset) payload quradi                                 |
-| `users.cursor(input)`                                          | cursor (keyset) payload quradi                                         |
-| `users.params(input)`                                          | pagination'siz payload (filter/sort/columns/with)                      |
-| `users.f`                                                      | `createFilters<IUser>()` — maydon-tipli builder                        |
-| `users.search(term, fields)`                                   | ko'p maydon bo'ylab OR-of-`contains` preset                            |
-| `users.schema(desc)`                                           | `defineListSchema` bog'langan (URL ↔ filter)                           |
-| `users.fromSearchParams(sp, {schema})`                         | `URLSearchParams`'dan to'g'ridan-to'g'ri list payload (SSR / hook'siz) |
-| `users.keys`                                                   | TanStack/SWR uchun barqaror query keys                                 |
-| `users.parseList / parseInfinite / parseCursor`                | javob meta'sini snake→camel                                            |
-| `ListResult<T> / InfiniteResult<T> / CursorResult<T>` (tiplar) | `parse*` qaytaradigan tiplar                                           |
+| A'zo                                                           | Nima                                                                         |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `users.list(input)`                                            | offset (page) payload quradi                                                 |
+| `users.infinite(input)`                                        | infinite (limit/offset) payload quradi                                       |
+| `users.cursor(input)`                                          | cursor (keyset) payload quradi                                               |
+| `users.params(input)`                                          | pagination'siz payload (filter/sort/columns/with)                            |
+| `users.f`                                                      | `createFilters<IUser>()` — maydon-tipli builder                              |
+| `users.search(term, fields, { operation? })`                   | ko'p maydon bo'ylab OR preset (`contains` default, `startsWith`, `endsWith`) |
+| `users.schema(desc)`                                           | `defineListSchema` bog'langan (URL ↔ filter)                                 |
+| `users.fromSearchParams(sp, {schema})`                         | `URLSearchParams`'dan to'g'ridan-to'g'ri list payload (SSR / hook'siz)       |
+| `users.keys`                                                   | TanStack/SWR uchun barqaror query keys                                       |
+| `users.parseList / parseInfinite / parseCursor`                | javob meta'sini snake→camel                                                  |
+| `ListResult<T> / InfiniteResult<T> / CursorResult<T>` (tiplar) | `parse*` qaytaradigan tiplar                                                 |
 
 Barcha builder'lar registry'ning `defaults` + `pruneEmpty`ini meros oladi; tiplar `IUser` va `adapter`dan kelib chiqadi.
 
@@ -155,8 +169,13 @@ f.contains("age", "x"); // ✗ compile-error — `contains` string-only
 ```ts
 users.search("ali", ["buyerName", "email"]);
 // → or(contains("buyerName","ali"), contains("email","ali"))
+users.search("ali", ["buyerName"], { operation: "startsWith" });
+// → or(startsWith("buyerName","ali")) — indeks ishlatishi mumkin
 ```
 
+- `contains` qimmat: `%ali%` B-tree indeksini ishlata olmaydi (Postgres'da to'liq skan, MongoDB'da regex). Katta jadvalda `startsWith` (`ali%`) yoki full-text qidiruvni tanlang.
+- Har maydon serverda `filterable` bo'lishi kerak, o'sha operator bilan (`{ buyerName: ["%_%"] }` yoki `["%_"]`); aks holda server `forbidden-key` / `forbidden-operator` bilan 400 qaytaradi.
+
 Tipsiz `f` ham bor: `import { f } from "@querykitjs/web"` (maydon-tip tekshiruvisiz, tez ishlatish).
 
 ## Sort — hamisha `[{ key, direction }]` (ko'p-maydon)
@@ -219,6 +238,15 @@ users.parseInfinite(res.data); // { data, meta: { hasMore, nextOffset, … } }
 users.parseCursor(res.data); // { data, meta: { nextCursor, hasNext, … } }
 ```
 
+**`withTotal: false`** — umumiy son kerak bo'lmasa (infinite-ga o'xshash ro'yxat, "keyingi" tugmasi), server count so'rovini ishlatmaydi:
+
+```ts
+const body = users.list({ page, perPage: 20, withTotal: false }); // payload'da withTotal: false (berilmasa — kalit yo'q)
+const { meta } = users.parseList(res.data); // meta.totalCount === null, meta.totalPages === null; hasNext ishlaydi
+```
+
+`Meta.totalCount` / `Meta.totalPages` tipi `number | null`: `null` — count ishlamagan; server umuman bermagan maydon avvalgidek `0`. zod (`makeOffsetParamsSchema`) va class-validator (`makeOffsetParamsDto`) `withTotal`ni qabul qiladi.
+
 `parse*` ikki darajaда bor (bitta umumiy implementatsiya — meta entity-agnostik):
 `qk.parseList/...` (registry, `data: unknown[]`) — `resource` bo'lmasa; `users.parseList/...` (entity'ga tipli).
 
@@ -276,7 +304,7 @@ Bo'sh/**yo'q** paramlar tashlanadi; `default` faqat param **yo'q** bo'lganда t
 ## React hook
 
 ```tsx
-import { useListParams } from "@querykitjs/web/react"; // react-router-dom ichida ishlatiladi
+import { useListParams } from "@querykitjs/web/react"; // react-router ichida ishlatiladi
 import { qk } from "@/lib/query";
 
 const users = qk.resource<IUser>("users");
@@ -301,7 +329,9 @@ function UsersListPage() {
 
 Input/sort/page o'zgarishi URL'ni o'zgartiradi → `params` o'zgaradi → `queryKey` o'zgaradi → TanStack qayta so'raydi (va har kombinatsiyani cache qiladi).
 
-**Router-agnostik** (Next.js, TanStack Router) — base hook'ga `searchParams` bering (`react-router-dom` talab qilmaydi):
+Hook `clamped: boolean` ham qaytaradi — URL'dagi `page` yoki `sort` limitdan oshgani uchun kesilgan (pastda «Limits»). URL'ni tuzatish uchun: `if (clamped) setPage(params.page)`.
+
+**Router-agnostik** (Next.js, TanStack Router) — base hook'ga `searchParams` bering (`react-router` talab qilmaydi):
 
 ```tsx
 import { useListParamsBase } from "@querykitjs/web/react";
@@ -465,6 +495,59 @@ createRegistry({ adapter: "drizzle-pg", defaults: { maxPerPage: 50, maxLimit: 25
 createQuery({ maxPerPage: Infinity });
 ```
 
+## Limits
+
+`perPage`/`limit` clamp qilinadi (yuqorida), lekin **sahifa chuqurligi** va **sort maydonlari soni** clamp qilinmaydi — builder `Error` tashlaydi, chunki jim kesish so'rov ma'nosini o'zgartirardi (boshqa sahifa yoki boshqa tartib). Qiymatlar `@querykitjs/core`dan — zod va class-validator bilan bir xil.
+
+| Limit           | Default  | Nima sanaladi                                        | Oshsa                                                                 |
+| --------------- | -------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
+| `maxOffset`     | `10 000` | `list`: `(page - 1) × perPage`; `infinite`: `offset` | `Error: querykit: page 502 × perPage 20 exceeds maxOffset (10000); …` |
+| `maxSortFields` | `3`      | normalizatsiyadan keyingi `sort` maydonlari          | `Error: querykit: sort with 4 fields exceeds maxSortFields (3)`       |
+
+```ts
+buildListParams({ page: 501, perPage: 20 }); // ✅ offset 10 000
+buildListParams({ page: 502, perPage: 20 }); // ❌ Error — chuqurroq sahifalar uchun buildCursorParams
+
+createQuery({ maxOffset: 50_000, maxSortFields: 4 });
+createRegistry({ adapter: "drizzle-pg", defaults: { maxOffset: 50_000 } });
+```
+
+- Filtr limitlari (chuqurlik, shartlar, `in` elementlari, satr uzunligi) web'da **tekshirilmaydi** — ularni server (zod / class-validator) rad etadi va 400 qaytaradi.
+- **URL o'quvchilar clamp qiladi.** URL foydalanuvchi qo'lida, shuning uchun `readListParams`, `searchParamsToPayload`, `resource.fromSearchParams` va hook'lar (`useListParams`, `useListParamsBase`) xato tashlamaydi: `page` ruxsat etilgan oxirgi sahifaga (`floor(maxOffset / perPage) + 1`), `sort` birinchi `maxSortFields` maydoniga kesiladi va natijada `clamped: true` bo'ladi. `?page=9999&size=20` → `page: 501`, `clamped: true`; `?sortType=a,b,c,d` → 3 maydon, `clamped: true`. Registry orqali — registry `defaults` limitlari bilan.
+
+```ts
+const read = readListParams(schema, new URLSearchParams("page=9999&size=20")); // { page: 501, perPage: 20, clamped: true, … }
+const body = users.fromSearchParams(sp, { schema }); // body.clamped === true
+JSON.stringify(body); // clamped yo'q — u payload'da non-enumerable, server'ga bormaydi
+const { params, clamped } = useListParams(users, { schema }); // render paytida xato yo'q
+```
+
+Dasturchi to'g'ridan-to'g'ri chaqirgan builder'lar (`buildListParams`, `resource.list`, …) avvalgidek `Error` tashlaydi.
+
+## Migrating (limitlar)
+
+- `buildListParams` / `buildInfiniteParams` / `createQuery` / registry `list`/`infinite` endi offset 10 000 dan chuqur yoki 3 tadan ko'p sort maydonli so'rovda `Error` tashlaydi (ilgari payload yasalardi va server uni qabul qilardi). Chuqur sahifalar — cursor; zarur bo'lsa `maxOffset` / `maxSortFields` bilan oshiring (serverda ham xuddi shu limitni oshiring).
+
+- `Meta.totalCount` / `Meta.totalPages` endi `number | null` (`withTotal: false` javobida `null`). `meta.totalCount + 1` kabi kod TS'da `null` tekshiruvini talab qiladi; `withTotal` yubormaydigan ilovada qiymat avvalgidek raqam.
+- URL'dan o'qilgan chuqur `page` endi xato emas, clamp (`clamped: true`) — error boundary yoki qo'lda tekshiruv kerak emas.
+
+## Xatolar — `isQueryKitError`
+
+Server so'rovni rad etsa (`forbidden-key`, `forbidden-operator`, `limit-exceeded`, `empty-filter`, …), backend `QueryKitError.info`ni 400 javobida qaytarishi mumkin. Javob konverti loyihaniki; web faqat `info` shaklini tiplaydi:
+
+```ts
+import { isQueryKitError, type QueryKitErrorBody } from "@querykitjs/web";
+
+// backend: catch (e) { if (e instanceof QueryKitError) return res.status(400).json({ error: e.info }); }
+const body = error.response?.data?.error;
+if (isQueryKitError(body)) {
+  // body: { reason, site, key, source?, operation? }
+  if (body.reason === "forbidden-key" && body.site === "filter") showFieldError(body.key);
+}
+```
+
+`isQueryKitError` `reason` va `site` ni core ro'yxatidan tekshiradi, `key` — satr; boshqa har obyekt (masalan `{ statusCode: 400, message }`) → `false`.
+
 ## So'rovni o'zingiz yuborasiz
 
 Kutubxona faqat **so'rovgacha** ishlaydi. Transport yo'q:
@@ -486,7 +569,7 @@ const { data, meta } = users.parseList(await res.json());
 | `registry.resource<T>(name)`                                                      | entity-tipli builder/filter/schema/keys/parser         |
 | `resource.list/infinite/cursor/params(input)`                                     | payload qurish (offset/infinite/cursor/pagination'siz) |
 | `resource.f` / `createFilters<T>()` / `f`                                         | tipli filter builder / tipli / tipsiz                  |
-| `resource.search(term, fields)`                                                   | OR-of-contains preset                                  |
+| `resource.search(term, fields, { operation? })`                                   | OR preset (`contains` / `startsWith` / `endsWith`)     |
 | `resource.schema(desc)` / `defineListSchema(desc)`                                | URL param → filter tavsifi                             |
 | `resource.fromSearchParams(sp, {schema})`                                         | searchParams → list payload (SSR)                      |
 | `resource.keys`                                                                   | TanStack/SWR query keys                                |
@@ -495,11 +578,12 @@ const { data, meta } = users.parseList(await res.json());
 | `buildParams / buildListParams / buildInfiniteParams / buildCursorParams`         | standalone builder'lar                                 |
 | `createQuery(config)`                                                             | registry'siz builder (default'lar/pruneEmpty)          |
 | `schemaToFilter(schema, sp)`                                                      | searchParams → `FieldCondition[]`                      |
-| `searchParamsToPayload(schema, sp)`                                               | searchParams → to'liq payload                          |
-| `readListParams(schema, sp)`                                                      | searchParams → `ListParams`                            |
+| `searchParamsToPayload(schema, sp)`                                               | searchParams → to'liq payload (clamp, `clamped`)       |
+| `readListParams(schema, sp, url?, limits?)`                                       | searchParams → `ListParams` + `clamped`                |
+| `isQueryKitError(body)` / `QueryKitErrorBody`                                     | 400 javobidagi querykit xatosini tanish                |
 | `setParam/setPage/setSize/setSort/resetParams`                                    | URL yozish (immutable, page-reset)                     |
 | `encodeSort/decodeSort`                                                           | `[{key,direction}]` ↔ `"-createdAt,id"` (multi-field)  |
-| `useListParams(resource, {schema})` (`/react`)                                    | URL-sync hook (react-router-dom)                       |
+| `useListParams(resource, {schema})` (`/react`)                                    | URL-sync hook (react-router)                           |
 | `useListParamsBase(resource, {schema, searchParams, setSearchParams})` (`/react`) | router-agnostik hook                                   |
 
 ## Ishlab chiqish