@querykitjs/mongoose 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Types, Model, Connection, ClientSession } from 'mongoose';
 import * as _querykitjs_core from '@querykitjs/core';
+import { SkippedCondition } from '@querykitjs/core';
 export { f } from '@querykitjs/core';
 
 /**
@@ -9,10 +10,8 @@ export { f } from '@querykitjs/core';
  * escape-hatch bound to a native Mongo `FilterQuery`.
  *
  * The public surface mirrors `@querykitjs/drizzle-pg` so the same frontend
- * request contract works regardless of backend.
- *
- * NOTE: Stage 1 exposes only read methods (+ scoped). Writes/upsert/aggregate/
- * transaction land in stage 2.
+ * request contract works regardless of backend: same option names, same
+ * semantics, one shared source in core.
  */
 
 /** Plain (lean) document type — what reads return. */
@@ -33,18 +32,25 @@ type Id = string | number | Types.ObjectId;
 type RawFilter<_TDoc = unknown> = Record<string, unknown>;
 /** Union of a document's field keys. */
 type FieldKey<TDoc> = keyof TDoc & string;
+/**
+ * A field key that also accepts any `string`. Filter/sort keys arrive from the
+ * wire as plain strings and the adapter skips the ones it cannot resolve, so a
+ * 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<FieldKey<TDoc>>;
-type AndGroup<TDoc = Record<string, unknown>> = _querykitjs_core.AndGroup<FieldKey<TDoc>, RawFilter<TDoc>>;
-type OrGroup<TDoc = Record<string, unknown>> = _querykitjs_core.OrGroup<FieldKey<TDoc>, RawFilter<TDoc>>;
-type NotGroup<TDoc = Record<string, unknown>> = _querykitjs_core.NotGroup<FieldKey<TDoc>, RawFilter<TDoc>>;
-type FilterNode<TDoc = Record<string, unknown>> = _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<TDoc>>;
-type Filter<TDoc = Record<string, unknown>> = _querykitjs_core.Filter<FieldKey<TDoc>, RawFilter<TDoc>>;
+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;
 /** One sort field by typed field key (`{ key, direction }`) — autocomplete. */
-type SortItem<TDoc = Record<string, unknown>> = _querykitjs_core.SortItem<FieldKey<TDoc>>;
+type SortItem<TDoc = Record<string, unknown>> = _querykitjs_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
@@ -63,36 +69,15 @@ interface QueryParams<TDoc = Record<string, unknown>> {
     withDeleted?: boolean;
 }
 /** Equality scope applied to every operation of a scoped repository. */
-type Scope<TDoc = Record<string, unknown>> = Partial<Record<FieldKey<TDoc>, FilterScalar>>;
+type Scope<TDoc = Record<string, unknown>> = _querykitjs_core.Scope<FieldKey<TDoc>>;
 interface ByIdParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
     /** Field to match against the id. Defaults to `"id"` (→ `_id`). */
-    idKey?: FieldKey<TDoc>;
+    idKey?: LooseFieldKey<TDoc>;
 }
 /** Options for {@link Repository.upsert} / {@link Repository.upsertMany}. */
-interface UpsertOptions<TDoc = Record<string, unknown>> {
-    /** Unique field(s) whose match triggers an update instead of an insert. */
-    target: FieldKey<TDoc> | FieldKey<TDoc>[];
-    /** Fields to update on conflict. Defaults to the inserted values minus `target`. */
-    set?: Partial<Insert<TDoc>>;
-}
-type AggKeys<TDoc> = FieldKey<TDoc> | FieldKey<TDoc>[];
-/** Aggregate query specification (mirrors drizzle-pg). */
-interface AggregateSpec<TDoc = Record<string, unknown>> {
-    filter?: Filter<TDoc>;
-    /** Group by these field(s); each appears in the output rows. */
-    groupBy?: AggKeys<TDoc>;
-    /** `$sum:1` → `count`. */
-    count?: boolean;
-    /** `$sum` → `sum_<field>`. */
-    sum?: AggKeys<TDoc>;
-    /** `$avg` → `avg_<field>`. */
-    avg?: AggKeys<TDoc>;
-    /** `$min` → `min_<field>`. */
-    min?: AggKeys<TDoc>;
-    /** `$max` → `max_<field>`. */
-    max?: AggKeys<TDoc>;
-    withDeleted?: boolean;
-}
+type UpsertOptions<TDoc = Record<string, unknown>> = _querykitjs_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>>;
 /** One aggregated result row (group fields + aggregate values). */
 type AggregateRow = Record<string, unknown>;
 interface OffsetParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc> {
@@ -117,7 +102,7 @@ interface CursorParams<TDoc = Record<string, unknown>> extends QueryParams<TDoc>
     limit?: number;
     cursor?: string | null;
     /** Field the cursor walks over. Defaults to `"id"` (→ `_id`). */
-    cursorKey?: FieldKey<TDoc>;
+    cursorKey?: LooseFieldKey<TDoc>;
     order?: SortDirection;
     direction?: "forward" | "backward";
 }
