@classytic/repo-core 0.27.1 → 0.29.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/index.d.mts

@@ -1,7 +1,7 @@
 import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
 import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
-import { RetryPolicy, throwIfAborted, withRetry } from "./resilience.mjs";
+import { RetryPolicy, isTransientError, throwIfAborted, withRetry } from "./resilience.mjs";
 import { ArchiveOptions, ArchivePort, ArchiveProgress, ArchiveResult, ArchiveSink, runChunkedArchive } from "./archive.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
@@ -12,4 +12,4 @@ import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs"
 import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepoOptions, ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { RetryingTransactionOptions, retryingTransaction } from "./retrying-transaction.mjs";
-export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/index.mjs

@@ -1,5 +1,5 @@
 import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
-import { throwIfAborted, withRetry } from "./resilience.mjs";
+import { isTransientError, throwIfAborted, withRetry } from "./resilience.mjs";
 import { runChunkedArchive } from "./archive.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
@@ -8,4 +8,4 @@ import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
 import { runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { retryingTransaction } from "./retrying-transaction.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };