@querykitjs/mongoose 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Types, Model, Connection, ClientSession } from 'mongoose';
-import * as _querykitjs_core from '@querykitjs/core';
-import { SkippedCondition } from '@querykitjs/core';
+import * as Core from '@querykitjs/core';
+import { AllRows, MutationCount, MutationRows, RelationRule, SkippedCondition, QueryLimits, createFilters as createFilters$1 } from '@querykitjs/core';
 export { f } from '@querykitjs/core';
 
 /**
@@ -38,19 +38,19 @@ type FieldKey<TDoc> = keyof TDoc & string;
  * validated payload can go straight into a repository call with no `as` cast.
  * Autocomplete still suggests the document's real fields.
  */
-type LooseFieldKey<TDoc> = _querykitjs_core.LooseKey<FieldKey<TDoc>>;
-type FilterOperator = _querykitjs_core.FilterOperator;
-type FilterScalar = _querykitjs_core.FilterScalar;
-type FilterValue = _querykitjs_core.FilterValue;
-type FieldCondition<TDoc = Record<string, unknown>> = _querykitjs_core.FieldCondition<LooseFieldKey<TDoc>>;
-type AndGroup<TDoc = Record<string, unknown>> = _querykitjs_core.AndGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type OrGroup<TDoc = Record<string, unknown>> = _querykitjs_core.OrGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type NotGroup<TDoc = Record<string, unknown>> = _querykitjs_core.NotGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type FilterNode<TDoc = Record<string, unknown>> = _querykitjs_core.FilterNode<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type Filter<TDoc = Record<string, unknown>> = _querykitjs_core.Filter<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type SortDirection = _querykitjs_core.SortDirection;
+type LooseFieldKey<TDoc> = Core.LooseKey<FieldKey<TDoc>>;
+type FilterOperator = Core.FilterOperator;
+type FilterScalar = Core.FilterScalar;
+type FilterValue = Core.FilterValue;
+type FieldCondition<TDoc = Record<string, unknown>> = Core.FieldCondition<LooseFieldKey<TDoc>>;
+type AndGroup<TDoc = Record<string, unknown>> = Core.AndGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type OrGroup<TDoc = Record<string, unknown>> = Core.OrGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type NotGroup<TDoc = Record<string, unknown>> = Core.NotGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type FilterNode<TDoc = Record<string, unknown>> = Core.FilterNode<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type Filter<TDoc = Record<string, unknown>> = Core.Filter<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type SortDirection = Core.SortDirection;
 /** One sort field by typed field key (`{ key, direction }`) — autocomplete. */
-type SortItem<TDoc = Record<string, unknown>> = _querykitjs_core.SortItem<LooseFieldKey<TDoc>>;
+type SortItem<TDoc = Record<string, unknown>> = Core.SortItem<LooseFieldKey<TDoc>>;
 /**
  * Sort — **always an array** of `{ key, direction }` (multi-field). This is the
  * exact shape the querykit frontend sends (`@querykitjs/web` decodes its
@@ -69,22 +69,25 @@ interface QueryParams<TDoc = Record<string, unknown>> {
     withDeleted?: boolean;
 }
 /** Equality scope applied to every operation of a scoped repository. */
-type Scope<TDoc = Record<string, unknown>> = _querykitjs_core.Scope<FieldKey<TDoc>>;
+type Scope<TDoc = Record<string, unknown>> = Core.Scope<FieldKey<TDoc>>;
 interface ByIdParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
     /** Field to match against the id. Defaults to `"id"` (→ `_id`). */
     idKey?: LooseFieldKey<TDoc>;
 }
 /** Options for {@link Repository.upsert} / {@link Repository.upsertMany}. */
-type UpsertOptions<TDoc = Record<string, unknown>> = _querykitjs_core.UpsertOptions<FieldKey<TDoc>, Insert<TDoc>>;
+type UpsertOptions<TDoc = Record<string, unknown>> = Core.UpsertOptions<FieldKey<TDoc>, Insert<TDoc>>;
 /** Aggregate query specification (`count`/`sum`/`avg`/`min`/`max` + `groupBy`). */
