@classytic/repo-core 0.28.0 → 0.30.0

package/dist/query-parser/parse-url.mjs

@@ -1,226 +1,93 @@
-import { TRUE, and, anyOf as in_, between, contains, endsWith, eq, gt, gte, iEq, isNotNull, isNull, like, lt, lte, ne, nin, regex, startsWith } from "../filter/builders.mjs";
-import { coerceList, coerceValue } from "./coerce.mjs";
-import { isControlParam } from "./reserved.mjs";
+import { QueryGrammarError } from "./errors.mjs";
+import { clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord } from "./grammar.mjs";
 //#region src/query-parser/parse-url.ts
-const DEFAULT_LIMIT = 20;
-const DEFAULT_MAX_LIMIT = 200;
-const DEFAULT_MAX_DEPTH = 10;
-const DEFAULT_MAX_REGEX = 500;
-const DEFAULT_MAX_SEARCH = 200;
 /**
-* Hard cap on URL parameter KEY length. Param keys land in regex-based
-* bracket parsing (`/^([^[\]]+)\[([^\]]+)\]$/` and friends); without a
-* length bound, a hostile caller can submit a 1MB key and force the
-* parser to scan the entire string for every regex try. Keys that
-* exceed this cap are silently skipped — legitimate URL params don't
-* approach this bound.
+* URL → {@link ParsedQuery} with a portable Filter IR. The grammar (keys, operators, coercion,
+* paging) is `./grammar.ts`'s; this adds only the IR emission and the populate spec.
+*
+*   ?status=active&age[gte]=18          → and(eq(status), gte(age, 18))
+*   ?role[in]=admin,editor              → in_(role, [...])
+*   ?name[contains]=john&sort=-createdAt → contains(name, 'john') + sort
 */
-const MAX_PARAM_KEY_LENGTH = 256;
-const ALL_OPERATORS = /* @__PURE__ */ new Set([
-	"eq",
-	"ne",
-	"gt",
-	"gte",
-	"lt",
-	"lte",
-	"in",
-	"nin",
-	"like",
-	"contains",
-	"startsWith",
-	"endsWith",
-	"ieq",
-	"regex",
-	"between",
-	"exists"
-]);
-/** Parse URL search params into a driver-agnostic ParsedQuery. */
+const FIELD_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)*$/;
+/** Parse URL search params into a driver-agnostic ParsedQuery. Invalid input throws a 400. */
 function parseUrl(input, options = {}) {
-	const params = normalize(input);
-	const maxLimit = options.maxLimit ?? DEFAULT_MAX_LIMIT;
-	const allowedOps = options.allowedOperators ? new Set(options.allowedOperators) : ALL_OPERATORS;
-	const rawPage = params.get("page");
-	const rawLimit = params.get("limit");
-	const after = params.get("after") ?? void 0;
-	const limit = clampLimit(rawLimit, options.defaultLimit ?? DEFAULT_LIMIT, maxLimit);
-	const page = rawPage !== null && rawPage !== void 0 ? toPositiveInt(rawPage) : void 0;
-	const sort = parseSort(params.get("sort"), options.allowedSortFields);
-	const select = parseSelect(params.get("select"));
-	const populate = parsePopulate(params);
-	const rawSearch = params.get("search");
-	const searchCap = options.maxSearchLength ?? DEFAULT_MAX_SEARCH;
-	const search = rawSearch !== null && rawSearch !== void 0 && rawSearch.length > 0 ? rawSearch.slice(0, searchCap) : void 0;
+	const record = toRecord(input);
+	const pageRequest = readPageRequest({
+		page: first(record["page"]),
+		limit: first(record["limit"]),
+		after: first(record["after"])
+	}, {
+		defaultLimit: options.defaultLimit,
+		maxLimit: options.maxLimit
+	});
+	const { clauses } = readFilterClauses(record, {
+		allowedFilterFields: options.allowedFilterFields,
+		allowedOperators: options.allowedOperators,
+		fieldTypes: options.fieldTypes,
+		maxTextLength: options.maxRegexLength ?? 500
+	});
 	const result = {
-		filter: parseFilters(params, {
-			allowedFields: options.allowedFilterFields,
-			allowedOps,
-			fieldTypes: options.fieldTypes,
-			maxDepth: options.maxFilterDepth ?? DEFAULT_MAX_DEPTH,
-			maxRegex: options.maxRegexLength ?? DEFAULT_MAX_REGEX
-		}),
-		limit
+		filter: clausesToFilter(clauses),
+		limit: pageRequest.limit
 	};
+	const sort = readSort(record["sort"], { allowedSortFields: options.allowedSortFields });
 	if (sort) result.sort = sort;
+	const select = readSelect(record["select"]);
 	if (select) result.select = select;
+	const populate = readPopulate(record);
 	if (populate.length > 0) result.populate = populate;
-	if (page !== void 0) result.page = page;
-	if (after !== void 0) result.after = after;
+	if (pageRequest.page !== void 0) result.page = pageRequest.page;
+	if (pageRequest.after !== void 0) result.after = pageRequest.after;
+	const search = readSearch(first(record["search"]), { maxSearchLength: options.maxSearchLength });
 	if (search !== void 0) result.search = search;
 	return result;
 }
-function normalize(input) {
-	if (input instanceof URLSearchParams) return {
-		get: (k) => input.get(k),
-		entries: () => input.entries(),
-		has: (k) => input.has(k)
-	};
-	if (Symbol.iterator in input) {
-		const usp = new URLSearchParams();
-		for (const [k, v] of input) usp.append(k, v);
-		return {
-			get: (k) => usp.get(k),
-			entries: () => usp.entries(),
-			has: (k) => usp.has(k)
-		};
-	}
-	const record = input;
-	const usp = new URLSearchParams();
-	for (const [k, v] of Object.entries(record)) {
-		if (v === void 0) continue;
-		if (Array.isArray(v)) for (const item of v) usp.append(k, item);
-		else usp.append(k, v);
-	}
-	return {
-		get: (k) => usp.get(k),
-		entries: () => usp.entries(),
-		has: (k) => usp.has(k)
-	};
-}
-function clampLimit(raw, fallback, max) {
-	if (raw === null || raw === void 0) return fallback;
-	const n = Number(raw);
-	if (!Number.isFinite(n) || n < 1) return fallback;
-	return Math.min(Math.floor(n), max);
-}
-function toPositiveInt(raw) {
-	const n = Number(raw);
-	if (!Number.isFinite(n) || n < 1) return void 0;
-	return Math.floor(n);
-}
-function parseSort(raw, allowed) {
-	if (!raw) return void 0;
-	const spec = {};
-	for (const piece of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
-		const desc = piece.startsWith("-");
-		const field = desc ? piece.slice(1) : piece.startsWith("+") ? piece.slice(1) : piece;
-		if (allowed && !allowed.includes(field)) continue;
-		spec[field] = desc ? -1 : 1;
-	}
-	return Object.keys(spec).length > 0 ? spec : void 0;
-}
-function parseSelect(raw) {
-	if (!raw) return void 0;
-	const spec = {};
-	for (const piece of raw.split(",").map((s) => s.trim()).filter(Boolean)) if (piece.startsWith("-")) spec[piece.slice(1)] = 0;
-	else spec[piece] = 1;
-	return Object.keys(spec).length > 0 ? spec : void 0;
+/** A repeated control param (`?limit=5&limit=9`) is ambiguous — refused rather than guessed. */
+function first(value) {
+	if (!Array.isArray(value)) return value;
+	if (value.length > 1) throw new QueryGrammarError("query", "a control parameter is repeated");
+	return value[0];
 }
 /**
-* Parse `populate[field][select]=...&populate[field][match][other]=...` into
-* an array of ParsedPopulate specs. Flat iteration keeps the parser simple;
-* nested populate (`populate[author][populate][org][select]=...`) is supported
-* one level deep.
+* `populate[path][select]=a,b` and `populate[path][match][field]=value` (field equality only —
+* a `$` key or a nested condition is refused, never passed to the kit).
 */
-function parsePopulate(params) {
-	const byField = /* @__PURE__ */ new Map();
-	for (const [key, value] of params.entries()) {
-		if (key.length > MAX_PARAM_KEY_LENGTH) continue;
-		if (!key.startsWith("populate[")) continue;
-		const match = /^populate\[([^\]]+)\](?:\[([^\]]+)\](?:\[([^\]]+)\])?)?$/.exec(key);
-		if (!match) continue;
-		const [, field, sub, subKey] = match;
-		if (!field) continue;
-		const existing = byField.get(field) ?? {};
-		if (!sub) byField.set(field, existing);
-		else if (sub === "select") {
-			existing.select = value;
-			byField.set(field, existing);
-		} else if (sub === "match" && subKey) {
-			existing.match = existing.match ?? {};
-			existing.match[subKey] = value;
-			byField.set(field, existing);
-		}
-	}
-	const out = [];
-	for (const [path, spec] of byField) {
-		const entry = { path };
-		if (spec.select !== void 0) entry.select = spec.select;
-		if (spec.match) entry.match = spec.match;
-		out.push(entry);
-	}
-	return out;
-}
-function parseFilters(params, ctx) {
-	const leaves = [];
-	const fieldGroups = /* @__PURE__ */ new Map();
-	for (const [key, rawValue] of params.entries()) {
-		if (key.length > MAX_PARAM_KEY_LENGTH) continue;
-		if (isControlParam(key) || key.startsWith("populate[")) continue;
-		const bracket = /^([^[\]]+)\[([^\]]+)\]$/.exec(key);
-		let field;
-		let op;
-		if (bracket) {
-			const [, f, o] = bracket;
-			if (!f || !o) continue;
-			field = f;
-			op = o;
-		} else {
-			field = key;
-			op = "eq";
+function readPopulate(record) {
+	const byPath = /* @__PURE__ */ new Map();
+	const entry = (path) => {
+		if (!FIELD_RE.test(path)) throw new QueryGrammarError(`populate[${path}]`, "not a field path", "syntax");
+		const existing = byPath.get(path) ?? { path };
+		byPath.set(path, existing);
+		return existing;
+	};
+	for (const [key, value] of Object.entries(record)) {
+		if (key === "populate" && value !== null && typeof value === "object" && !Array.isArray(value)) {
+			for (const [path, spec] of Object.entries(value)) {
+				const target = entry(path);
+				if (spec === null || typeof spec !== "object" || Array.isArray(spec)) continue;
+				const { select, match } = spec;
+				if (typeof select === "string") target.select = select;
+				if (match !== void 0) target.match = readMatch(path, match);
+			}
+			continue;
 		}
-		if (ctx.allowedFields && !ctx.allowedFields.includes(field)) continue;
-		if (!ctx.allowedOps.has(op)) continue;
-		const fieldType = ctx.fieldTypes?.[field];
-		const leaf = buildLeaf(field, op, rawValue, fieldType, ctx);
-		if (!leaf) continue;
-		const bucket = fieldGroups.get(field) ?? [];
-		bucket.push(leaf);
-		fieldGroups.set(field, bucket);
+		const flat = /^populate\[([^\]]+)\](?:\[(select|match)\](?:\[([^\]]+)\])?)?$/.exec(key);
+		if (!flat) continue;
+		const [, path, sub, matchField] = flat;
+		const target = entry(path);
+		if (sub === "select") target.select = String(value);
+		if (sub === "match" && matchField) target.match = {
+			...target.match,
+			...readMatch(path, { [matchField]: value })
+		};
 	}
-	for (const [, nodes] of fieldGroups) if (nodes.length === 1) leaves.push(nodes[0]);
-	else leaves.push(and(...nodes));
-	if (leaves.length === 0) return TRUE;
-	if (leaves.length === 1) return leaves[0];
-	return and(...leaves);
+	return [...byPath.values()];
 }
