@querykitjs/mongoose 2.0.0 → 3.0.0

package/README.en.md

@@ -69,6 +69,15 @@ bun add @querykitjs/mongoose mongoose
 
 `mongoose` (>= 8) is a peer dependency.
 
+### Requirements
+
+|                   | Version            | Tested (`bun run test:matrix`) |
+| ----------------- | ------------------ | ------------------------------ |
+| Node.js           | `>=22.12`          | 24                             |
+| `mongoose` (peer) | `^8.24 \|\| ^9.11` | 8.24.7, 9.11.4                 |
+
+Node 20 is no longer supported (`engines`: `>=22.12`). Peer ranges cover the last two majors; both ends are tested.
+
 ## Setup
 
 ### 1. Registry (once)
@@ -99,6 +108,12 @@ The `connection` is passed in (so transactions share the right session).
 `maxPerPage`/`maxLimit` are a **second layer**: even if validation
 (`@querykitjs/zod` factories) is bypassed, the repository clamps.
 
+`timestamps` — the createdAt / deletedAt field names (for example in a snake_case project): the default sort and the default `sortable` use that `createdAt`, soft delete (`softDelete`, `restore`, `withDeleted`) uses that `deletedAt`.
+
+```ts
+export const registry = createRegistry(mongoose.connection, { timestamps: { createdAt: "created_at", deletedAt: "deleted_at" } });
+```
+
 ### 2. Per-model repositories
 
 ```ts
@@ -199,6 +214,41 @@ A `scope` or `cursorKey` key is **always** fatal, regardless of `strict`.
 - **Cursor** keys on `_id` by default (override with `cursorKey`) — stable under inserts.
 - **Transactions need a replica set** — a single-node one is enough for local dev (`mongod --replSet rs0` then `rs.initiate()`, or [`mongodb-memory-server`](https://github.com/typegoose/mongodb-memory-server) in tests).
 
+- **Indexes and operators.** `startsWith` is an anchored (`^`) but case-insensitive (`i`) regex: MongoDB uses an index poorly for it. On a large collection keep a lowercase shadow field (`nameLower`) and give that `=` / `startsWith`. `contains`, `endsWith`, `!=` and `notIn` cannot use an index (COLLSCAN) — closed in the default `filterable`, open them only for small collections. Use `in` for enum fields.
+
+## Safe by default — `filterable`, `sortable`, `limits`
+
+A client filters and sorts only by the paths the server allows, and only with the operators it allows. A refused request stops with a `QueryKitError` before it reaches MongoDB — whatever `strict` and `onSkippedCondition` say. Option names, defaults and `reason`/`site` are the same as drizzle-pg's and prisma-pg's (`id` ≡ `_id`).
+
+```ts
+const usersRepository = registry.repository(User, {
+  forcedColumns: { _id: true, name: true, status: true, createdAt: true },
+  filterable: {
+    status: ["=", "in"],
+    createdAt: ["between", ">=", "<="],
+    name: ["startsWith"], // open only where listed
+  },
+  sortable: ["_id", "createdAt", "name"],
+  limits: { maxInItems: 500 },
+  maxTimeMS: 1000,
+});
+```
+
+| Option       | When not given (default)                                                                                | When refused                                                         |
+| ------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `filterable` | `allowedColumns` (else the `forcedColumns` keys, else only the primary key), with `"="` and `"in"` only | `reason: "forbidden-key"` / `"forbidden-operator"`, `site: "filter"` |
+| `sortable`   | the primary key and `createdAt` (when the table has it); a client-sent `cursorKey` too                  | `reason: "forbidden-key"`, `site: "sort"` / `"cursorKey"`            |
+| `limits`     | core `DEFAULT_QUERY_LIMITS` (depth 5, conditions 30, array 200, string 256, offset 10 000, sort 3)      | `reason: "limit-exceeded"`, `site: "filter"` / `"sort"` / `"page"`   |
+
+- `aggregate`: the `filter` and every `groupBy`/`sum`/`avg`/`min`/`max` column must be in `filterable` (`site: "aggregate"`).
+- `findById`: only the client `filter` is checked; `idKey` is the server's choice.
+- A key the table does **not** have (`nope`) stays `unknown-key` — skipped, or an error under `strict`.
+- Mutation filters (`updateMany`, `deleteMany`, …) count as server code and are not checked.
+- Operator aliases are one: `["="]` also admits `eq`, `["contains"]` also `%_%`. `"*"` admits every operator.
+- An unbranded raw Mongo filter (`{ $where: … }`, `{ secret: { $regex: … } }`, `{ $expr: … }`) can come from a JSON body — `forbidden-key`, nothing is sent (R19). Server code brands it with `raw({...})`; ⚠️ `raw()` is not checked by `filterable`.
+- LIKE patterns: more than `maxLikeWildcards` (2) `%`/`_` → `limit-exceeded`; a run of `%%` counts once.
+- Every read (`find`, `findOne`, `countDocuments`, `aggregate`) carries `maxTimeMS` (default 2 000); past it ⇒ `QueryKitTimeoutError` (`code: "QUERYKIT_TIMEOUT"`) — map it to 503/504, not 400.
+
 ## Advanced filters
 
 A filter is a tree of field conditions and logical groups (`and`/`or`/`not`). A flat array is treated as implicit `AND`. `id` resolves to `_id`.
@@ -232,6 +282,8 @@ Falls back to `createdAt DESC`, then `_id DESC`, when no sort is given — a det
 ```ts
 // 1. Offset — total_items / total_pages
 const page = await usersRepository.findList({ page: 2, perPage: 20, filter, sort });
