@atscript/db 0.1.146 → 0.1.148

package/dist/{nested-writer-CnOOAehr.mjs → nested-writer-CUBoq1ZO.mjs}

@@ -1,6 +1,134 @@
-import { i as DepthLimitExceededError, r as DbError } from "./db-error-D5uilS_A.mjs";
-import { r as getPath } from "./object-TkiJQ-Dp.mjs";
+import { i as DepthLimitExceededError, r as DbError } from "./db-error-Az85UhTX.mjs";
+import { a as isPlainObject, r as getPath } from "./object-TkiJQ-Dp.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
+import { isRelationOp } from "@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 (!isPlainObject(value)) return false;
+	for (const key in value) if (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("$") && isPlainObject(value)) for (const [op, operand] of Object.entries(value)) {
+		if (!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 DbError("INVALID_QUERY", [{
+		path,
+		message
+	}]);
+}
+function notSupported(path, message) {
+	return new 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 (!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 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 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 (!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(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 = 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,4 +1471,4 @@ async function viaReplace(via, targets, parentPK, maxDepth, depth) {
 	await viaLinkTargets(via, targets, parentPK, maxDepth, depth);
 }
 //#endregion
-export { findRemoteFK as C, findFKForRelation as S, tableNameOf as T, remapDeleteFkViolation as _, batchPatchNestedFrom as a, sameKey as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, enrichFkViolation as g, validateBatch as h, batchInsertNestedVia as i, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, pkTupleKey as v, resolveRelationTargetTable as w, findFKEntryForRelation as x, rowMatchesKey as y };
+export { isResolvedRelationFilter as A, slicePerGroup as B, REL_FILTER_MAX_NODES as C, createRelationFilterHost as D, containsRelationFilter as E, compositeKey as F, isFieldRef as G, computeOf as H, findFKEntryForRelation as I, walkViewExpr as J, translateQueryTree as K, findFKForRelation as L, relGuardState as M, relationStaticFilter as N, forEachResolvedRelation as O, resolveRelationFilterTree as P, findRemoteFK as R, REL_FILTER_MAX_DEPTH as S, andFilters as T, computedOperands as U, tableNameOf as V, evaluateExpr as W, remapDeleteFkViolation as _, batchPatchNestedFrom as a, sameKey as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, enrichFkViolation as g, validateBatch as h, batchInsertNestedVia as i, noteRelationFilter as j, hasRelationOp as k, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, viewExprNullable as q, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, pkTupleKey as v, ResolvedRelationFilter as w, uniqueKeyTuple as x, rowMatchesKey as y, resolveRelationTargetTable as z };

package/dist/numeric-operand-B1jKH7x5.mjs

@@ -0,0 +1,21 @@
+//#region src/shared/numeric-operand.ts
+/** Primitive tags of timestamps (MySQL may store them as native `TIMESTAMP`). */
+const TIMESTAMP_TAGS = [
+	"timestamp",
+	"created",
+	"updated"
+];
+/**
+* Why a field cannot be an arithmetic operand, or `undefined` when it can: it
+* must be a `number` — not a decimal (exact; an expression is IEEE double) and
+* not a timestamp-tagged number. The one rule behind `@db.compute` (declared,
+* from the `.as` source) and query-time arithmetic (from the runtime
+* descriptor), so the two cannot diverge. Storage rules (`@db.ignore`,
+* encrypted, JSON) stay with the callers.
+*/
+function numericTypeProblem({ base, tags }) {
+	if (base !== "number" && base !== "integer") return base === "decimal" ? "is a decimal" : `is a ${base}`;
+	if (tags && TIMESTAMP_TAGS.some((t) => tags.has(t))) return "is a timestamp";
+}
+//#endregion
+export { numericTypeProblem as t };

package/dist/numeric-operand-DKfiRLYp.cjs

@@ -0,0 +1,26 @@
+//#region src/shared/numeric-operand.ts
+/** Primitive tags of timestamps (MySQL may store them as native `TIMESTAMP`). */
+const TIMESTAMP_TAGS = [
+	"timestamp",
+	"created",
+	"updated"
+];
+/**
+* Why a field cannot be an arithmetic operand, or `undefined` when it can: it
+* must be a `number` — not a decimal (exact; an expression is IEEE double) and
+* not a timestamp-tagged number. The one rule behind `@db.compute` (declared,
+* from the `.as` source) and query-time arithmetic (from the runtime
+* descriptor), so the two cannot diverge. Storage rules (`@db.ignore`,
+* encrypted, JSON) stay with the callers.
+*/
+function numericTypeProblem({ base, tags }) {
+	if (base !== "number" && base !== "integer") return base === "decimal" ? "is a decimal" : `is a ${base}`;
+	if (tags && TIMESTAMP_TAGS.some((t) => tags.has(t))) return "is a timestamp";
+}
+//#endregion
+Object.defineProperty(exports, "numericTypeProblem", {
+	enumerable: true,
+	get: function() {
+		return numericTypeProblem;
+	}
+});

package/dist/ops.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_db_error = require("./db-error-DRQH4sLY.cjs");
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {

package/dist/ops.mjs

@@ -1,4 +1,4 @@
-import { r as DbError } from "./db-error-D5uilS_A.mjs";
+import { r as DbError } from "./db-error-Az85UhTX.mjs";
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {