@querykitjs/mongoose 1.0.0 → 2.0.0

package/README.en.md

@@ -83,7 +83,21 @@ export const registry = createRegistry(mongoose.connection);
 // export const registry = createRegistry(mongoose.connection, { defaultPerPage: 20, defaultLimit: 20 });
 ```
 
-`defaultPerPage` (findList) / `defaultLimit` (infinite/cursor) fall back to `@querykitjs/core`'s **20** when omitted. The `connection` is passed in (so transactions share the right session).
+The `connection` is passed in (so transactions share the right session).
+
+**`createRegistry` options** — identical to the drizzle-pg adapter:
+
+| Option               | Default                           | Meaning                                                      |
+| -------------------- | --------------------------------- | ------------------------------------------------------------ |
+| `defaultPerPage`     | core `DEFAULT_PER_PAGE` (20)      | `findList` page size                                         |
+| `defaultLimit`       | core `DEFAULT_LIMIT` (20)         | `findInfinite`/`findCursor` limit                            |
+| `maxPerPage`         | core `DEFAULT_MAX_PER_PAGE` (200) | upper bound for `perPage` (`Infinity` disables it)           |
+| `maxLimit`           | core `DEFAULT_MAX_LIMIT` (200)    | upper bound for `limit`                                      |
+| `strict`             | `false`                           | unknown key → `QueryKitError` (400) instead of a silent drop |
+| `onSkippedCondition` | —                                 | callback for every dropped condition                         |
+
+`maxPerPage`/`maxLimit` are a **second layer**: even if validation
+(`@querykitjs/zod` factories) is bypassed, the repository clamps.
 
 ### 2. Per-model repositories
 
@@ -97,6 +111,82 @@ export const usersRepository = registry.repository(User, base => ({
 }));
 ```
 
+`repository()` takes four shapes (the same as the drizzle-pg adapter):
+
+```ts
+registry.repository(User);                            // plain
+registry.repository(User, base => ({ … }));           // + custom methods
+registry.repository(User, options);                   // + per-repo options
+registry.repository(User, options, base => ({ … }));  // both
+```
+
+### 3. Projection guards (`RepositoryOptions`)
+
+`columns` can arrive straight from the client, so the safe selection is declared
+on the **repository** — where `scope` (RBAC) already lives:
+
+```ts
+export const usersRepository = registry.repository(User, {
+  forcedColumns: { _id: true, fullName: true, email: true }, // password can never come out
+});
+
+// or softer: the client picks, but only from this list
+export const postsRepository = registry.repository(Post, {
+  allowedColumns: ["_id", "title", "createdAt"],
+});
+```
+
+| Option           | Behaviour                                                                     |
+| ---------------- | ----------------------------------------------------------------------------- |
+| `forcedColumns`  | the client's `columns` is **ignored entirely**                                |
+| `allowedColumns` | the client's selection is **intersected**; empty intersection → the allowlist |
+| `scope`          | constant equality filter on every read/write (also available via `scoped()`)  |
+| `relations`      | populatable relations (type-only — drives `with` inference)                   |
+
+Details worth knowing:
+
+- An empty intersection yields the allowlist, **not the full document**.
+- `aggregate` is guarded too: `min("password")` or `groupBy: "password"` leaks as
+  much as a projection.
+- `cursorKey` comes from the client and the cursor field must be selected for
+  pagination — under a guard it stays in the query but is **stripped** from the
+  documents you get back.
+- `forcedColumns: {}` or `allowedColumns: []` **throws** when the repository is built.
+- ⚠️ The guard affects **read** methods only (`findAll`/`findOne`/`findById`/
+  `findList`/`findInfinite`/`findCursor` + `aggregate`). Write methods (`create`,
+  `upsert`, `updateById`, `softDelete`, …) return the **full document** by type
+  contract. Re-read with `findById`, or map it yourself, before handing a write
+  result to a client.
+
+### 4. Bad conditions: watch them, or refuse them
+
+An unknown filter/sort key is **dropped silently** by default. The catch: a filter
+is meant to _narrow_ a result set, so a mistyped key that vanishes makes the
+endpoint return **more** data than intended.
+
+```ts
+// step 1: watch (behaviour unchanged)
+createRegistry(mongoose.connection, {
+  onSkippedCondition: info => logger.warn({ querykit: info }, "condition dropped"),
+});
+
+// step 2: once the log is clean — strict mode
+createRegistry(mongoose.connection, { strict: true });
+```
+
+```ts
+import { QueryKitError } from "@querykitjs/core";
+
+try {
+  return await usersRepository.findList(params);
+} catch (err) {
+  if (err instanceof QueryKitError) return c.json({ error: err.message, info: err.info }, 400);
+  throw err;
+}
+```
+
+A `scope` or `cursorKey` key is **always** fatal, regardless of `strict`.
+
 ## MongoDB specifics
 
 - **`id` ↔ `_id`.** Use `"id"` anywhere (filters, `columns`, `idKey`, `cursorKey`) — it resolves to Mongo's `_id`, so the wire contract is identical to the SQL adapter. String ids from the frontend cast to `ObjectId` automatically:
@@ -186,6 +276,36 @@ await mine.findList({ page: 1 }); // { supervisorId: user.id, ... }
 await mine.create({ ... });        // supervisorId forced to user.id
 ```
 
+A scope can also be given as `registry.repository(Model, { scope })`. An unknown
+scope key **throws** when the repository is built — dropping it silently would
+remove the RBAC filter.
+
+## Wire (JSON) values and migrating from DbService
+
+A request body is JSON, so a date always arrives as a **string**. The adapter
+casts it according to the schema path:
+
+```json
+{ "key": "createdAt", "operation": "<=", "value": "2026-07-28T12:00:00.000Z" }
+```
+
+- `Date` paths get the ISO string cast to a `Date`. The scope is **deliberately**
+  the same as drizzle-pg's: each adapter only judges the types it maps through JS
+  and leaves the rest to the database.
+- `in`/`notIn` arrays, `between`/`notBetween` tuples and cursor tokens are covered
+  too (`cursorKey: "createdAt"` paginates correctly).
+- ⚠️ **Documented divergence:** Mongo cannot `$regex` a `Date` path
+  (`Can't use $options with Date`), so a text-pattern operator
+  (`contains`/`ilike`/…) on a date field is **skipped**. drizzle-pg _can_ match it
+  (Postgres renders the timestamp as text). Neither adapter crashes, and the
+  difference shows up in `onSkippedCondition`.
+- An unparseable value (`"not-a-date"`) drops the condition (or 400s under
+  `strict`). **One** bad element in an `in` list drops the whole condition.
+
+**Migrating from DbService:** the old wire's `type: "date"` field is no longer
+needed — `@querykitjs/zod` strips it (without erroring) and coercion happens
+server-side from the path type.
+
 ## Soft-delete
 
 Auto-enabled when the schema has a `deletedAt` path. Reads exclude soft-deleted docs by default; `withDeleted: true` includes them. When the schema has no `{ timestamps: true }` but a manual `updatedAt` path, it is bumped on every update.

package/README.md

@@ -83,7 +83,21 @@ export const registry = createRegistry(mongoose.connection);
 // export const registry = createRegistry(mongoose.connection, { defaultPerPage: 20, defaultLimit: 20 });
 ```
 
-`defaultPerPage` (findList) / `defaultLimit` (infinite/cursor) berilmasa `@querykitjs/core`ning **20**siga tushadi. `connection` tashqaridan beriladi (tranzaksiya to'g'ri session'ni ulashsin uchun).
+`connection` tashqaridan beriladi (tranzaksiya to'g'ri session'ni ulashsin uchun).
+
+**`createRegistry` opsiyalari** — drizzle-pg adapteri bilan **aynan bir xil**:
+
+| Opsiya               | Default                           | Ma'nosi                                                   |
+| -------------------- | --------------------------------- | --------------------------------------------------------- |
+| `defaultPerPage`     | core `DEFAULT_PER_PAGE` (20)      | `findList` sahifa o'lchami                                |
+| `defaultLimit`       | core `DEFAULT_LIMIT` (20)         | `findInfinite`/`findCursor` `limit`i                      |
+| `maxPerPage`         | core `DEFAULT_MAX_PER_PAGE` (200) | `perPage` yuqori chegarasi (`Infinity` — o'chirish)       |
+| `maxLimit`           | core `DEFAULT_MAX_LIMIT` (200)    | `limit` yuqori chegarasi                                  |
+| `strict`             | `false`                           | noma'lum kalit → `QueryKitError` (400), jimgina skip emas |
+| `onSkippedCondition` | —                                 | tashlab yuborilgan har bir shart uchun callback           |
+
+`maxPerPage`/`maxLimit` — **ikkinchi himoya qatlami**: validatsiya
+(`@querykitjs/zod` factory'lari) chetlab o'tilsa ham repository o'zi clamp qiladi.
 
 ### 2. Har model uchun repository
 
@@ -97,6 +111,82 @@ export const usersRepository = registry.repository(User, base => ({
 }));
 ```
 
+`repository()` to'rt shaklda chaqiriladi (drizzle-pg adapteri bilan bir xil):
+
+```ts
+registry.repository(User);                            // sof
+registry.repository(User, base => ({ … }));           // + custom metodlar
+registry.repository(User, options);                   // + per-repo opsiyalar
+registry.repository(User, options, base => ({ … }));  // ikkisi ham
+```
+
+### 3. Projection himoyasi (`RepositoryOptions`)
+
+`columns` clientdan kelishi mumkin, shuning uchun xavfsiz tanlov **repository'da**
+belgilanadi — `scope` (RBAC) allaqachon shu yo'lda:
+
+```ts
+export const usersRepository = registry.repository(User, {
+  forcedColumns: { _id: true, fullName: true, email: true }, // parol hech qachon chiqmaydi
+});
+
+// yoki yumshoqroq: client faqat shu ro'yxatdan tanlaydi
+export const postsRepository = registry.repository(Post, {
+  allowedColumns: ["_id", "title", "createdAt"],
+});
+```
+
+| Opsiya           | Xulqi                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------- |
+| `forcedColumns`  | client `columns`i **butunlay e'tiborsiz**                                             |
+| `allowedColumns` | client tanlovi allowlist bilan **kesiladi**; kesishma bo'sh bo'lsa → allowlist        |
+| `scope`          | har bir o'qish/yozishga doimiy tenglik filtri (`scoped()` bilan ham berilishi mumkin) |
+| `relations`      | populate qilinadigan relation'lar (faqat tip — `with` inference uchun)                |
+
+Muhim nozikliklar:
+
+- Kesishma bo'sh bo'lganda natija **to'liq hujjat emas** — allowlistning o'zi.
+- `aggregate` ham shu guard ostida: `min("password")` yoki
+  `groupBy: "password"` projection bilan bir xil miqdorda ma'lumot chiqaradi.
+- `cursorKey` clientdan keladi va cursor maydoni paginatsiya uchun majburan
+  tanlanadi — guard bor bo'lsa u maydon so'rovda qoladi, lekin qaytariladigan
+  hujjatlardan **olib tashlanadi**.
+- `forcedColumns: {}` yoki `allowedColumns: []` — repository yaratilishida **xato**.
+- ⚠️ Guard **faqat o'qish** metodlariga ta'sir qiladi (`findAll`/`findOne`/
+  `findById`/`findList`/`findInfinite`/`findCursor` + `aggregate`). Yozish
+  metodlari (`create`, `upsert`, `updateById`, `softDelete`, …) tip kontrakti
+  bo'yicha **to'liq hujjatni** qaytaradi. Yozish natijasini clientga
+  qaytarishdan oldin `findById` bilan qayta o'qing yoki o'zingiz map qiling.
+
+### 4. Noto'g'ri shartlar: kuzatish yoki rad etish
+
+Noma'lum filter/sort kaliti default'da **jimgina tashlab yuboriladi**. Muammosi:
+filter natijani _cheklash_ uchun ishlatiladi, shuning uchun typo qilingan kalit
+yo'qolsa endpoint kutilganidan **ko'proq** data qaytaradi.
+
+```ts
+// 1-qadam: kuzatish (xulq o'zgarmaydi)
+createRegistry(mongoose.connection, {
+  onSkippedCondition: info => logger.warn({ querykit: info }, "shart tashlab yuborildi"),
+});
+
+// 2-qadam: log tozalanganda — qattiq rejim
+createRegistry(mongoose.connection, { strict: true });
+```
+
+```ts
+import { QueryKitError } from "@querykitjs/core";
+
+try {
+  return await usersRepository.findList(params);
+} catch (err) {
+  if (err instanceof QueryKitError) return c.json({ error: err.message, info: err.info }, 400);
+  throw err;
+}
+```
+
+`scope` va `cursorKey` kaliti **har doim** fatal (`strict`dan qat'i nazar).
+
 ## MongoDB-ga xos jihatlar
 
 - **`id` ↔ `_id`.** Istalgan joyda `"id"` ishlating (filter, `columns`, `idKey`, `cursorKey`) — u Mongo'ning `_id`siga o'giriladi, wire kontrakti SQL adapter bilan bir xil. Frontend'дан kelган string id'lar avtomatik `ObjectId`ga cast bo'ladi:
@@ -186,6 +276,36 @@ await mine.findList({ page: 1 }); // { supervisorId: user.id, ... }
 await mine.create({ ... });        // supervisorId majburan user.id
 ```
 
+Scope'ni `registry.repository(Model, { scope })` bilan ham berish mumkin.
+Noma'lum scope kaliti — repository yaratilishida **xato** (jimgina tashlansa
+RBAC filtri yo'qolib ketardi).
+
+## Wire (JSON) qiymatlari va DbService'dan migratsiya
+
+Backend so'rov body'sini JSON'da oladi, ya'ni sana har doim **string** bo'lib
+keladi. Adapter uni schema path tipiga qarab avtomatik cast qiladi:
+
+```json
+{ "key": "createdAt", "operation": "<=", "value": "2026-07-28T12:00:00.000Z" }
+```
+
+- `Date` path'lari → ISO string avtomatik `Date`ga aylanadi. Qamrov **ataylab**
+  drizzle-pg bilan bir xil: u ham faqat JS orqali map qilinadigan tiplarni
+  hukm qiladi, qolganini bazaga qoldiradi.
+- `in`/`notIn` massivlari, `between`/`notBetween` tuple'lari va cursor token ham
+  qamraladi (`cursorKey: "createdAt"` ishlaydi).
+- ⚠️ **Hujjatlashtirilgan farq:** Mongo `Date` path'da `$regex` qila olmaydi
+  (`Can't use $options with Date`), shuning uchun date maydonidagi text-pattern
+  operatori (`contains`/`ilike`/…) **tashlab yuboriladi**. drizzle-pg esa buni
+  bajaradi (Postgres timestamp'ni text sifatida render qiladi). Ikkalasi ham
+  crash qilmaydi; farq `onSkippedCondition`da ko'rinadi.
+- Parse bo'lmaydigan qiymat (`"not-a-date"`) shartni bekor qiladi (`strict`da —
+  400). `in` ro'yxatidagi **bitta** yaroqsiz element butun shartni bekor qiladi.
+
+**DbService migratsiyasi:** eski wire'dagi `type: "date"` maydoni endi keraksiz —
+`@querykitjs/zod` uni strip qiladi (xato bermaydi), coercion esa server tomonda
+path tipidan avtomatik.
+
 ## Soft-delete
 
 Schema'да `deletedAt` path bo'lsa avtomatik yoqiladi. O'qishlar default'да soft-delete qilingan hujjatlarni chiqarib tashlaydi; `withDeleted: true` ularni ham qo'shadi. `{ timestamps: true }` bo'lmasa lekin qo'lда `updatedAt` path bo'lsa, har update'да bumps qilinadi.

package/dist/index.cjs

@@ -23,6 +23,44 @@ function castValue(model, field, value) {
     return value;
   }
 }