-type AggregateSpec<TDoc = Record<string, unknown>> = _querykitjs_core.AggregateSpec<FieldKey<TDoc>, Filter<TDoc>>;
+type AggregateSpec<TDoc = Record<string, unknown>> = Core.AggregateSpec<FieldKey<TDoc>, Filter<TDoc>>;
 /** One aggregated result row (group fields + aggregate values). */
 type AggregateRow = Record<string, unknown>;
+
 interface OffsetParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
     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;
+type OffsetMeta = Core.OffsetMeta;
 interface OffsetResult<T> {
     data: T[];
     meta: OffsetMeta;
@@ -93,7 +96,7 @@ interface InfiniteParams<TDoc = Record<string, unknown>> extends QueryParams<TDo
     limit?: number;
     offset?: number;
 }
-type InfiniteMeta = _querykitjs_core.InfiniteMeta;
+type InfiniteMeta = Core.InfiniteMeta;
 interface InfiniteResult<T> {
     data: T[];
     meta: InfiniteMeta;
@@ -106,14 +109,23 @@ interface CursorParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc>
     order?: SortDirection;
     direction?: "forward" | "backward";
 }
-type CursorMeta = _querykitjs_core.CursorMeta;
+type CursorMeta = Core.CursorMeta;
 interface CursorResult<T> {
     data: T[];
     meta: CursorMeta;
 }
