@querykitjs/prisma-pg 1.0.1 → 2.0.0

package/README.en.md

@@ -31,16 +31,35 @@ const { data, meta } = await usersRepository.findList({
 - **Soft delete** — automatic when the model has `deletedAt`; `softDelete`/`restore`/`withDeleted`.
 - **Upsert / bulk** — `upsert`, `upsertMany`.
 - **Framework-agnostic** — it knows nothing about HTTP: Express, Hono, NestJS, background jobs, all the same.
-- **Cross-adapter parity** — the same surface and the same results as `@querykitjs/drizzle-pg` and `@querykitjs/mongoose` ([PARITY.md](./PARITY.md)).
+- **Cross-adapter parity** — the same surface and the same results as `@querykitjs/drizzle-pg` and `@querykitjs/mongoose`.
 
 ## Install
 
 ```bash
-bun add @querykitjs/prisma-pg @prisma/client
-# or: npm i @querykitjs/prisma-pg @prisma/client
+bun add @querykitjs/prisma-pg @prisma/client @prisma/adapter-pg pg
+# or: npm i @querykitjs/prisma-pg @prisma/client @prisma/adapter-pg pg
 ```
 
-`@prisma/client` (>=5) is a peer dependency. The package never **imports** your generated client: it reads model metadata off your client instance at runtime and derives types from the delegate you pass in.
+`@prisma/client` (`^6.19 || ^7.10`) is a peer dependency; `@prisma/adapter-pg` and `pg` belong to your app (Prisma 7 requires a driver adapter). The package never **imports** your generated client: it reads model metadata off your client instance at runtime and derives types from the delegate you pass in.
+
+### Requirements
+
+|                         | Version            | Tested (`bun run test:matrix`) |
+| ----------------------- | ------------------ | ------------------------------ |
+| Node.js                 | `>=22.12`          | 24                             |
+| `@prisma/client` (peer) | `^6.19 \|\| ^7.10` | 6.19.3, 7.10.1                 |
+
+Node 20 is no longer supported (`engines`: `>=22.12`). Peer ranges cover the last two majors; both ends are tested.
+
+### Prisma 7 and Prisma 6
+
+The adapter reads model metadata from the client instance you pass in, so it works the same with either major. Both are tested (`test:matrix`) with the `prisma-client` generator and `@prisma/adapter-pg`.
+
+- **Prisma 7** — generator `provider = "prisma-client"` with an `output` (e.g. `"../generated/prisma"`); the datasource `url` lives in `prisma.config.ts`, not in the schema; build the client with a driver adapter as in the Setup below.
+- **Prisma 6.19** — the same generator and adapter work; keep `url = env("DATABASE_URL")` in the schema's `datasource` block. A `prisma-client-js` client created with `new PrismaClient()` keeps working too.
+- **Pitfall — non-`public` schema:** with a driver adapter Prisma ignores a `?schema=` parameter in the connection string, so queries go to `public`. Pass the schema to the adapter: `new PrismaPg({ connectionString }, { schema: "app" })`.
+
+**Migrating to Prisma 7:** switch the generator to `prisma-client` with an `output`, import `PrismaClient` from that output, install `@prisma/adapter-pg` + `pg` and pass `adapter`, and move the `url` to `prisma.config.ts`. Nothing changes in your `createRegistry` / repository code.
 
 ## Setup
 
@@ -48,15 +67,22 @@ bun add @querykitjs/prisma-pg @prisma/client
 
 ```ts
 // db/registry.ts
-import { PrismaClient } from "@prisma/client";
+import { PrismaPg } from "@prisma/adapter-pg";
 import { createRegistry } from "@querykitjs/prisma-pg";
+import { PrismaClient } from "../generated/prisma/client"; // `prisma-client` generator output
 
-export const prisma = new PrismaClient();
+export const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }) });
 export const registry = createRegistry(prisma);
 // or with pagination defaults:
 // export const registry = createRegistry(prisma, { defaultPerPage: 20, defaultLimit: 20 });
 ```
 
+`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(prisma, { timestamps: { createdAt: "created_at", deletedAt: "deleted_at" } });
+```
+
 ### 2. Repository (per model)
 
 A model is taken by its **handle**, the way drizzle-pg takes a table object and mongoose takes a `Model`. Its name (the delegate key, camelCase) works too: `User` → `"user"`, `LegalEntity` → `"legalEntity"`.
@@ -129,6 +155,39 @@ export class UsersController {
 
 A validated payload goes into the repository params with **no cast** — the contract is closed through `@querykitjs/core`.
 
+## Safe by default — `filterable`, `sortable`, `limits`
+
+A client filters and sorts only by the fields the server allows, and only with the operators it allows. A refused request stops with a `QueryKitError` before Prisma is called — whatever `strict` and `onSkippedCondition` say (it is never dropped silently). Option names, defaults and `reason`/`site` are the same as drizzle-pg's.
+
+```ts
+const usersRepository = registry.repository(prisma.user, {
+  forcedColumns: { id: true, name: true, email: true, createdAt: true },
+  filterable: {
+    email: ["=", "in"],
+    createdAt: ["between", ">=", "<="],
+    name: ["contains"], // "contains" and its token "%_%" are one operator
+    "posts.title": ["="], // a relation field — "relation.field"
+  },
+  sortable: ["id", "createdAt", "name"],
+  limits: { maxInItems: 500 }, // over the registry's createRegistry(..., { limits })
+});
+```
+
+| 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.
+- The policy applies to **every** read call on the repository — the server's own filters in custom methods too (`findBySlug` needs `slug` in `filterable`). For internal queries on fields you do not open to clients, build a separate, wider repository and never hand it to a route.
+- A relation field is opened or kept closed with a `"relation.field"` key (`posts.secret` not listed ⇒ `forbidden-key`). The adapter does not compile such a key into a filter (it stays `unknown-key`); use `raw()` for a relation predicate.
+- An unbranded raw Prisma `where` object (`{ secret: { startsWith: "a" } }`) can come from a JSON body — `forbidden-key` (R19). Server code brands it with `raw({...})`; ⚠️ a `raw()` node is not checked by `filterable`, never build one from request data.
+
 ## Advanced filters
 
 A filter is a tree of field conditions and logical groups (`and`/`or`/`not`). A flat array is implicit `AND`.
@@ -161,17 +220,19 @@ await usersRepository.findAll({
 
 `contains`/`startsWith`/`endsWith` are case-**insensitive** (`mode: "insensitive"`), `like` is case-**sensitive**, `ilike` is insensitive — exactly as in the drizzle-pg adapter.
 
-> **LIKE patterns.** Prisma has no raw SQL `LIKE` inside `where`, so the pattern is translated — **exactly**, so any pattern returns the same rows as on drizzle-pg: `%ali%` → `contains`, `ali%` → `startsWith`, `%ali` → `endsWith`, no wildcard → `equals`. Interior `%` and `_` are handled with two identities — `LIKE 'A%S'` ≡ `LIKE 'A%S%' AND LIKE '%S'`, and for a pattern with no `%`, `LIKE 'P'` ≡ `LIKE 'P%' AND NOT LIKE 'P_%'` (which pins the length). Only a **malformed** pattern (a dangling trailing `\`) is dropped and reported. Details: [PARITY.md](./PARITY.md) §5.1.
+> **LIKE patterns.** Prisma has no raw SQL `LIKE` inside `where`, so the pattern is translated — **exactly**, so any pattern returns the same rows as on drizzle-pg: `%ali%` → `contains`, `ali%` → `startsWith`, `%ali` → `endsWith`, no wildcard → `equals`. Interior `%` and `_` are handled with two identities — `LIKE 'A%S'` ≡ `LIKE 'A%S%' AND LIKE '%S'`, and for a pattern with no `%`, `LIKE 'P'` ≡ `LIKE 'P%' AND NOT LIKE 'P_%'` (which pins the length). Only a **malformed** pattern (a dangling trailing `\`) is dropped and reported.
 
 ### Raw `where` escape hatch
 
-For anything the DSL cannot express (relation predicates, JSON filters), pass a Prisma `where` object as a filter node:
+For anything the DSL cannot express (relation predicates, JSON filters), pass a Prisma `where` object branded with `raw()` as a filter node (R19 — an unbranded object is `forbidden-key`; ⚠️ `raw()` is not checked by `filterable`):
 
 ```ts
-await usersRepository.findAll({ filter: { posts: { some: { title: { contains: "querykit" } } } } });
+import { raw } from "@querykitjs/core";
+
+await usersRepository.findAll({ filter: raw({ posts: { some: { title: { contains: "querykit" } } } }) });
 
 await usersRepository.findAll({
-  filter: f.or(f.eq("role", "admin"), { posts: { some: { published: true } } }),
+  filter: f.or(f.eq("role", "admin"), raw({ posts: { some: { published: true } } })),
 });
 ```
 
@@ -219,6 +280,8 @@ Unknown keys are skipped; if no valid sort remains it falls back to `createdAt d
 // 1) Offset — with total_items/total_pages
 const list = await usersRepository.findList({ page: 2, perPage: 20 });
 list.meta; // { total_items, total_pages, current_page, per_page, has_next, has_prev }
+// 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 — no COUNT
 const feed = await postsRepository.findInfinite({ limit: 20, offset: 40 });
@@ -230,12 +293,35 @@ const p2 = await postsRepository.findCursor({ limit: 20, cursor: p1.meta.next_cu
 p1.meta; // { limit, has_next, has_prev, next_cursor, prev_cursor }
 ```
 
+### 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(prisma, { cursorSecret: process.env.CURSOR_SECRET });
+```
+
 `perPage`/`limit` are **capped** (`DEFAULT_MAX_PER_PAGE` = 200) — the repository clamps even if validation was bypassed.
 
 > Cursor tokens are **byte-identical** to the drizzle-pg and mongoose adapters', so an old token keeps working if the backend swaps ORMs.
 
 ## Typed `columns` and `with`
 
+A client `with` opens only the relations listed in `relations` (task 014, R21):
+
+```ts
+const usersRepository = registry.repository("user", {
+  relations: { posts: { columns: ["id", "title"], filterable: { published: "*" } } },
+});
+await usersRepository.findAll({ with: { posts: { where: { published: true }, take: 5 } } }); // posts: id, title
+```
+
+- `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 `include` (with `nested`), `where` (its fields in `filterable`), `take` / `skip`, `orderBy` on allowed columns.
+
 ```ts
 const picked = await usersRepository.findAll({ columns: { id: true, email: true } });
 //    ^? { id: number; email: string }[]   — `name` is not even in the type
@@ -255,8 +341,29 @@ A `with` value may be `true` or a Prisma relation config:
 await usersRepository.findAll({ with: { posts: { select: { title: true }, take: 5, orderBy: { createdAt: "desc" } } } });
 ```
 
+## 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.
+- `updateWhere` `rows` come from one `updateManyAndReturn` (atomic). `deleteWhere` `rows` are read **just before** the delete (Prisma has no `deleteManyAndReturn`) — not atomic: a row changed in between may or may not be listed.
+
 ## 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 () => {
   const user = await usersRepository.create({ name: "Ali", email: "ali@example.com" });
@@ -278,6 +385,12 @@ await mine.create({ title: "New" }); // authorId filled in automatically
 
 The scope is `AND`ed into every read/write and merged into inserts (scope wins). If a scope key does not resolve on the model, building the repository **throws** — dropping it silently would remove the 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 } });
+```
+
 ## Projection guards
 
 ```ts
@@ -318,13 +431,60 @@ await ordersRepository.aggregate({ sum: "amount", avg: "amount", groupBy: "regio
 >
 > **Bulk.** Prisma has no bulk upsert, so `upsertMany` issues sequential `upsert`s (input order preserved). Wrap large imports in `registry.transaction()`.
 
+## 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, uuid, 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). prisma-pg emits `{ sort, nulls }` only where the field is known to be optional (see Limitations).
+- **A malformed sort item** (`null`, `{}`) is dropped and reported as `invalid-value` (`site: "sort"`), an error under `strict`.
+
+## Migrating to 2.0
+
+In 2.0 a repository without a policy is **narrow**: `=` and `in` on `allowedColumns` / `forcedColumns` / the `@id` field only, sorting by `@id` and `createdAt`. To bring back the 1.x behaviour for one repository on purpose:
+
+```ts
+const open = registry.repository(prisma.user, {
+  filterable: { id: "*", name: "*", email: "*", age: "*", createdAt: "*" },
+  sortable: ["id", "name", "email", "age", "createdAt"],
+});
+```
+
+A raw `where` now needs `raw()` (R19):
+
+```ts
+import { raw } from "@querykitjs/core";
+
+// 1.x — forbidden-key in 2.0:
+// await usersRepository.findAll({ filter: { posts: { some: { published: true } } } });
+
+// 2.0:
+await usersRepository.findAll({ filter: raw({ posts: { some: { published: true } } }) });
+```
+
+- First collect from `onSkippedCondition` logs which fields and operators are in use, then narrow `filterable` to exactly those — `"*"` is a stopgap.
+- New `QueryKitError` reasons: `forbidden-key`, `forbidden-operator`, `limit-exceeded`; new site: `page`. Return them as 400.
+- Pages deeper than offset 10 000 are now refused — use `findCursor`, or raise it with `limits: { maxOffset }`.
+- 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"`.
+- A scope value may be `{ in: [...] }`; the registry option `timestamps` names the createdAt / deletedAt fields.
+
 ## Limitations
 
 - `updateById` / `deleteById` / `softDelete` / `restore` require a **single-field `@id`**. Prisma's `update`/`delete` accept only a unique `where`, while querykit's predicate also carries the scope and soft-delete guards. With a composite `@@id`, use `updateWhere`/`deleteWhere`.
 - Filter/sort keys are **Prisma field names** (`createdAt`), not DB columns (`created_at`) — Prisma's own `where` does not accept a `@map`ped name either.
 - Text operators only apply to `String` fields; on any other type the condition is dropped and reported.
 
-Full list and the three-adapter comparison: [PARITY.md](./PARITY.md).
+These are pinned by `test/contract.ts`, which asserts all three adapters agree on the same payload.
+
+- **`_` in `like` / `ilike`.** Prisma has no one-character wildcard: an unescaped `_` is `invalid-value` (an error under strict). Write `\\_` for a literal underscore.
+- **uuid fields.** When the runtime model does not expose `@db.Uuid`, a malformed uuid reaches Postgres (22P02 / P2023) unless the field is declared: `fields: [{ name: "ref", nativeType: "Uuid" }]` — then it is `invalid-value`.
+- **NULL order on Prisma 7.** Prisma 7's runtime model does not say whether a field is optional; `nulls` is emitted only when that is known. Declare it: `registry.repository(prisma.user, { fields: [{ name: "age", isRequired: false }] })` — otherwise that field keeps PostgreSQL's order.
 
 ## API reference
 

package/README.md

@@ -31,16 +31,35 @@ const { data, meta } = await usersRepository.findList({
 - **Soft-delete** — `deletedAt` maydoni bo'lsa avtomatik; `softDelete`/`restore`/`withDeleted`.
 - **Upsert / bulk** — `upsert`, `upsertMany`.
 - **Framework-agnostik** — HTTP'ni bilmaydi: Express, Hono, NestJS, fon vazifalari — hammasiga tushadi.
-- **Cross-adapter parity** — `@querykitjs/drizzle-pg` va `@querykitjs/mongoose` bilan bir xil yuza va bir xil natija ([PARITY.md](./PARITY.md)).
+- **Cross-adapter parity** — `@querykitjs/drizzle-pg` va `@querykitjs/mongoose` bilan bir xil yuza va bir xil natija.
 
 ## O'rnatish
 
 ```bash
-bun add @querykitjs/prisma-pg @prisma/client
-# yoki: npm i @querykitjs/prisma-pg @prisma/client
+bun add @querykitjs/prisma-pg @prisma/client @prisma/adapter-pg pg
+# yoki: npm i @querykitjs/prisma-pg @prisma/client @prisma/adapter-pg pg
 ```
 
-`@prisma/client` (>=5) — peer dependency. Paket generatsiya qilingan client'ni **import qilmaydi**: model metadata'sini ish vaqtida sizning client instansiyangizdan o'qiydi, tiplarni esa siz uzatgan delegate'dan chiqaradi.
+`@prisma/client` (`^6.19 || ^7.10`) — peer dependency; `@prisma/adapter-pg` va `pg` — ilovangizning bog'liqligi (Prisma 7 driver adapter talab qiladi). Paket generatsiya qilingan client'ni **import qilmaydi**: model metadata'sini ish vaqtida sizning client instansiyangizdan o'qiydi, tiplarni esa siz uzatgan delegate'dan chiqaradi.
+
+### Talablar
+
+|                         | Versiya            | Tekshiriladi (`bun run test:matrix`) |
+| ----------------------- | ------------------ | ------------------------------------ |
+| Node.js                 | `>=22.12`          | 24                                   |
+| `@prisma/client` (peer) | `^6.19 \|\| ^7.10` | 6.19.3, 7.10.1                       |
+
+Node 20 endi qo'llab-quvvatlanmaydi (`engines`: `>=22.12`). Peer diapazoni — oxirgi ikki major; ikkala cheti testda.
+
+### Prisma 7 va Prisma 6
+
+Adapter model metadata'sini siz bergan client instansiyasidan o'qiydi, shuning uchun ikkala major bilan bir xil ishlaydi. Ikkalasi ham `prisma-client` generatori va `@prisma/adapter-pg` bilan testda (`test:matrix`).
+
+- **Prisma 7** — generator `provider = "prisma-client"` va `output` (masalan `"../generated/prisma"`); datasource `url` sxemada emas, `prisma.config.ts` da; client quyidagi Sozlash'dagidek driver adapter bilan yaratiladi.
+- **Prisma 6.19** — xuddi shu generator va adapter ishlaydi; sxemaning `datasource` blokida `url = env("DATABASE_URL")` qoladi. `prisma-client-js` bilan `new PrismaClient()` orqali yaratilgan client ham ishlashda davom etadi.
+- **Tuzoq — `public` bo'lmagan schema:** driver adapter bilan Prisma connection string'dagi `?schema=` parametrini e'tiborsiz qoldiradi va so'rovlar `public`ga ketadi. Schema'ni adapterga bering: `new PrismaPg({ connectionString }, { schema: "app" })`.
+
+**Prisma 7 ga o'tish:** generatorni `output` bilan `prisma-client` ga almashtiring, `PrismaClient`ni shu chiqishdan import qiling, `@prisma/adapter-pg` + `pg` o'rnatib `adapter` bering, `url`ni `prisma.config.ts` ga ko'chiring. `createRegistry` / repository kodingizda hech narsa o'zgarmaydi.
 
 ## Sozlash
 
@@ -48,15 +67,22 @@ bun add @querykitjs/prisma-pg @prisma/client
 
 ```ts
 // db/registry.ts
-import { PrismaClient } from "@prisma/client";
+import { PrismaPg } from "@prisma/adapter-pg";
 import { createRegistry } from "@querykitjs/prisma-pg";
+import { PrismaClient } from "../generated/prisma/client"; // `prisma-client` generator chiqishi
 
-export const prisma = new PrismaClient();
+export const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }) });
 export const registry = createRegistry(prisma);
 // yoki pagination default'larini sozlab:
 // export const registry = createRegistry(prisma, { defaultPerPage: 20, defaultLimit: 20 });
 ```
 
+`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(prisma, { timestamps: { createdAt: "created_at", deletedAt: "deleted_at" } });
+```
+
 ### 2. Repository (model bo'yicha)
 
 Model **handle** bilan olinadi — `drizzle-pg` jadval obyektini, `mongoose` esa `Model`ni qabul qilgani kabi. Nom (delegate kaliti, camelCase) ham qabul qilinadi: `User` → `"user"`, `LegalEntity` → `"legalEntity"`.
@@ -129,6 +155,39 @@ export class UsersController {
 
 Validatsiyalangan payload repository params'iga **cast'siz** tushadi — kontrakt `@querykitjs/core` orqali yopilgan.
 
+## Safe by default — `filterable`, `sortable`, `limits`
+
+Mijoz faqat server ruxsat bergan maydon bo'yicha, faqat ruxsat bergan operator bilan filtrlaydi va saralaydi. Ruxsatsiz so'rov Prisma'ga yetmasdan `QueryKitError` bilan to'xtaydi — `strict` va `onSkippedCondition`dan qat'i nazar (jim tashlanmaydi). Opsiya nomlari, default'lar, `reason`/`site` — drizzle-pg bilan bir xil.
+
+```ts
+const usersRepository = registry.repository(prisma.user, {
+  forcedColumns: { id: true, name: true, email: true, createdAt: true },
+  filterable: {
+    email: ["=", "in"],
+    createdAt: ["between", ">=", "<="],
+    name: ["contains"], // "contains" va uning tokeni "%_%" — bitta operator
+    "posts.title": ["="], // relation maydoni — "relation.field"
+  },
+  sortable: ["id", "createdAt", "name"],
+  limits: { maxInItems: 500 }, // registry createRegistry(..., { limits }) ustidan
+});
+```
+
+| 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.
+- Siyosat repository'ning **har** o'qish chaqiruviga qo'llanadi — custom metodlardagi server filtrlari ham (`findBySlug` uchun `slug` `filterable`da). Mijozga ochilmaydigan maydon bo'yicha ichki so'rov uchun alohida, kengroq repository yarating va uni route'ga bermang.
+- Relation maydoni `"relation.field"` kaliti bilan yopiladi yoki ochiladi (`posts.secret` — ro'yxatda bo'lmasa `forbidden-key`). Adapter bunday kalitni filtr sifatida kompilyatsiya qilmaydi (avvalgidek `unknown-key`); relation predikati uchun `raw()` ishlating.
+- Brendsiz xom Prisma `where` obyekti (`{ secret: { startsWith: "a" } }`) JSON'dan kelishi mumkin — `forbidden-key` (R19). Server kodi `raw({...})` bilan belgilaydi; ⚠️ `raw()` tuguni `filterable` bilan tekshirilmaydi, uni so'rov ma'lumotidan qurmang.
+
 ## Advanced filterlar
 
 Filter — field shartlari va mantiqiy guruhlar (`and`/`or`/`not`) daraxti. Flat massiv implicit `AND`.
@@ -161,17 +220,19 @@ await usersRepository.findAll({
 
 `contains`/`startsWith`/`endsWith` — **case-insensitive** (`mode: "insensitive"`), `like` — case-sensitive, `ilike` — insensitive. Bu drizzle-pg adapteri bilan aynan bir xil.
 
-> **LIKE pattern'lari.** Prisma `where` ichida xom SQL `LIKE` yo'q, shuning uchun pattern tarjima qilinadi — lekin **aniq**, ya'ni har qanday pattern drizzle-pg bilan bir xil qatorlarni qaytaradi: `%ali%` → `contains`, `ali%` → `startsWith`, `%ali` → `endsWith`, wildcard'siz → `equals`. Ichki `%` va `_` uchun ikkita ayniyat ishlatiladi — `LIKE 'A%S'` ≡ `LIKE 'A%S%' AND LIKE '%S'`, va `%`siz pattern uchun `LIKE 'P'` ≡ `LIKE 'P%' AND NOT LIKE 'P_%'` (uzunlikni qadaydi). Faqat **buzuq** pattern (oxirida osilib qolgan `\`) tashlanadi va reportlanadi. Batafsil: [PARITY.md](./PARITY.md) §5.1.
+> **LIKE pattern'lari.** Prisma `where` ichida xom SQL `LIKE` yo'q, shuning uchun pattern tarjima qilinadi — lekin **aniq**, ya'ni har qanday pattern drizzle-pg bilan bir xil qatorlarni qaytaradi: `%ali%` → `contains`, `ali%` → `startsWith`, `%ali` → `endsWith`, wildcard'siz → `equals`. Ichki `%` va `_` uchun ikkita ayniyat ishlatiladi — `LIKE 'A%S'` ≡ `LIKE 'A%S%' AND LIKE '%S'`, va `%`siz pattern uchun `LIKE 'P'` ≡ `LIKE 'P%' AND NOT LIKE 'P_%'` (uzunlikni qadaydi). Faqat **buzuq** pattern (oxirida osilib qolgan `\`) tashlanadi va reportlanadi.
 
 ### Xom `where` escape-hatch
 
-DSL ifodalay olmaydigan narsalar (relation predikatlari, `mode`, JSON filtrlari) uchun to'g'ridan-to'g'ri Prisma `where` obyekti tugun sifatida beriladi:
+DSL ifodalay olmaydigan narsalar (relation predikatlari, `mode`, JSON filtrlari) uchun Prisma `where` obyekti `raw()` bilan belgilanib tugun sifatida beriladi (R19 — brendsiz obyekt `forbidden-key`; ⚠️ `raw()` `filterable`dan o'tmaydi):
 
 ```ts
-await usersRepository.findAll({ filter: { posts: { some: { title: { contains: "querykit" } } } } });
+import { raw } from "@querykitjs/core";
+
+await usersRepository.findAll({ filter: raw({ posts: { some: { title: { contains: "querykit" } } } }) });
 
 await usersRepository.findAll({
-  filter: f.or(f.eq("role", "admin"), { posts: { some: { published: true } } }),
+  filter: f.or(f.eq("role", "admin"), raw({ posts: { some: { published: true } } })),
 });
 ```
 
@@ -219,6 +280,8 @@ Noma'lum kalit skip qilinadi; yaroqli sort qolmasa `createdAt desc`, u ham bo'lm
 // 1) Offset — total_items/total_pages bilan
 const list = await usersRepository.findList({ page: 2, perPage: 20 });
 list.meta; // { total_items, total_pages, current_page, per_page, has_next, has_prev }
+// 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 — COUNT'siz
 const feed = await postsRepository.findInfinite({ limit: 20, offset: 40 });
@@ -230,12 +293,35 @@ const p2 = await postsRepository.findCursor({ limit: 20, cursor: p1.meta.next_cu
 p1.meta; // { limit, has_next, has_prev, next_cursor, prev_cursor }
 ```
 
+### 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(prisma, { cursorSecret: process.env.CURSOR_SECRET });
+```
+
 `perPage`/`limit` **cheklangan** (`DEFAULT_MAX_PER_PAGE` = 200) — validatsiya chetlab o'tilsa ham repository o'zi clamp qiladi.
 
 > Cursor tokeni `drizzle-pg` va `mongoose` adapterlari bilan **bayt-ma-bayt bir xil** — backend ORM'i almashsa ham eski token ishlayveradi.
 
 ## Tipli `columns` va `with`
 
+Mijoz `with` bilan faqat `relations`da yozilgan relation'larni ochadi (task 014, R21):
+
+```ts
+const usersRepository = registry.repository("user", {
+  relations: { posts: { columns: ["id", "title"], filterable: { published: "*" } } },
+});
+await usersRepository.findAll({ with: { posts: { where: { published: true }, take: 5 } } }); // posts: id, title
+```
+
+- `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 `include` (`nested` bilan), `where` (maydonlari `filterable`da), `take` / `skip`, ruxsat etilgan ustunlar bo'yicha `orderBy`.
+
 ```ts
 const picked = await usersRepository.findAll({ columns: { id: true, email: true } });
 //    ^? { id: number; email: string }[]   — `name` tipda ham yo'q
@@ -255,8 +341,29 @@ const both = await usersRepository.findAll({ columns: { id: true }, with: { post
 await usersRepository.findAll({ with: { posts: { select: { title: true }, take: 5, orderBy: { createdAt: "desc" } } } });
 ```
 
+## 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.
+- `updateWhere` `rows` — bitta `updateManyAndReturn` natijasi (atomar). `deleteWhere` `rows` — o'chirishdan **oldin** o'qiladi (Prisma'da `deleteManyAndReturn` yo'q) — atomar emas: orada o'zgargan qator ro'yxatda bo'lishi yoki bo'lmasligi mumkin.
+
 ## Tranzaksiyalar
 
+> ⚠️ 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 () => {
   const user = await usersRepository.create({ name: "Ali", email: "ali@example.com" });
@@ -278,6 +385,12 @@ await mine.create({ title: "Yangi" }); // authorId avtomatik qo'yiladi
 
 Scope har bir o'qish/yozishga `AND` bilan qo'shiladi va insert'larga singdiriladi (scope ustun keladi). Scope kaliti model'da topilmasa repository **yaratilishida** xato beradi — jimgina tushib qolsa filtr yo'qolardi.
 
+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 } });
+```
+
 ## Projeksiya guard'lari
 
 ```ts
@@ -318,13 +431,60 @@ await ordersRepository.aggregate({ sum: "amount", avg: "amount", groupBy: "regio
 >
 > **Bulk.** Prisma'da bulk upsert yo'q — `upsertMany` ketma-ket `upsert` qiladi (kirish tartibi saqlanadi). Katta importlar uchun `registry.transaction()` ichida chaqiring.
 
+## 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, uuid, 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). prisma-pg `{ sort, nulls }` ni faqat maydon ixtiyoriy ekani ma'lum bo'lsa qo'yadi (pastdagi Cheklovlar).
+- **Buzuq sort elementi** (`null`, `{}`) — tashlanadi va `invalid-value` (`site: "sort"`) bilan xabar qilinadi, `strict` da xato.
+
+## Migrating to 2.0
+
+2.0 da siyosatsiz repository **tor**: faqat `allowedColumns` / `forcedColumns` / `@id` maydoni bo'yicha `=` va `in`, sort — `@id` va `createdAt`. 1.x xulqini bitta repository uchun ataylab qaytarish:
+
+```ts
+const open = registry.repository(prisma.user, {
+  filterable: { id: "*", name: "*", email: "*", age: "*", createdAt: "*" },
+  sortable: ["id", "name", "email", "age", "createdAt"],
+});
+```
+
+Xom `where` endi `raw()` bilan (R19):
+
+```ts
+import { raw } from "@querykitjs/core";
+
+// 1.x — 2.0 da forbidden-key:
+// await usersRepository.findAll({ filter: { posts: { some: { published: true } } } });
+
+// 2.0:
+await usersRepository.findAll({ filter: raw({ posts: { some: { published: true } } }) });
+```
+
+- Avval `onSkippedCondition` loglaridan ishlatilayotgan maydon/operatorlarni yig'ing, keyin `filterable`ni aynan shularga toraytiring — `"*"` vaqtinchalik yo'l.
+- `QueryKitError`ning yangi `reason`lari: `forbidden-key`, `forbidden-operator`, `limit-exceeded`; yangi `site`: `page`. Ularni 400 qilib qaytaring.
+- Offset 10 000 dan chuqur sahifalar endi rad etiladi — `findCursor` ishlating yoki `limits: { maxOffset }` bilan oshiring.
+- 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"`.
+- Scope qiymati `{ in: [...] }` bo'lishi mumkin; `timestamps` registry opsiyasi createdAt / deletedAt nomlarini beradi.
+
 ## Cheklovlar
 
 - `updateById` / `deleteById` / `softDelete` / `restore` — **bitta maydonli `@id`** talab qiladi. Prisma `update`/`delete` faqat unique `where` qabul qiladi, querykit predikati esa scope va soft-delete guard'ini ham olib yuradi. Kompozit `@@id` bo'lsa `updateWhere`/`deleteWhere` ishlating.
 - Filter/sort kalitlari — **Prisma maydon nomi** (`createdAt`), DB ustun nomi (`created_at`) emas. Prisma `where`ning o'zi ham `@map`langan nomni qabul qilmaydi.
 - Matn operatorlari faqat `String` maydonlarda; boshqa tipda shart tashlanadi va reportlanadi.
 
-To'liq ro'yxat va uchala adapter solishtiruvi: [PARITY.md](./PARITY.md).
+Bu farqlar `test/contract.ts` bilan qadalgan — uchala adapter bir xil payloaddan bir xil natija berishi shu yerda tekshiriladi.
+
+- **`like` / `ilike` da `_`.** Prisma'da bitta belgili wildcard yo'q: qochirilmagan `_` → `invalid-value` (strict'da xato). Literal `_` uchun `\\_` yozing.
+- **uuid maydonlari.** Runtime model `@db.Uuid` ni bermasa, noto'g'ri uuid Postgres'ga yetadi (22P02 / P2023) — maydonni e'lon qiling: `fields: [{ name: "ref", nativeType: "Uuid" }]`, shunda `invalid-value`.
+- **NULL tartibi Prisma 7 da.** Prisma 7 runtime modeli maydon ixtiyoriymi-yo'qligini bermaydi; `nulls` faqat ma'lum bo'lsa qo'yiladi. Ixtiyoriy maydonni e'lon qiling: `registry.repository(prisma.user, { fields: [{ name: "age", isRequired: false }] })` — aks holda o'sha maydonda PostgreSQL tartibi.
 
 ## API ma'lumotnoma