+// withTotal: false — no count query (large tables): perPage + 1 rows, total_items / total_pages = null
+const fast = await usersRepository.findList({ page: 2, perPage: 20, withTotal: false });
 
 // 2. Infinite scroll (limit + offset) — has_more / next_offset
 const feed = await usersRepository.findInfinite({ limit: 20, offset: 40 });
@@ -242,8 +294,32 @@ const p2 = await usersRepository.findCursor({ limit: 20, cursor: p1.meta.next_cu
 const back = await usersRepository.findCursor({ cursor: p2.meta.prev_cursor, direction: "backward" });
 ```
 
+### Cursor: ties and signing
+
+- The seek key is `(cursorKey, _id)`: with a non-unique `cursorKey` (for example a shared `createdAt`) no row is skipped or repeated. When `cursorKey` is the primary key itself the seek uses that one field.
+- A token (v2) holds only scalar values (string, number, boolean, ISO date) and they are cast to the field type; an object, an array or a value that does not fit → `QueryKitError` `reason: "invalid-value"`, `site: "cursorKey"` (the driver is not called).
+- The registry option `cursorSecret` signs tokens with HMAC-SHA256; an unsigned or altered token → `invalid-value`. Without it tokens are unsigned — a client can build one itself (still only within the allowed `sortable` keys and the filter).
+
+```ts
+export const registry = createRegistry(mongoose.connection, { cursorSecret: process.env.CURSOR_SECRET });
+```
+
 ## Typed relations & field selection
 
+A client `with` opens only the relations listed in `relations` (task 014, R21):
+
+```ts
+const postsRepository = registry.repository(Post, {
+  relations: { author: { model: User, columns: ["name"] } }, // model — for typing only
+});
+await postsRepository.findAll({ with: { author: true } }); // author with name only
+```
+
+- `columns` is required — a list or an explicit `"*"`. `with: { rel: true }` also selects only those columns.
+- An unlisted relation, column, filter field or nested relation → `QueryKitError` `reason: "forbidden-key"`, `site: "with"`, `key` `relation` or `relation.field`; the driver is not called.
+- Allowed options: `select`, a nested `populate` (with `nested`), `match` (its fields in `filterable`; no `$where` / `$expr`), `options.limit` / `options.skip`.
+- The shorthand `{ author: User }` is for typing only: `with: { author: … }` → `forbidden-key`.
+
 Read methods infer their return type from `with` (populate) and `columns` — no manual generics:
 
 ```ts
@@ -255,10 +331,31 @@ rows[0].id; // ObjectId
 rows[0].email; // ❌ type error — not selected
 ```
 
-To type populated relations at runtime, pass the referenced models: `registry.repository(Post, { relations: { author: User } })`.
+To type and open populated relations, give the referenced model inside the rule: `registry.repository(Post, { relations: { author: { model: User, columns: ["name"] } } })` (the shorthand `{ author: User }` only types — it does not allow `with`).
+
+## Bulk update and delete
+
+`updateWhere` / `deleteWhere` are one write (no read before it) and return `{ count }`:
+
+```ts
+const { count } = await usersRepository.updateWhere([{ key: "status", value: "trial" }], { status: "expired" });
+await usersRepository.deleteWhere([{ key: "status", value: "expired" }]); // { count }
+
+// returning: { limit } — { count, rows }, at most limit rows (maxLimit, default 200)
+const { rows } = await usersRepository.updateWhere(filter, patch, { returning: { limit: 50 } });
+
+// no filter — only when you say so (the scope still applies)
+await usersRepository.deleteWhere({ all: true });
+```
+
+- An empty filter (`undefined`, `{}`, `[]`) or one whose every condition was skipped (for example only an unknown key) → `QueryKitError` `reason: "empty-filter"`, `site: "mutation"` — the driver is not called, the table is never wiped silently.
+- A mutation filter passes `filterable` and `limits` like a read's (`forbidden-key`, `forbidden-operator`, `limit-exceeded`) — the server's own filters too.
+- `rows` are **not** atomic: `updateWhere` reads them right **after** the update with the same filter (if the patch changes a filtered field, other documents may show up); `deleteWhere` reads them just **before** the delete. `count` is `matchedCount` / `deletedCount`.
 
 ## Transactions
 
+> ⚠️ Only **database work** inside the callback. External effects (HTTP calls, messages, email) go through an outbox: the driver may retry the transaction, and an external effect would run again and cannot be rolled back.
+
 ```ts
 await registry.transaction(async () => {
   await dispatchesRepository.create({ ... });
@@ -280,6 +377,57 @@ A scope can also be given as `registry.repository(Model, { scope })`. An unknown
 scope key **throws** when the repository is built — dropping it silently would
 remove the RBAC filter.
 
+A scope value may also be a list (task 014): `{ shopId: { in: [1, 2] } }` limits every read and write to those values; an empty list (`{ in: [] }`) matches no row (not an error). `create` fills in the equality scopes only.
+
+```ts
+const mine = repository.scoped({ shopId: { in: user.shopIds } });
+```
+
+## Values, NULL order and parity
+
+All three adapters (drizzle-pg, prisma-pg, mongoose) return the same result (task 021):
+
+- **Literal value operators.** `contains`, `startsWith` and `endsWith` match their value literally: `startsWith "%"` finds only rows starting with `%`, `contains "_"` a real `_`. Wildcards belong to `like` / `ilike` / `notLike` only.
+- **Type casting.** Every value is cast to its field type (number, boolean, date, ObjectId, enum). A mismatch (`age = "abc"`) is `invalid-value`: the condition is dropped and `onSkippedCondition` is called, a `QueryKitError` under `strict`; the driver is not called.
+- **`not`** follows SQL three-valued logic: `not(and(…))` / `not(or(…))` over a NULL field agree on every adapter.
+- **NULL order.** NULL first on `asc`, last on `desc` (MongoDB's order).
+- **A malformed sort item** (`null`, `{}`) is dropped and reported as `invalid-value` (`site: "sort"`), an error under `strict`.
+
+## Migrating to 3.0
+
+In 3.0 a repository without a policy is **narrow**: `=` and `in` on `allowedColumns` / `forcedColumns` / `_id` only, sorting by `_id` and `createdAt`. To bring back the 2.x behaviour for one repository on purpose:
+
+```ts
+const open = registry.repository(User, {
+  filterable: { _id: "*", name: "*", email: "*", status: "*", createdAt: "*" },
+  sortable: ["_id", "name", "email", "status", "createdAt"],
+});
+```
+
+A raw Mongo filter now needs `raw()` (R19):
+
+```ts
+import { raw } from "@querykitjs/core";
+
+// 2.x — forbidden-key in 3.0:
+// await usersRepository.findAll({ filter: { age: { $gt: 18 } } });
+
+// 3.0:
+await usersRepository.findAll({ filter: raw({ age: { $gt: 18 } }) });
+```
+
+- New reasons: `forbidden-key`, `forbidden-operator`, `limit-exceeded`; new site: `page` — return them as 400.
+- Pages deeper than offset 10 000 are refused — use `findCursor`, or raise `limits: { maxOffset }`.
+- Every read runs with `maxTimeMS: 2000`; raise `maxTimeMS` on the repository for long report queries. A timeout throws `QueryKitTimeoutError`.
+- A LIKE pattern with more than 2 wildcards is refused (`maxLikeWildcards`).
+- Cursor tokens are v2 now (task 012): an old (v1) `next_cursor` / `prev_cursor` is refused with `invalid-value` — after the upgrade start paging from the first page again.
+- `updateWhere` / `deleteWhere` return `{ count }` instead of `Row[]` (task 013); for rows pass `{ returning: { limit } }` → `{ count, rows }`.
+- A filterless `updateWhere` / `deleteWhere` is `empty-filter`; write `{ all: true }` for every row. A mutation filter now passes the `filterable` policy.
+- `OffsetMeta.total_items` / `total_pages` are typed `number | null` (`null` with `withTotal: false`).
+- `with` now needs the `relations` allow-list (task 014): on a repository without it `with` is `forbidden-key`, `site: "with"`.
+- `relations: { author: User }` → `relations: { author: { model: User, columns: ["name"] } }` (the shorthand no longer allows `with`).
+- A scope value may be `{ in: [...] }`; the registry option `timestamps` names the createdAt / deletedAt fields.
+
 ## Wire (JSON) values and migrating from DbService
 
 A request body is JSON, so a date always arrives as a **string**. The adapter
@@ -294,11 +442,9 @@ casts it according to the schema path:
   and leaves the rest to the database.
 - `in`/`notIn` arrays, `between`/`notBetween` tuples and cursor tokens are covered
   too (`cursorKey: "createdAt"` paginates correctly).
-- ⚠️ **Documented divergence:** Mongo cannot `$regex` a `Date` path
-  (`Can't use $options with Date`), so a text-pattern operator
-  (`contains`/`ilike`/…) on a date field is **skipped**. drizzle-pg _can_ match it
-  (Postgres renders the timestamp as text). Neither adapter crashes, and the
-  difference shows up in `onSkippedCondition`.
+- Mongo cannot `$regex` a `Date` path (`Can't use $options with Date`), so a
+  text-pattern operator (`contains`/`ilike`/…) on a date field is **skipped** as
+  `invalid-value` and reported in `onSkippedCondition` — the SQL adapters do the same.
 - An unparseable value (`"not-a-date"`) drops the condition (or 400s under
   `strict`). **One** bad element in an `in` list drops the whole condition.
 
@@ -327,22 +473,22 @@ await ordersRepository.aggregate({ sum: "amount", groupBy: "region" });
 
 ## API reference
 
-| Method                                                         | Returns                      |
-| -------------------------------------------------------------- | ---------------------------- |
-| `findAll(params?)`                                             | `Row[]`                      |
-| `findOne(params?)` / `findById(id, params?)`                   | `Row \| undefined`           |
-| `findList(params?)`                                            | `{ data, meta }` offset      |
-| `findInfinite(params?)`                                        | `{ data, meta }` infinite    |
-| `findCursor(params?)`                                          | `{ data, meta }` cursor      |
-| `count(filter?)` / `exists(filter?)`                           | `number` / `boolean`         |
-| `aggregate(spec)`                                              | `AggregateRow[]`             |
-| `create(values)` / `createMany(values)`                        | `Row` / `Row[]`              |
-| `upsert(values, opts)` / `upsertMany(values, opts)`            | `Row` / `Row[]`              |
-| `updateById(id, patch, idKey?)` / `updateWhere(filter, patch)` | `Row \| undefined` / `Row[]` |
-| `deleteById(id, idKey?)` / `deleteWhere(filter)`               | `Row \| undefined` / `Row[]` |
-| `softDelete(id)` / `restore(id)`                               | `Row \| undefined`           |
-| `scoped(scope)`                                                | scoped `Repository`          |
-| `registry.transaction(fn)`                                     | result of `fn`               |
+| Method                                                                   | Returns                                                               |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `findAll(params?)`                                                       | `Row[]`                                                               |
+| `findOne(params?)` / `findById(id, params?)`                             | `Row \| undefined`                                                    |
+| `findList(params?)`                                                      | `{ data, meta }` offset                                               |
+| `findInfinite(params?)`                                                  | `{ data, meta }` infinite                                             |
+| `findCursor(params?)`                                                    | `{ data, meta }` cursor                                               |
+| `count(filter?)` / `exists(filter?)`                                     | `number` / `boolean`                                                  |
+| `aggregate(spec)`                                                        | `AggregateRow[]`                                                      |
+| `create(values)` / `createMany(values)`                                  | `Row` / `Row[]`                                                       |
+| `upsert(values, opts)` / `upsertMany(values, opts)`                      | `Row` / `Row[]`                                                       |
+| `updateById(id, patch, idKey?)` / `updateWhere(filter, patch, options?)` | `Row \| undefined` / `{ count }` (`{ count, rows }` with `returning`) |
+| `deleteById(id, idKey?)` / `deleteWhere(filter, options?)`               | `Row \| undefined` / `{ count }` (`{ count, rows }` with `returning`) |
+| `softDelete(id)` / `restore(id)`                                         | `Row \| undefined`                                                    |
+| `scoped(scope)`                                                          | scoped `Repository`                                                   |
+| `registry.transaction(fn)`                                               | result of `fn`                                                        |
 
 ## Development
 

package/README.md

@@ -69,6 +69,15 @@ bun add @querykitjs/mongoose mongoose
 
 `mongoose` (>= 8) — peer dependency.
 
+### Talablar
+
+|                   | Versiya            | Tekshiriladi (`bun run test:matrix`) |
+| ----------------- | ------------------ | ------------------------------------ |
+| Node.js           | `>=22.12`          | 24                                   |
+| `mongoose` (peer) | `^8.24 \|\| ^9.11` | 8.24.7, 9.11.4                       |
+
+Node 20 endi qo'llab-quvvatlanmaydi (`engines`: `>=22.12`). Peer diapazoni — oxirgi ikki major; ikkala cheti testda.
+
 ## Sozlash
 
 ### 1. Registry (bir marta)
@@ -99,6 +108,12 @@ export const registry = createRegistry(mongoose.connection);
 `maxPerPage`/`maxLimit` — **ikkinchi himoya qatlami**: validatsiya
 (`@querykitjs/zod` factory'lari) chetlab o'tilsa ham repository o'zi clamp qiladi.
 
+`timestamps` — createdAt / deletedAt maydon nomlari (masalan snake_case loyihada): default sort va default `sortable` shu `createdAt`ni, soft-delete (`softDelete`, `restore`, `withDeleted`) shu `deletedAt`ni ishlatadi.
+
+```ts
+export const registry = createRegistry(mongoose.connection, { timestamps: { createdAt: "created_at", deletedAt: "deleted_at" } });
+```
+
 ### 2. Har model uchun repository
 
 ```ts
@@ -199,6 +214,41 @@ try {
 - **Cursor** default `_id` bo'yicha (`cursorKey` bilan o'zgartiring) — insert'larда barqaror.
 - **Tranzaksiya replica set talab qiladi** — lokal dev uchun bir-nodали yetarli (`mongod --replSet rs0` so'ng `rs.initiate()`, yoki testда [`mongodb-memory-server`](https://github.com/typegoose/mongodb-memory-server)).
 
+- **Indekslar va operatorlar.** `startsWith` — `^` bilan bog'langan, lekin registrga sezgirsiz (`i`) regex: MongoDB uni indeks bilan yomon ishlatadi. Katta kolleksiyada kichik harfli soya maydon (`nameLower`) saqlang va unga `=` / `startsWith` bering. `contains`, `endsWith`, `!=`, `notIn` indeksdan foydalana olmaydi (COLLSCAN) — default `filterable`da yopiq, faqat kichik kolleksiyalar uchun oching. Enum maydonlarida `in` ishlating.
+
+## Safe by default — `filterable`, `sortable`, `limits`
+
+Mijoz faqat server ruxsat bergan path bo'yicha, faqat ruxsat bergan operator bilan filtrlaydi va saralaydi. Ruxsatsiz so'rov MongoDB'ga yetmasdan `QueryKitError` bilan to'xtaydi — `strict` va `onSkippedCondition`dan qat'i nazar. Opsiya nomlari, default'lar, `reason`/`site` — drizzle-pg va prisma-pg bilan bir xil (`id` ≡ `_id`).
+
+```ts
+const usersRepository = registry.repository(User, {
+  forcedColumns: { _id: true, name: true, status: true, createdAt: true },
+  filterable: {
+    status: ["=", "in"],
+    createdAt: ["between", ">=", "<="],
+    name: ["startsWith"], // faqat shu yerda ochilgan
+  },
+  sortable: ["_id", "createdAt", "name"],
+  limits: { maxInItems: 500 },
+  maxTimeMS: 1000,
+});
+```
+
+| Opsiya       | Berilmasa (default)                                                                                                  | Rad etilsa                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `filterable` | `allowedColumns` (yo'q bo'lsa `forcedColumns` kalitlari, u ham yo'q bo'lsa faqat primary key), faqat `"="` va `"in"` | `reason: "forbidden-key"` / `"forbidden-operator"`, `site: "filter"` |
+| `sortable`   | primary key va `createdAt` (jadvalda bo'lsa); mijoz yuborgan `cursorKey` ham shu ro'yxatdan                          | `reason: "forbidden-key"`, `site: "sort"` / `"cursorKey"`            |
+| `limits`     | core `DEFAULT_QUERY_LIMITS` (chuqurlik 5, shartlar 30, massiv 200, satr 256, offset 10 000, sort 3)                  | `reason: "limit-exceeded"`, `site: "filter"` / `"sort"` / `"page"`   |
+
+- `aggregate`: `filter` va har `groupBy`/`sum`/`avg`/`min`/`max` ustuni `filterable` ichida bo'lishi shart (`site: "aggregate"`).
+- `findById`: faqat mijoz `filter`i tekshiriladi; `idKey` — server tanlovi.
+- Jadvalda **yo'q** kalit (`nope`) avvalgidek `unknown-key` — skip yoki `strict`da xato.
+- Mutatsiya metodlari (`updateMany`, `deleteMany`, …) filtri server kodi deb hisoblanadi va tekshirilmaydi.
+- Operator aliaslari bitta: `["="]` `eq`ni ham, `["contains"]` `%_%`ni ham ochadi. `"*"` — barcha operatorlar.
+- Brendsiz xom Mongo filtri (`{ $where: … }`, `{ secret: { $regex: … } }`, `{ $expr: … }`) JSON'dan kelishi mumkin — `forbidden-key`, so'rov yuborilmaydi (R19). Server kodi `raw({...})` bilan belgilaydi; ⚠️ `raw()` `filterable` bilan tekshirilmaydi.
+- LIKE naqshi: `maxLikeWildcards` (2) dan ko'p `%`/`_` → `limit-exceeded`; ketma-ket `%%` bitta hisoblanadi.
+- Har o'qish (`find`, `findOne`, `countDocuments`, `aggregate`) `maxTimeMS` (default 2 000) bilan; oshsa `QueryKitTimeoutError` (`code: "QUERYKIT_TIMEOUT"`) — uni 503/504 qiling, 400 emas.
+
 ## Ilg'or filterlar
 
 Filter — maydon shartlari va mantiqiy guruhlar (`and`/`or`/`not`) daraxti. Yassi massiv = implicit `AND`. `id` — `_id`ga o'giriladi.
@@ -232,6 +282,8 @@ Sort berilmasa `createdAt DESC` ga, u bo'lmasa `_id DESC` ga tushadi — paginat
 ```ts
 // 1. Offset — total_items / total_pages
 const page = await usersRepository.findList({ page: 2, perPage: 20, filter, sort });
+// withTotal: false — count so'ralmaydi (katta jadval): perPage + 1 qator, total_items / total_pages = null
+const fast = await usersRepository.findList({ page: 2, perPage: 20, withTotal: false });
 
 // 2. Infinite scroll (limit + offset) — has_more / next_offset
 const feed = await usersRepository.findInfinite({ limit: 20, offset: 40 });
@@ -242,8 +294,32 @@ const p2 = await usersRepository.findCursor({ limit: 20, cursor: p1.meta.next_cu
 const back = await usersRepository.findCursor({ cursor: p2.meta.prev_cursor, direction: "backward" });
 ```
 
+### Cursor: teng qiymatlar va imzo
+
+- Seek kaliti `(cursorKey, _id)`: `cursorKey` unikal bo'lmasa ham (masalan bir xil `createdAt`) hech bir qator tushib qolmaydi va takrorlanmaydi. `cursorKey` primary key'ning o'zi bo'lsa — bitta maydonli seek.
+- Token (v2) ichida faqat skalyar qiymat (satr, son, boolean, ISO sana) bo'ladi va maydon tipiga cast qilinadi; obyekt, massiv yoki mos kelmaydigan qiymat → `QueryKitError` `reason: "invalid-value"`, `site: "cursorKey"` (drayver chaqirilmaydi).
+- Registry opsiyasi `cursorSecret` token'ni HMAC-SHA256 bilan imzolaydi; imzosiz yoki o'zgartirilgan token → `invalid-value`. Usiz token imzosiz — mijoz uni o'zi yasay oladi (faqat ruxsat etilgan `sortable` kalit va filter doirasida).
+
+```ts
+export const registry = createRegistry(mongoose.connection, { cursorSecret: process.env.CURSOR_SECRET });
+```
+
 ## Tipli relation'lar va maydon tanlash
 
+Mijoz `with` bilan faqat `relations`da yozilgan relation'larni ochadi (task 014, R21):
+
+```ts
+const postsRepository = registry.repository(Post, {
+  relations: { author: { model: User, columns: ["name"] } }, // model — faqat tip uchun
+});
+await postsRepository.findAll({ with: { author: true } }); // author faqat name bilan
+```
+
+- `columns` majburiy — ro'yxat yoki aniq `"*"`. `with: { rel: true }` ham faqat shu ustunlarni tanlaydi.
+- Ro'yxatda yo'q relation, ustun, filtr maydoni yoki ichki relation → `QueryKitError` `reason: "forbidden-key"`, `site: "with"`, `key` — `relation` yoki `relation.field`; drayver chaqirilmaydi.
+- Ruxsat etilgan opsiyalar: `select`, ichki `populate` (`nested` bilan), `match` (maydonlari `filterable`da; `$where` / `$expr` yo'q), `options.limit` / `options.skip`.
+- Qisqa yozuv `{ author: User }` faqat tip uchun: `with: { author: … }` → `forbidden-key`.
+
 O'qish metodlari natija tipini `with` (populate) va `columns`dan chiqaradi — qo'lda generic yo'q:
 
 ```ts
@@ -255,10 +331,31 @@ rows[0].id; // ObjectId
 rows[0].email; // ❌ tip xatosi — tanlanmagan
 ```
 
-Populate qilingan relation'larni runtime'да tiplash uchun ref model'larni bering: `registry.repository(Post, { relations: { author: User } })`.
+Populate qilingan relation'larni tiplash va ochish uchun ref model'ni rule ichida bering: `registry.repository(Post, { relations: { author: { model: User, columns: ["name"] } } })` (qisqa `{ author: User }` faqat tip — `with`ga ruxsat bermaydi).
+
+## Ommaviy yangilash va o'chirish
+
+`updateWhere` / `deleteWhere` — bitta yozish so'rovi (oldin o'qish yo'q), natija `{ count }`:
+
+```ts
+const { count } = await usersRepository.updateWhere([{ key: "status", value: "trial" }], { status: "expired" });
+await usersRepository.deleteWhere([{ key: "status", value: "expired" }]); // { count }
+
+// returning: { limit } — `{ count, rows }`, ko'pi bilan limit ta qator (maxLimit, default 200)
+const { rows } = await usersRepository.updateWhere(filter, patch, { returning: { limit: 50 } });
+
+// filtrsiz — faqat aniq ko'rsatilsa (scope baribir qo'llanadi)
+await usersRepository.deleteWhere({ all: true });
+```
+
+- Bo'sh filtr (`undefined`, `{}`, `[]`) yoki hamma sharti tashlab yuborilgan filtr (masalan faqat noma'lum kalit) → `QueryKitError` `reason: "empty-filter"`, `site: "mutation"` — drayver chaqirilmaydi, jadval jim o'chmaydi.
+- Mutatsiya filtri o'qishdagidek `filterable` va `limits`dan o'tadi (`forbidden-key`, `forbidden-operator`, `limit-exceeded`). Server'ning o'z filtri ham.
+- `rows` atomar **emas**: `updateWhere` — yangilashdan **keyin** shu filtr bilan o'qiladi (patch filtrdagi maydonni o'zgartirsa, boshqa hujjatlar chiqishi mumkin); `deleteWhere` — o'chirishdan **oldin** o'qiladi. `count` — `matchedCount` / `deletedCount`.
 
 ## Tranzaksiya
 
+> ⚠️ Callback ichida **faqat DB amallari**. Tashqi amallar (HTTP, xabar, email) — outbox orqali: drayver tranzaksiyani qayta urinishi mumkin, tashqi amal esa takrorlanadi va qaytarib bo'lmaydi.
+
 ```ts
 await registry.transaction(async () => {
   await dispatchesRepository.create({ ... });
@@ -280,6 +377,57 @@ Scope'ni `registry.repository(Model, { scope })` bilan ham berish mumkin.
 Noma'lum scope kaliti — repository yaratilishida **xato** (jimgina tashlansa
 RBAC filtri yo'qolib ketardi).
 
+Scope qiymati ro'yxat ham bo'lishi mumkin (task 014): `{ shopId: { in: [1, 2] } }` — har o'qish va yozish shu qiymatlar bilan cheklanadi; bo'sh ro'yxat (`{ in: [] }`) — hech qanday qator (xato emas). `create` faqat tenglik scope'larini to'ldiradi.
+
+```ts
+const mine = repository.scoped({ shopId: { in: user.shopIds } });
+```
+
+## Qiymatlar, NULL tartibi va bir xillik
+
+Uchala adapter (drizzle-pg, prisma-pg, mongoose) bir xil natija beradi (task 021):
+
+- **Literal qiymat operatorlari.** `contains`, `startsWith`, `endsWith` qiymatni harfma-harf qidiradi: `startsWith "%"` faqat `%` bilan boshlanuvchi qatorlar, `contains "_"` — haqiqiy `_`. Wildcard faqat `like` / `ilike` / `notLike` da.
+- **Tip cast'i.** Har qiymat maydon tipiga keltiriladi (son, boolean, sana, ObjectId, enum). Mos kelmasa (`age = "abc"`) — `invalid-value`: shart tashlanadi va `onSkippedCondition` chaqiriladi, `strict` da `QueryKitError`; drayver chaqirilmaydi.
+- **`not`** — SQL uch qiymatli mantiq: NULL maydon bo'yicha `not(and(…))` / `not(or(…))` hamma adapterda bir xil.
+- **NULL tartibi.** `asc` — NULL birinchi, `desc` — NULL oxirida (MongoDB tartibi).
+- **Buzuq sort elementi** (`null`, `{}`) — tashlanadi va `invalid-value` (`site: "sort"`) bilan xabar qilinadi, `strict` da xato.
+
+## Migrating to 3.0
+
+3.0 da siyosatsiz repository **tor**: faqat `allowedColumns` / `forcedColumns` / `_id` bo'yicha `=` va `in`, sort — `_id` va `createdAt`. 2.x xulqini bitta repository uchun ataylab qaytarish:
+
+```ts
+const open = registry.repository(User, {
+  filterable: { _id: "*", name: "*", email: "*", status: "*", createdAt: "*" },
+  sortable: ["_id", "name", "email", "status", "createdAt"],
+});
+```
+
+Xom Mongo filtri endi `raw()` bilan (R19):
+
+```ts
+import { raw } from "@querykitjs/core";
+
+// 2.x — 3.0 da forbidden-key:
+// await usersRepository.findAll({ filter: { age: { $gt: 18 } } });
+
+// 3.0:
+await usersRepository.findAll({ filter: raw({ age: { $gt: 18 } }) });
+```
+
+- Yangi `reason`lar: `forbidden-key`, `forbidden-operator`, `limit-exceeded`; yangi `site`: `page` — 400 qiling.
+- Offset 10 000 dan chuqur sahifalar rad etiladi — `findCursor` ishlating yoki `limits: { maxOffset }` bilan oshiring.
+- Har o'qish `maxTimeMS: 2000` bilan; uzoqroq hisobot so'rovlari uchun repository'da `maxTimeMS`ni oshiring. Vaqt tugasa `QueryKitTimeoutError`.
+- LIKE naqshida 2 tadan ko'p wildcard rad etiladi (`maxLikeWildcards`).
+- Cursor token formati v2 (task 012): eski (v1) `next_cursor` / `prev_cursor` endi `invalid-value` bilan rad etiladi — yangilashdan keyin paginatsiyani birinchi sahifadan boshlang.
+- `updateWhere` / `deleteWhere` endi `Row[]` emas, `{ count }` qaytaradi (task 013); qatorlar kerak bo'lsa `{ returning: { limit } }` → `{ count, rows }`.
+- Filtrsiz `updateWhere` / `deleteWhere` → `empty-filter`; hamma qatorlar uchun `{ all: true }` yozing. Mutatsiya filtri endi `filterable` siyosatidan o'tadi.
+- `OffsetMeta.total_items` / `total_pages` tipi `number | null` (`withTotal: false` bilan `null`).
+- `with` endi faqat `relations` allow-list bilan ishlaydi (task 014): ro'yxatsiz repository'da `with` → `forbidden-key`, `site: "with"`.
+- `relations: { author: User }` → `relations: { author: { model: User, columns: ["name"] } }` (qisqa yozuv endi `with`ga ruxsat bermaydi).
+- Scope qiymati `{ in: [...] }` bo'lishi mumkin; `timestamps` registry opsiyasi createdAt / deletedAt nomlarini beradi.
+
 ## Wire (JSON) qiymatlari va DbService'dan migratsiya
 
 Backend so'rov body'sini JSON'da oladi, ya'ni sana har doim **string** bo'lib
@@ -294,11 +442,10 @@ keladi. Adapter uni schema path tipiga qarab avtomatik cast qiladi:
   hukm qiladi, qolganini bazaga qoldiradi.
 - `in`/`notIn` massivlari, `between`/`notBetween` tuple'lari va cursor token ham
   qamraladi (`cursorKey: "createdAt"` ishlaydi).
-- ⚠️ **Hujjatlashtirilgan farq:** Mongo `Date` path'da `$regex` qila olmaydi
-  (`Can't use $options with Date`), shuning uchun date maydonidagi text-pattern
-  operatori (`contains`/`ilike`/…) **tashlab yuboriladi**. drizzle-pg esa buni
-  bajaradi (Postgres timestamp'ni text sifatida render qiladi). Ikkalasi ham
-  crash qilmaydi; farq `onSkippedCondition`da ko'rinadi.
+- Mongo `Date` path'da `$regex` qila olmaydi (`Can't use $options with Date`),
+  shuning uchun date maydonidagi text-pattern operatori (`contains`/`ilike`/…)
+  `invalid-value` sifatida **tashlab yuboriladi** va `onSkippedCondition`da ko'rinadi —
+  SQL adapterlar ham shunday qiladi.
 - Parse bo'lmaydigan qiymat (`"not-a-date"`) shartni bekor qiladi (`strict`da —
   400). `in` ro'yxatidagi **bitta** yaroqsiz element butun shartni bekor qiladi.
 
@@ -327,22 +474,22 @@ await ordersRepository.aggregate({ sum: "amount", groupBy: "region" });
 
 ## API ma'lumotnoma
 
-| Metod                                                          | Qaytaradi                    |
-| -------------------------------------------------------------- | ---------------------------- |
-| `findAll(params?)`                                             | `Row[]`                      |
-| `findOne(params?)` / `findById(id, params?)`                   | `Row \| undefined`           |
-| `findList(params?)`                                            | `{ data, meta }` offset      |
-| `findInfinite(params?)`                                        | `{ data, meta }` infinite    |
-| `findCursor(params?)`                                          | `{ data, meta }` cursor      |
-| `count(filter?)` / `exists(filter?)`                           | `number` / `boolean`         |
-| `aggregate(spec)`                                              | `AggregateRow[]`             |
-| `create(values)` / `createMany(values)`                        | `Row` / `Row[]`              |
-| `upsert(values, opts)` / `upsertMany(values, opts)`            | `Row` / `Row[]`              |
-| `updateById(id, patch, idKey?)` / `updateWhere(filter, patch)` | `Row \| undefined` / `Row[]` |
-| `deleteById(id, idKey?)` / `deleteWhere(filter)`               | `Row \| undefined` / `Row[]` |
-| `softDelete(id)` / `restore(id)`                               | `Row \| undefined`           |
-| `scoped(scope)`                                                | scoped `Repository`          |
-| `registry.transaction(fn)`                                     | `fn` natijasi                |
+| Metod                                                                    | Qaytaradi                                                             |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `findAll(params?)`                                                       | `Row[]`                                                               |
+| `findOne(params?)` / `findById(id, params?)`                             | `Row \| undefined`                                                    |
+| `findList(params?)`                                                      | `{ data, meta }` offset                                               |
+| `findInfinite(params?)`                                                  | `{ data, meta }` infinite                                             |
+| `findCursor(params?)`                                                    | `{ data, meta }` cursor                                               |
+| `count(filter?)` / `exists(filter?)`                                     | `number` / `boolean`                                                  |
+| `aggregate(spec)`                                                        | `AggregateRow[]`                                                      |
+| `create(values)` / `createMany(values)`                                  | `Row` / `Row[]`                                                       |
+| `upsert(values, opts)` / `upsertMany(values, opts)`                      | `Row` / `Row[]`                                                       |
+| `updateById(id, patch, idKey?)` / `updateWhere(filter, patch, options?)` | `Row \| undefined` / `{ count }` (`{ count, rows }` with `returning`) |
+| `deleteById(id, idKey?)` / `deleteWhere(filter, options?)`               | `Row \| undefined` / `{ count }` (`{ count, rows }` with `returning`) |
+| `softDelete(id)` / `restore(id)`                                         | `Row \| undefined`                                                    |
+| `scoped(scope)`                                                          | scoped `Repository`                                                   |
+| `registry.transaction(fn)`                                               | `fn` natijasi                                                         |
 
 ## Ishlab chiqish