+var TEXT_OPERATORS = new Set(core.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 core.QueryKitError(full);
+  diag.onSkipped?.(full);
+}
 
 // src/internal/operators.ts
 var esc = (s) => String(s ?? "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -84,32 +122,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 ?? "=";
@@ -124,14 +177,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
@@ -139,11 +192,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;
@@ -170,6 +224,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");
@@ -177,12 +232,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 core.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 };
@@ -193,9 +260,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;
@@ -281,7 +363,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 }),
@@ -301,7 +383,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),
@@ -318,12 +400,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 core.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);
@@ -332,6 +414,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();
@@ -342,16 +425,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));
@@ -429,7 +516,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 {
@@ -438,12 +530,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}` };
         }
       };
@@ -477,11 +569,16 @@ function createRegistry(connection, options = {}) {
   const runtime = {
     getSession: () => ctx.get()?.session,
     defaultPerPage: options.defaultPerPage ?? core.DEFAULT_PER_PAGE,
-    defaultLimit: options.defaultLimit ?? core.DEFAULT_LIMIT
+    defaultLimit: options.defaultLimit ?? core.DEFAULT_LIMIT,
+    maxPerPage: options.maxPerPage ?? core.DEFAULT_MAX_PER_PAGE,
+    maxLimit: options.maxLimit ?? core.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) => {