@@ -133,10 +118,37 @@ type DocOf<M> = M extends Model<infer T> ? T : never;
 type RelationDocs<TRel extends RelationMap> = {
     [K in keyof TRel]: DocOf<TRel[K]>;
 };
-/** Options for `registry.repository(model, options)`. */
-interface RepositoryOptions<TRel extends RelationMap = RelationMap> {
+/**
+ * Options for `registry.repository(model, options)`.
+ *
+ * Philosophy: the guard lives in the **repository**, not the route — `scope`
+ * (RBAC) already worked that way and projection joins it. Same names and same
+ * semantics as the drizzle-pg adapter's `RepositoryOptions`.
+ *
+ * ⚠️ `forcedColumns`/`allowedColumns` affect **read** methods only
+ * (`findAll`/`findOne`/`findById`/`findList`/`findInfinite`/`findCursor` +
+ * `aggregate`). Write methods (`create`, `upsert`, `updateById`, `softDelete`, …)
+ * return the full `Row` by type contract — trimming it at runtime would make the
+ * type a lie. Re-read with `findById`, or map it yourself, before handing a write
+ * result to a client.
+ */
+interface RepositoryOptions<TDoc = any, TRel extends RelationMap = RelationMap> {
     /** Declare populatable relations (field → model) so `with` types the result. */
     relations?: TRel;
+    /** Constant equality filter added to every read/write (RBAC / multi-tenancy). */
+    scope?: Scope<TDoc>;
+    /**
+     * Forced projection — the client's `columns` is **ignored entirely**. Keeps a
+     * password out of a `users` response without a `{ ...params, columns }` trick in
+     * every route. Must select at least one field, else building the repository throws.
+     */
+    forcedColumns?: ColumnSelection<TDoc>;
+    /**
+     * Allowlist — the client's `columns` is intersected with it. An empty
+     * intersection yields the allowlist itself, **never** the full document.
+     * An empty array throws (a projection selecting nothing means "everything").
+     */
+    allowedColumns?: readonly FieldKey<TDoc>[];
 }
 type TrueKeys<T> = {
     [K in keyof T]: T[K] extends true ? K : never;
@@ -154,7 +166,7 @@ type Params<TBase, TColumns, TWith> = Omit<TBase, "columns" | "with"> & {
     with?: TWith;
 };
 /**
- * Table-scoped repository (stage 1: reads + scoped). Read methods infer their
+ * Model-scoped repository. Read methods infer their
  * return type from the `columns` argument, mirroring `@querykitjs/drizzle-pg`.
  */
 interface Repository<TDoc = Record<string, unknown>, TRel extends Record<string, unknown> = Record<never, never>> {
@@ -192,12 +204,35 @@ 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. */
+/** {@link createRegistry} options — pagination defaults and bounds. */
 interface RegistryOptions {
     /** `findList` default page size (core `DEFAULT_PER_PAGE` = 20). */
     defaultPerPage?: number;
     /** `findInfinite`/`findCursor` default limit (core `DEFAULT_LIMIT` = 20). */
     defaultLimit?: number;
+    /**
+     * Upper bound for `perPage` (core `DEFAULT_MAX_PER_PAGE` = 200). Applied even
+     * when validation was bypassed — defense in depth. Disable with `Infinity`.
+     */
+    maxPerPage?: number;
+    /** Upper bound for `limit` (`findInfinite`/`findCursor`, core `DEFAULT_MAX_LIMIT` = 200). */
+    maxLimit?: number;
+    /**
+     * **Strict mode.** An unknown filter/sort key, or a value the operator cannot
+     * use, is no longer dropped silently — a `QueryKitError` is thrown (the backend
+     * maps it to a 400). Defaults to `false`, keeping the legacy (DbService)
+     * behaviour that dozens of existing endpoints rely on.
+     *
+     * Why it matters: a filter is meant to **narrow** a result set, so a mistyped
+     * key that vanishes silently makes the endpoint return **more** data than
+     * intended, with nothing in the log to show it.
+     */
+    strict?: boolean;
+    /**
+     * 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;
 }
 /** 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;
@@ -208,9 +243,9 @@ interface Registry {
     /** …extended with custom methods (2nd-arg extender fn — same as drizzle-pg). */
     repository<TDoc, TExt extends Record<string, unknown>>(model: Model<TDoc>, extend: RepositoryExtender<TDoc, Record<never, never>, TExt>): Repository<TDoc> & TExt;
     /** …with typed relations so populated `with` fields are typed. */
-    repository<TDoc, TRel extends RelationMap>(model: Model<TDoc>, options: RepositoryOptions<TRel>): Repository<TDoc, RelationDocs<TRel>>;
+    repository<TDoc, TRel extends RelationMap>(model: Model<TDoc>, options: RepositoryOptions<TDoc, TRel>): Repository<TDoc, RelationDocs<TRel>>;
     /** …with both typed relations and custom methods. */
-    repository<TDoc, TRel extends RelationMap, TExt extends Record<string, unknown>>(model: Model<TDoc>, options: RepositoryOptions<TRel>, extend: RepositoryExtender<TDoc, RelationDocs<TRel>, TExt>): Repository<TDoc, RelationDocs<TRel>> & TExt;
+    repository<TDoc, TRel extends RelationMap, TExt extends Record<string, unknown>>(model: Model<TDoc>, options: RepositoryOptions<TDoc, TRel>, extend: RepositoryExtender<TDoc, RelationDocs<TRel>, TExt>): Repository<TDoc, RelationDocs<TRel>> & TExt;
     /** Runs `fn` inside a MongoDB transaction (requires a replica set). */
     transaction<T>(fn: () => Promise<T>): Promise<T>;
 }
@@ -238,16 +273,20 @@ interface RepoRuntime {
     getSession: () => ClientSession | undefined;
     defaultPerPage: number;
     defaultLimit: number;
-}
-/** Per-repository configuration (scope). */
-interface RepoConfig<TDoc> {
-    scope?: Scope<TDoc>;
+    /** Upper bound for `perPage`, applied even when validation was bypassed. */
+    maxPerPage: number;
+    /** Upper bound for `limit` (`findInfinite`/`findCursor`). */
+    maxLimit: number;
+    /** Throw `QueryKitError` instead of dropping an unresolvable condition. */
+    strict: boolean;
+    /** Called for every dropped condition (also when `strict` is off). */
+    onSkippedCondition?: (info: SkippedCondition) => void;
 }
 /**
  * Build a model-scoped repository. `runtime` (session getter + defaults) comes
  * from the registry, so this file never touches the connection directly.
  */
-declare function buildRepository<TDoc>(runtime: RepoRuntime, model: Model<TDoc>, config?: RepoConfig<TDoc>): Repository<TDoc>;
+declare function buildRepository<TDoc>(runtime: RepoRuntime, model: Model<TDoc>, config?: RepositoryOptions<TDoc>): Repository<TDoc>;
 
 /**
  * Typed, ergonomic filter builders for a document type (field-name autocomplete).
@@ -276,6 +315,7 @@ declare function createFilters<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>>;
@@ -284,4 +324,4 @@ declare function createFilters<TDoc>(): {
     not: (node: _querykitjs_core.FilterNode<FieldKey<TDoc>, RawFilter<_TDoc>>) => _querykitjs_core.NotGroup<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 NotGroup, type OffsetMeta, type OffsetParams, type OffsetResult, type OrGroup, type QueryParams, type RawFilter, type Registry, type RegistryOptions, type RelationDocs, type RelationMap, type RepoConfig, 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 { 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_LIMIT, DEFAULT_PER_PAGE, createFilters as createFilters$1 } from '@querykitjs/core';
+import { TEXT_FILTER_OPERATORS, QueryKitError, DEFAULT_MAX_LIMIT, DEFAULT_MAX_PER_PAGE, DEFAULT_LIMIT, DEFAULT_PER_PAGE, createFilters as createFilters$1 } from '@querykitjs/core';
 export { f } from '@querykitjs/core';
 import { AsyncLocalStorage } from 'async_hooks';
 
@@ -22,6 +22,44 @@ function castValue(model, field, value) {
     return value;
   }
 }
+var TEXT_OPERATORS = new Set(TEXT_FILTER_OPERATORS);
+var INVALID_VALUE = /* @__PURE__ */ Symbol("querykit.invalid-value");
+var isTextOperator = (operator) => TEXT_OPERATORS.has(operator);
+function isDatePath(model, field) {
+  return model.schema.path(field)?.instance === "Date";
+}
+function castForPath(model, field, value) {
+  const path = model.schema.path(field);
+  if (!path || path.instance !== "Date" || value === null || value === void 0) return value;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? INVALID_VALUE : value;
+  try {
+    const cast = path.cast(value);
+    if (cast instanceof Date) return Number.isNaN(cast.getTime()) ? INVALID_VALUE : cast;
+    return cast ?? INVALID_VALUE;
+  } catch {
+    return INVALID_VALUE;
+  }
+}
+function coerceCondition(model, field, operator, value) {
+  if (value === void 0 || TEXT_OPERATORS.has(operator)) return value;
+  if (Array.isArray(value)) {
+    const items = [];
+    for (const item of value) {
+      const cast2 = castForPath(model, field, item);
+      if (cast2 === INVALID_VALUE) return INVALID_VALUE;
+      items.push(cast2);
+    }
+    return items;
+  }
+  const cast = castForPath(model, field, value);
+  return cast === INVALID_VALUE ? INVALID_VALUE : cast;
+}
+function reportSkip(diag, info) {
+  if (!diag) return;
+  const full = { ...info, source: diag.source };
+  if (diag.strict) throw new QueryKitError(full);
+  diag.onSkipped?.(full);
+}
 
 // src/internal/operators.ts
 var esc = (s) => String(s ?? "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -83,32 +121,47 @@ function combine(kind, parts) {
   if (valid.length === 1) return valid[0];
   return { [kind]: valid };
 }
-function buildCondition(model, cond) {
+function buildCondition(model, cond, diag) {
   const operator = cond.operation ?? "=";
   const build = operators[operator];
   if (!build) throw new Error(`Unsupported filter operator: "${operator}"`);
   const field = resolveField(model, cond.key);
-  if (!field) return void 0;
-  const fragment = build(cond.value);
-  if (fragment === void 0) return void 0;
+  if (!field) {
+    reportSkip(diag, { site: "filter", key: cond.key, operation: operator, reason: "unknown-key" });
+    return void 0;
+  }
+  if (isTextOperator(operator) && isDatePath(model, field)) {
+    reportSkip(diag, { site: "filter", key: cond.key, operation: operator, reason: "invalid-value" });
+    return void 0;
+  }
+  const value = coerceCondition(model, field, operator, cond.value);
+  if (value === INVALID_VALUE) {
+    reportSkip(diag, { site: "filter", key: cond.key, operation: operator, reason: "invalid-value" });
+    return void 0;
+  }
+  const fragment = build(value);
+  if (fragment === void 0) {
+    reportSkip(diag, { site: "filter", key: cond.key, operation: operator, reason: "invalid-value" });
+    return void 0;
+  }
   return { [field]: fragment };
 }
-function buildNode(model, node) {
-  if (isFieldCondition(node)) return buildCondition(model, node);
+function buildNode(model, node, diag) {
+  if (isFieldCondition(node)) return buildCondition(model, node, diag);
   if (isObject(node)) {
     if ("and" in node)
       return combine(
         "$and",
-        node.and.map((n) => buildNode(model, n))
+        node.and.map((n) => buildNode(model, n, diag))
       );
     if ("or" in node)
       return combine(
         "$or",
-        node.or.map((n) => buildNode(model, n))
+        node.or.map((n) => buildNode(model, n, diag))
       );
     if ("not" in node) {
       const notNode = node.not;
-      const inner = buildNode(model, notNode);
+      const inner = buildNode(model, notNode, diag);
       if (!inner) return void 0;
       if (isFieldCondition(notNode)) {
         const op = notNode.operation ?? "=";
@@ -123,14 +176,14 @@ function buildNode(model, node) {
   }
   return void 0;
 }
-function buildWhere(model, filter) {
+function buildWhere(model, filter, diag) {
   if (filter === void 0) return void 0;
   if (Array.isArray(filter))
     return combine(
       "$and",
-      filter.map((c) => buildNode(model, c))
+      filter.map((c) => buildNode(model, c, diag))
     );
-  return buildNode(model, filter);
+  return buildNode(model, filter, diag);
 }
 
 // src/internal/order-by.ts
@@ -138,11 +191,12 @@ function normalize(sort) {
   if (!sort) return [];
   return sort.filter((item) => item && item.key).map((item) => ({ key: item.key, direction: item.direction ?? "asc" }));
 }
-function buildSort(model, sort) {
+function buildSort(model, sort, diag) {
   const spec = {};
   for (const item of normalize(sort)) {
     const field = resolveField(model, item.key);
     if (field) spec[field] = item.direction === "desc" ? -1 : 1;
+    else reportSkip(diag, { site: "sort", key: item.key, reason: "unknown-key" });
   }
   if (Object.keys(spec).length === 0) {
     if (hasPath(model, "createdAt")) spec.createdAt = -1;
@@ -169,6 +223,7 @@ function decodeCursor(cursor) {
 }
 
 // src/repository.ts
+var clampPageSize = (requested, fallback, max) => Math.min(max, Math.max(1, Math.trunc(requested ?? fallback)));
 function buildRepository(runtime, model, config = {}) {
   const m = model;
   const hasDeletedAt = hasPath(m, "deletedAt");
@@ -176,12 +231,24 @@ function buildRepository(runtime, model, config = {}) {
   const stampUpdatedAt = hasPath(m, "updatedAt") && !timestampsOn;
   const forUpdate = (patch) => stampUpdatedAt ? { ...patch, updatedAt: /* @__PURE__ */ new Date() } : patch;
   const scopeConditions = config.scope ? Object.entries(config.scope).map(([key, value]) => ({ key, operation: "=", value })) : [];
+  for (const condition of scopeConditions) {
+    if (!resolveField(m, condition.key)) {
+      throw new QueryKitError({ source: m.modelName, site: "filter", key: condition.key, reason: "unknown-key" });
+    }
+  }
   const scopeWhere = scopeConditions.length ? buildWhere(m, scopeConditions) : void 0;
-  const sortSpec = (sort) => buildSort(m, sort);
+  const diag = {
+    source: m.modelName,
+    strict: runtime.strict,
+    onSkipped: runtime.onSkippedCondition
+  };
+  const sortSpec = (sort) => buildSort(m, sort, diag);
   const composeWhere = (userFilter, withDeleted) => {
-    const parts = [buildWhere(m, userFilter), scopeWhere, hasDeletedAt && !withDeleted ? { deletedAt: { $eq: null } } : void 0].filter(
-      (p) => p !== void 0
-    );
+    const parts = [
+      buildWhere(m, userFilter, diag),
+      scopeWhere,
+      hasDeletedAt && !withDeleted ? { deletedAt: { $eq: null } } : void 0
+    ].filter((p) => p !== void 0);
     if (parts.length === 0) return {};
     if (parts.length === 1) return parts[0];
     return { $and: parts };
@@ -192,9 +259,24 @@ function buildRepository(runtime, model, config = {}) {
     if (Array.isArray(filter)) return [...filter, idCondition];
     return { and: [filter, idCondition] };
   };
+  const truthyKeys = (selection) => Object.entries(selection).filter(([, on]) => on).map(([key]) => key);
+  const forcedKeys = config.forcedColumns ? truthyKeys(config.forcedColumns) : void 0;
+  if (config.forcedColumns && forcedKeys.length === 0) {
+    throw new Error("buildRepository: forcedColumns must select at least one field (an empty selection would return the full document).");
+  }
+  const allowed = config.allowedColumns ? new Set(config.allowedColumns) : void 0;
+  if (config.allowedColumns && allowed.size === 0) {
+    throw new Error("buildRepository: allowedColumns must list at least one field (an empty allowlist would return the full document).");
+  }
+  const guarded = Boolean(forcedKeys ?? allowed);
+  const permits = (key) => forcedKeys ? forcedKeys.includes(key) : allowed ? allowed.has(key) : true;
+  const intersectAllowed = (requested) => {
+    const hit = requested.filter((key) => allowed.has(key));
+    return hit.length > 0 ? hit : [...allowed];
+  };
   const projection = (columns) => {
-    if (!columns) return void 0;
-    const keys = Object.keys(columns).filter((k) => columns[k]);
+    const requested = columns ? truthyKeys(columns) : [];
+    const keys = forcedKeys ?? (allowed ? intersectAllowed(requested) : requested);
     if (keys.length === 0) return void 0;
     const proj = {};
     let includesId = false;
@@ -280,7 +362,7 @@ function buildRepository(runtime, model, config = {}) {
     },
     async findList(params = {}) {
       const page = Math.max(1, Math.trunc(params.page ?? 1));
-      const perPage = Math.max(1, Math.trunc(params.perPage ?? runtime.defaultPerPage));
+      const perPage = clampPageSize(params.perPage, runtime.defaultPerPage, runtime.maxPerPage);
       const where = composeWhere(params.filter, params.withDeleted);
       const [data, total_items] = await Promise.all([
         runFind(where, { sort: sortSpec(params.sort), columns: params.columns, with: params.with, limit: perPage, skip: (page - 1) * perPage }),
@@ -300,7 +382,7 @@ function buildRepository(runtime, model, config = {}) {
       };
     },
     async findInfinite(params = {}) {
-      const limit = Math.max(1, Math.trunc(params.limit ?? runtime.defaultLimit));
+      const limit = clampPageSize(params.limit, runtime.defaultLimit, runtime.maxLimit);
       const offset = Math.max(0, Math.trunc(params.offset ?? 0));
       const rows = await runFind(composeWhere(params.filter, params.withDeleted), {
         sort: sortSpec(params.sort),
@@ -317,12 +399,12 @@ function buildRepository(runtime, model, config = {}) {
       };
     },
     async findCursor(params = {}) {
-      const limit = Math.max(1, Math.trunc(params.limit ?? runtime.defaultLimit));
+      const limit = clampPageSize(params.limit, runtime.defaultLimit, runtime.maxLimit);
       const cursorKey = params.cursorKey ?? "id";
       const order = params.order ?? "asc";
       const direction = params.direction ?? "forward";
       const field = resolveField(m, cursorKey);
-      if (!field) throw new Error(`findCursor: unknown cursorKey "${cursorKey}".`);
+      if (!field) throw new QueryKitError({ source: diag.source, site: "cursorKey", key: cursorKey, reason: "unknown-key" });
       const decoded = decodeCursor(params.cursor);
       const cursorValue = decoded !== void 0 ? castValue(m, field, decoded) : void 0;
       const baseWhere = composeWhere(params.filter, params.withDeleted);
@@ -331,6 +413,7 @@ function buildRepository(runtime, model, config = {}) {
       const where = seek ? Object.keys(baseWhere).length ? { $and: [baseWhere, seek] } : seek : baseWhere;
       const selected = projection(params.columns);
       const proj = selected ? { ...selected, [field]: 1 } : void 0;
+      const leaksCursorField = guarded && selected !== void 0 && !permits(cursorKey) && !permits(field);
       let q = m.find(where, proj).sort({ [field]: ascInQuery ? 1 : -1 }).limit(limit + 1);
       q = applyPopulate(q, params.with);
       const rows = await attachSession(q).lean().exec();
@@ -341,16 +424,20 @@ function buildRepository(runtime, model, config = {}) {
       const last = pageRows[pageRows.length - 1];
       const has_next = direction === "forward" ? hasExtra : cursorValue !== void 0;
       const has_prev = direction === "forward" ? cursorValue !== void 0 : hasExtra;
-      return {
-        data: pageRows,
-        meta: {
-          limit,
-          has_next,
-          has_prev,
-          next_cursor: has_next && last ? encodeCursor(last[field]) : null,
-          prev_cursor: has_prev && first ? encodeCursor(first[field]) : null
-        }
+      const meta = {
+        limit,
+        has_next,
+        has_prev,
+        next_cursor: has_next && last ? encodeCursor(last[field]) : null,
+        prev_cursor: has_prev && first ? encodeCursor(first[field]) : null
       };
+      if (leaksCursorField) {
+        pageRows = pageRows.map((row) => {
+          const { [field]: _cursor, ...rest } = row;
+          return rest;
+        });
+      }
+      return { data: pageRows, meta };
     },
     count(filter) {
       return countWhere(composeWhere(filter));
@@ -428,7 +515,12 @@ function buildRepository(runtime, model, config = {}) {
       return row ?? void 0;
     },
     async aggregate(spec) {
-      const groupKeys = toArr(spec.groupBy);
+      const aggregable = (key) => {
+        const field = permits(key) ? resolveField(m, key) : void 0;
+        if (!field) reportSkip(diag, { site: "aggregate", key, reason: "unknown-key" });
+        return field;
+      };
+      const groupKeys = toArr(spec.groupBy).filter((key) => Boolean(aggregable(key)));
       const rawMatch = composeWhere(spec.filter, spec.withDeleted);
       let match = rawMatch;
       try {
@@ -437,12 +529,12 @@ function buildRepository(runtime, model, config = {}) {
         match = q.getFilter();
       } catch {
       }
-      const groupId = groupKeys.length ? Object.fromEntries(groupKeys.map((k) => [k, `$${resolveField(m, k) ?? k}`])) : null;
+      const groupId = groupKeys.length ? Object.fromEntries(groupKeys.map((k) => [k, `$${aggregable(k) ?? k}`])) : null;
       const group = { _id: groupId };
       if (spec.count) group.count = { $sum: 1 };
       const addAgg = (op, keys, prefix) => {
         for (const k of keys) {
-          const field = resolveField(m, k);
+          const field = aggregable(k);
           if (field) group[`${prefix}_${k}`] = { [op]: `$${field}` };
         }
       };
@@ -476,11 +568,16 @@ function createRegistry(connection, options = {}) {
   const runtime = {
     getSession: () => ctx.get()?.session,
     defaultPerPage: options.defaultPerPage ?? DEFAULT_PER_PAGE,
-    defaultLimit: options.defaultLimit ?? DEFAULT_LIMIT
+    defaultLimit: options.defaultLimit ?? DEFAULT_LIMIT,
+    maxPerPage: options.maxPerPage ?? DEFAULT_MAX_PER_PAGE,
+    maxLimit: options.maxLimit ?? DEFAULT_MAX_LIMIT,
+    strict: options.strict ?? false,
+    onSkippedCondition: options.onSkippedCondition
   };
   function repository(model, arg2, arg3) {
+    const repoOptions = typeof arg2 === "function" ? void 0 : arg2;
     const extend = typeof arg2 === "function" ? arg2 : arg3;
-    const base = buildRepository(runtime, model);
+    const base = buildRepository(runtime, model, repoOptions);
     return extend ? { ...base, ...extend(base) } : base;
   }
   const transaction = async (fn) => {