@atscript/db-mongo 0.1.146 → 0.1.147

package/dist/mongo-accumulator-Y_xVYo3C.mjs

@@ -0,0 +1,534 @@
+import { DbError, andFilters, containsRelationFilter, isFieldRef, isResolvedRelationFilter, walkFilter } from "@atscript/db";
+import { BSONRegExp } from "mongodb";
+import { assertAggregateFn } from "@atscript/db/agg";
+//#region src/lib/lookup-join.ts
+/**
+* The correlation of a pipeline `$lookup`: `let` binds each outer field to a
+* variable (`<prefix>k<i>`), and the first sub-pipeline stages match the
+* inner field against it with SQL `=` semantics — a NULL or missing key on
+* either side never relates (aggregation `$eq(null, null)` is true, and a
+* missing `let` field would equal a missing inner field):
+*
+* 1. `$match: { $expr: { $eq: [inner, $$var] } }` (an `$and` of `$eq`s for a
+*    composite key) — kept bare so the lookup can use an index on the inner
+*    field(s); anything else inside that `$expr` turns every lookup into a
+*    collection scan;
+* 2. `$match: { <inner>: { $ne: null } }` per key part — the NULL guard, as a
+*    query-level stage. A NULL / missing outer key (`$ifNull` folds "missing"
+*    into `null`) only `$eq`s inner NULL / missing values, which this stage
+*    drops.
+*/
+function correlate(prefix, pairs) {
+	if (pairs.length === 0) throw new Error("A $lookup correlation needs at least one key pair");
+	const vars = {};
+	const eqs = [];
+	const guard = {};
+	for (const [i, pair] of pairs.entries()) {
+		const name = `${prefix}k${i}`;
+		vars[name] = { $ifNull: [`$${pair.outer}`, null] };
+		eqs.push({ $eq: [`$${pair.inner}`, `$$${name}`] });
+		guard[pair.inner] = { $ne: null };
+	}
+	return {
+		let: vars,
+		stages: [{ $match: { $expr: eqs.length === 1 ? eqs[0] : { $and: eqs } } }, { $match: guard }]
+	};
+}
+//#endregion
+//#region src/lib/mongo-view-expr.ts
+/**
+* `x IS NOT NULL` in SQL terms — true when `x` is neither null nor missing.
+* Aggregation order puts a missing value below null and every other value
+* above it, so one comparison covers both (`{ $ne: [x, null] }` alone would
+* be true for a MISSING field).
+* @since 0.1.136
+*/
+function notNullExpr(x) {
+	return { $gt: [x, null] };
+}
+/** `x IS NULL` in SQL terms — true when `x` is null or missing (see {@link notNullExpr}). @since 0.1.136 */
+function isNullExpr(x) {
+	return { $lte: [x, null] };
+}
+/**
+* `x`, with a missing value read as null — for a projected column (a missing
+* key would drop it from the row) and a `$group` key (missing and null would
+* form two groups). Only where a value may be missing: the wrapper hides the
+* path from `$match` / `$sort` pushdown.
+* @since 0.1.136
+*/
+function orNull(x) {
+	return { $ifNull: [x, null] };
+}
+/** A literal inside `$expr` — `$`-prefixed strings would otherwise read as field paths. */
+function literal(value) {
+	return typeof value === "string" && value.startsWith("$") ? { $literal: value } : value;
+}
+const COMPARISONS = {
+	$eq: "$eq",
+	$ne: "$ne",
+	$gt: "$gt",
+	$gte: "$gte",
+	$lt: "$lt",
+	$lte: "$lte"
+};
+/** `cond` AND-guarded so that every field operand is non-null (SQL: NULL operand → not true). */
+function guarded(operands, cond) {
+	return { $and: [...operands.map((o) => notNullExpr(o)), cond] };
+}
+/**
+* Field-to-field comparison `x <op> y` (`$eq` … `$lte`): both operands must
+* be non-null (SQL `NULL = NULL` is UNKNOWN) — view predicates and
+* `buildMongoFilter`'s field operands.
+* @since 0.1.137
+*/
+function fieldCompareExpr(op, x, y) {
+	return guarded([x, y], { [op]: [x, y] });
+}
+/**
+* Translates a view predicate (join condition, conditional-aggregate filter)
+* to an aggregation expression for `$match: { $expr }` / `$cond`, matching
+* SQL's three-valued logic wherever a NULL operand makes SQL's comparison
+* UNKNOWN (treated as false):
+*
+* - `<`, `<=`, `>`, `>=`, `!= <literal>`, field `=` field, field `!=` field
+*   and `not in` are guarded with "every field operand is not null";
+* - `= null` / `not exists` → null-or-missing; `!= null` / `exists` → neither;
+* - `= <literal>` and `in (…)` compare directly (a null operand never equals
+*   a non-null literal); an empty `not in` is true;
+* - `and` / `or` / `not` map directly — so `not (x > 1)` is TRUE for a null
+*   `x` here while SQL yields UNKNOWN (documented divergence);
+* - `matches` is rejected (`$regexMatch` needs MongoDB 4.2).
+* @since 0.1.136
+*/
+function queryNodeToExpr(node, pathOf) {
+	if ("$and" in node) return { $and: node.$and.map((n) => queryNodeToExpr(n, pathOf)) };
+	if ("$or" in node) return { $or: node.$or.map((n) => queryNodeToExpr(n, pathOf)) };
+	if ("$not" in node) return { $not: [queryNodeToExpr(node.$not, pathOf)] };
+	const comp = node;
+	const x = pathOf(comp.left);
+	switch (comp.op) {
+		case "$exists": return comp.right === false ? isNullExpr(x) : notNullExpr(x);
+		case "$in": return { $in: [x, (Array.isArray(comp.right) ? comp.right : [comp.right]).map((v) => literal(v))] };
+		case "$nin": {
+			const values = Array.isArray(comp.right) ? comp.right : [comp.right];
+			if (values.length === 0) return { $literal: true };
+			return guarded([x], { $not: [{ $in: [x, values.map((v) => literal(v))] }] });
+		}
+		case "$regex": throw new Error("matches is not supported in view predicates");
+		default:
+	}
+	const op = COMPARISONS[comp.op];
+	if (!op) throw new Error(`Operator "${comp.op}" is not supported in view predicates`);
+	if (isFieldRef(comp.right)) return fieldCompareExpr(op, x, pathOf(comp.right));
+	if (comp.right === null || comp.right === void 0) {
+		if (op === "$eq") return isNullExpr(x);
+		if (op === "$ne") return notNullExpr(x);
+		return { $literal: false };
+	}
+	const value = literal(comp.right);
+	if (op === "$eq") return { $eq: [x, value] };
+	return guarded([x], { [op]: [x, value] });
+}
+/**
+* A computed view column (`@db.compute`) as an aggregation expression:
+* `$add` / `$subtract` / `$multiply`; `/` → `$divide` guarded so a zero
+* divisor yields null (`$divide` by 0 is an error in MongoDB); unary minus →
+* `$multiply` by -1; `coalesce` → nested two-argument `$ifNull` (the
+* multi-argument form needs MongoDB 5.0). A null or missing operand yields
+* null, like SQL. Evaluated in double like the SQL adapters (MongoDB 4.0+):
+* literals render `{ $toDouble: n }` and `operand` — which renders a field
+* leaf (a view path) — must return a double too (`$toDouble` over a plain
+* column; a computed operand is one already). Without the casts int/long
+* arithmetic would stay exact past 2^53 where SQL rounds.
+* @since 0.1.147
+*/
+function exprToMongo(node, operand) {
+	if (typeof node === "number") return { $toDouble: node };
+	if ("field" in node) return operand(node.field);
+	const args = node.args.map((arg) => exprToMongo(arg, operand));
+	switch (node.op) {
+		case "+": return { $add: args };
+		case "-": return { $subtract: args };
+		case "*": return { $multiply: args };
+		case "/": return { $cond: [
+			{ $eq: [args[1], 0] },
+			null,
+			{ $divide: args }
+		] };
+		case "neg": return { $multiply: [-1, args[0]] };
+		default: return args.reduceRight((rest, arg) => ({ $ifNull: [arg, rest] }));
+	}
+}
+//#endregion
+//#region src/lib/mongo-filter.ts
+const EMPTY = {};
+function parseRegexString(value) {
+	if (value instanceof RegExp) return {
+		pattern: value.source,
+		flags: value.flags
+	};
+	const str = String(value);
+	const match = str.match(/^\/(.+)\/([gimsuy]*)$/);
+	if (match) return {
+		pattern: match[1],
+		flags: match[2]
+	};
+	return {
+		pattern: str,
+		flags: ""
+	};
+}
+/**
+* Earth radius in meters used by MongoDB's `$centerSphere` radians conversion
+* (Mongo documents dividing by 6378.1 km).
+*/
+const EARTH_RADIUS_M = 6378100;
+const mongoVisitor = {
+	comparison(field, op, value) {
+		if (op === "$eq") return { [field]: value };
+		if (op === "$exists") return value ? { [field]: { $ne: null } } : { [field]: null };
+		if (op === "$regex") {
+			const { pattern, flags } = parseRegexString(value);
+			return flags ? { [field]: {
+				$regex: pattern,
+				$options: flags
+			} } : { [field]: { $regex: pattern } };
+		}
+		if (op === "$geoWithin") {
+			const { center, radius } = value;
+			return { [field]: { $geoWithin: { $centerSphere: [center, radius / EARTH_RADIUS_M] } } };
+		}
+		return { [field]: { [op]: value } };
+	},
+	and(children) {
+		if (children.length === 0) return EMPTY;
+		if (children.length === 1) return children[0];
+		return { $and: children };
+	},
+	or(children) {
+		if (children.length === 0) return { _impossible: true };
+		if (children.length === 1) return children[0];
+		return { $or: children };
+	},
+	not(child) {
+		return { $nor: [child] };
+	},
+	relation(field, op) {
+		throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+			path: field,
+			message: `Relational predicate "${op}" on "${field}" reached a plain MongoDB filter — it needs an aggregation pipeline (buildMongoQuery)`
+		}]);
+	}
+};
+/** A `{ $field: path }` comparison operand (a field-to-field comparison). */
+function isFieldOperand(value) {
+	return value !== null && typeof value === "object" && typeof value.$field === "string";
+}
+/**
+* {@link mongoVisitor} plus field-to-field comparisons (`{ $field }` operands →
+* `$expr`), null-guarded like SQL ({@link fieldCompareExpr}).
+*/
+const fieldOperandVisitor = {
+	...mongoVisitor,
+	comparison(field, op, value) {
+		return isFieldOperand(value) ? { $expr: fieldCompareExpr(op, `$${field}`, `$${value.$field}`) } : mongoVisitor.comparison(field, op, value);
+	}
+};
+/**
+* Translates a generic {@link FilterExpr} into a MongoDB-compatible
+* {@link Filter} document.
+*
+* MongoDB's query language is nearly identical to the `FilterExpr` structure,
+* so this is largely a structural pass-through via the `walkFilter` visitor.
+* `fieldOperands` (view predicates only — `translateQueryTree` output) turns
+* `{ $field: path }` operands into field-to-field `$expr` comparisons; a
+* request filter never gets that reading.
+*
+* Predicate-free filters only: a relational predicate (`$some` / `$none`)
+* throws `REL_FILTER_NOT_SUPPORTED` — render those with
+* {@link buildMongoQuery} / {@link mongoFilterStages}.
+*/
+function buildMongoFilter(filter, { fieldOperands = false, collation } = {}) {
+	if (!filter || Object.keys(filter).length === 0) return EMPTY;
+	return walkFilter(filter, fieldOperands ? fieldOperandVisitor : collation ? collatedVisitor(collation) : mongoVisitor) ?? EMPTY;
+}
+/** Regex metacharacters (PCRE) escaped in an exact-match pattern. */
+const REGEX_SPECIAL = /[\\^$.|?*+()[\]{}]/g;
+/** A case-insensitive regex matching exactly `value` (`\z`: `$` would also match before a final newline). */
+function exactNocase(value) {
+	return new BSONRegExp(`^${value.replace(REGEX_SPECIAL, "\\$&").replaceAll("\0", "\\x00")}\\z`, "i");
+}
+/** Operators whose result never depends on a string collation. */
+const COLLATION_FREE_OPS = new Set([
+	"$regex",
+	"$exists",
+	"$geoWithin"
+]);
+const isStringOrHasString = (value) => typeof value === "string" || Array.isArray(value) && value.some((v) => typeof v === "string");
+/**
+* A comparison on a field with a non-binary collation, rendered without a
+* query-level collation (`undefined`: the value is not collation-sensitive —
+* render it as usual).
+*/
+function collatedComparison(field, op, value, collation) {
+	if (COLLATION_FREE_OPS.has(op) || !isStringOrHasString(value)) return;
+	if (collation === "nocase") {
+		if (op === "$eq") return { [field]: exactNocase(value) };
+		if (op === "$ne") return { [field]: { $not: exactNocase(value) } };
+		if ((op === "$in" || op === "$nin") && Array.isArray(value)) return { [field]: { [op]: value.map((v) => typeof v === "string" ? exactNocase(v) : v) } };
+	}
+	throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path: field,
+		message: `"${op}" on the ${collation} field "${field}" cannot be combined with relational predicates on MongoDB (a pipeline with $lookup stages cannot apply a per-field collation) — only $eq / $ne / $in / $nin / $regex / $exists on a 'nocase' field are supported there`
+	}]);
+}
+/** {@link mongoVisitor} with `collation`-aware comparisons ({@link collatedComparison}). */
+function collatedVisitor(collation) {
+	return {
+		...mongoVisitor,
+		comparison(field, op, value) {
+			const collate = collation(field);
+			return (collate && collate !== "binary" ? collatedComparison(field, op, value, collate) : void 0) ?? mongoVisitor.comparison(field, op, value);
+		}
+	};
+}
+/**
+* The per-field collation of a table, read from its (Mongo) adapter's
+* `fieldCollation` — what a relational-predicate pipeline renders `'nocase'`
+* fields with ({@link TMongoFilterOptions.collation}).
+*/
+function collationOfAdapter(adapter) {
+	const source = adapter;
+	return typeof source?.fieldCollation === "function" ? (field) => source.fieldCollation(field) : void 0;
+}
+/**
+* Prefix of the temporary fields predicate lookups write (`<prefix><n>`) —
+* long and specific so it cannot plausibly collide with a stored field; the
+* fields are dropped with `$unset` before any row leaves the pipeline.
+*
+* @since 0.1.147
+*/
+const REL_FILTER_TEMP_PREFIX = "__atscript_rf_";
+/** Splits a filter's top-level conjuncts (keys, `$and` members) by whether they hold a predicate. */
+function splitConjuncts(filter, pre, post) {
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and" && Array.isArray(value)) {
+			for (const child of value) splitConjuncts(child, pre, post);
+			continue;
+		}
+		const part = { [key]: value };
+		(containsRelationFilter(part) ? post : pre).push(part);
+	}
+}
+function isEmptyFilter(filter) {
+	return !filter || Object.keys(filter).length === 0;
+}
+function malformed(field, message) {
+	return new DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path: field,
+		message
+	}]);
+}
+/** A per-query renderer: one temp-field / variable counter shared by every nesting level. */
+function createPredicateRenderer() {
+	let seq = 0;
+	/** `collation`: the per-field collation of the table `filter` reads. */
+	const level = (filter, collation) => {
+		const preParts = [];
+		const postParts = [];
+		if (filter) splitConjuncts(filter, preParts, postParts);
+		const lookups = [];
+		const temp = [];
+		const visitor = {
+			...collation ? collatedVisitor(collation) : mongoVisitor,
+			relation(field, op, operand) {
+				if (!isResolvedRelationFilter(operand)) throw malformed(field, `Relational predicate "${op}" on "${field}" was not resolved by the table — query through the table API`);
+				const n = seq++;
+				const as = `${REL_FILTER_TEMP_PREFIX}${n}`;
+				lookups.push(lookupOf(operand, field, as, `rf${n}`));
+				temp.push(as);
+				return op === "$some" ? { [as]: { $ne: [] } } : { [as]: { $size: 0 } };
+			}
+		};
+		const pre = preParts.length > 0 ? buildMongoFilter(andFilters(...preParts), { collation }) : void 0;
+		const match = postParts.length > 0 ? walkFilter(andFilters(...postParts), visitor) ?? EMPTY : EMPTY;
+		return {
+			pre: isEmptyFilter(pre) ? void 0 : pre,
+			lookups,
+			match,
+			temp
+		};
+	};
+	/**
+	* Stages narrowing a lookup's documents to `filter` (nested predicates
+	* included), compared with the looked-up table's own collation. No
+	* `$unset`: the lookup projects `_id` only.
+	*/
+	const filterStages = (filter, adapter) => stagesOf(level(filter, collationOfAdapter(adapter)), false);
+	const lookupOf = (node, field, as, vars) => {
+		const exists = [{ $limit: 1 }, { $project: { _id: 1 } }];
+		if (node.kind === "via") return viaLookupOf(node, field, as, vars, exists);
+		if (node.pairs.length === 0) throw malformed(field, `Relational predicate on "${field}" has no join key pairs`);
+		const join = correlate(vars, node.pairs.map((p) => ({
+			outer: p.source,
+			inner: p.target
+		})));
+		return { $lookup: {
+			from: node.target.name,
+			let: join.let,
+			pipeline: [
+				...join.stages,
+				...filterStages(node.filter, node.target.adapter),
+				...exists
+			],
+			as
+		} };
+	};
+	const viaLookupOf = (node, field, as, vars, exists) => {
+		const junction = node.junction;
+		if (!junction || junction.toSource.length === 0 || junction.toTarget.length === 0) throw malformed(field, `Relational predicate on the via relation "${field}" has no junction correlation`);
+		const n = seq++;
+		const targetAs = `${REL_FILTER_TEMP_PREFIX}${n}`;
+		const toSource = correlate(vars, junction.toSource.map((p) => ({
+			outer: p.source,
+			inner: p.junction
+		})));
+		const toTarget = correlate(`rf${n}`, junction.toTarget.map((p) => ({
+			outer: p.junction,
+			inner: p.target
+		})));
+		return { $lookup: {
+			from: junction.name,
+			let: toSource.let,
+			pipeline: [
+				...toSource.stages,
+				...filterStages(junction.filter, junction.adapter),
+				{ $lookup: {
+					from: node.target.name,
+					let: toTarget.let,
+					pipeline: [
+						...toTarget.stages,
+						...filterStages(node.filter, node.target.adapter),
+						...exists
+					],
+					as: targetAs
+				} },
+				{ $match: { [targetAs]: { $ne: [] } } },
+				...exists
+			],
+			as
+		} };
+	};
+	return level;
+}
+/**
+* Renders a translated filter that may hold relational predicates
+* (`{ nav: { $some | $none: ResolvedRelationFilter } }`) for an aggregation
+* pipeline. Each predicate becomes a correlated `$lookup` into the related
+* collection (`let` = the source key fields; a bare `$expr` `$eq` per key
+* part — index-friendly — then a `{ <key>: { $ne: null } }` guard; the
+* inner filter — nested predicates as lookups inside it — then
+* `$limit: 1`); `via` looks up the junction, and inside it the target. The
+* predicate itself reads the lookup's temporary array field
+* ({@link REL_FILTER_TEMP_PREFIX}`<n>`). Top-level conjuncts without
+* predicates go to `pre` so the lookups run only for documents that survive
+* them.
+*
+* Run the pipeline WITHOUT an operation-wide `collation`: it would apply to
+* the join keys and the related tables' fields too. Each related table's
+* `'nocase'` fields are compared case-insensitively explicitly (see
+* {@link TMongoFilterOptions.collation}, which does the same for the source).
+*
+* A predicate-free filter yields `{ pre, lookups: [], match: {}, temp: [] }`.
+*
+* @since 0.1.147
+*/
+function buildMongoQuery(filter, options = {}) {
+	return createPredicateRenderer()(filter, options.collation);
+}
+/**
+* The pipeline stages that apply `filter`: `[{ $match }]` for a
+* predicate-free filter (exactly what the reads always emitted — `options`
+* is ignored then), else `$match(pre)` → predicate `$lookup`s → `$match` →
+* `$unset` of the temporary fields ({@link buildMongoQuery}).
+*
+* @since 0.1.147
+*/
+function mongoFilterStages(filter, options = {}) {
+	if (!containsRelationFilter(filter)) return [{ $match: buildMongoFilter(filter) }];
+	return planStages(buildMongoQuery(filter, options));
+}
+/**
+* The stages of a {@link TMongoFilterPlan}, in order: `$match(pre)`, the
+* lookups, `$match(match)`, `$unset` of the temporary fields.
+*
+* @since 0.1.147
+*/
+function planStages(plan) {
+	return stagesOf(plan, true);
+}
+function stagesOf(plan, unset) {
+	const stages = [];
+	if (plan.pre) stages.push({ $match: plan.pre });
+	stages.push(...plan.lookups);
+	if (!isEmptyFilter(plan.match)) stages.push({ $match: plan.match });
+	if (unset && plan.temp.length > 0) stages.push({ $unset: plan.temp });
+	return stages;
+}
+//#endregion
+//#region src/lib/mongo-accumulator.ts
+/**
+* The `$group` accumulator of one aggregate — shared by grouped queries
+* (`agg.ts`) and managed views (`mongo-view-pipeline.ts`), so both count and
+* sum alike.
+*
+* - `count(*)` → `{ $sum: 1 }`; `count(f)` counts values that are neither
+*   null nor missing (SQL `COUNT(f)`);
+* - `sum` / `avg` / `min` / `max` → `$sum` / `$avg` / `$min` / `$max` (all
+*   skip null / missing values);
+* - `countDistinct(f)` → `{ $addToSet: { $ifNull: [f, "$$REMOVE"] } }`, a
+*   SET of the non-null values (`$$REMOVE` adds nothing) the caller turns
+*   into its size with {@link distinctCountExpr}.
+*
+* `where` (a conditional aggregate's row predicate, an aggregation
+* expression) swaps the source for `{ $cond: [where, src, null] }` — the
+* rejected rows contribute a null, which every accumulator skips — and makes
+* the counts `{ $sum: { $cond: [where (and not null), 1, 0] } }`.
+*
+* @param fn - The aggregate function (re-asserted: `INVALID_QUERY` when unknown).
+* @param src - The source operand (`"$path"`), or `"*"` for `count(*)`.
+* @param where - Row predicate of a conditional aggregate.
+* @param path - Error path of the re-assertion.
+*/
+function buildAccumulator(fn, src, where, path) {
+	assertAggregateFn(fn, path);
+	if (fn === "count") {
+		if (src === "*") return { $sum: where ? { $cond: [
+			where,
+			1,
+			0
+		] } : 1 };
+		return { $sum: { $cond: [
+			where ? { $and: [where, notNullExpr(src)] } : notNullExpr(src),
+			1,
+			0
+		] } };
+	}
+	const value = where ? { $cond: [
+		where,
+		src,
+		null
+	] } : src;
+	return fn === "countDistinct" ? { $addToSet: { $ifNull: [value, "$$REMOVE"] } } : { [`$${fn}`]: value };
+}
+/**
+* The size of a `countDistinct` set (`"$alias"`) — the value the accumulator
+* stands for, projected right after `$group` so later stages (`$having`,
+* `$sort`) see a number.
+*/
+function distinctCountExpr(set) {
+	return { $size: set };
+}
+//#endregion
+export { buildMongoQuery as a, planStages as c, queryNodeToExpr as d, correlate as f, buildMongoFilter as i, exprToMongo as l, distinctCountExpr as n, collationOfAdapter as o, REL_FILTER_TEMP_PREFIX as r, mongoFilterStages as s, buildAccumulator as t, orNull as u };