-function buildLeaf(field, op, rawValue, fieldType, ctx) {
-	switch (op) {
-		case "eq": return eq(field, coerceValue(rawValue, fieldType));
-		case "ne": return ne(field, coerceValue(rawValue, fieldType));
-		case "gt": return gt(field, coerceValue(rawValue, fieldType));
-		case "gte": return gte(field, coerceValue(rawValue, fieldType));
-		case "lt": return lt(field, coerceValue(rawValue, fieldType));
-		case "lte": return lte(field, coerceValue(rawValue, fieldType));
-		case "in": return in_(field, coerceList(rawValue, fieldType));
-		case "nin": return nin(field, coerceList(rawValue, fieldType));
-		case "like": return like(field, rawValue);
-		case "contains": return contains(field, rawValue);
-		case "startsWith": return startsWith(field, rawValue);
-		case "endsWith": return endsWith(field, rawValue);
-		case "ieq": return iEq(field, rawValue);
-		case "regex":
-			if (rawValue.length > ctx.maxRegex) return void 0;
-			return regex(field, rawValue);
-		case "between": {
-			const parts = coerceList(rawValue, fieldType);
-			if (parts.length < 2) return void 0;
-			return between(field, parts[0], parts[1]);
-		}
-		case "exists": {
-			const val = rawValue.toLowerCase();
-			return val === "true" || val === "1" ? isNotNull(field) : isNull(field);
-		}
-	}
+function readMatch(path, match) {
+	if (match === null || typeof match !== "object" || Array.isArray(match)) throw new QueryGrammarError(`populate[${path}][match]`, "use populate[path][match][field]=value", "syntax");
+	for (const [field, value] of Object.entries(match)) if (!FIELD_RE.test(field) || value !== null && typeof value === "object") throw new QueryGrammarError(`populate[${path}][match]`, `field equality only: "${field}"`, "syntax");
+	return match;
 }
 //#endregion
 export { parseUrl };

package/dist/query-parser/regex-safety.d.mts

@@ -0,0 +1,31 @@
+//#region src/query-parser/regex-safety.d.ts
+/**
+ * ReDoS assessment for a user-supplied regex — the ONE analyser every parser uses.
+ *
+ * STRUCTURAL, not a regex over the regex: the pattern is walked token by token with a group stack,
+ * so nesting is seen however it is spelled. A pattern is unsafe when:
+ *   - a group REPEATED by `*`, `+` or `{n,}` / `{n,m}` (m > 1) contains a repetition or an
+ *     alternation — `(a+)+`, `(a*)*`, `(.*)*`, `(a|aa)+`, `((ab)*)+` (exponential backtracking);
+ *   - it uses a backreference (`\1`, `\k<name>`) — matching becomes NP-hard;
+ *   - it carries more than {@link MAX_UNBOUNDED_QUANTIFIERS} unbounded quantifiers
+ *     (`.*.*.*…` — polynomial, but degree grows with each);
+ *   - it exceeds the complexity budget: more than 8 groups, more than 10 alternations, or
+ *     unbounded quantifiers × groups above 40 (`(a*)(b+)(c*)…` — dense, overlapping, polynomial);
+ *   - it is not valid syntax.
+ * Conservative on purpose: `(foo|bar)+` is refused too. A user regex runs on a shared database;
+ * refusing a rare legitimate pattern costs a 400, accepting a hostile one costs the server.
+ */
+declare const MAX_UNBOUNDED_QUANTIFIERS = 20;
+type RegexRisk = {
+  readonly safe: true;
+} | {
+  readonly safe: false;
+  readonly reason: 'nested-quantifier' | 'backreference' | 'too-many-quantifiers' | 'too-complex' | 'invalid' | 'too-long';
+};
+declare function assessRegex(pattern: string, options?: {
+  maxLength?: number;
+}): RegexRisk;
+/** Escape every regex metacharacter — the literal-match fallback for an unsafe pattern. */
+declare function escapeRegex(value: string): string;
+//#endregion
+export { MAX_UNBOUNDED_QUANTIFIERS, RegexRisk, assessRegex, escapeRegex };

package/dist/query-parser/regex-safety.mjs

@@ -0,0 +1,151 @@
+//#region src/query-parser/regex-safety.ts
+/**
+* ReDoS assessment for a user-supplied regex — the ONE analyser every parser uses.
+*
+* STRUCTURAL, not a regex over the regex: the pattern is walked token by token with a group stack,
+* so nesting is seen however it is spelled. A pattern is unsafe when:
+*   - a group REPEATED by `*`, `+` or `{n,}` / `{n,m}` (m > 1) contains a repetition or an
+*     alternation — `(a+)+`, `(a*)*`, `(.*)*`, `(a|aa)+`, `((ab)*)+` (exponential backtracking);
+*   - it uses a backreference (`\1`, `\k<name>`) — matching becomes NP-hard;
+*   - it carries more than {@link MAX_UNBOUNDED_QUANTIFIERS} unbounded quantifiers
+*     (`.*.*.*…` — polynomial, but degree grows with each);
+*   - it exceeds the complexity budget: more than 8 groups, more than 10 alternations, or
+*     unbounded quantifiers × groups above 40 (`(a*)(b+)(c*)…` — dense, overlapping, polynomial);
+*   - it is not valid syntax.
+* Conservative on purpose: `(foo|bar)+` is refused too. A user regex runs on a shared database;
+* refusing a rare legitimate pattern costs a 400, accepting a hostile one costs the server.
+*/
+const MAX_UNBOUNDED_QUANTIFIERS = 20;
+/**
+* The quantifier token at `i`: its length, whether it repeats (max > 1), whether the count is
+* VARIABLE (min ≠ max — the source of backtracking ambiguity; `{2}` is not) and whether it is unbounded.
+*/
+function readQuantifier(p, i) {
+	const c = p[i];
+	if (c === "*" || c === "+") return {
+		length: 1,
+		repeats: true,
+		variable: true,
+		unbounded: true
+	};
+	if (c === "?") return {
+		length: 1,
+		repeats: false,
+		variable: true,
+		unbounded: false
+	};
+	if (c !== "{") return null;
+	const m = /^\{(\d+)(,(\d*))?\}/.exec(p.slice(i));
+	if (!m) return null;
+	const min = Number(m[1]);
+	const max = m[2] !== void 0 ? m[3] === "" ? Number.POSITIVE_INFINITY : Number(m[3]) : min;
+	return {
+		length: m[0].length,
+		repeats: max > 1,
+		variable: min !== max,
+		unbounded: max === Number.POSITIVE_INFINITY
+	};
+}
+function assessRegex(pattern, options = {}) {
+	if (options.maxLength !== void 0 && pattern.length > options.maxLength) return {
+		safe: false,
+		reason: "too-long"
+	};
+	try {
+		new RegExp(pattern);
+	} catch {
+		return {
+			safe: false,
+			reason: "invalid"
+		};
+	}
+	const stack = [{
+		repeats: false,
+		alternates: false
+	}];
+	/** The group that just closed — the atom a following quantifier applies to. */
+	let closedGroup = null;
+	let unbounded = 0;
+	let groups = 0;
+	let alternations = 0;
+	for (let i = 0; i < pattern.length; i++) {
+		const c = pattern[i];
+		const top = stack[stack.length - 1];
+		if (c === "\\") {
+			const next = pattern[i + 1] ?? "";
+			if (/[1-9]/.test(next) || next === "k") return {
+				safe: false,
+				reason: "backreference"
+			};
+			i += 1;
+			closedGroup = null;
+			continue;
+		}
+		if (c === "[") {
+			let j = i + 1;
+			if (pattern[j] === "^") j++;
+			if (pattern[j] === "]") j++;
+			while (j < pattern.length && pattern[j] !== "]") j += pattern[j] === "\\" ? 2 : 1;
+			i = j;
+			closedGroup = null;
+			continue;
+		}
+		if (c === "(") {
+			groups += 1;
+			stack.push({
+				repeats: false,
+				alternates: false
+			});
+			if (pattern[i + 1] === "?") {
+				const kind = /^\?(?:[:=!]|<[=!]|<[A-Za-z_][A-Za-z0-9_]*>)/.exec(pattern.slice(i + 1));
+				if (kind) i += kind[0].length;
+			}
+			closedGroup = null;
+			continue;
+		}
+		if (c === ")") {
+			const frame = stack.pop();
+			const parent = stack[stack.length - 1];
+			if (frame.repeats) parent.repeats = true;
+			closedGroup = frame;
+			continue;
+		}
+		if (c === "|") {
+			alternations += 1;
+			top.alternates = true;
+			closedGroup = null;
+			continue;
+		}
+		const q = readQuantifier(pattern, i);
+		if (q) {
+			if (q.unbounded) unbounded += 1;
+			if (q.repeats) {
+				if (closedGroup && (closedGroup.repeats || closedGroup.alternates)) return {
+					safe: false,
+					reason: "nested-quantifier"
+				};
+			}
+			if (q.repeats && q.variable) top.repeats = true;
+			i += q.length - 1;
+			if (pattern[i + 1] === "?" || pattern[i + 1] === "+") i += 1;
+			closedGroup = null;
+			continue;
+		}
+		closedGroup = null;
+	}
+	if (unbounded > 20) return {
+		safe: false,
+		reason: "too-many-quantifiers"
+	};
+	if (groups > 8 || alternations > 10 || unbounded * groups > 40) return {
+		safe: false,
+		reason: "too-complex"
+	};
+	return { safe: true };
+}
+/** Escape every regex metacharacter — the literal-match fallback for an unsafe pattern. */
+function escapeRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+export { MAX_UNBOUNDED_QUANTIFIERS, assessRegex, escapeRegex };

package/dist/query-parser/reserved.mjs

@@ -31,6 +31,7 @@ const STANDARD_RESERVED_PARAMS = /* @__PURE__ */ new Set([
 	"select",
 	"populate",
 	"search",
+	"filter",
 	"_count",
 	"_distinct",
 	"_exists"

package/dist/query-parser/types.d.mts

@@ -1,4 +1,5 @@
 import { Filter } from "../filter/types.mjs";
+import { QueryFieldType } from "./coerce.mjs";
 //#region src/query-parser/types.d.ts
 /** Sort direction on a single field. */
 type ParsedSortDirection = 1 | -1;
@@ -51,47 +52,36 @@ interface ParsedQuery {
   /** Free-text search term (kits interpret per backend — $text, FTS, etc.). */
   search?: string;
 }
-/**
- * Configuration knobs for the parser. All optional — sane defaults cover
- * typical arc use cases.
- */
+/** Parser knobs. Every allowlist REFUSES (400) what it does not name — never drops it. */
 interface QueryParserOptions {
-  /** Default per-page count when the URL omits `limit`. Default: 20. */
+  /** Per-page count when the URL omits `limit`. Default: 20. */
   defaultLimit?: number;
-  /** Hard cap on `limit` to prevent resource exhaustion. Default: 200. */
+  /** Cap on `limit`; a larger request is clamped to it. Default: 1000. */
   maxLimit?: number;
-  /** Allowlist of filter field names. When set, unknown fields are dropped. */
+  /** Filterable fields. */
   allowedFilterFields?: readonly string[];
-  /** Allowlist of sort field names. When set, unknown fields are dropped. */
+  /** Sortable fields. */
   allowedSortFields?: readonly string[];
-  /** Allowlist of operator names accepted in bracket syntax. */
+  /** URL operator names permitted in `field[op]`. */
   allowedOperators?: readonly BracketOperator[];
-  /** Max filter nesting depth (defends against filter-bomb URLs). Default: 10. */
-  maxFilterDepth?: number;
-  /** Regex pattern length cap (ReDoS defense). Default: 500. */
+  /** Longest text-operator value or regex pattern. Default: 500. */
   maxRegexLength?: number;
-  /** Search query length cap. Default: 200. */
+  /** Longest `search`. Default: 200. */
   maxSearchLength?: number;
   /**
-   * Field-type hints for value coercion. When a filter field is in this
-   * map, the URL string value is coerced to the declared type:
-   *   - `'number'`  → `Number(value)`
-   *   - `'boolean'` → `'true'`/`'1'` → true, else false
-   *   - `'date'`    → `new Date(value)` (validated)
-   *   - `'string'`  → left as-is (default for unlisted fields)
-   *
-   * Use this to avoid the heuristic coercion's footguns (e.g. `?sku=12345`
-   * against a string SKU column — without a hint, heuristics turn it into
-   * a number and the SQL comparison fails).
+   * Declared field types — exact coercion, and a value that does not fit is refused. Without one,
+   * the grammar's conservative heuristic applies (see `coerceQueryValue`).
    */
-  fieldTypes?: Record<string, 'string' | 'number' | 'boolean' | 'date'>;
+  fieldTypes?: Record<string, QueryFieldType>;
 }
 /**
  * Bracket operators accepted in URL syntax. When you see `field[op]=value`
  * in a URL, `op` is one of these. Kept as a closed set — new operators
  * require a new version.
  */
-type BracketOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'contains' | 'startsWith' | 'endsWith' | 'ieq' | 'regex' | 'between' | 'exists';
+type BracketOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'contains' | 'startsWith' | 'endsWith' | 'ieq' | 'regex' | 'between' | 'exists' |
+/** Flags for the `regex` on the same field (`i`, `m`, `s`, `x`). */
+'options';
 /**
  * Input shape for `parseUrl`. URL search params can be sourced from
  * `URLSearchParams.entries()`, Fastify's `request.query`, or

package/dist/repository/types.d.mts

@@ -844,7 +844,7 @@ type AggCacheOptions = CacheOptions;
  * | --------------- | ------------------------------ | ------------------------ | ----------- |
  * | `allowDiskUse`  | `aggregate({ allowDiskUse })`  | ignored (planner spills) | per-driver  |
  * | `maxTimeMs`     | `aggregate({ maxTimeMS })`     | ignored (sync driver)    | per-driver  |
- * | `indexHint`     | `aggregate({ hint })`          | ignored (planner-driven) | per-driver  |
+ * | `indexHint`     | `{ leadingKeys }` checked; else `hint` | ignored (planner-driven) | per-driver  |
  *
  * **Hosts that need a hint to work** must pin the kit version that
  * supports it via peer-deps. Falling back to "ignored" keeps mixed-
@@ -874,10 +874,11 @@ interface AggExecutionHints {
    */
   maxTimeMs?: number;
   /**
-   * Index hint passed to the planner. Kit-specific shape:
-   * mongokit accepts `{ field: 1 }` or an index name string;
-   * sqlitekit ignores (the SQLite planner picks indexes itself).
-   * Use sparingly — most aggregations plan correctly without hints.
+   * Index hint. The PORTABLE form is `{ leadingKeys: string[] }` — an expectation that an index
+   * leading with those fields serves this read. It is never forced: mongokit checks a declared
+   * index matches (and throws a configuration error naming what is declared if none does); kits
+   * whose planner picks indexes itself (sqlitekit) ignore it. Any other shape is kit-specific and
+   * FORCED — mongokit sends a `{ field: 1 }` object or an index name as the driver `hint`.
    */
   indexHint?: unknown;
 }

package/dist/schema/field-rules.mjs

@@ -158,17 +158,60 @@ function mergeFieldRuleConstraints(schemas, schemaOptions) {
 		for (const [field, rule] of Object.entries(rules)) {
 			const prop = properties[field];
 			if (!prop || typeof prop !== "object") continue;
-			if (rule.minLength != null && prop["minLength"] == null) prop["minLength"] = rule.minLength;
-			if (rule.maxLength != null && prop["maxLength"] == null) prop["maxLength"] = rule.maxLength;
-			if (rule.min != null && prop["minimum"] == null) prop["minimum"] = rule.min;
-			if (rule.max != null && prop["maximum"] == null) prop["maximum"] = rule.max;
-			if (rule.pattern != null && prop["pattern"] == null) prop["pattern"] = rule.pattern;
-			if (rule.enum != null && prop["enum"] == null) prop["enum"] = rule.enum;
+			for (const target of elementSchemas(prop)) {
+				if (rule.minLength != null && target["minLength"] == null) target["minLength"] = rule.minLength;
+				if (rule.maxLength != null && target["maxLength"] == null) target["maxLength"] = rule.maxLength;
+				if (rule.min != null && target["minimum"] == null) target["minimum"] = rule.min;
+				if (rule.max != null && target["maximum"] == null) target["maximum"] = rule.max;
+				if (rule.pattern != null && target["pattern"] == null) target["pattern"] = rule.pattern;
+				if (rule.enum != null && target["enum"] == null) target["enum"] = rule.enum;
+			}
 			if (rule.description != null && prop["description"] == null) prop["description"] = rule.description;
 			if (rule.nullable === true) applyNullable(prop);
 		}
 	}
 }
+/** Is this property typed as an array — `'array'` or a tuple that includes it? */
+function isArrayTyped(prop) {
+	const type = prop["type"];
+	return type === "array" || Array.isArray(type) && type.includes("array");
+}
+/**
+* Where a VALUE constraint (`enum`, `pattern`, `minLength`, …) belongs.
+*
+* On a scalar property: the property. On an array property: every ELEMENT
+* schema, never the array.
+*
+* Writing them onto the array is not merely redundant, it is wrong in two
+* different directions depending on the keyword, and neither one throws:
+*
+* - `enum` on an array compares the WHOLE array to each member, which a list
+*   of strings can never equal — so every write is refused, including one that
+*   omits the field, and the error names a field the caller did not send.
+* - `pattern`, `minLength`, `maxLength`, `minimum`, `maximum` are string /
+*   number keywords, and JSON Schema ignores them on an array — so the rule
+*   validates NOTHING while reading as enforced.
+*
+* `min`/`max` therefore bound each element's value, not the item count. That
+* keeps one meaning per keyword; reinterpreting them as `minItems` on arrays
+* only would make a rule's meaning depend on a type the author never wrote.
+*
+* A property with no `items` gets one, so the constraint is never dropped. A
+* tuple-form `items` (an array of schemas) constrains every position.
+*/
+function elementSchemas(prop) {
+	if (Array.isArray(prop["anyOf"])) {
+		const branches = prop["anyOf"].filter((b) => b !== null && typeof b === "object" && isArrayTyped(b));
+		if (branches.length > 0) return branches.flatMap((b) => elementSchemas(b));
+	}
+	if (!isArrayTyped(prop)) return [prop];
+	const items = prop["items"];
+	if (Array.isArray(items)) return items.filter((s) => s !== null && typeof s === "object");
+	if (items && typeof items === "object") return [items];
+	const created = {};
+	prop["items"] = created;
+	return [created];
+}
 /**
 * Widen a JSON Schema property to also accept `null`.
 *