@atscript/db 0.1.146 → 0.1.148

package/dist/{nested-writer-xfQwxplL.cjs → nested-writer-BUQvk6QT.cjs}

@@ -1,6 +1,134 @@
-const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_db_error = require("./db-error-DRQH4sLY.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
+let _uniqu_core = require("@uniqu/core");
+//#region src/query/query-tree.ts
+/**
+* `true` when a query-tree operand is a field reference (`{ field, type? }`)
+* rather than a literal — e.g. the right side of a field-to-field comparison.
+* @since 0.1.136
+*/
+function isFieldRef(value) {
+	return value !== null && typeof value === "object" && "field" in value;
+}
+/**
+* Translates a JS-emitted query tree into a FilterExpr.
+* Resolves field references (type + field path) to physical column names
+* via the provided resolver function.
+*/
+function translateQueryTree(node, resolveField) {
+	if ("$and" in node) return { $and: node.$and.map((n) => translateQueryTree(n, resolveField)) };
+	if ("$or" in node) return { $or: node.$or.map((n) => translateQueryTree(n, resolveField)) };
+	if ("$not" in node) return { $not: translateQueryTree(node.$not, resolveField) };
+	const comp = node;
+	const leftField = resolveField(comp.left);
+	if (isFieldRef(comp.right)) {
+		const rightField = resolveField(comp.right);
+		return { [leftField]: { [comp.op]: { $field: rightField } } };
+	}
+	if (comp.op === "$exists") return { [leftField]: { $exists: comp.right !== false } };
+	return { [leftField]: { [comp.op]: comp.right } };
+}
+/**
+* Calls `leaf` with the field path of every field-reference leaf of a
+* computed-column expression (`@db.compute`), in source order — leaves name
+* the view's own fields.
+* @since 0.1.147
+*/
+function walkViewExpr(expr, leaf) {
+	if (typeof expr === "number") return;
+	if ("field" in expr) {
+		leaf(expr.field);
+		return;
+	}
+	for (const arg of expr.args) walkViewExpr(arg, leaf);
+}
+/**
+* Evaluates a computed expression in process (the memory adapter, a test, a
+* third-party adapter) with the semantics every adapter shares: IEEE double,
+* a leaf is `Number()`-ed, NULL / undefined propagates as `null`, `/` by zero
+* is `null`, `coalesce` returns its first non-null value.
+* @since 0.1.148
+*/
+function evaluateExpr(expr, leaf) {
+	if (typeof expr === "number") return expr;
+	if ("field" in expr) {
+		const v = leaf(expr.field);
+		if (v === null || v === void 0) return null;
+		const n = Number(v);
+		return Number.isNaN(n) ? null : n;
+	}
+	if (expr.op === "coalesce") {
+		for (const arg of expr.args) {
+			const v = evaluateExpr(arg, leaf);
+			if (v !== null) return v;
+		}
+		return null;
+	}
+	const a = evaluateExpr(expr.args[0], leaf);
+	if (a === null) return null;
+	if (expr.op === "neg") return -a;
+	const b = evaluateExpr(expr.args[1], leaf);
+	if (b === null) return null;
+	switch (expr.op) {
+		case "+": return a + b;
+		case "-": return a - b;
+		case "*": return a * b;
+		default: return b === 0 ? null : a / b;
+	}
+}
+/**
+* Whether a computed-column expression may yield NULL: a `/` (division by
+* zero is NULL), a leaf for which `nullableLeaf` holds, or an operation over
+* a nullable operand — `coalesce` only when every argument is nullable.
+* @since 0.1.147
+*/
+function viewExprNullable(expr, nullableLeaf) {
+	if (typeof expr === "number") return false;
+	if ("field" in expr) return nullableLeaf(expr.field);
+	if (expr.op === "/") return true;
+	if (expr.op === "coalesce") return expr.args.every((a) => viewExprNullable(a, nullableLeaf));
+	return expr.args.some((a) => viewExprNullable(a, nullableLeaf));
+}
+/**
+* The `@db.compute` expression of a view field, if any.
+* @since 0.1.147
+*/
+function computeOf(fieldType) {
+	return fieldType?.metadata.get("db.compute");
+}
+/**
+* The transitive non-computed operands of the `@db.compute` field `field` of
+* `viewType`: its leaves, a computed leaf replaced by its own operands, and
+* (`via`) the computed fields passed through. `undefined` when `field` is not
+* computed. Cycles are not followed (they are rejected where the view's
+* columns are built).
+* @since 0.1.147
+*/
+function computedOperands(viewType, field) {
+	const props = viewType.type.kind === "object" ? viewType.type.props : void 0;
+	const exprOf = (name) => computeOf(props?.get(name));
+	const root = exprOf(field);
+	if (root === void 0) return void 0;
+	const out = /* @__PURE__ */ new Set();
+	const via = [];
+	const seen = new Set([field]);
+	const visit = (expr) => walkViewExpr(expr, (path) => {
+		const nested = exprOf(path);
+		if (nested === void 0) out.add(path);
+		else if (!seen.has(path)) {
+			seen.add(path);
+			via.push(path);
+			visit(nested);
+		}
+	});
+	visit(root);
+	return {
+		operands: [...out],
+		via
+	};
+}
+//#endregion
 //#region src/rel/relation-helpers.ts
 /**
 * Finds the FK entry that connects a `@db.rel.to` relation to its target.
@@ -52,10 +180,462 @@ function tableNameOf(type) {
 function resolveRelationTargetTable(relation) {
 	return tableNameOf(relation.targetType());
 }
+/**
+* A string key of `fields`' values on `obj` — equal for rows that agree on
+* every field (`null` / `undefined` key distinctly from any string). `read`
+* reads one field (default: a top-level property).
+*/
+function compositeKey(fields, obj, read = (o, f) => o[f]) {
+	let key = "";
+	for (let i = 0; i < fields.length; i++) {
+		if (i > 0) key += "\0\0";
+		const v = read(obj, fields[i]);
+		key += v === null || v === void 0 ? "\0" : String(v);
+	}
+	return key;
+}
+/**
+* Keeps, of each group of `rows` sharing `keyOf(row)`, the rows `page`
+* selects — `$skip` / `$limit` applied per group, in the order of `rows`.
+* The order of the kept rows is preserved.
+*/
+function slicePerGroup(rows, keyOf, page) {
+	const skip = page.skip ?? 0;
+	const end = page.limit === void 0 ? Infinity : skip + page.limit;
+	const seen = /* @__PURE__ */ new Map();
+	const kept = [];
+	for (const row of rows) {
+		const key = keyOf(row);
+		const index = seen.get(key) ?? 0;
+		seen.set(key, index + 1);
+		if (index >= skip && index < end) kept.push(row);
+	}
+	return kept;
+}
+//#endregion
+//#region src/query/relation-filter.ts
+/**
+* Relational filter predicates (`{ nav: { $some | $none: <filter on the
+* related table> } }`) — resolution against the related tables.
+*
+* Semantics: `rel(r, nav)` is exactly the set of related rows `$with=nav`
+* loads for row `r` (same foreign-key pairing, the relation's
+* `@db.rel.filter` included). `$some: F` holds when one of them matches `F`,
+* `$none: F` when none does; a NULL foreign-key component means "no related
+* row". The core resolves each predicate into a {@link ResolvedRelationFilter}
+* (physical names on every side, the inner filter translated by the related
+* table's own field mapper) before the adapter sees the filter — adapters
+* only render it.
+*
+* @since 0.1.147
+*/
+/**
+* Maximum nesting of relational predicates in one filter, server-added ones
+* included (a predicate inside a predicate's operand counts one level). The
+* core backstop for every caller; higher than moost-db's per-client limit
+* (`REL_FILTER_CLIENT_MAX_DEPTH`) so server overlays (row scopes,
+* `transformRelationFilter`) have headroom above what a client may send.
+*/
+const REL_FILTER_MAX_DEPTH = 4;
+/** Maximum number of relational predicates in one filter (nested and server-added ones included). See {@link REL_FILTER_MAX_DEPTH}. */
+const REL_FILTER_MAX_NODES = 16;
+/**
+* Cross-realm brand of {@link ResolvedRelationFilter}: `instanceof` fails when
+* two copies of `@atscript/db` are loaded (ESM + CJS, or nested installs) and
+* an adapter from one sees nodes built by the other.
+*/
+const RESOLVED_BRAND = Symbol.for("@atscript/db:ResolvedRelationFilter");
+/**
+* A relational predicate as adapters receive it — the operand of
+* `FilterVisitor.relation(field, op, operand)` once the core translated the
+* filter. Every name is physical:
+*
+* - `to` / `from`: `pairs` correlate a SOURCE column with a TARGET column
+*   (`target.<pair.target> = source.<pair.source>`, one pair per composite
+*   key part);
+* - `via`: `pairs` is empty — `junction.toSource` correlates the junction
+*   with the source row, `junction.toTarget` with the target row.
+*
+* `filter` is the inner filter on the TARGET (already translated by the
+* target's field mapper: renames, flattening, value formatters; nested
+* predicates resolved the same way), conjoined with the target part of the
+* relation's `@db.rel.filter`. `{}` matches every related row.
+*
+* @since 0.1.147
+*/
+var ResolvedRelationFilter = class {
+	/** @internal cross-realm brand (see {@link isResolvedRelationFilter}). */
+	[RESOLVED_BRAND] = true;
+	kind;
+	/** Logical navigation field name on the source table. */
+	nav;
+	source;
+	target;
+	pairs;
+	junction;
+	filter;
+	constructor(init) {
+		this.kind = init.kind;
+		this.nav = init.nav;
+		this.source = init.source;
+		this.target = init.target;
+		this.pairs = init.pairs;
+		this.junction = init.junction;
+		this.filter = init.filter;
+	}
+};
+/** `true` for a {@link ResolvedRelationFilter} (the resolved operand of a predicate). */
+function isResolvedRelationFilter(value) {
+	return typeof value === "object" && value !== null && value[RESOLVED_BRAND] === true;
+}
+/** `true` when `value` (a filter entry's value) is an operator map with a `$some` / `$none` key. */
+function hasRelationOp(value) {
+	if (!require_object.isPlainObject(value)) return false;
+	for (const key in value) if ((0, _uniqu_core.isRelationOp)(key)) return true;
+	return false;
+}
+/**
+* Pre-scan results of filters the core BUILT (translated / resolved
+* filters, never mutated after) — adapters scan the same translated filter
+* several times per operation. Caller-owned filters are never cached: they
+* may be mutated between two queries.
+*/
+const relationFilterCache = /* @__PURE__ */ new WeakMap();
+/** @internal Records the pre-scan result of a filter the core built. */
+function noteRelationFilter(filter, has) {
+	if (filter && typeof filter === "object") relationFilterCache.set(filter, has);
+}
+/**
+* `true` when `filter` holds a relational predicate anywhere outside
+* predicate operands (through `$and` / `$or` / `$not`) — the cheap pre-scan
+* the field mappers and renderers use to keep predicate-free filters on
+* their fast paths. Results for filters the core translated are cached.
+*/
+function containsRelationFilter(filter) {
+	if (!filter || typeof filter !== "object") return false;
+	const cached = relationFilterCache.get(filter);
+	if (cached !== void 0) return cached;
+	for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") {
+		if (Array.isArray(value) && value.some((child) => containsRelationFilter(child))) return true;
+	} else if (key === "$not") {
+		if (containsRelationFilter(value)) return true;
+	} else if (!key.startsWith("$") && hasRelationOp(value)) return true;
+	return false;
+}
+/**
+* Calls `visit` for every resolved predicate of a TRANSLATED filter,
+* depth-first: the top-level ones, then (with `nested`) those inside each
+* operand — target filters and junction filters alike. Adapters use it to
+* prepare per-predicate data (memory snapshots, self-referencing checks).
+*/
+function forEachResolvedRelation(filter, visit, nested = true) {
+	if (!filter || typeof filter !== "object") return;
+	for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") {
+		if (Array.isArray(value)) for (const child of value) forEachResolvedRelation(child, visit, nested);
+	} else if (key === "$not") forEachResolvedRelation(value, visit, nested);
+	else if (!key.startsWith("$") && require_object.isPlainObject(value)) for (const [op, operand] of Object.entries(value)) {
+		if (!(0, _uniqu_core.isRelationOp)(op) || !isResolvedRelationFilter(operand)) continue;
+		visit(operand, op);
+		if (nested) {
+			forEachResolvedRelation(operand.filter, visit, nested);
+			forEachResolvedRelation(operand.junction?.filter, visit, nested);
+		}
+	}
+}
+/** A fresh {@link TRelGuardState} for one query. */
+function relGuardState(write = false) {
+	return {
+		depth: 0,
+		counter: { nodes: 0 },
+		write,
+		path: ""
+	};
+}
+function invalid(path, message) {
+	return new require_db_error.DbError("INVALID_QUERY", [{
+		path,
+		message
+	}]);
+}
+function notSupported(path, message) {
+	return new require_db_error.DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path,
+		message
+	}]);
+}
+/** The present, non-empty `parts` ANDed (`{}` when none, a single one as is). */
+function andFilters(...parts) {
+	const present = parts.filter((p) => p != null && Object.keys(p).length > 0);
+	if (present.length === 0) return {};
+	if (present.length === 1) return present[0];
+	return { $and: present };
+}
+const NO_STATIC_FILTER = {};
+const staticFilterCache = /* @__PURE__ */ new WeakMap();
+/**
+* A relation's `@db.rel.filter` as logical filters per side — what `$with`
+* loading and relational predicates both AND into the related rows (the
+* filter is part of the relation's meaning). Top-level `and` conditions are
+* split by side: an unqualified field and the related type's fields go to
+* `target`, the `@db.rel.via` junction's to `junction`. A single condition
+* that reads both sides (e.g. an `or` across them) or compares two fields is
+* rejected with `INVALID_QUERY` — `name` is the navigation field (error path).
+*
+* @since 0.1.147
+*/
+function relationStaticFilter(relation, name = "") {
+	if (!relation.filter) return NO_STATIC_FILTER;
+	const cached = staticFilterCache.get(relation);
+	if (cached) return cached;
+	const targetType = relation.targetType();
+	const junctionType = relation.viaType?.();
+	const targetName = tableNameOf(targetType);
+	const junctionName = junctionType ? tableNameOf(junctionType) : void 0;
+	const sideOf = (ref) => {
+		const type = ref.type?.();
+		if (!type || type === targetType || tableNameOf(type) === targetName) return "target";
+		if (junctionType && (type === junctionType || tableNameOf(type) === junctionName)) return "junction";
+		throw invalid(name, `@db.rel.filter on "${name}" references a type other than the related type` + (junctionType ? " and the junction" : "") + " — only those can be referenced");
+	};
+	const target = [];
+	const junction = [];
+	const conjuncts = "$and" in relation.filter ? relation.filter.$and : [relation.filter];
+	for (const conjunct of conjuncts) {
+		const sides = /* @__PURE__ */ new Set();
+		collectSides(conjunct, (ref) => sides.add(sideOf(ref)), name);
+		if (sides.size > 1) throw invalid(name, `@db.rel.filter on "${name}" has a condition reading both the junction and the related type — split it into separate "and" conditions`);
+		const filter = translateQueryTree(conjunct, (ref) => ref.field);
+		(sides.has("junction") ? junction : target).push(filter);
+	}
+	const result = {
+		target: target.length > 0 ? andFilters(...target) : void 0,
+		junction: junction.length > 0 ? andFilters(...junction) : void 0
+	};
+	staticFilterCache.set(relation, result);
+	return result;
+}
+function collectSides(node, visit, name) {
+	if ("$and" in node) {
+		for (const child of node.$and) collectSides(child, visit, name);
+		return;
+	}
+	if ("$or" in node) {
+		for (const child of node.$or) collectSides(child, visit, name);
+		return;
+	}
+	if ("$not" in node) {
+		collectSides(node.$not, visit, name);
+		return;
+	}
+	visit(node.left);
+	if (isFieldRef(node.right)) throw invalid(name, `@db.rel.filter on "${name}" compares two fields — only field-to-value conditions are supported`);
+}
+function zip(left, right, a, b) {
+	return left.map((value, i) => ({
+		[a]: value,
+		[b]: right[i]
+	}));
+}
+/**
+* The {@link TRelationFilterHost} of a readable: resolves a navigation
+* field's related table (and junction) through `resolve` (the readable's
+* table resolver), pairing foreign keys exactly like `$with` loading does
+* (`findFKEntryForRelation` / `findRemoteFK`).
+*/
+function createRelationFilterHost(owner, resolve) {
+	const plans = /* @__PURE__ */ new Map();
+	const sameAdapter = (other, path, what) => {
+		if (!owner.getAdapter().sharesStoreWith(other.getAdapter())) throw notSupported(path, `Relational predicate on "${path}": the ${what} table lives in a different database or adapter`);
+	};
+	const planOf = (nav, path) => {
+		const cached = plans.get(nav);
+		if (cached) return cached;
+		const meta = owner.getMetadata();
+		const relation = meta.relations.get(nav);
+		if (!relation) throw invalid(path, `"$some" / "$none" are only valid on a navigation relation — "${nav}" is not one`);
+		const target = resolve(relation.targetType());
+		if (!target) throw notSupported(path, `Relational predicate on "${path}": the related table is not available`);
+		sameAdapter(target, path, "related");
+		let plan;
+		if (relation.direction === "to") {
+			const fk = findFKEntryForRelation(relation, meta.foreignKeys);
+			if (!fk) throw invalid(path, `Relation "${nav}" has no foreign key to filter by`);
+			plan = {
+				kind: "to",
+				relation,
+				target,
+				pairs: zip(fk.fields, fk.targetFields, "source", "target")
+			};
+		} else if (relation.direction === "from") {
+			const fk = findRemoteFK(target.getMetadata(), owner.tableName, relation.alias);
+			if (!fk) throw invalid(path, `Relation "${nav}" has no foreign key to filter by`);
+			plan = {
+				kind: "from",
+				relation,
+				target,
+				pairs: zip(fk.targetFields, fk.fields, "source", "target")
+			};
+		} else {
+			const junctionType = relation.viaType?.();
+			const junction = junctionType ? resolve(junctionType) : void 0;
+			if (!junction) throw notSupported(path, `Relational predicate on "${path}": the junction table is not available`);
+			sameAdapter(junction, path, "junction");
+			const junctionMeta = junction.getMetadata();
+			const fkToThis = findRemoteFK(junctionMeta, owner.tableName);
+			const fkToTarget = findRemoteFK(junctionMeta, tableNameOf(relation.targetType()));
+			if (!fkToThis || !fkToTarget) throw invalid(path, `Relation "${nav}" has no junction foreign keys to filter by`);
+			if (fkToThis === fkToTarget) throw invalid(path, `Relation "${nav}" is a self-referencing many-to-many — relational predicates cannot tell its two junction keys apart`);
+			plan = {
+				kind: "via",
+				relation,
+				target,
+				pairs: [],
+				junction: {
+					owner: junction,
+					toSource: zip(fkToThis.fields, fkToThis.targetFields, "junction", "source"),
+					toTarget: zip(fkToTarget.fields, fkToTarget.targetFields, "junction", "target")
+				}
+			};
+		}
+		plans.set(nav, plan);
+		return plan;
+	};
+	const tableOf = (o) => {
+		const adapter = o.getAdapter();
+		return {
+			table: adapter.resolveTableName(),
+			name: adapter.resolveTableName(false),
+			adapter
+		};
+	};
+	return {
+		guard(nav, op, inner, state) {
+			const path = state.path ? `${state.path}.${nav}` : nav;
+			const depth = state.depth + 1;
+			if (depth > 4) throw invalid("", `Relational predicates nest at most 4 levels deep`);
+			if (++state.counter.nodes > 16) throw invalid("", `At most 16 relational predicates per query`);
+			if (!require_object.isPlainObject(inner)) throw invalid(path, `"${op}" on "${path}" expects a filter object`);
+			const plan = planOf(nav, path);
+			relationStaticFilter(plan.relation, path);
+			try {
+				plan.target._guardRelationOperand(inner, {
+					...state,
+					depth,
+					path
+				});
+			} catch (error) {
+				throw prefixError(error, path);
+			}
+		},
+		resolve(nav, _op, inner, depth) {
+			if (depth > 4) throw invalid("", `Relational predicates nest at most 4 levels deep`);
+			const plan = planOf(nav, nav);
+			const ownerMeta = owner.getMetadata();
+			const targetMeta = plan.target.getMetadata();
+			const statics = relationStaticFilter(plan.relation, nav);
+			const filter = plan.target._resolveRelationOperand(andFilters(statics.target, inner), depth);
+			let junction;
+			if (plan.junction) {
+				const junctionMeta = plan.junction.owner.getMetadata();
+				junction = {
+					...tableOf(plan.junction.owner),
+					toSource: plan.junction.toSource.map((p) => ({
+						junction: junctionMeta.physicalPath(p.junction),
+						source: ownerMeta.physicalPath(p.source)
+					})),
+					toTarget: plan.junction.toTarget.map((p) => ({
+						junction: junctionMeta.physicalPath(p.junction),
+						target: targetMeta.physicalPath(p.target)
+					})),
+					...statics.junction ? { filter: plan.junction.owner._resolveRelationOperand(statics.junction, depth) } : {}
+				};
+			}
+			return new ResolvedRelationFilter({
+				kind: plan.kind,
+				nav,
+				source: tableOf(owner),
+				target: tableOf(plan.target),
+				pairs: plan.pairs.map((p) => ({
+					source: ownerMeta.physicalPath(p.source),
+					target: targetMeta.physicalPath(p.target)
+				})),
+				junction,
+				filter
+			});
+		}
+	};
+}
+/** Re-throws a related table's guard error with its paths under the navigation chain. */
+function prefixError(error, path) {
+	if (!(error instanceof require_db_error.DbError)) return error;
+	if (error.errors.every((e) => !e.path)) return error;
+	if (error.errors.every((e) => e.path === path || e.path.startsWith(`${path}.`))) return error;
+	const errors = error.errors.map((e) => ({
+		path: e.path ? `${path}.${e.path}` : path,
+		message: e.message
+	}));
+	return new require_db_error.DbError(error.code, errors, `${errors[0]?.message ?? error.message} (in "${path}")`);
+}
+/**
+* Resolves every relational predicate of a (logical) filter through
+* `meta.relationFilters` — the step every field-mapper entry point runs
+* first. Predicates at the top of `filter` are at level `depth + 1`.
+* Already-resolved operands pass through, so translating twice is safe.
+* One pass: unchanged subtrees (and `filter` itself, when nothing needed
+* resolving) are returned as they are.
+*/
+function resolveRelationFilterTree(filter, meta, depth) {
+	let out;
+	for (const [key, value] of Object.entries(filter)) {
+		let next = value;
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) {
+				let children;
+				for (let i = 0; i < value.length; i++) {
+					const child = value[i];
+					if (!child || typeof child !== "object") continue;
+					const resolved = resolveRelationFilterTree(child, meta, depth);
+					if (resolved === child) continue;
+					children ??= [...value];
+					children[i] = resolved;
+				}
+				if (children) next = children;
+			}
+		} else if (key === "$not") {
+			if (value && typeof value === "object") next = resolveRelationFilterTree(value, meta, depth);
+		} else if (!key.startsWith("$") && hasRelationOp(value)) next = resolvePredicateMap(key, value, meta, depth);
+		if (next === value) continue;
+		out ??= { ...filter };
+		out[key] = next;
+	}
+	if (!out) return filter;
+	noteRelationFilter(out, true);
+	return out;
+}
+/** One `{ $some | $none: … }` map of `key` resolved (operands already resolved pass through). */
+function resolvePredicateMap(key, value, meta, depth) {
+	const host = meta.relationFilters;
+	if (!host) {
+		if (!meta.navFields.has(key)) throw invalid(key, `"$some" / "$none" are only valid on a navigation relation — "${key}" is not one`);
+		throw notSupported(key, `Relational predicate on "${key}" needs the table to come from a DbSpace (no table resolver)`);
+	}
+	const ops = {};
+	for (const [op, operand] of Object.entries(value)) {
+		if (!(0, _uniqu_core.isRelationOp)(op)) throw invalid(key, `Cannot mix "$some" / "$none" with "${op}" on "${key}"`);
+		ops[op] = isResolvedRelationFilter(operand) ? operand : host.resolve(key, op, operand, depth + 1);
+	}
+	return ops;
+}
 //#endregion
 //#region src/shared/keys.ts
-/** String form of a key value (an ObjectId stringifies to its hex, a bigint to its digits). */
+/**
+* String form of a key value, equal across driver representations: an
+* ObjectId stringifies to its hex, a bigint to its digits, a Date to its ISO
+* instant, a Buffer / Uint8Array to hex.
+*/
 function keyString(value) {
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+	if (value instanceof Uint8Array) return Array.from(value, (b) => b.toString(16).padStart(2, "0")).join("");
 	return String(value);
 }
 /** Key equality across driver representations (number vs numeric string, ObjectId vs hex). */
@@ -82,6 +662,20 @@ function rowMatchesKey(row, key) {
 	for (const field in key) if (!sameKey(require_object.getPath(row, field), key[field])) return false;
 	return true;
 }
+/**
+* Identity of the key tuple `fields` of `row` for uniqueness checks, or
+* `undefined` when any component is null / missing (a NULL never collides).
+* Equal across driver representations (see {@link keyString}).
+*/
+function uniqueKeyTuple(row, fields) {
+	const parts = [];
+	for (const field of fields) {
+		const value = require_object.getPath(row, field);
+		if (value === void 0 || value === null) return void 0;
+		parts.push(keyString(value));
+	}
+	return JSON.stringify(parts);
+}
 //#endregion
 //#region src/table/error-utils.ts
 /**
@@ -877,6 +1471,30 @@ async function viaReplace(via, targets, parentPK, maxDepth, depth) {
 	await viaLinkTargets(via, targets, parentPK, maxDepth, depth);
 }
 //#endregion
+Object.defineProperty(exports, "REL_FILTER_MAX_DEPTH", {
+	enumerable: true,
+	get: function() {
+		return REL_FILTER_MAX_DEPTH;
+	}
+});
+Object.defineProperty(exports, "REL_FILTER_MAX_NODES", {
+	enumerable: true,
+	get: function() {
+		return REL_FILTER_MAX_NODES;
+	}
+});
+Object.defineProperty(exports, "ResolvedRelationFilter", {
+	enumerable: true,
+	get: function() {
+		return ResolvedRelationFilter;
+	}
+});
+Object.defineProperty(exports, "andFilters", {
+	enumerable: true,
+	get: function() {
+		return andFilters;
+	}
+});
 Object.defineProperty(exports, "applyPatchNestedTo", {
 	enumerable: true,
 	get: function() {
@@ -943,12 +1561,48 @@ Object.defineProperty(exports, "checkDepthOverflow", {
 		return checkDepthOverflow;
 	}
 });
+Object.defineProperty(exports, "compositeKey", {
+	enumerable: true,
+	get: function() {
+		return compositeKey;
+	}
+});
+Object.defineProperty(exports, "computeOf", {
+	enumerable: true,
+	get: function() {
+		return computeOf;
+	}
+});
+Object.defineProperty(exports, "computedOperands", {
+	enumerable: true,
+	get: function() {
+		return computedOperands;
+	}
+});
+Object.defineProperty(exports, "containsRelationFilter", {
+	enumerable: true,
+	get: function() {
+		return containsRelationFilter;
+	}
+});
+Object.defineProperty(exports, "createRelationFilterHost", {
+	enumerable: true,
+	get: function() {
+		return createRelationFilterHost;
+	}
+});
 Object.defineProperty(exports, "enrichFkViolation", {
 	enumerable: true,
 	get: function() {
 		return enrichFkViolation;
 	}
 });
+Object.defineProperty(exports, "evaluateExpr", {
+	enumerable: true,
+	get: function() {
+		return evaluateExpr;
+	}
+});
 Object.defineProperty(exports, "findFKEntryForRelation", {
 	enumerable: true,
 	get: function() {
@@ -967,6 +1621,36 @@ Object.defineProperty(exports, "findRemoteFK", {
 		return findRemoteFK;
 	}
 });
+Object.defineProperty(exports, "forEachResolvedRelation", {
+	enumerable: true,
+	get: function() {
+		return forEachResolvedRelation;
+	}
+});
+Object.defineProperty(exports, "hasRelationOp", {
+	enumerable: true,
+	get: function() {
+		return hasRelationOp;
+	}
+});
+Object.defineProperty(exports, "isFieldRef", {
+	enumerable: true,
+	get: function() {
+		return isFieldRef;
+	}
+});
+Object.defineProperty(exports, "isResolvedRelationFilter", {
+	enumerable: true,
+	get: function() {
+		return isResolvedRelationFilter;
+	}
+});
+Object.defineProperty(exports, "noteRelationFilter", {
+	enumerable: true,
+	get: function() {
+		return noteRelationFilter;
+	}
+});
 Object.defineProperty(exports, "pkTupleKey", {
 	enumerable: true,
 	get: function() {
@@ -991,12 +1675,30 @@ Object.defineProperty(exports, "preValidateNestedFrom", {
 		return preValidateNestedFrom;
 	}
 });
+Object.defineProperty(exports, "relGuardState", {
+	enumerable: true,
+	get: function() {
+		return relGuardState;
+	}
+});
+Object.defineProperty(exports, "relationStaticFilter", {
+	enumerable: true,
+	get: function() {
+		return relationStaticFilter;
+	}
+});
 Object.defineProperty(exports, "remapDeleteFkViolation", {
 	enumerable: true,
 	get: function() {
 		return remapDeleteFkViolation;
 	}
 });
+Object.defineProperty(exports, "resolveRelationFilterTree", {
+	enumerable: true,
+	get: function() {
+		return resolveRelationFilterTree;
+	}
+});
 Object.defineProperty(exports, "resolveRelationTargetTable", {
 	enumerable: true,
 	get: function() {
@@ -1015,15 +1717,45 @@ Object.defineProperty(exports, "sameKey", {
 		return sameKey;
 	}
 });
+Object.defineProperty(exports, "slicePerGroup", {
+	enumerable: true,
+	get: function() {
+		return slicePerGroup;
+	}
+});
 Object.defineProperty(exports, "tableNameOf", {
 	enumerable: true,
 	get: function() {
 		return tableNameOf;
 	}
 });
+Object.defineProperty(exports, "translateQueryTree", {
+	enumerable: true,
+	get: function() {
+		return translateQueryTree;
+	}
+});
+Object.defineProperty(exports, "uniqueKeyTuple", {
+	enumerable: true,
+	get: function() {
+		return uniqueKeyTuple;
+	}
+});
 Object.defineProperty(exports, "validateBatch", {
 	enumerable: true,
 	get: function() {
 		return validateBatch;
 	}
 });
+Object.defineProperty(exports, "viewExprNullable", {
+	enumerable: true,
+	get: function() {
+		return viewExprNullable;
+	}
+});
+Object.defineProperty(exports, "walkViewExpr", {
+	enumerable: true,
+	get: function() {
+		return walkViewExpr;
+	}
+});