-/** Map of relation field name → the Mongoose model it refers to. */
-type RelationMap = Record<string, Model<any>>;
-type DocOf<M> = M extends Model<infer T> ? T : never;
+
+/**
+ * Relation field → its rule (task 014, R21): `{ model?, columns, filterable?, nested? }` opens it for a
+ * client `with` (`columns` required — a list or `"*"`). A bare model (`{ author: User }`) still types
+ * `with`, but opens nothing: `with: { author: … }` is `forbidden-key`, `site: "with"`.
+ */
+type RelationMap = Record<string, Model<any> | (RelationRule & {
+    model?: Model<any>;
+})>;
+type DocOf<M> = M extends Model<infer T> ? T : M extends {
+    model: Model<infer T>;
+} ? T : Record<string, unknown>;
 /** Resolve a {@link RelationMap} to `{ field: <its document type> }`. */
 type RelationDocs<TRel extends RelationMap> = {
     [K in keyof TRel]: DocOf<TRel[K]>;
@@ -133,7 +145,7 @@ type RelationDocs<TRel extends RelationMap> = {
  * result to a client.
  */
 interface RepositoryOptions<TDoc = any, TRel extends RelationMap = RelationMap> {
-    /** Declare populatable relations (field → model) so `with` types the result. */
+    /** Populatable relations: field → `{ model?, columns, filterable?, nested? }` (R21), or a bare model (typing only). */
     relations?: TRel;
     /** Constant equality filter added to every read/write (RBAC / multi-tenancy). */
     scope?: Scope<TDoc>;
@@ -149,6 +161,23 @@ interface RepositoryOptions<TDoc = any, TRel extends RelationMap = RelationMap>
      * An empty array throws (a projection selecting nothing means "everything").
      */
     allowedColumns?: readonly FieldKey<TDoc>[];
+    /**
+     * Paths a client may filter by, and the operators for each (`"*"` — all). A path
+     * not listed ⇒ `reason: "forbidden-key"`, an operator not listed ⇒
+     * `"forbidden-operator"` — a `QueryKitError` whatever `strict` says, before the
+     * query runs. **When not given** — `allowedColumns` (else the `forcedColumns` keys,
+     * else only `_id`) with `"="` and `"in"` only. `aggregate` paths come from this list too.
+     */
+    filterable?: Core.Filterable<FieldKey<TDoc> | "_id">;
+    /**
+     * Paths a client may sort (and use as `cursorKey`) by. When not given — `_id` and
+     * `createdAt` (when the schema has it). Anything else ⇒ `reason: "forbidden-key"`.
+     */
+    sortable?: readonly (FieldKey<TDoc> | "_id")[];
+    /** Request limits for this repository — over the registry's `limits`. */
+    limits?: Partial<Core.QueryLimits>;
+    /** Read time limit for this repository, in ms — over the registry's `maxTimeMS`. */
+    maxTimeMS?: number;
 }
 type TrueKeys<T> = {
     [K in keyof T]: T[K] extends true ? K : never;
@@ -190,12 +219,32 @@ interface Repository<TDoc = Record<string, unknown>, TRel extends Record<string,
     upsertMany(values: Insert<TDoc>[], options: UpsertOptions<TDoc>): Promise<Row<TDoc>[]>;
     /** Update one document by id; returns the updated doc (or undefined). */
     updateById(id: Id, patch: Partial<Insert<TDoc>>, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
-    /** Update all documents matching the filter; returns the updated docs. */
-    updateWhere(filter: Filter<TDoc>, patch: Partial<Insert<TDoc>>): Promise<Row<TDoc>[]>;
+    /**
+     * Update every document matching the filter in one `updateMany` → `{ count }` (matched, 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<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` — the rows are read right after the update with the same filter (not atomic). */
+    updateWhere(filter: Filter<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
     /** Hard-delete one document by id; returns the deleted doc (or undefined). */
     deleteById(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
-    /** Hard-delete all documents matching the filter; returns the deleted docs. */
-    deleteWhere(filter: Filter<TDoc>): Promise<Row<TDoc>[]>;
+    /** Hard-delete every document matching the filter in one `deleteMany` → `{ count }` (same rules as `updateWhere`). */
+    deleteWhere(filter: Filter<TDoc> | AllRows, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` — the rows are read just before the delete (not atomic). */
+    deleteWhere(filter: Filter<TDoc> | AllRows, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
     /** Soft-delete (set `deletedAt`); requires a `deletedAt` schema path. */
     softDelete(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
     /** Restore a soft-deleted document (`deletedAt = null`). */
@@ -204,6 +253,7 @@ interface Repository<TDoc = Record<string, unknown>, TRel extends Record<string,
     aggregate(spec: AggregateSpec<TDoc>): Promise<AggregateRow[]>;
     scoped(scope: Scope<TDoc>): Repository<TDoc, TRel>;
 }
+
 /** {@link createRegistry} options — pagination defaults and bounds. */
 interface RegistryOptions {
     /** `findList` default page size (core `DEFAULT_PER_PAGE` = 20). */
@@ -232,7 +282,32 @@ interface RegistryOptions {
      * Called for every dropped condition (also when `strict` is off). Migration
      * path: watch with the hook first, flip `strict: true` once the log is clean.
      */
-    onSkippedCondition?: (info: _querykitjs_core.SkippedCondition) => void;
+    onSkippedCondition?: (info: Core.SkippedCondition) => void;
+    /**
+     * Server-side request limits (core `DEFAULT_QUERY_LIMITS`) — enforced even when
+     * validation was bypassed. Past one ⇒ `QueryKitError` (`reason: "limit-exceeded"`).
+     * A repository's own `limits` win.
+     */
+    limits?: Partial<Core.QueryLimits>;
+    /**
+     * Time limit for every read (`find`, `findOne`, `countDocuments`, `aggregate`), in ms.
+     * Default `2000`. Past it MongoDB aborts the read and the repository throws
+     * `QueryKitTimeoutError` (`code: "QUERYKIT_TIMEOUT"`). A repository's own `maxTimeMS` wins.
+     */
+    maxTimeMS?: number;
+    /**
+     * Signs cursor tokens (HMAC-SHA256, task 012). With it a token that was not
+     * issued by this server — or was changed — is `invalid-value`.
+     */
+    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;
+    };
 }
 /** Extends a base repository with custom, model-specific methods (drizzle-pg style). */
 type RepositoryExtender<TDoc, TRel extends Record<string, unknown>, TExt extends Record<string, unknown>> = (base: Repository<TDoc, TRel>) => TExt;
@@ -281,10 +356,22 @@ 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>;
+    /** Read time limit in ms; a repository's own `maxTimeMS` wins. */
+    maxTimeMS: number;
+    /** 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` (session getter + defaults) comes
- * from the registry, so this file never touches the connection directly.
+ * from the registry, so this module never touches the connection directly.
  */
 declare function buildRepository<TDoc>(runtime: RepoRuntime, model: Model<TDoc>, config?: RepositoryOptions<TDoc>): Repository<TDoc>;
 
@@ -299,29 +386,7 @@ declare function buildRepository<TDoc>(runtime: RepoRuntime, model: Model<TDoc>,
  * await usersRepo.findAll({ filter: uf.and(uf.eq("status", "active"), uf.gte("age", 18)) });
  * ```
  */
-declare function createFilters<TDoc>(): {
-    eq: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    ne: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    gt: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    gte: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    lt: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    lte: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    contains: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    startsWith: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    endsWith: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    like: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    ilike: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    notLike: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    in: (key: FieldKey<TDoc>, value: Array<string | number>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    notIn: (key: FieldKey<TDoc>, value: Array<string | number>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    between: (key: FieldKey<TDoc>, min: _querykitjs_core.FilterScalar | Date, max: _querykitjs_core.FilterScalar | Date) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    notBetween: (key: FieldKey<TDoc>, min: _querykitjs_core.FilterScalar | Date, max: _querykitjs_core.FilterScalar | Date) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    range: (key: FieldKey<TDoc>, from: _querykitjs_core.FilterScalar | Date, to: _querykitjs_core.FilterScalar | Date) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>[];
-    isNull: (key: FieldKey<TDoc>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    isNotNull: (key: FieldKey<TDoc>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    and: (...nodes: _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<_TDoc>>[]) => _querykitjs_core.AndGroup<FieldKey<TDoc>, RawFilter<_TDoc>>;
-    or: (...nodes: _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<_TDoc>>[]) => _querykitjs_core.OrGroup<FieldKey<TDoc>, RawFilter<_TDoc>>;
-    not: (node: _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<_TDoc>>) => _querykitjs_core.NotGroup<FieldKey<TDoc>, RawFilter<_TDoc>>;
-};
+declare function createFilters<TDoc>(): ReturnType<typeof createFilters$1<FieldKey<TDoc>, RawFilter<TDoc>>>;
 
-export { type AggregateRow, type AggregateSpec, type AndGroup, type ByIdParams, type ColumnSelection, type CursorMeta, type CursorParams, type CursorResult, type FieldCondition, type FieldKey, type Filter, type FilterNode, type FilterOperator, type FilterScalar, type FilterValue, type Id, type InfiniteMeta, type InfiniteParams, type InfiniteResult, type Insert, type LooseFieldKey, type NotGroup, type OffsetMeta, type OffsetParams, type OffsetResult, type OrGroup, type QueryParams, type RawFilter, type Registry, type RegistryOptions, type RelationDocs, type RelationMap, type RepoRuntime, type Repository, type RepositoryExtender, type RepositoryOptions, type Result, type Row, type Scope, type Sort, type SortDirection, type SortItem, type UpsertOptions, type WithRelations, buildRepository, createFilters, createRegistry };
+export { buildRepository, createFilters, createRegistry };
+export type { AggregateRow, AggregateSpec, AndGroup, ByIdParams, ColumnSelection, CursorMeta, CursorParams, CursorResult, FieldCondition, FieldKey, Filter, FilterNode, FilterOperator, FilterScalar, FilterValue, Id, InfiniteMeta, InfiniteParams, InfiniteResult, Insert, LooseFieldKey, NotGroup, OffsetMeta, OffsetParams, OffsetResult, OrGroup, QueryParams, RawFilter, Registry, RegistryOptions, RelationDocs, RelationMap, RepoRuntime, Repository, RepositoryExtender, RepositoryOptions, Result, Row, Scope, Sort, SortDirection, SortItem, UpsertOptions, WithRelations };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Types, Model, Connection, ClientSession } from 'mongoose';
-import * as _querykitjs_core from '@querykitjs/core';
-import { SkippedCondition } from '@querykitjs/core';
+import * as Core from '@querykitjs/core';
+import { AllRows, MutationCount, MutationRows, RelationRule, SkippedCondition, QueryLimits, createFilters as createFilters$1 } from '@querykitjs/core';
 export { f } from '@querykitjs/core';
 
 /**
@@ -38,19 +38,19 @@ type FieldKey<TDoc> = keyof TDoc & string;
  * validated payload can go straight into a repository call with no `as` cast.
  * Autocomplete still suggests the document's real fields.
  */
-type LooseFieldKey<TDoc> = _querykitjs_core.LooseKey<FieldKey<TDoc>>;
-type FilterOperator = _querykitjs_core.FilterOperator;
-type FilterScalar = _querykitjs_core.FilterScalar;
-type FilterValue = _querykitjs_core.FilterValue;
-type FieldCondition<TDoc = Record<string, unknown>> = _querykitjs_core.FieldCondition<LooseFieldKey<TDoc>>;
-type AndGroup<TDoc = Record<string, unknown>> = _querykitjs_core.AndGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type OrGroup<TDoc = Record<string, unknown>> = _querykitjs_core.OrGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type NotGroup<TDoc = Record<string, unknown>> = _querykitjs_core.NotGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type FilterNode<TDoc = Record<string, unknown>> = _querykitjs_core.FilterNode<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type Filter<TDoc = Record<string, unknown>> = _querykitjs_core.Filter<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
-type SortDirection = _querykitjs_core.SortDirection;
+type LooseFieldKey<TDoc> = Core.LooseKey<FieldKey<TDoc>>;
+type FilterOperator = Core.FilterOperator;
+type FilterScalar = Core.FilterScalar;
+type FilterValue = Core.FilterValue;
+type FieldCondition<TDoc = Record<string, unknown>> = Core.FieldCondition<LooseFieldKey<TDoc>>;
+type AndGroup<TDoc = Record<string, unknown>> = Core.AndGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type OrGroup<TDoc = Record<string, unknown>> = Core.OrGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type NotGroup<TDoc = Record<string, unknown>> = Core.NotGroup<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type FilterNode<TDoc = Record<string, unknown>> = Core.FilterNode<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type Filter<TDoc = Record<string, unknown>> = Core.Filter<LooseFieldKey<TDoc>, RawFilter<TDoc>>;
+type SortDirection = Core.SortDirection;
 /** One sort field by typed field key (`{ key, direction }`) — autocomplete. */
-type SortItem<TDoc = Record<string, unknown>> = _querykitjs_core.SortItem<LooseFieldKey<TDoc>>;
+type SortItem<TDoc = Record<string, unknown>> = Core.SortItem<LooseFieldKey<TDoc>>;
 /**
  * Sort — **always an array** of `{ key, direction }` (multi-field). This is the
  * exact shape the querykit frontend sends (`@querykitjs/web` decodes its
@@ -69,22 +69,25 @@ interface QueryParams<TDoc = Record<string, unknown>> {
     withDeleted?: boolean;
 }
 /** Equality scope applied to every operation of a scoped repository. */
-type Scope<TDoc = Record<string, unknown>> = _querykitjs_core.Scope<FieldKey<TDoc>>;
+type Scope<TDoc = Record<string, unknown>> = Core.Scope<FieldKey<TDoc>>;
 interface ByIdParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
     /** Field to match against the id. Defaults to `"id"` (→ `_id`). */
     idKey?: LooseFieldKey<TDoc>;
 }
 /** Options for {@link Repository.upsert} / {@link Repository.upsertMany}. */
-type UpsertOptions<TDoc = Record<string, unknown>> = _querykitjs_core.UpsertOptions<FieldKey<TDoc>, Insert<TDoc>>;
+type UpsertOptions<TDoc = Record<string, unknown>> = Core.UpsertOptions<FieldKey<TDoc>, Insert<TDoc>>;
 /** Aggregate query specification (`count`/`sum`/`avg`/`min`/`max` + `groupBy`). */
-type AggregateSpec<TDoc = Record<string, unknown>> = _querykitjs_core.AggregateSpec<FieldKey<TDoc>, Filter<TDoc>>;
+type AggregateSpec<TDoc = Record<string, unknown>> = Core.AggregateSpec<FieldKey<TDoc>, Filter<TDoc>>;
 /** One aggregated result row (group fields + aggregate values). */
 type AggregateRow = Record<string, unknown>;
+
 interface OffsetParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
     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;
+type OffsetMeta = Core.OffsetMeta;
 interface OffsetResult<T> {
     data: T[];
     meta: OffsetMeta;
@@ -93,7 +96,7 @@ interface InfiniteParams<TDoc = Record<string, unknown>> extends QueryParams<TDo
     limit?: number;
     offset?: number;
 }
-type InfiniteMeta = _querykitjs_core.InfiniteMeta;
+type InfiniteMeta = Core.InfiniteMeta;
 interface InfiniteResult<T> {
     data: T[];
     meta: InfiniteMeta;
@@ -106,14 +109,23 @@ interface CursorParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc>
     order?: SortDirection;
     direction?: "forward" | "backward";
 }
-type CursorMeta = _querykitjs_core.CursorMeta;
+type CursorMeta = Core.CursorMeta;
 interface CursorResult<T> {
     data: T[];
     meta: CursorMeta;
 }
-/** Map of relation field name → the Mongoose model it refers to. */
-type RelationMap = Record<string, Model<any>>;
-type DocOf<M> = M extends Model<infer T> ? T : never;
+
+/**
+ * Relation field → its rule (task 014, R21): `{ model?, columns, filterable?, nested? }` opens it for a
+ * client `with` (`columns` required — a list or `"*"`). A bare model (`{ author: User }`) still types
+ * `with`, but opens nothing: `with: { author: … }` is `forbidden-key`, `site: "with"`.
+ */
+type RelationMap = Record<string, Model<any> | (RelationRule & {
+    model?: Model<any>;
+})>;
+type DocOf<M> = M extends Model<infer T> ? T : M extends {
+    model: Model<infer T>;
+} ? T : Record<string, unknown>;
 /** Resolve a {@link RelationMap} to `{ field: <its document type> }`. */
 type RelationDocs<TRel extends RelationMap> = {
     [K in keyof TRel]: DocOf<TRel[K]>;
@@ -133,7 +145,7 @@ type RelationDocs<TRel extends RelationMap> = {
  * result to a client.
  */
 interface RepositoryOptions<TDoc = any, TRel extends RelationMap = RelationMap> {
-    /** Declare populatable relations (field → model) so `with` types the result. */
+    /** Populatable relations: field → `{ model?, columns, filterable?, nested? }` (R21), or a bare model (typing only). */
     relations?: TRel;
     /** Constant equality filter added to every read/write (RBAC / multi-tenancy). */
     scope?: Scope<TDoc>;
@@ -149,6 +161,23 @@ interface RepositoryOptions<TDoc = any, TRel extends RelationMap = RelationMap>
      * An empty array throws (a projection selecting nothing means "everything").
      */
     allowedColumns?: readonly FieldKey<TDoc>[];
+    /**
+     * Paths a client may filter by, and the operators for each (`"*"` — all). A path
+     * not listed ⇒ `reason: "forbidden-key"`, an operator not listed ⇒
+     * `"forbidden-operator"` — a `QueryKitError` whatever `strict` says, before the
+     * query runs. **When not given** — `allowedColumns` (else the `forcedColumns` keys,
+     * else only `_id`) with `"="` and `"in"` only. `aggregate` paths come from this list too.
+     */
+    filterable?: Core.Filterable<FieldKey<TDoc> | "_id">;
+    /**
+     * Paths a client may sort (and use as `cursorKey`) by. When not given — `_id` and
+     * `createdAt` (when the schema has it). Anything else ⇒ `reason: "forbidden-key"`.
+     */
+    sortable?: readonly (FieldKey<TDoc> | "_id")[];
+    /** Request limits for this repository — over the registry's `limits`. */
+    limits?: Partial<Core.QueryLimits>;
+    /** Read time limit for this repository, in ms — over the registry's `maxTimeMS`. */
+    maxTimeMS?: number;
 }
 type TrueKeys<T> = {
     [K in keyof T]: T[K] extends true ? K : never;
@@ -190,12 +219,32 @@ interface Repository<TDoc = Record<string, unknown>, TRel extends Record<string,
     upsertMany(values: Insert<TDoc>[], options: UpsertOptions<TDoc>): Promise<Row<TDoc>[]>;
     /** Update one document by id; returns the updated doc (or undefined). */
     updateById(id: Id, patch: Partial<Insert<TDoc>>, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
-    /** Update all documents matching the filter; returns the updated docs. */
-    updateWhere(filter: Filter<TDoc>, patch: Partial<Insert<TDoc>>): Promise<Row<TDoc>[]>;
+    /**
+     * Update every document matching the filter in one `updateMany` → `{ count }` (matched, 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<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` — the rows are read right after the update with the same filter (not atomic). */
+    updateWhere(filter: Filter<TDoc> | AllRows, patch: Partial<Insert<TDoc>>, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
     /** Hard-delete one document by id; returns the deleted doc (or undefined). */
     deleteById(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
-    /** Hard-delete all documents matching the filter; returns the deleted docs. */
-    deleteWhere(filter: Filter<TDoc>): Promise<Row<TDoc>[]>;
+    /** Hard-delete every document matching the filter in one `deleteMany` → `{ count }` (same rules as `updateWhere`). */
+    deleteWhere(filter: Filter<TDoc> | AllRows, options?: {
+        returning?: false;
+    }): Promise<MutationCount>;
+    /** With `returning: { limit }`: `{ count, rows }` — the rows are read just before the delete (not atomic). */
+    deleteWhere(filter: Filter<TDoc> | AllRows, options: {
+        returning: {
+            limit: number;
+        };
+    }): Promise<MutationRows<Row<TDoc>>>;
     /** Soft-delete (set `deletedAt`); requires a `deletedAt` schema path. */
     softDelete(id: Id, idKey?: FieldKey<TDoc>): Promise<Row<TDoc> | undefined>;
     /** Restore a soft-deleted document (`deletedAt = null`). */
@@ -204,6 +253,7 @@ interface Repository<TDoc = Record<string, unknown>, TRel extends Record<string,
     aggregate(spec: AggregateSpec<TDoc>): Promise<AggregateRow[]>;
     scoped(scope: Scope<TDoc>): Repository<TDoc, TRel>;
 }
+
 /** {@link createRegistry} options — pagination defaults and bounds. */
 interface RegistryOptions {
     /** `findList` default page size (core `DEFAULT_PER_PAGE` = 20). */
@@ -232,7 +282,32 @@ interface RegistryOptions {
      * Called for every dropped condition (also when `strict` is off). Migration
      * path: watch with the hook first, flip `strict: true` once the log is clean.
      */
-    onSkippedCondition?: (info: _querykitjs_core.SkippedCondition) => void;
+    onSkippedCondition?: (info: Core.SkippedCondition) => void;
+    /**
+     * Server-side request limits (core `DEFAULT_QUERY_LIMITS`) — enforced even when
+     * validation was bypassed. Past one ⇒ `QueryKitError` (`reason: "limit-exceeded"`).
+     * A repository's own `limits` win.
+     */
+    limits?: Partial<Core.QueryLimits>;
+    /**
+     * Time limit for every read (`find`, `findOne`, `countDocuments`, `aggregate`), in ms.
+     * Default `2000`. Past it MongoDB aborts the read and the repository throws
+     * `QueryKitTimeoutError` (`code: "QUERYKIT_TIMEOUT"`). A repository's own `maxTimeMS` wins.
+     */
+    maxTimeMS?: number;
+    /**
+     * Signs cursor tokens (HMAC-SHA256, task 012). With it a token that was not
+     * issued by this server — or was changed — is `invalid-value`.
+     */
+    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;
+    };
 }
 /** Extends a base repository with custom, model-specific methods (drizzle-pg style). */
 type RepositoryExtender<TDoc, TRel extends Record<string, unknown>, TExt extends Record<string, unknown>> = (base: Repository<TDoc, TRel>) => TExt;
@@ -281,10 +356,22 @@ 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>;
+    /** Read time limit in ms; a repository's own `maxTimeMS` wins. */
+    maxTimeMS: number;
+    /** 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` (session getter + defaults) comes
- * from the registry, so this file never touches the connection directly.
+ * from the registry, so this module never touches the connection directly.
  */
 declare function buildRepository<TDoc>(runtime: RepoRuntime, model: Model<TDoc>, config?: RepositoryOptions<TDoc>): Repository<TDoc>;
 
@@ -299,29 +386,7 @@ declare function buildRepository<TDoc>(runtime: RepoRuntime, model: Model<TDoc>,
  * await usersRepo.findAll({ filter: uf.and(uf.eq("status", "active"), uf.gte("age", 18)) });
  * ```
  */
-declare function createFilters<TDoc>(): {
-    eq: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    ne: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    gt: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    gte: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    lt: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    lte: (key: FieldKey<TDoc>, value: _querykitjs_core.FilterValue) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    contains: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    startsWith: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    endsWith: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    like: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    ilike: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    notLike: (key: FieldKey<TDoc>, value: string) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    in: (key: FieldKey<TDoc>, value: Array<string | number>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    notIn: (key: FieldKey<TDoc>, value: Array<string | number>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    between: (key: FieldKey<TDoc>, min: _querykitjs_core.FilterScalar | Date, max: _querykitjs_core.FilterScalar | Date) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    notBetween: (key: FieldKey<TDoc>, min: _querykitjs_core.FilterScalar | Date, max: _querykitjs_core.FilterScalar | Date) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    range: (key: FieldKey<TDoc>, from: _querykitjs_core.FilterScalar | Date, to: _querykitjs_core.FilterScalar | Date) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>[];
-    isNull: (key: FieldKey<TDoc>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    isNotNull: (key: FieldKey<TDoc>) => _querykitjs_core.FieldCondition<FieldKey<TDoc>>;
-    and: (...nodes: _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<_TDoc>>[]) => _querykitjs_core.AndGroup<FieldKey<TDoc>, RawFilter<_TDoc>>;
-    or: (...nodes: _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<_TDoc>>[]) => _querykitjs_core.OrGroup<FieldKey<TDoc>, RawFilter<_TDoc>>;
-    not: (node: _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<_TDoc>>) => _querykitjs_core.NotGroup<FieldKey<TDoc>, RawFilter<_TDoc>>;
-};
+declare function createFilters<TDoc>(): ReturnType<typeof createFilters$1<FieldKey<TDoc>, RawFilter<TDoc>>>;
 
-export { type AggregateRow, type AggregateSpec, type AndGroup, type ByIdParams, type ColumnSelection, type CursorMeta, type CursorParams, type CursorResult, type FieldCondition, type FieldKey, type Filter, type FilterNode, type FilterOperator, type FilterScalar, type FilterValue, type Id, type InfiniteMeta, type InfiniteParams, type InfiniteResult, type Insert, type LooseFieldKey, type NotGroup, type OffsetMeta, type OffsetParams, type OffsetResult, type OrGroup, type QueryParams, type RawFilter, type Registry, type RegistryOptions, type RelationDocs, type RelationMap, type RepoRuntime, type Repository, type RepositoryExtender, type RepositoryOptions, type Result, type Row, type Scope, type Sort, type SortDirection, type SortItem, type UpsertOptions, type WithRelations, buildRepository, createFilters, createRegistry };
+export { buildRepository, createFilters, createRegistry };
+export type { AggregateRow, AggregateSpec, AndGroup, ByIdParams, ColumnSelection, CursorMeta, CursorParams, CursorResult, FieldCondition, FieldKey, Filter, FilterNode, FilterOperator, FilterScalar, FilterValue, Id, InfiniteMeta, InfiniteParams, InfiniteResult, Insert, LooseFieldKey, NotGroup, OffsetMeta, OffsetParams, OffsetResult, OrGroup, QueryParams, RawFilter, Registry, RegistryOptions, RelationDocs, RelationMap, RepoRuntime, Repository, RepositoryExtender, RepositoryOptions, Result, Row, Scope, Sort, SortDirection, SortItem, UpsertOptions, WithRelations };