@querykitjs/prisma-pg 1.0.0 → 2.0.0

package/dist/index.d.cts

@@ -1,53 +1,16 @@
-import { Types } from '@prisma/client/runtime/library';
 import * as _querykitjs_core from '@querykitjs/core';
-import { SkippedCondition } from '@querykitjs/core';
+import { AllRows, MutationCount, MutationRows, Relations, SkippedCondition, QueryLimits } from '@querykitjs/core';
 export { f } from '@querykitjs/core';
+import { Types } from '@prisma/client/runtime/client';
 
 /**
- * Model metadata — the Prisma counterpart of drizzle's `columns.ts` and
- * mongoose's `fields.ts`.
- *
- * Prisma's `where` is keyed by **model field name** (camelCase), never by the DB
- * column — but a client may well send `created_at`, which drizzle-pg accepts. So
- * each field's `@map`ped column is recorded as an alias and `resolveField`
- * translates it back, keeping the two Postgres adapters interchangeable.
- *
- * Getting the field list without importing the generated client is the other
- * half of the job: this package must typecheck with no generated client present,
- * so metadata is read off the client **instance** at runtime, through a fallback
- * chain.
+ * Prisma type utilities the public types are built from. Not re-exported by
+ * `types/index.ts`: they are implementation helpers, not part of the API.
  */
-/** One model field, normalized across every metadata source. */
-interface FieldMeta {
-    name: string;
-    /** Prisma type name: `"Int"`, `"String"`, `"DateTime"`, an enum or model name, … */
-    type: string;
-    kind: "scalar" | "enum" | "object" | "unsupported";
-    isId: boolean;
-    /** `@updatedAt` — Prisma bumps these itself, so the adapter must not. */
-    isUpdatedAt: boolean;
-    isList: boolean;
-    /** The `@map`ped database column, when it differs from the field name. */
-    dbName?: string;
-}
-/** Everything the repository needs to know about one model. */
-interface ModelMeta {
-    /** Prisma model name (`"User"`) — used as the diagnostics `source`. */
-    name: string;
-    fields: Map<string, FieldMeta>;
-    /** `@map`ped DB column → Prisma field name, so `created_at` also resolves. */
-    byDbName: Map<string, string>;
-    /** The `@id` field name; undefined for a composite `@@id`. */
-    idField: string | undefined;
-    /** Fields that uniquely address a row — one `@id`, or every `@@id` field. */
-    primaryKey: string[];
-    /** Prisma's name for a composite key (`@@id(name:)`), else the joined fields. */
-    primaryKeyName: string | undefined;
-    hasDeletedAt: boolean;
-    /** Present only when the field exists **and** is not `@updatedAt`-managed. */
-    stampUpdatedAt: string | undefined;
-    hasCreatedAt: boolean;
-}
+
+type ArgsOf<TDelegate, TOperation extends Types.Public.Operation> = Types.Public.Args<TDelegate, TOperation>;
+/** One row with the given Prisma args applied (`select` / `include`). */
+type RowWith<TDelegate, TArgs> = Types.Public.Result<TDelegate, TArgs, "findFirstOrThrow">;
 
 /**
  * QueryKit Prisma adapter — public types. The DSL/filter/meta types come from
@@ -60,8 +23,9 @@ interface ModelMeta {
  * names, same semantics, one shared source in core.
  *
  * ⚠️ This file must never import from `@prisma/client` itself — only from
- * `@prisma/client/runtime/library`, which exists whether or not a client has been
- * generated. That is what lets the package typecheck and build in CI with no
+ * `@prisma/client/runtime/client`, which exists whether or not a client has been
+ * generated (Prisma 6.19 and 7 both ship it; 7 has no `runtime/library`). That
+ * is what lets the package typecheck and build in CI with no
  * `prisma generate` step, while still inferring exact row types in a consumer's
  * project. `Types.Public.*` are Prisma's own public type utilities; the generated
  * client re-exports the very same ones as `Prisma.Result` / `Prisma.Args`.
@@ -84,9 +48,6 @@ type ModelKey<TClient> = {
 }[keyof TClient & string];
 /** The delegate behind a model key. */
 type DelegateOf<TClient, TKey extends ModelKey<TClient>> = TClient[TKey];
-type ArgsOf<TDelegate, TOperation extends Types.Public.Operation> = Types.Public.Args<TDelegate, TOperation>;
-/** One row with the given Prisma args applied (`select` / `include`). */
-type RowWith<TDelegate, TArgs> = Types.Public.Result<TDelegate, TArgs, "findFirstOrThrow">;
 /** Full row shape of a model (what reads return with no `columns`/`with`). */
 type Row<TDelegate> = RowWith<TDelegate, Record<string, never>>;
 /** Insertable shape — the model's `create` data. */
@@ -160,10 +121,13 @@ type UpsertOptions<TDelegate = AnyDelegate> = _querykitjs_core.UpsertOptions<Fie
 type AggregateSpec<TDelegate = AnyDelegate> = _querykitjs_core.AggregateSpec<FieldKey<TDelegate>, Filter<TDelegate>>;
 /** One aggregated result row (group fields + aggregate values). */
 type AggregateRow = Record<string, unknown>;
+
 /** Offset (classic page-based) pagination. */
 interface OffsetParams<TDelegate = AnyDelegate> extends QueryParams<TDelegate> {
     page?: number;
     perPage?: number;
+    /** `false` — no count query: `perPage + 1` rows are read, `total_items` / `total_pages` are `null` (task 013). Default `true`. */
+    withTotal?: boolean;
 }
 type OffsetMeta = _querykitjs_core.OffsetMeta;
 interface OffsetResult<T> {
@@ -197,6 +161,7 @@ interface CursorResult<T> {
     data: T[];
     meta: CursorMeta;
 }
+
 type TrueKeys<T> = {
     [K in keyof T]: T[K] extends true ? K : never;
 }[keyof T];
@@ -273,12 +238,32 @@ interface Repository<TDelegate = AnyDelegate> {
     upsertMany(values: Insert<TDelegate>[], options: UpsertOptions<TDelegate>): Promise<Row<TDelegate>[]>;
     /** Update one row by id; returns the updated row (or `undefined`). */
     updateById(id: Id, patch: Partial<Insert<TDelegate>>, idKey?: FieldKey<TDelegate>): Promise<Row<TDelegate> | undefined>;
-    /** Update every row matching the filter; returns the updated rows. */
-    updateWhere(filter: Filter<TDelegate>, patch: Partial<Insert<TDelegate>>): Promise<Row<TDelegate>[]>;
+    /**
+     * Update every row matching the filter in one atomic `updateMany` → `{ count }` (task 013).
+     * No filter only with `{ all: true }` (the scope still applies); an empty or fully skipped
+     * filter is `QueryKitError` `empty-filter`. The filter passes the request policy like a read.
+     */
+    updateWhere(filter: Filter<TDelegate> | AllRows, patch: Partial<Insert<TDelegate>>, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` from one atomic `updateManyAndReturn`, at most `limit` rows. */
+    updateWhere(filter: Filter<TDelegate> | AllRows, patch: Partial<Insert<TDelegate>>, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDelegate>>>;
     /** Hard-delete one row by id; returns the deleted row (or `undefined`). */
     deleteById(id: Id, idKey?: FieldKey<TDelegate>): Promise<Row<TDelegate> | undefined>;
-    /** Hard-delete every row matching the filter; returns the deleted rows. */
-    deleteWhere(filter: Filter<TDelegate>): Promise<Row<TDelegate>[]>;
+    /** Hard-delete every row matching the filter in one `deleteMany` → `{ count }` (same rules as `updateWhere`). */
+    deleteWhere(filter: Filter<TDelegate> | AllRows, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` — the rows are read just before the delete (not atomic). */
+    deleteWhere(filter: Filter<TDelegate> | AllRows, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDelegate>>>;
     /** Soft-delete (set `deletedAt`); requires a `deletedAt` field. */
     softDelete(id: Id, idKey?: FieldKey<TDelegate>): Promise<Row<TDelegate> | undefined>;
     /** Restore a soft-deleted row (`deletedAt = null`). */
@@ -293,6 +278,69 @@ interface Repository<TDelegate = AnyDelegate> {
 }
 /** Extends a base repository with custom, model-specific methods. */
 type RepositoryExtender<TDelegate, TExt extends Record<string, unknown>> = (base: Repository<TDelegate>) => TExt;
+
+/**
+ * Model metadata — the Prisma counterpart of drizzle's `columns.ts` and
+ * mongoose's `fields.ts`.
+ *
+ * Prisma's `where` is keyed by **model field name** (camelCase), never by the DB
+ * column — but a client may well send `created_at`, which drizzle-pg accepts. So
+ * each field's `@map`ped column is recorded as an alias and `resolveField`
+ * translates it back, keeping the two Postgres adapters interchangeable.
+ *
+ * Getting the field list without importing the generated client is the other
+ * half of the job: this package must typecheck with no generated client present,
+ * so metadata is read off the client **instance** at runtime, through a fallback
+ * chain.
+ */
+/** One model field, normalized across every metadata source. */
+interface FieldMeta {
+    name: string;
+    /** Prisma type name: `"Int"`, `"String"`, `"DateTime"`, an enum or model name, … */
+    type: string;
+    kind: "scalar" | "enum" | "object" | "unsupported";
+    isId: boolean;
+    /** `@updatedAt` — Prisma bumps these itself, so the adapter must not. */
+    isUpdatedAt: boolean;
+    isList: boolean;
+    /** The `@map`ped database column, when it differs from the field name. */
+    dbName?: string;
+    /** `false` for an optional (nullable) field — Prisma accepts `nulls` in `orderBy` only there (task 021 B11). */
+    isRequired?: boolean;
+    /** The database type (`"Uuid"` for `@db.Uuid`) — from the runtime model when it has one, or the `fields` override (task 021 B8). */
+    nativeType?: string;
+    /** An enum field's values (from the runtime data model), for the task 021 B8 cast. */
+    enumValues?: readonly string[];
+}
+/** Everything the repository needs to know about one model. */
+interface ModelMeta {
+    /** Prisma model name (`"User"`) — used as the diagnostics `source`. */
+    name: string;
+    fields: Map<string, FieldMeta>;
+    /** `@map`ped DB column → Prisma field name, so `created_at` also resolves. */
+    byDbName: Map<string, string>;
+    /** The `@id` field name; undefined for a composite `@@id`. */
+    idField: string | undefined;
+    /** Fields that uniquely address a row — one `@id`, or every `@@id` field. */
+    primaryKey: string[];
+    /** Prisma's name for a composite key (`@@id(name:)`), else the joined fields. */
+    primaryKeyName: string | undefined;
+    hasDeletedAt: boolean;
+    /** Present only when the field exists **and** is not `@updatedAt`-managed. */
+    stampUpdatedAt: string | undefined;
+    hasCreatedAt: boolean;
+}
+/**
+ * Read a model's metadata off a live Prisma client, trying, in order:
+ * `_runtimeDataModel` → `delegate.fields` → the caller-supplied `override`.
+ *
+ * Throws when none of them work — the same reasoning as drizzle's "table not in
+ * schema" error: a repository built on unknown metadata would silently skip
+ * *every* filter key and return the whole table.
+ */
+/** A `fields` override entry: a full field, or a patch of a discovered one by `name` (e.g. `{ name: "age", isRequired: false }`). */
+type FieldOverride = Pick<FieldMeta, "name"> & Partial<FieldMeta>;
+
 /** {@link createRegistry} options — pagination defaults and bounds. */
 interface RegistryOptions {
     /** `findList` default page size (core `DEFAULT_PER_PAGE` = 20). */
@@ -321,6 +369,27 @@ interface RegistryOptions {
      * path: watch with the hook first, flip `strict: true` once the log is clean.
      */
     onSkippedCondition?: (info: _querykitjs_core.SkippedCondition) => void;
+    /**
+     * Server-side request limits (core `DEFAULT_QUERY_LIMITS`: depth 5, conditions 30,
+     * array 200, string 256, offset 10 000, sort 3) — enforced even when validation was
+     * bypassed. Past one ⇒ `QueryKitError` (`reason: "limit-exceeded"`). A repository's
+     * own `limits` win.
+     */
+    limits?: Partial<_querykitjs_core.QueryLimits>;
+    /**
+     * Signs cursor tokens (HMAC-SHA256, task 012). With it a token that was not
+     * issued by this server — or was changed — is `invalid-value`. Without it tokens
+     * are unsigned but still checked (scalar values, v2 shape).
+     */
+    cursorSecret?: string;
+    /**
+     * The createdAt / deletedAt field names (task 014; default `createdAt`, `deletedAt`): the default
+     * sort and the default `sortable` use `createdAt`, soft delete uses `deletedAt`.
+     */
+    timestamps?: {
+        createdAt?: string;
+        deletedAt?: string;
+    };
 }
 /**
  * Options for `registry.repository(model, options)`.
@@ -336,6 +405,12 @@ interface RegistryOptions {
  * yourself, before handing a write result to a client.
  */
 interface RepositoryOptions<TDelegate = AnyDelegate> {
+    /**
+     * Relations a client may open with `with` (task 014, R21): relation → `{ columns, filterable?, nested? }`.
+     * `columns` is required (a list or `"*"`); an unlisted relation, column, `where` field or nested
+     * `include` is `QueryKitError` `forbidden-key`, `site: "with"`. Without it `with` opens nothing.
+     */
+    relations?: Relations;
     /** Constant equality filter added to every read/write (RBAC / multi-tenancy). */
     scope?: Scope<TDelegate>;
     /**
@@ -355,7 +430,24 @@ interface RepositoryOptions<TDelegate = AnyDelegate> {
      * the Prisma client itself (it tries `_runtimeDataModel`, then the public
      * `delegate.fields`) — e.g. behind an unusual client wrapper.
      */
-    fields?: readonly FieldMeta[];
+    fields?: readonly FieldOverride[];
+    /**
+     * Fields a client may filter by, and the operators for each (`"*"` — all). A
+     * relation field is `"relation.field"` (`"posts.title": ["="]`). A field not
+     * listed ⇒ `reason: "forbidden-key"`, an operator not listed ⇒ `"forbidden-operator"`
+     * — a `QueryKitError` whatever `strict` says, before Prisma is called.
+     * **When not given** — `allowedColumns` (else the `forcedColumns` keys, else only
+     * the `@id` field) with `"="` and `"in"` only. `aggregate` fields come from this list too.
+     */
+    filterable?: _querykitjs_core.Filterable<FieldKey<TDelegate> | `${string}.${string}`>;
+    /**
+     * Fields a client may sort (and use as `cursorKey`) by. When not given — the
+     * `@id` field and `createdAt` (when the model has it). Anything else ⇒
+     * `reason: "forbidden-key"`.
+     */
+    sortable?: readonly FieldKey<TDelegate>[];
+    /** Request limits for this repository — over the registry's `limits`. */
+    limits?: Partial<_querykitjs_core.QueryLimits>;
 }
 /** DB registry: created once, yields model repositories. */
 interface Registry<TClient extends AnyClient = AnyClient> {
@@ -447,10 +539,20 @@ interface RepoRuntime {
     strict: boolean;
     /** Called for every dropped condition (also when `strict` is off). */
     onSkippedCondition?: (info: SkippedCondition) => void;
+    /** Registry-level request limits; a repository's own `limits` win. */
+    limits?: Partial<QueryLimits>;
+    /** Signs cursor tokens (task 012). */
+    cursorSecret?: string;
+    /** createdAt / deletedAt field names (task 014); default `createdAt`, `deletedAt`. */
+    timestamps?: {
+        createdAt?: string;
+        deletedAt?: string;
+    };
 }
+
 /**
  * Build a model-scoped repository. `runtime` (client + ambient transaction
- * context) comes from the registry, so this file never touches the app's
+ * context) comes from the registry, so this module never touches the app's
  * database handle directly.
  */
 declare function buildRepository<TDelegate>(runtime: RepoRuntime, modelKey: string, config?: RepositoryOptions<TDelegate>): Repository<TDelegate>;
@@ -491,4 +593,5 @@ declare function createFilters<TDelegate>(): {
     not: (node: _querykitjs_core.FilterNode<FieldKey<TDelegate>, RawWhere<TDelegate>>) => _querykitjs_core.NotGroup<FieldKey<TDelegate>, RawWhere<TDelegate>>;
 };
 
-export { type AggregateRow, type AggregateSpec, type AndGroup, type AnyClient, type AnyDelegate, type ByIdParams, type ColumnSelection, type CursorMeta, type CursorParams, type CursorResult, type DelegateOf, type FieldCondition, type FieldKey, type FieldMeta, type Filter, type FilterNode, type FilterOperator, type FilterScalar, type FilterValue, type Id, type IncludeInput, type InfiniteMeta, type InfiniteParams, type InfiniteResult, type Insert, type LooseFieldKey, type ModelKey, type ModelMeta, type NotGroup, type OffsetMeta, type OffsetParams, type OffsetResult, type OrGroup, type QueryParams, type RawWhere, type Registry, type RegistryOptions, type RepoRuntime, type Repository, type RepositoryExtender, type RepositoryOptions, type ResultFor, type Row, type Scope, type SelectInput, type Sort, type SortDirection, type SortItem, type UpsertOptions, type WithRelations, buildRepository, createFilters, createRegistry };
+export { buildRepository, createFilters, createRegistry };
+export type { AggregateRow, AggregateSpec, AndGroup, AnyClient, AnyDelegate, ByIdParams, ColumnSelection, CursorMeta, CursorParams, CursorResult, DelegateOf, FieldCondition, FieldKey, FieldMeta, Filter, FilterNode, FilterOperator, FilterScalar, FilterValue, Id, IncludeInput, InfiniteMeta, InfiniteParams, InfiniteResult, Insert, LooseFieldKey, ModelKey, ModelMeta, NotGroup, OffsetMeta, OffsetParams, OffsetResult, OrGroup, QueryParams, RawWhere, Registry, RegistryOptions, RepoRuntime, Repository, RepositoryExtender, RepositoryOptions, ResultFor, Row, Scope, SelectInput, Sort, SortDirection, SortItem, UpsertOptions, WithRelations };

package/dist/index.d.ts

@@ -1,53 +1,16 @@
-import { Types } from '@prisma/client/runtime/library';
 import * as _querykitjs_core from '@querykitjs/core';
-import { SkippedCondition } from '@querykitjs/core';
+import { AllRows, MutationCount, MutationRows, Relations, SkippedCondition, QueryLimits } from '@querykitjs/core';
 export { f } from '@querykitjs/core';
+import { Types } from '@prisma/client/runtime/client';
 
 /**
- * Model metadata — the Prisma counterpart of drizzle's `columns.ts` and
- * mongoose's `fields.ts`.
- *
- * Prisma's `where` is keyed by **model field name** (camelCase), never by the DB
- * column — but a client may well send `created_at`, which drizzle-pg accepts. So
- * each field's `@map`ped column is recorded as an alias and `resolveField`
- * translates it back, keeping the two Postgres adapters interchangeable.
- *
- * Getting the field list without importing the generated client is the other
- * half of the job: this package must typecheck with no generated client present,
- * so metadata is read off the client **instance** at runtime, through a fallback
- * chain.
+ * Prisma type utilities the public types are built from. Not re-exported by
+ * `types/index.ts`: they are implementation helpers, not part of the API.
  */
-/** One model field, normalized across every metadata source. */
-interface FieldMeta {
-    name: string;
-    /** Prisma type name: `"Int"`, `"String"`, `"DateTime"`, an enum or model name, … */
-    type: string;
-    kind: "scalar" | "enum" | "object" | "unsupported";
-    isId: boolean;
-    /** `@updatedAt` — Prisma bumps these itself, so the adapter must not. */
-    isUpdatedAt: boolean;
-    isList: boolean;
-    /** The `@map`ped database column, when it differs from the field name. */
-    dbName?: string;
-}
-/** Everything the repository needs to know about one model. */
-interface ModelMeta {
-    /** Prisma model name (`"User"`) — used as the diagnostics `source`. */
-    name: string;
-    fields: Map<string, FieldMeta>;
-    /** `@map`ped DB column → Prisma field name, so `created_at` also resolves. */
-    byDbName: Map<string, string>;
-    /** The `@id` field name; undefined for a composite `@@id`. */
-    idField: string | undefined;
-    /** Fields that uniquely address a row — one `@id`, or every `@@id` field. */
-    primaryKey: string[];
-    /** Prisma's name for a composite key (`@@id(name:)`), else the joined fields. */
-    primaryKeyName: string | undefined;
-    hasDeletedAt: boolean;
-    /** Present only when the field exists **and** is not `@updatedAt`-managed. */
-    stampUpdatedAt: string | undefined;
-    hasCreatedAt: boolean;
-}
+
+type ArgsOf<TDelegate, TOperation extends Types.Public.Operation> = Types.Public.Args<TDelegate, TOperation>;
+/** One row with the given Prisma args applied (`select` / `include`). */
+type RowWith<TDelegate, TArgs> = Types.Public.Result<TDelegate, TArgs, "findFirstOrThrow">;
 
 /**
  * QueryKit Prisma adapter — public types. The DSL/filter/meta types come from
@@ -60,8 +23,9 @@ interface ModelMeta {
  * names, same semantics, one shared source in core.
  *
  * ⚠️ This file must never import from `@prisma/client` itself — only from
- * `@prisma/client/runtime/library`, which exists whether or not a client has been
- * generated. That is what lets the package typecheck and build in CI with no
+ * `@prisma/client/runtime/client`, which exists whether or not a client has been
+ * generated (Prisma 6.19 and 7 both ship it; 7 has no `runtime/library`). That
+ * is what lets the package typecheck and build in CI with no
  * `prisma generate` step, while still inferring exact row types in a consumer's
  * project. `Types.Public.*` are Prisma's own public type utilities; the generated
  * client re-exports the very same ones as `Prisma.Result` / `Prisma.Args`.
@@ -84,9 +48,6 @@ type ModelKey<TClient> = {
 }[keyof TClient & string];
 /** The delegate behind a model key. */
 type DelegateOf<TClient, TKey extends ModelKey<TClient>> = TClient[TKey];
-type ArgsOf<TDelegate, TOperation extends Types.Public.Operation> = Types.Public.Args<TDelegate, TOperation>;
-/** One row with the given Prisma args applied (`select` / `include`). */
-type RowWith<TDelegate, TArgs> = Types.Public.Result<TDelegate, TArgs, "findFirstOrThrow">;
 /** Full row shape of a model (what reads return with no `columns`/`with`). */
 type Row<TDelegate> = RowWith<TDelegate, Record<string, never>>;
 /** Insertable shape — the model's `create` data. */
@@ -160,10 +121,13 @@ type UpsertOptions<TDelegate = AnyDelegate> = _querykitjs_core.UpsertOptions<Fie
 type AggregateSpec<TDelegate = AnyDelegate> = _querykitjs_core.AggregateSpec<FieldKey<TDelegate>, Filter<TDelegate>>;
 /** One aggregated result row (group fields + aggregate values). */
 type AggregateRow = Record<string, unknown>;
+
 /** Offset (classic page-based) pagination. */
 interface OffsetParams<TDelegate = AnyDelegate> extends QueryParams<TDelegate> {
     page?: number;
     perPage?: number;
+    /** `false` — no count query: `perPage + 1` rows are read, `total_items` / `total_pages` are `null` (task 013). Default `true`. */
+    withTotal?: boolean;
 }
 type OffsetMeta = _querykitjs_core.OffsetMeta;
 interface OffsetResult<T> {
@@ -197,6 +161,7 @@ interface CursorResult<T> {
     data: T[];
     meta: CursorMeta;
 }
+
 type TrueKeys<T> = {
     [K in keyof T]: T[K] extends true ? K : never;
 }[keyof T];
@@ -273,12 +238,32 @@ interface Repository<TDelegate = AnyDelegate> {
     upsertMany(values: Insert<TDelegate>[], options: UpsertOptions<TDelegate>): Promise<Row<TDelegate>[]>;
     /** Update one row by id; returns the updated row (or `undefined`). */
     updateById(id: Id, patch: Partial<Insert<TDelegate>>, idKey?: FieldKey<TDelegate>): Promise<Row<TDelegate> | undefined>;
-    /** Update every row matching the filter; returns the updated rows. */
-    updateWhere(filter: Filter<TDelegate>, patch: Partial<Insert<TDelegate>>): Promise<Row<TDelegate>[]>;
+    /**
+     * Update every row matching the filter in one atomic `updateMany` → `{ count }` (task 013).
+     * No filter only with `{ all: true }` (the scope still applies); an empty or fully skipped
+     * filter is `QueryKitError` `empty-filter`. The filter passes the request policy like a read.
+     */
+    updateWhere(filter: Filter<TDelegate> | AllRows, patch: Partial<Insert<TDelegate>>, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` from one atomic `updateManyAndReturn`, at most `limit` rows. */
+    updateWhere(filter: Filter<TDelegate> | AllRows, patch: Partial<Insert<TDelegate>>, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDelegate>>>;
     /** Hard-delete one row by id; returns the deleted row (or `undefined`). */
     deleteById(id: Id, idKey?: FieldKey<TDelegate>): Promise<Row<TDelegate> | undefined>;
-    /** Hard-delete every row matching the filter; returns the deleted rows. */
-    deleteWhere(filter: Filter<TDelegate>): Promise<Row<TDelegate>[]>;
+    /** Hard-delete every row matching the filter in one `deleteMany` → `{ count }` (same rules as `updateWhere`). */
+    deleteWhere(filter: Filter<TDelegate> | AllRows, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` — the rows are read just before the delete (not atomic). */
+    deleteWhere(filter: Filter<TDelegate> | AllRows, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDelegate>>>;
     /** Soft-delete (set `deletedAt`); requires a `deletedAt` field. */
     softDelete(id: Id, idKey?: FieldKey<TDelegate>): Promise<Row<TDelegate> | undefined>;
     /** Restore a soft-deleted row (`deletedAt = null`). */
@@ -293,6 +278,69 @@ interface Repository<TDelegate = AnyDelegate> {
 }
 /** Extends a base repository with custom, model-specific methods. */
 type RepositoryExtender<TDelegate, TExt extends Record<string, unknown>> = (base: Repository<TDelegate>) => TExt;
+
+/**
+ * Model metadata — the Prisma counterpart of drizzle's `columns.ts` and
+ * mongoose's `fields.ts`.
+ *
+ * Prisma's `where` is keyed by **model field name** (camelCase), never by the DB
+ * column — but a client may well send `created_at`, which drizzle-pg accepts. So
+ * each field's `@map`ped column is recorded as an alias and `resolveField`
+ * translates it back, keeping the two Postgres adapters interchangeable.
+ *
+ * Getting the field list without importing the generated client is the other
+ * half of the job: this package must typecheck with no generated client present,
+ * so metadata is read off the client **instance** at runtime, through a fallback
+ * chain.
+ */
+/** One model field, normalized across every metadata source. */
+interface FieldMeta {
+    name: string;
+    /** Prisma type name: `"Int"`, `"String"`, `"DateTime"`, an enum or model name, … */
+    type: string;
+    kind: "scalar" | "enum" | "object" | "unsupported";
+    isId: boolean;
+    /** `@updatedAt` — Prisma bumps these itself, so the adapter must not. */
+    isUpdatedAt: boolean;
+    isList: boolean;
+    /** The `@map`ped database column, when it differs from the field name. */
+    dbName?: string;
+    /** `false` for an optional (nullable) field — Prisma accepts `nulls` in `orderBy` only there (task 021 B11). */
+    isRequired?: boolean;
+    /** The database type (`"Uuid"` for `@db.Uuid`) — from the runtime model when it has one, or the `fields` override (task 021 B8). */
+    nativeType?: string;
+    /** An enum field's values (from the runtime data model), for the task 021 B8 cast. */
+    enumValues?: readonly string[];
+}
+/** Everything the repository needs to know about one model. */
+interface ModelMeta {
+    /** Prisma model name (`"User"`) — used as the diagnostics `source`. */
+    name: string;
+    fields: Map<string, FieldMeta>;
+    /** `@map`ped DB column → Prisma field name, so `created_at` also resolves. */
+    byDbName: Map<string, string>;
+    /** The `@id` field name; undefined for a composite `@@id`. */
+    idField: string | undefined;
+    /** Fields that uniquely address a row — one `@id`, or every `@@id` field. */
+    primaryKey: string[];
+    /** Prisma's name for a composite key (`@@id(name:)`), else the joined fields. */
+    primaryKeyName: string | undefined;
+    hasDeletedAt: boolean;
+    /** Present only when the field exists **and** is not `@updatedAt`-managed. */
+    stampUpdatedAt: string | undefined;
+    hasCreatedAt: boolean;
+}
+/**
+ * Read a model's metadata off a live Prisma client, trying, in order:
+ * `_runtimeDataModel` → `delegate.fields` → the caller-supplied `override`.
+ *
+ * Throws when none of them work — the same reasoning as drizzle's "table not in
+ * schema" error: a repository built on unknown metadata would silently skip
+ * *every* filter key and return the whole table.
+ */
+/** A `fields` override entry: a full field, or a patch of a discovered one by `name` (e.g. `{ name: "age", isRequired: false }`). */
+type FieldOverride = Pick<FieldMeta, "name"> & Partial<FieldMeta>;
+
 /** {@link createRegistry} options — pagination defaults and bounds. */
 interface RegistryOptions {
     /** `findList` default page size (core `DEFAULT_PER_PAGE` = 20). */
@@ -321,6 +369,27 @@ interface RegistryOptions {
      * path: watch with the hook first, flip `strict: true` once the log is clean.
      */
     onSkippedCondition?: (info: _querykitjs_core.SkippedCondition) => void;
+    /**
+     * Server-side request limits (core `DEFAULT_QUERY_LIMITS`: depth 5, conditions 30,
+     * array 200, string 256, offset 10 000, sort 3) — enforced even when validation was
+     * bypassed. Past one ⇒ `QueryKitError` (`reason: "limit-exceeded"`). A repository's
+     * own `limits` win.
+     */
+    limits?: Partial<_querykitjs_core.QueryLimits>;
+    /**
+     * Signs cursor tokens (HMAC-SHA256, task 012). With it a token that was not
+     * issued by this server — or was changed — is `invalid-value`. Without it tokens
+     * are unsigned but still checked (scalar values, v2 shape).
+     */
+    cursorSecret?: string;
+    /**
+     * The createdAt / deletedAt field names (task 014; default `createdAt`, `deletedAt`): the default
+     * sort and the default `sortable` use `createdAt`, soft delete uses `deletedAt`.
+     */
+    timestamps?: {
+        createdAt?: string;
+        deletedAt?: string;
+    };
 }
 /**
  * Options for `registry.repository(model, options)`.
@@ -336,6 +405,12 @@ interface RegistryOptions {
  * yourself, before handing a write result to a client.
  */
 interface RepositoryOptions<TDelegate = AnyDelegate> {
+    /**
+     * Relations a client may open with `with` (task 014, R21): relation → `{ columns, filterable?, nested? }`.
+     * `columns` is required (a list or `"*"`); an unlisted relation, column, `where` field or nested
+     * `include` is `QueryKitError` `forbidden-key`, `site: "with"`. Without it `with` opens nothing.
+     */
+    relations?: Relations;
     /** Constant equality filter added to every read/write (RBAC / multi-tenancy). */
     scope?: Scope<TDelegate>;
     /**
@@ -355,7 +430,24 @@ interface RepositoryOptions<TDelegate = AnyDelegate> {
      * the Prisma client itself (it tries `_runtimeDataModel`, then the public
      * `delegate.fields`) — e.g. behind an unusual client wrapper.
      */
-    fields?: readonly FieldMeta[];
+    fields?: readonly FieldOverride[];
+    /**
+     * Fields a client may filter by, and the operators for each (`"*"` — all). A
+     * relation field is `"relation.field"` (`"posts.title": ["="]`). A field not
+     * listed ⇒ `reason: "forbidden-key"`, an operator not listed ⇒ `"forbidden-operator"`
+     * — a `QueryKitError` whatever `strict` says, before Prisma is called.
+     * **When not given** — `allowedColumns` (else the `forcedColumns` keys, else only
+     * the `@id` field) with `"="` and `"in"` only. `aggregate` fields come from this list too.
+     */
+    filterable?: _querykitjs_core.Filterable<FieldKey<TDelegate> | `${string}.${string}`>;
+    /**
+     * Fields a client may sort (and use as `cursorKey`) by. When not given — the
+     * `@id` field and `createdAt` (when the model has it). Anything else ⇒
+     * `reason: "forbidden-key"`.
+     */
+    sortable?: readonly FieldKey<TDelegate>[];
+    /** Request limits for this repository — over the registry's `limits`. */
+    limits?: Partial<_querykitjs_core.QueryLimits>;
 }
 /** DB registry: created once, yields model repositories. */
 interface Registry<TClient extends AnyClient = AnyClient> {
@@ -447,10 +539,20 @@ interface RepoRuntime {
     strict: boolean;
     /** Called for every dropped condition (also when `strict` is off). */
     onSkippedCondition?: (info: SkippedCondition) => void;
+    /** Registry-level request limits; a repository's own `limits` win. */
+    limits?: Partial<QueryLimits>;
+    /** Signs cursor tokens (task 012). */
+    cursorSecret?: string;
+    /** createdAt / deletedAt field names (task 014); default `createdAt`, `deletedAt`. */
+    timestamps?: {
+        createdAt?: string;
+        deletedAt?: string;
+    };
 }
+
 /**
  * Build a model-scoped repository. `runtime` (client + ambient transaction
- * context) comes from the registry, so this file never touches the app's
+ * context) comes from the registry, so this module never touches the app's
  * database handle directly.
  */
 declare function buildRepository<TDelegate>(runtime: RepoRuntime, modelKey: string, config?: RepositoryOptions<TDelegate>): Repository<TDelegate>;
@@ -491,4 +593,5 @@ declare function createFilters<TDelegate>(): {
     not: (node: _querykitjs_core.FilterNode<FieldKey<TDelegate>, RawWhere<TDelegate>>) => _querykitjs_core.NotGroup<FieldKey<TDelegate>, RawWhere<TDelegate>>;
 };
 
-export { type AggregateRow, type AggregateSpec, type AndGroup, type AnyClient, type AnyDelegate, type ByIdParams, type ColumnSelection, type CursorMeta, type CursorParams, type CursorResult, type DelegateOf, type FieldCondition, type FieldKey, type FieldMeta, type Filter, type FilterNode, type FilterOperator, type FilterScalar, type FilterValue, type Id, type IncludeInput, type InfiniteMeta, type InfiniteParams, type InfiniteResult, type Insert, type LooseFieldKey, type ModelKey, type ModelMeta, type NotGroup, type OffsetMeta, type OffsetParams, type OffsetResult, type OrGroup, type QueryParams, type RawWhere, type Registry, type RegistryOptions, type RepoRuntime, type Repository, type RepositoryExtender, type RepositoryOptions, type ResultFor, type Row, type Scope, type SelectInput, type Sort, type SortDirection, type SortItem, type UpsertOptions, type WithRelations, buildRepository, createFilters, createRegistry };
+export { buildRepository, createFilters, createRegistry };
+export type { AggregateRow, AggregateSpec, AndGroup, AnyClient, AnyDelegate, ByIdParams, ColumnSelection, CursorMeta, CursorParams, CursorResult, DelegateOf, FieldCondition, FieldKey, FieldMeta, Filter, FilterNode, FilterOperator, FilterScalar, FilterValue, Id, IncludeInput, InfiniteMeta, InfiniteParams, InfiniteResult, Insert, LooseFieldKey, ModelKey, ModelMeta, NotGroup, OffsetMeta, OffsetParams, OffsetResult, OrGroup, QueryParams, RawWhere, Registry, RegistryOptions, RepoRuntime, Repository, RepositoryExtender, RepositoryOptions, ResultFor, Row, Scope, SelectInput, Sort, SortDirection, SortItem, UpsertOptions, WithRelations };