package/dist/mongo-filter-CGd9ryOD.d.cts

@@ -0,0 +1,123 @@
+import { FilterExpr, TDbCollation } from "@atscript/db";
+import { Document, Filter } from "mongodb";
+
+//#region src/lib/mongo-filter.d.ts
+/**
+ * Translates a generic {@link FilterExpr} into a MongoDB-compatible
+ * {@link Filter} document.
+ *
+ * MongoDB's query language is nearly identical to the `FilterExpr` structure,
+ * so this is largely a structural pass-through via the `walkFilter` visitor.
+ * `fieldOperands` (view predicates only — `translateQueryTree` output) turns
+ * `{ $field: path }` operands into field-to-field `$expr` comparisons; a
+ * request filter never gets that reading.
+ *
+ * Predicate-free filters only: a relational predicate (`$some` / `$none`)
+ * throws `REL_FILTER_NOT_SUPPORTED` — render those with
+ * {@link buildMongoQuery} / {@link mongoFilterStages}.
+ */
+declare function buildMongoFilter(filter: FilterExpr, {
+  fieldOperands,
+  collation
+}?: {
+  fieldOperands?: boolean;
+  collation?: TMongoFieldCollation;
+}): Filter<any>;
+/**
+ * A table's per-field collation (`@db.column.collate`), keyed by PHYSICAL
+ * field path — `undefined` / `'binary'` compare byte-wise. See
+ * {@link TMongoFilterOptions.collation}.
+ *
+ * @since 0.1.147
+ */
+type TMongoFieldCollation = (field: string) => TDbCollation | undefined;
+/** Options of {@link buildMongoQuery} / {@link mongoFilterStages}. @since 0.1.147 */
+interface TMongoFilterOptions {
+  /**
+   * The source table's per-field collation. A pipeline with relational
+   * predicates runs WITHOUT an operation-wide `collation` (it would govern
+   * every `$lookup` too — join keys and the related table's fields), so a
+   * `'nocase'` field's comparisons are rendered explicitly instead: `$eq` /
+   * `$ne` / `$in` / `$nin` on string values become anchored, escaped
+   * case-insensitive regular expressions. Range operators on a string value
+   * and every string comparison on a `'unicode'` field cannot be rendered
+   * faithfully and throw `REL_FILTER_NOT_SUPPORTED`.
+   *
+   * Omitted: the source's own fields compare byte-wise. Predicate operands
+   * always use the RELATED table's collation (read from its adapter).
+   */
+  collation?: TMongoFieldCollation;
+}
+/**
+ * The per-field collation of a table, read from its (Mongo) adapter's
+ * `fieldCollation` — what a relational-predicate pipeline renders `'nocase'`
+ * fields with ({@link TMongoFilterOptions.collation}).
+ */
+declare function collationOfAdapter(adapter: unknown): TMongoFieldCollation | undefined;
+/**
+ * Prefix of the temporary fields predicate lookups write (`<prefix><n>`) —
+ * long and specific so it cannot plausibly collide with a stored field; the
+ * fields are dropped with `$unset` before any row leaves the pipeline.
+ *
+ * @since 0.1.147
+ */
+declare const REL_FILTER_TEMP_PREFIX = "__atscript_rf_";
+/**
+ * A filter rendered for an aggregation pipeline — what
+ * {@link buildMongoQuery} returns. Stage order: `$match: pre` (when set),
+ * the `lookups`, `$match: match` (when non-empty), `$unset: temp`
+ * ({@link mongoFilterStages} assembles them).
+ *
+ * @since 0.1.147
+ */
+interface TMongoFilterPlan {
+  /** The predicate-free top-level conjuncts — matched BEFORE the lookups, so they run only for surviving documents. */
+  pre?: Filter<any>;
+  /** One `$lookup` per relational predicate, each writing a temporary array field (at most one element). */
+  lookups: Document[];
+  /** The rest of the filter, predicates read as `{ <temp>: { $ne: [] } }` (`$some`) / `{ <temp>: { $size: 0 } }` (`$none`). */
+  match: Filter<any>;
+  /** The temporary fields the lookups add ({@link REL_FILTER_TEMP_PREFIX}`<n>`, dropped with `$unset`). */
+  temp: string[];
+}
+/**
+ * Renders a translated filter that may hold relational predicates
+ * (`{ nav: { $some | $none: ResolvedRelationFilter } }`) for an aggregation
+ * pipeline. Each predicate becomes a correlated `$lookup` into the related
+ * collection (`let` = the source key fields; a bare `$expr` `$eq` per key
+ * part — index-friendly — then a `{ <key>: { $ne: null } }` guard; the
+ * inner filter — nested predicates as lookups inside it — then
+ * `$limit: 1`); `via` looks up the junction, and inside it the target. The
+ * predicate itself reads the lookup's temporary array field
+ * ({@link REL_FILTER_TEMP_PREFIX}`<n>`). Top-level conjuncts without
+ * predicates go to `pre` so the lookups run only for documents that survive
+ * them.
+ *
+ * Run the pipeline WITHOUT an operation-wide `collation`: it would apply to
+ * the join keys and the related tables' fields too. Each related table's
+ * `'nocase'` fields are compared case-insensitively explicitly (see
+ * {@link TMongoFilterOptions.collation}, which does the same for the source).
+ *
+ * A predicate-free filter yields `{ pre, lookups: [], match: {}, temp: [] }`.
+ *
+ * @since 0.1.147
+ */
+declare function buildMongoQuery(filter: FilterExpr | undefined, options?: TMongoFilterOptions): TMongoFilterPlan;
+/**
+ * The pipeline stages that apply `filter`: `[{ $match }]` for a
+ * predicate-free filter (exactly what the reads always emitted — `options`
+ * is ignored then), else `$match(pre)` → predicate `$lookup`s → `$match` →
+ * `$unset` of the temporary fields ({@link buildMongoQuery}).
+ *
+ * @since 0.1.147
+ */
+declare function mongoFilterStages(filter: FilterExpr | undefined, options?: TMongoFilterOptions): Document[];
+/**
+ * The stages of a {@link TMongoFilterPlan}, in order: `$match(pre)`, the
+ * lookups, `$match(match)`, `$unset` of the temporary fields.
+ *
+ * @since 0.1.147
+ */
+declare function planStages(plan: TMongoFilterPlan): Document[];
+//#endregion
+export { buildMongoFilter as a, mongoFilterStages as c, TMongoFilterPlan as i, planStages as l, TMongoFieldCollation as n, buildMongoQuery as o, TMongoFilterOptions as r, collationOfAdapter as s, REL_FILTER_TEMP_PREFIX as t };