@atscript/db 0.1.141 → 0.1.143

package/dist/nested-writer-xfQwxplL.cjs

@@ -0,0 +1,1029 @@
+const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_object = require("./object-Djg28csK.cjs");
+let _atscript_typescript_utils = require("@atscript/typescript/utils");
+//#region src/rel/relation-helpers.ts
+/**
+* Finds the FK entry that connects a `@db.rel.to` relation to its target.
+*/
+function findFKForRelation(relation, foreignKeys) {
+	const fk = findFKEntryForRelation(relation, foreignKeys);
+	return fk && {
+		localFields: fk.fields,
+		targetFields: fk.targetFields
+	};
+}
+/**
+* The `@db.rel.FK` entry {@link findFKForRelation} pairs with a relation: the
+* one sharing its alias, else (no alias) the first one targeting its table.
+*/
+function findFKEntryForRelation(relation, foreignKeys) {
+	if (relation.alias) {
+		for (const fk of foreignKeys.values()) if (fk.alias === relation.alias) return fk;
+		return;
+	}
+	const targetTable = resolveRelationTargetTable(relation);
+	for (const fk of foreignKeys.values()) if (fk.targetTable === targetTable) return fk;
+}
+/**
+* Finds a FK on a remote table that points back to a given table name.
+*/
+function findRemoteFK(targetTable, thisTableName, alias) {
+	for (const fk of targetTable.foreignKeys.values()) {
+		if (alias && fk.alias === alias && fk.targetTable === thisTableName) return fk;
+		if (!alias && fk.targetTable === thisTableName) return fk;
+	}
+}
+/**
+* Physical name of an annotated type — its `@db.table`, else its `@db.view`
+* name (a view is a readable source too, since 0.1.141), else its type id
+* (`""` when none is set). The rule relations, foreign keys and view plans
+* use to name a referenced table or view.
+* @since 0.1.136
+*/
+function tableNameOf(type) {
+	const table = type?.metadata?.get("db.table");
+	if (table) return table;
+	const view = type?.metadata?.get("db.view");
+	return typeof view === "string" && view || type?.id || "";
+}
+/**
+* Resolves the target table name from a relation's target type metadata.
+*/
+function resolveRelationTargetTable(relation) {
+	return tableNameOf(relation.targetType());
+}
+//#endregion
+//#region src/shared/keys.ts
+/** String form of a key value (an ObjectId stringifies to its hex, a bigint to its digits). */
+function keyString(value) {
+	return String(value);
+}
+/** Key equality across driver representations (number vs numeric string, ObjectId vs hex). */
+function sameKey(a, b) {
+	if (a === b) return true;
+	if (a === null || a === void 0 || b === null || b === void 0) return false;
+	return keyString(a) === keyString(b);
+}
+/**
+* One string identity for the key tuple `fields` of `row` (dot-paths read
+* nested) — equal for equal keys across driver representations. Used to
+* dedupe / match rows by primary key in memory.
+*/
+function pkTupleKey(row, fields) {
+	let out = "";
+	for (let i = 0; i < fields.length; i++) {
+		if (i > 0) out += "\0";
+		out += keyString(require_object.getPath(row, fields[i]));
+	}
+	return out;
+}
+/** Whether `row` carries exactly the values of an equality filter `{ field: value, … }`. */
+function rowMatchesKey(row, key) {
+	for (const field in key) if (!sameKey(require_object.getPath(row, field), key[field])) return false;
+	return true;
+}
+//#endregion
+//#region src/table/error-utils.ts
+/**
+* Prefixes error paths with a nav field context.
+* Ensures errors from child table operations (e.g., FK violations on a comment)
+* get paths like `comments[0].authorId` instead of just `authorId`.
+*/
+function prefixErrorPaths(errors, prefix) {
+	return errors.map((err) => ({
+		...err,
+		path: err.path ? `${prefix}.${err.path}` : prefix
+	}));
+}
+/**
+* Wraps an async nested operation and prefixes error paths with the nav field context.
+*/
+async function wrapNestedError(navField, fn) {
+	try {
+		return await fn();
+	} catch (error) {
+		if (error instanceof _atscript_typescript_utils.ValidatorError) throw new _atscript_typescript_utils.ValidatorError(prefixErrorPaths(error.errors, navField));
+		if (error instanceof require_db_error.DbError) throw new require_db_error.DbError(error.code, prefixErrorPaths(error.errors, navField));
+		throw error;
+	}
+}
+/**
+* Catches `DbError('FK_VIOLATION')` with empty paths (from adapters that
+* enforce FKs natively but can't report which field failed) and enriches
+* the error with all FK field names from table metadata.
+*/
+async function enrichFkViolation(meta, fn) {
+	try {
+		return await fn();
+	} catch (error) {
+		if (error instanceof require_db_error.DbError && error.code === "FK_VIOLATION" && error.errors.every((err) => !err.path)) {
+			const msg = error.errors[0]?.message ?? error.message;
+			const errors = [];
+			for (const [, fk] of meta.foreignKeys) for (const field of fk.fields) errors.push({
+				path: field,
+				message: msg
+			});
+			throw new require_db_error.DbError("FK_VIOLATION", errors.length > 0 ? errors : error.errors);
+		}
+		throw error;
+	}
+}
+/**
+* Wraps a delete operation: catches native `FK_VIOLATION` errors (e.g. SQLite
+* RESTRICT) and re-throws as `CONFLICT` (409) with a descriptive message.
+*/
+async function remapDeleteFkViolation(tableName, fn) {
+	try {
+		return await fn();
+	} catch (error) {
+		if (error instanceof require_db_error.DbError && error.code === "FK_VIOLATION") throw new require_db_error.DbError("CONFLICT", [{
+			path: tableName,
+			message: `Cannot delete from "${tableName}": referenced by child records (RESTRICT)`
+		}]);
+		throw error;
+	}
+}
+//#endregion
+//#region src/rel/nested-writer.ts
+/** A TO relation's target table and the local → target foreign key. */
+function resolveToRelation(host, relation) {
+	const targetTable = host._writeTableResolver?.(relation.targetType());
+	const fk = targetTable && host._findFKForRelation(relation);
+	return targetTable && fk ? {
+		targetTable,
+		fk
+	} : void 0;
+}
+/** A FROM relation's child table and the child → parent foreign key (when declared). */
+function resolveFromRelation(host, relation) {
+	const targetTable = host._writeTableResolver?.(relation.targetType());
+	return targetTable ? {
+		targetTable,
+		remoteFK: host._findRemoteFK(targetTable, host.tableName, relation.alias)
+	} : void 0;
+}
+function resolveViaRelation(host, relation) {
+	if (!relation.viaType || !host._writeTableResolver) return void 0;
+	const targetTable = host._writeTableResolver(relation.targetType());
+	const junctionTable = targetTable && host._writeTableResolver(relation.viaType());
+	if (!targetTable || !junctionTable) return void 0;
+	const fkToThis = host._findRemoteFK(junctionTable, host.tableName);
+	const fkToTarget = host._findRemoteFK(junctionTable, resolveRelationTargetTable(relation));
+	const targetPKField = targetTable.primaryKeys[0];
+	if (!fkToThis || !fkToTarget || !targetPKField || fkToThis.fields.length !== 1 || fkToTarget.fields.length !== 1) return;
+	return {
+		targetTable,
+		junctionTable,
+		fkToThis: fkToThis.fields[0],
+		fkToTarget: fkToTarget.fields[0],
+		targetPKField
+	};
+}
+/** The parent's single primary-key field — nested FROM / VIA writes need one. */
+function parentPKFieldOf(host) {
+	return host._meta.primaryKeys.length === 1 ? host._meta.primaryKeys[0] : void 0;
+}
+/** Whether any item carries a (non-null) value for `navField` — a phase's cheap skip. */
+function hasNavValue(items, navField) {
+	return items.some((item) => item[navField] !== void 0 && item[navField] !== null);
+}
+/** The nested TO objects of a batch for one relation, with their source indices. */
+function nestedToObjects(items, navField) {
+	const parents = [];
+	const sourceIndices = [];
+	for (let i = 0; i < items.length; i++) {
+		const nested = items[i][navField];
+		if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+			parents.push(nested);
+			sourceIndices.push(i);
+		}
+	}
+	return {
+		parents,
+		sourceIndices
+	};
+}
+/**
+* Checks if any payload contains navigational data that would be silently
+* dropped because maxDepth is 0.
+*/
+function checkDepthOverflow(payloads, maxDepth, meta) {
+	if (meta.navFields.size === 0) return;
+	for (const payload of payloads) for (const navField of meta.navFields) if (payload[navField] !== void 0) throw new Error(`Nested data in '${navField}' exceeds maxDepth (${maxDepth}). Increase maxDepth or strip nested data before writing.`);
+}
+/**
+* Validates a batch of items using the given validator and context.
+* Wraps per-item validation errors with array index paths for batch operations.
+*/
+function validateBatch(validator, items, ctx) {
+	for (let i = 0; i < items.length; i++) try {
+		validator.validate(items[i], false, ctx);
+	} catch (error) {
+		if (items.length > 1) {
+			if (error instanceof _atscript_typescript_utils.ValidatorError) throw new _atscript_typescript_utils.ValidatorError(error.errors.map((err) => ({
+				...err,
+				path: `[${i}].${err.path}`
+			})));
+			if (error instanceof require_db_error.DepthLimitExceededError) throw new require_db_error.DepthLimitExceededError(`[${i}].${error.field}`, error.declared, error.actual);
+		}
+		throw error;
+	}
+}
+/**
+* Pre-validates FROM children (type + FK constraints) before the main insert.
+* Catches errors early before the parent record is committed.
+*/
+async function preValidateNestedFrom(host, originals) {
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "from" || !hasNavValue(originals, navField)) continue;
+		const from = resolveFromRelation(host, relation);
+		if (!from) continue;
+		const allChildren = [];
+		for (const orig of originals) {
+			const children = orig[navField];
+			if (!Array.isArray(children)) continue;
+			for (const child of children) {
+				const childData = { ...child };
+				if (from.remoteFK) {
+					for (const field of from.remoteFK.fields) if (!(field in childData)) childData[field] = 0;
+				}
+				allChildren.push(childData);
+			}
+		}
+		if (allChildren.length === 0) continue;
+		await wrapNestedError(navField, () => from.targetTable.preValidateItems(allChildren, { excludeFkTargetTable: host.tableName }));
+	}
+}
+/**
+* Batch-creates TO dependencies before the main insert.
+*/
+async function batchInsertNestedTo(host, items, maxDepth, depth) {
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "to" || !hasNavValue(items, navField)) continue;
+		const to = resolveToRelation(host, relation);
+		if (!to) continue;
+		const { parents, sourceIndices } = nestedToObjects(items, navField);
+		if (parents.length === 0) continue;
+		const result = await to.targetTable.insertMany(parents, {
+			maxDepth,
+			_depth: depth + 1
+		});
+		if (to.fk.localFields.length === 1) {
+			const fkField = to.fk.localFields[0];
+			for (let j = 0; j < sourceIndices.length; j++) items[sourceIndices[j]][fkField] = result.insertedIds[j];
+		}
+	}
+}
+/**
+* Batch-creates FROM dependents after the main insert.
+*/
+async function batchInsertNestedFrom(host, originals, parentIds, maxDepth, depth) {
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "from" || !hasNavValue(originals, navField)) continue;
+		const from = resolveFromRelation(host, relation);
+		const remoteFK = from?.remoteFK;
+		if (!from || !remoteFK) continue;
+		const allChildren = [];
+		for (let i = 0; i < originals.length; i++) {
+			const children = originals[i][navField];
+			if (!Array.isArray(children)) continue;
+			for (const child of children) {
+				const childData = { ...child };
+				if (remoteFK.fields.length === 1) childData[remoteFK.fields[0]] = parentIds[i];
+				allChildren.push(childData);
+			}
+		}
+		if (allChildren.length === 0) continue;
+		await wrapNestedError(navField, () => from.targetTable.insertMany(allChildren, {
+			maxDepth,
+			_depth: depth + 1
+		}));
+	}
+}
+/**
+* Batch-creates VIA (M:N) targets and junction entries after the main insert.
+*/
+async function batchInsertNestedVia(host, originals, parentIds, maxDepth, depth) {
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "via" || !hasNavValue(originals, navField)) continue;
+		const via = resolveViaRelation(host, relation);
+		if (!via) continue;
+		for (let i = 0; i < originals.length; i++) {
+			const targets = originals[i][navField];
+			const parentPK = parentIds[i];
+			if (!Array.isArray(targets) || targets.length === 0 || parentPK === void 0) continue;
+			await viaLinkTargets(via, targets, parentPK, maxDepth, depth);
+		}
+	}
+}
+/**
+* Batch-replaces TO dependencies before the main replace.
+*/
+async function batchReplaceNestedTo(host, items, maxDepth, depth) {
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "to" || !hasNavValue(items, navField)) continue;
+		const to = resolveToRelation(host, relation);
+		if (!to) continue;
+		const { parents, sourceIndices } = nestedToObjects(items, navField);
+		if (parents.length === 0) continue;
+		await to.targetTable.bulkReplace(parents, {
+			maxDepth,
+			_depth: depth + 1
+		});
+		if (to.fk.localFields.length === 1 && to.fk.targetFields.length === 1) {
+			const fkField = to.fk.localFields[0];
+			const targetField = to.fk.targetFields[0];
+			for (let j = 0; j < sourceIndices.length; j++) items[sourceIndices[j]][fkField] = parents[j][targetField];
+		}
+	}
+}
+/**
+* Batch-replaces FROM dependents after the main replace. `plan` is the
+* {@link planNestedFromVia} result for `originals` (`mode: "replace"`);
+* omitted, the plan is made here first.
+*/
+async function batchReplaceNestedFrom(host, originals, maxDepth, depth, plan) {
+	plan ??= await planNestedFromVia(host, originals, "replace");
+	const parentPKField = parentPKFieldOf(host);
+	if (parentPKField === void 0) return;
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "from" || !hasNavValue(originals, navField)) continue;
+		const target = fromWriteTarget(host, relation, navField, plan, maxDepth, depth);
+		if (!target) continue;
+		for (const original of originals) {
+			const children = original[navField];
+			const parentPK = original[parentPKField];
+			if (Array.isArray(children) && parentPK !== void 0) await fromReplace(target, children, parentPK);
+		}
+	}
+}
+/**
+* Handles VIA (M:N) relations during replace.
+*/
+async function batchReplaceNestedVia(host, originals, maxDepth, depth) {
+	const parentPKField = parentPKFieldOf(host);
+	if (parentPKField === void 0) return;
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "via" || !hasNavValue(originals, navField)) continue;
+		const via = resolveViaRelation(host, relation);
+		if (!via) continue;
+		for (const original of originals) {
+			const targets = original[navField];
+			const parentPK = original[parentPKField];
+			if (Array.isArray(targets) && parentPK !== void 0) await viaReplace(via, targets, parentPK, maxDepth, depth);
+		}
+	}
+}
+/**
+* Validates the FROM and VIA nested writes of a batch BEFORE the main write
+* (since 0.1.143), so a rejected nested operation never leaves the main
+* write applied — even on adapters whose transaction is a pass-through. One
+* read per relation for the whole batch; the entries are evaluated in memory
+* in apply order (`$replace` → `$update` → `$upsert`). `mode: "patch"`
+* checks the operators, `mode: "replace"` the plain arrays of a PUT:
+* - FROM: a keyed child that exists under another parent (or none) → `CONFLICT`;
+*   a `$update` entry without the child PK → `NOT_FOUND`;
+* - VIA: a keyed `$update` / `$upsert` target not linked to the parent →
+*   `CONFLICT`; a `$update` entry without the target PK → `NOT_FOUND`.
+*
+* The apply phases write the planned FROM children through filters
+* constrained to their parent (`{ pk, fk: parentPK }`), so a child
+* re-parented between the plan and the write is never touched.
+*/
+async function planNestedFromVia(host, originals, mode) {
+	const owned = /* @__PURE__ */ new Map();
+	const parentPKField = parentPKFieldOf(host);
+	if (parentPKField === void 0) return { owned };
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction === "to" || !hasNavValue(originals, navField)) continue;
+		if (relation.direction === "from") {
+			const from = resolveFromRelation(host, relation);
+			if (!from?.remoteFK || from.remoteFK.fields.length !== 1) continue;
+			owned.set(navField, await checkFromOwnership(from.targetTable, from.remoteFK.fields[0], originals, parentPKField, navField, mode));
+			continue;
+		}
+		const via = mode === "patch" ? resolveViaRelation(host, relation) : void 0;
+		if (via) await checkViaLinks(via, originals, parentPKField, navField);
+	}
+	return { owned };
+}
+/**
+* Plans the TO relation patches of a batch BEFORE the main patch (since
+* 0.1.143). A nested TO object always patches the row the STORED foreign key
+* references. `targets[i]` is item `i`'s stored row (at least its foreign-key
+* columns; `null` = missing) as the table pinned it inside the transaction;
+* omitted, each item's row is read here. Rejected with `INVALID_QUERY`
+* (nothing written): a payload that changes that foreign key AND carries a
+* nested object for the same relation, and a nested object whose own key
+* names a different row. An item whose source row does not exist is skipped
+* (the main patch matches nothing for it). A stored `null` foreign key (or a
+* composite one) → `FK_VIOLATION`.
+*/
+async function planPatchNestedTo(host, items, targets) {
+	const plans = [];
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "to" || !hasNavValue(items, navField)) continue;
+		const to = resolveToRelation(host, relation);
+		if (!to) continue;
+		const { parents, sourceIndices } = nestedToObjects(items, navField);
+		if (parents.length === 0) continue;
+		const fkField = to.fk.localFields[0];
+		if (to.fk.localFields.length !== 1) throw new require_db_error.DbError("FK_VIOLATION", [{
+			path: fkField,
+			message: `Cannot patch relation '${navField}' — foreign key '${fkField}' is null`
+		}]);
+		const targetField = to.fk.targetFields.length === 1 ? to.fk.targetFields[0] : void 0;
+		const entries = [];
+		for (let j = 0; j < parents.length; j++) {
+			const index = sourceIndices[j];
+			const item = items[index];
+			const current = targets ? targets[index] : await host.findOne({
+				filter: host._extractRecordFilter(item),
+				controls: { $select: [fkField] }
+			});
+			if (!current) continue;
+			const stored = current[fkField];
+			const payloadFk = item[fkField];
+			if (payloadFk !== void 0 && !sameKey(payloadFk, stored)) throw new require_db_error.DbError("INVALID_QUERY", [{
+				path: fkField,
+				message: `Cannot change '${fkField}' and patch relation '${navField}' in one payload — the nested patch targets the currently referenced record`
+			}]);
+			if (stored === null || stored === void 0) throw new require_db_error.DbError("FK_VIOLATION", [{
+				path: fkField,
+				message: `Cannot patch relation '${navField}' — foreign key '${fkField}' is null`
+			}]);
+			const patch = { ...parents[j] };
+			if (targetField !== void 0) {
+				const nestedKey = patch[targetField];
+				if (nestedKey !== void 0 && !sameKey(nestedKey, stored)) throw new require_db_error.DbError("INVALID_QUERY", [{
+					path: `${navField}.${targetField}`,
+					message: `Cannot patch relation '${navField}' — '${targetField}' does not match the currently referenced record`
+				}]);
+				patch[targetField] = stored;
+			}
+			entries.push({
+				index,
+				patch
+			});
+		}
+		if (entries.length > 0) plans.push({
+			navField,
+			targetTable: to.targetTable,
+			entries
+		});
+	}
+	return plans;
+}
+/**
+* Applies the TO patches {@link planPatchNestedTo} planned — after the main
+* patch, only for the items it matched (`matched[i]`; all when omitted).
+*/
+async function applyPatchNestedTo(plans, maxDepth, depth, matched) {
+	for (const plan of plans) {
+		const patches = plan.entries.filter((e) => !matched || matched[e.index]).map((e) => e.patch);
+		if (patches.length === 0) continue;
+		await plan.targetTable.bulkUpdate(patches, {
+			maxDepth,
+			_depth: depth + 1
+		});
+	}
+}
+/**
+* Batch-patches TO dependencies: {@link planPatchNestedTo} +
+* {@link applyPatchNestedTo} in one step (the table itself plans before and
+* applies after its main patch).
+*/
+async function batchPatchNestedTo(host, items, maxDepth, depth) {
+	await applyPatchNestedTo(await planPatchNestedTo(host, items), maxDepth, depth);
+}
+/**
+* Batch-patches FROM (1:N) dependencies after the main patch.
+* Supports patch operators: $replace, $insert, $remove, $update, $upsert.
+* `plan` is the {@link planNestedFromVia} result for `originals`
+* (`mode: "patch"`); omitted, the plan is made here first.
+*/
+async function batchPatchNestedFrom(host, originals, maxDepth, depth, plan) {
+	plan ??= await planNestedFromVia(host, originals, "patch");
+	const parentPKField = parentPKFieldOf(host);
+	if (parentPKField === void 0) return;
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "from" || !hasNavValue(originals, navField)) continue;
+		const target = fromWriteTarget(host, relation, navField, plan, maxDepth, depth);
+		if (!target) continue;
+		const { targetTable, fkField, childPKs } = target;
+		for (const original of originals) {
+			const navValue = original[navField];
+			const parentPK = original[parentPKField];
+			if (navValue === void 0 || navValue === null || parentPK === void 0) continue;
+			const ops = extractNavPatchOps(navValue);
+			if (ops.replace) await fromReplace(target, ops.replace, parentPK);
+			if (ops.remove && ops.remove.length > 0) {
+				const removeFilters = ops.remove.map((child) => {
+					const rec = child;
+					const f = {};
+					for (const pk of childPKs) f[pk] = rec[pk];
+					f[fkField] = parentPK;
+					return f;
+				});
+				await targetTable.deleteMany(orFilter(removeFilters));
+			}
+			if (ops.update && ops.update.length > 0) await fromUpdate(target, withField(ops.update, fkField, parentPK));
+			if (ops.upsert) {
+				const toUpdate = [];
+				const toInsert = [];
+				for (const child of ops.upsert) {
+					const rec = {
+						...child,
+						[fkField]: parentPK
+					};
+					(isKeyed(rec, childPKs) ? toUpdate : toInsert).push(rec);
+				}
+				if (toUpdate.length > 0) await fromUpdate(target, toUpdate);
+				if (toInsert.length > 0) await wrapNestedError(navField, () => targetTable.insertMany(toInsert, {
+					maxDepth,
+					_depth: depth + 1
+				}));
+			}
+			if (ops.insert && ops.insert.length > 0) {
+				const items = withField(ops.insert, fkField, parentPK);
+				await wrapNestedError(navField, () => targetTable.insertMany(items, {
+					maxDepth,
+					_depth: depth + 1
+				}));
+			}
+		}
+	}
+}
+/**
+* Batch-patches VIA (M:N) dependencies after the main patch.
+* Supports patch operators: $replace, $insert, $remove, $update, $upsert.
+* `plan` marks `originals` as already validated by {@link planNestedFromVia}
+* (`mode: "patch"`); omitted, they are validated here first.
+*/
+async function batchPatchNestedVia(host, originals, maxDepth, depth, plan) {
+	if (!plan) await planNestedFromVia(host, originals, "patch");
+	const parentPKField = parentPKFieldOf(host);
+	if (parentPKField === void 0) return;
+	for (const [navField, relation] of host._meta.relations) {
+		if (relation.direction !== "via" || !hasNavValue(originals, navField)) continue;
+		const via = resolveViaRelation(host, relation);
+		if (!via) continue;
+		const { targetTable, junctionTable, fkToThis, fkToTarget, targetPKField } = via;
+		for (const original of originals) {
+			const navValue = original[navField];
+			const parentPK = original[parentPKField];
+			if (navValue === void 0 || navValue === null || parentPK === void 0) continue;
+			const ops = extractNavPatchOps(navValue);
+			if (ops.replace) await viaReplace(via, ops.replace, parentPK, maxDepth, depth);
+			if (ops.remove && ops.remove.length > 0) {
+				const targetPKs = ops.remove.map((t) => t[targetPKField]).filter((pk) => pk !== void 0 && pk !== null);
+				if (targetPKs.length > 0) await junctionTable.deleteMany({
+					[fkToThis]: parentPK,
+					[fkToTarget]: targetPKs.length === 1 ? targetPKs[0] : { $in: targetPKs }
+				});
+			}
+			if (ops.update && ops.update.length > 0) {
+				const toUpdate = ops.update.map((t) => ({ ...t }));
+				await targetTable.bulkUpdate(toUpdate, {
+					maxDepth,
+					_depth: depth + 1
+				});
+			}
+			if (ops.upsert && ops.upsert.length > 0) {
+				const toUpdate = [];
+				const toInsert = [];
+				for (const target of ops.upsert) {
+					const rec = { ...target };
+					const pk = rec[targetPKField];
+					(pk !== void 0 && pk !== null ? toUpdate : toInsert).push(rec);
+				}
+				if (toUpdate.length > 0) await targetTable.bulkUpdate(toUpdate, {
+					maxDepth,
+					_depth: depth + 1
+				});
+				if (toInsert.length > 0) await viaLinkTargets(via, toInsert, parentPK, maxDepth, depth);
+			}
+			if (ops.insert && ops.insert.length > 0) await viaLinkTargets(via, ops.insert, parentPK, maxDepth, depth);
+		}
+	}
+}
+/**
+* Extracts patch operations from a nav field value.
+* Plain array → $replace. Object with $insert, $remove, etc. → individual ops.
+*/
+function extractNavPatchOps(navValue) {
+	if (Array.isArray(navValue)) return { replace: navValue };
+	if (typeof navValue !== "object" || navValue === null) return {};
+	const obj = navValue;
+	return {
+		replace: obj.$replace !== void 0 ? obj.$replace : void 0,
+		insert: obj.$insert !== void 0 ? obj.$insert : void 0,
+		remove: obj.$remove !== void 0 ? obj.$remove : void 0,
+		update: obj.$update !== void 0 ? obj.$update : void 0,
+		upsert: obj.$upsert !== void 0 ? obj.$upsert : void 0
+	};
+}
+/** `filters` as one filter — a lone filter as-is, several `$or`-ed. */
+function orFilter(filters) {
+	return filters.length === 1 ? filters[0] : { $or: filters };
+}
+/** Copies of `entries` with `field` set to `value` (a child's foreign key to its parent). */
+function withField(entries, field, value) {
+	const out = [];
+	for (const entry of entries) out.push({
+		...entry,
+		[field]: value
+	});
+	return out;
+}
+/** Identity of a junction link (parent key, target key). */
+function linkKey(parentPK, targetPK) {
+	return `${keyString(parentPK)}\0${keyString(targetPK)}`;
+}
+/** Whether `rec` carries every primary-key field (a table without one keys nothing). */
+function isKeyed(rec, pkFields) {
+	return pkFields.length > 0 && pkFields.every((pk) => rec[pk] !== void 0);
+}
+/** The primary-key equality filter of a keyed entry. */
+function keyFilter(rec, pkFields) {
+	const f = {};
+	for (const pk of pkFields) f[pk] = rec[pk];
+	return f;
+}
+/**
+* Nested `$update` entries are identified by the related table's primary key
+* only (since 0.1.143) — a unique key could name a row outside the relation.
+*/
+function requireKeys(entries, pkFields, navField, op) {
+	for (let i = 0; i < entries.length; i++) {
+		const rec = entries[i];
+		const missing = pkFields.find((pk) => rec[pk] === void 0 || rec[pk] === null);
+		if (missing !== void 0) throw new require_db_error.DbError("NOT_FOUND", [{
+			path: `${navField}.${op}[${i}].${missing}`,
+			message: `Missing primary key field "${missing}" in '${navField}' ${op} entry`
+		}]);
+	}
+}
+/**
+* FROM half of {@link planNestedFromVia}: ONE read of every keyed child the
+* batch names; a child that exists under a different parent (or none) →
+* `CONFLICT`. Keys that match no row pass (the usual "nothing matched"
+* semantics apply). Returns the keys of the children found under their parent.
+*/
+async function checkFromOwnership(targetTable, fkField, originals, parentPKField, navField, mode) {
+	const childPKs = targetTable.primaryKeys;
+	const claims = [];
+	const claim = (entries, parentPK, op) => {
+		for (const entry of entries) {
+			const child = entry;
+			if (isKeyed(child, childPKs)) claims.push({
+				parentPK,
+				child,
+				op
+			});
+		}
+	};
+	for (const original of originals) {
+		const parentPK = original[parentPKField];
+		const navValue = original[navField];
+		if (parentPK === void 0 || navValue === void 0 || navValue === null) continue;
+		if (mode === "replace") {
+			if (Array.isArray(navValue)) claim(navValue, parentPK, "replace");
+			continue;
+		}
+		const ops = extractNavPatchOps(navValue);
+		if (ops.replace) claim(ops.replace, parentPK, "replace");
+		if (ops.update && ops.update.length > 0) {
+			requireKeys(ops.update, childPKs, navField, "$update");
+			claim(ops.update, parentPK, "$update");
+		}
+		if (ops.upsert) claim(ops.upsert, parentPK, "$upsert");
+	}
+	const owned = /* @__PURE__ */ new Set();
+	if (claims.length === 0) return owned;
+	const rows = await targetTable.findMany({
+		filter: orFilter(claims.map((c) => keyFilter(c.child, childPKs))),
+		controls: { $select: [...childPKs, fkField] }
+	});
+	const parentOf = /* @__PURE__ */ new Map();
+	for (const row of rows) parentOf.set(pkTupleKey(row, childPKs), row[fkField]);
+	for (const { parentPK, child, op } of claims) {
+		const key = pkTupleKey(child, childPKs);
+		if (!parentOf.has(key)) continue;
+		if (!sameKey(parentOf.get(key), parentPK)) throw new require_db_error.DbError("CONFLICT", [{
+			path: navField,
+			message: `Cannot ${op} '${navField}' — record [${childPKs.map((pk) => keyString(child[pk])).join(", ")}] is not a child of this record`
+		}]);
+		owned.add(key);
+	}
+	return owned;
+}
+/**
+* VIA half of {@link planNestedFromVia}: ONE junction read for every keyed
+* `$update` / `$upsert` target of the batch; a target not currently linked
+* to its parent → `CONFLICT` (since 0.1.143) — whether or not the target
+* exists. Linking an existing target is `$insert`'s job.
+*/
+async function checkViaLinks(via, originals, parentPKField, navField) {
+	const { junctionTable, fkToThis, fkToTarget, targetPKField } = via;
+	const claims = [];
+	for (const original of originals) {
+		const parentPK = original[parentPKField];
+		const navValue = original[navField];
+		if (parentPK === void 0 || navValue === void 0 || navValue === null) continue;
+		const ops = extractNavPatchOps(navValue);
+		if (ops.update && ops.update.length > 0) {
+			requireKeys(ops.update, [targetPKField], navField, "$update");
+			for (const t of ops.update) claims.push({
+				parentPK,
+				targetPK: t[targetPKField],
+				op: "$update"
+			});
+		}
+		for (const t of ops.upsert ?? []) {
+			const targetPK = t[targetPKField];
+			if (targetPK !== void 0 && targetPK !== null) claims.push({
+				parentPK,
+				targetPK,
+				op: "$upsert"
+			});
+		}
+	}
+	if (claims.length === 0) return;
+	const links = await junctionTable.findMany({
+		filter: orFilter(claims.map((c) => ({
+			[fkToThis]: c.parentPK,
+			[fkToTarget]: c.targetPK
+		}))),
+		controls: { $select: [fkToThis, fkToTarget] }
+	});
+	const linked = new Set(links.map((j) => linkKey(j[fkToThis], j[fkToTarget])));
+	const unlinked = claims.find((c) => !linked.has(linkKey(c.parentPK, c.targetPK)));
+	if (unlinked) throw new require_db_error.DbError("CONFLICT", [{
+		path: navField,
+		message: `Cannot ${unlinked.op} '${navField}' — record [${keyString(unlinked.targetPK)}] is not linked to this record (link it with $insert first)`
+	}]);
+}
+function fromWriteTarget(host, relation, navField, plan, maxDepth, depth) {
+	const from = resolveFromRelation(host, relation);
+	if (!from?.remoteFK || from.remoteFK.fields.length !== 1) return void 0;
+	return {
+		targetTable: from.targetTable,
+		navField,
+		fkField: from.remoteFK.fields[0],
+		childPKs: from.targetTable.primaryKeys,
+		owned: plan.owned.get(navField) ?? /* @__PURE__ */ new Set(),
+		maxDepth,
+		depth
+	};
+}
+/**
+* Write options that pin each child to its parent: the child table ANDs
+* `{ fk: <item's fk> }` into every row filter (the foreign key is never
+* SET — a child is never re-parented), and a planned-owned child that no
+* longer matches → `CONFLICT` (rolled back).
+*/
+function ownedWriteOpts(target, items) {
+	return {
+		maxDepth: target.maxDepth,
+		_depth: target.depth + 1,
+		_ownedBy: {
+			field: target.fkField,
+			strict: items.map((item) => target.owned.has(pkTupleKey(item, target.childPKs)))
+		}
+	};
+}
+/** FROM `$update` / keyed `$upsert`: patch the parent's own children. */
+async function fromUpdate(target, items) {
+	await wrapNestedError(target.navField, () => target.targetTable.bulkUpdate(items, ownedWriteOpts(target, items)));
+}
+/**
+* FROM $replace helper: delete the parent's orphans, replace its keyed
+* children, insert the rest.
+*/
+async function fromReplace(target, children, parentPK) {
+	const { targetTable, navField, fkField, childPKs, maxDepth, depth } = target;
+	const toReplace = [];
+	const toInsert = [];
+	const keep = /* @__PURE__ */ new Set();
+	for (const child of children) {
+		const childData = {
+			...child,
+			[fkField]: parentPK
+		};
+		if (isKeyed(childData, childPKs)) {
+			keep.add(pkTupleKey(childData, childPKs));
+			toReplace.push(childData);
+		} else toInsert.push(childData);
+	}
+	const existing = await targetTable.findMany({
+		filter: { [fkField]: parentPK },
+		controls: childPKs.length > 0 ? { $select: [...childPKs] } : {}
+	});
+	const orphanFilters = [];
+	for (const row of existing) if (!keep.has(pkTupleKey(row, childPKs))) orphanFilters.push({
+		...keyFilter(row, childPKs),
+		[fkField]: parentPK
+	});
+	if (orphanFilters.length > 0) await targetTable.deleteMany(orFilter(orphanFilters));
+	if (toReplace.length > 0) await wrapNestedError(navField, () => targetTable.bulkReplace(toReplace, ownedWriteOpts(target, toReplace)));
+	if (toInsert.length > 0) await wrapNestedError(navField, () => targetTable.insertMany(toInsert, {
+		maxDepth,
+		_depth: depth + 1
+	}));
+}
+/**
+* Links `targets` to the parent: keyed entries by their key, unkeyed ones
+* inserted first — then one junction insert.
+*/
+async function viaLinkTargets(via, targets, parentPK, maxDepth, depth) {
+	const { targetTable, junctionTable, fkToThis, fkToTarget, targetPKField } = via;
+	const toInsert = [];
+	const targetIds = [];
+	for (const t of targets) {
+		const rec = t;
+		const pk = rec[targetPKField];
+		if (pk !== void 0 && pk !== null) targetIds.push(pk);
+		else toInsert.push({ ...rec });
+	}
+	if (toInsert.length > 0) {
+		const result = await targetTable.insertMany(toInsert, {
+			maxDepth,
+			_depth: depth + 1
+		});
+		targetIds.push(...result.insertedIds);
+	}
+	if (targetIds.length > 0) await junctionTable.insertMany(targetIds.map((targetId) => ({
+		[fkToThis]: parentPK,
+		[fkToTarget]: targetId
+	})), { maxDepth: 0 });
+}
+/**
+* VIA $replace helper: clear junctions, replace/insert targets, rebuild junctions.
+*/
+async function viaReplace(via, targets, parentPK, maxDepth, depth) {
+	const { targetTable, junctionTable, fkToThis, targetPKField } = via;
+	await junctionTable.deleteMany({ [fkToThis]: parentPK });
+	const toReplace = [];
+	for (const t of targets) {
+		const rec = t;
+		const pk = rec[targetPKField];
+		if (pk !== void 0 && pk !== null && Object.keys(rec).some((k) => k !== targetPKField)) toReplace.push({ ...rec });
+	}
+	if (toReplace.length > 0) await targetTable.bulkReplace(toReplace, {
+		maxDepth,
+		_depth: depth + 1
+	});
+	await viaLinkTargets(via, targets, parentPK, maxDepth, depth);
+}
+//#endregion
+Object.defineProperty(exports, "applyPatchNestedTo", {
+	enumerable: true,
+	get: function() {
+		return applyPatchNestedTo;
+	}
+});
+Object.defineProperty(exports, "batchInsertNestedFrom", {
+	enumerable: true,
+	get: function() {
+		return batchInsertNestedFrom;
+	}
+});
+Object.defineProperty(exports, "batchInsertNestedTo", {
+	enumerable: true,
+	get: function() {
+		return batchInsertNestedTo;
+	}
+});
+Object.defineProperty(exports, "batchInsertNestedVia", {
+	enumerable: true,
+	get: function() {
+		return batchInsertNestedVia;
+	}
+});
+Object.defineProperty(exports, "batchPatchNestedFrom", {
+	enumerable: true,
+	get: function() {
+		return batchPatchNestedFrom;
+	}
+});
+Object.defineProperty(exports, "batchPatchNestedTo", {
+	enumerable: true,
+	get: function() {
+		return batchPatchNestedTo;
+	}
+});
+Object.defineProperty(exports, "batchPatchNestedVia", {
+	enumerable: true,
+	get: function() {
+		return batchPatchNestedVia;
+	}
+});
+Object.defineProperty(exports, "batchReplaceNestedFrom", {
+	enumerable: true,
+	get: function() {
+		return batchReplaceNestedFrom;
+	}
+});
+Object.defineProperty(exports, "batchReplaceNestedTo", {
+	enumerable: true,
+	get: function() {
+		return batchReplaceNestedTo;
+	}
+});
+Object.defineProperty(exports, "batchReplaceNestedVia", {
+	enumerable: true,
+	get: function() {
+		return batchReplaceNestedVia;
+	}
+});
+Object.defineProperty(exports, "checkDepthOverflow", {
+	enumerable: true,
+	get: function() {
+		return checkDepthOverflow;
+	}
+});
+Object.defineProperty(exports, "enrichFkViolation", {
+	enumerable: true,
+	get: function() {
+		return enrichFkViolation;
+	}
+});
+Object.defineProperty(exports, "findFKEntryForRelation", {
+	enumerable: true,
+	get: function() {
+		return findFKEntryForRelation;
+	}
+});
+Object.defineProperty(exports, "findFKForRelation", {
+	enumerable: true,
+	get: function() {
+		return findFKForRelation;
+	}
+});
+Object.defineProperty(exports, "findRemoteFK", {
+	enumerable: true,
+	get: function() {
+		return findRemoteFK;
+	}
+});
+Object.defineProperty(exports, "pkTupleKey", {
+	enumerable: true,
+	get: function() {
+		return pkTupleKey;
+	}
+});
+Object.defineProperty(exports, "planNestedFromVia", {
+	enumerable: true,
+	get: function() {
+		return planNestedFromVia;
+	}
+});
+Object.defineProperty(exports, "planPatchNestedTo", {
+	enumerable: true,
+	get: function() {
+		return planPatchNestedTo;
+	}
+});
+Object.defineProperty(exports, "preValidateNestedFrom", {
+	enumerable: true,
+	get: function() {
+		return preValidateNestedFrom;
+	}
+});
+Object.defineProperty(exports, "remapDeleteFkViolation", {
+	enumerable: true,
+	get: function() {
+		return remapDeleteFkViolation;
+	}
+});
+Object.defineProperty(exports, "resolveRelationTargetTable", {
+	enumerable: true,
+	get: function() {
+		return resolveRelationTargetTable;
+	}
+});
+Object.defineProperty(exports, "rowMatchesKey", {
+	enumerable: true,
+	get: function() {
+		return rowMatchesKey;
+	}
+});
+Object.defineProperty(exports, "sameKey", {
+	enumerable: true,
+	get: function() {
+		return sameKey;
+	}
+});
+Object.defineProperty(exports, "tableNameOf", {
+	enumerable: true,
+	get: function() {
+		return tableNameOf;
+	}
+});
+Object.defineProperty(exports, "validateBatch", {
+	enumerable: true,
+	get: function() {
+		return validateBatch;
+	}
+});