@atscript/db 0.1.141 → 0.1.143

package/dist/{object-DSN0h9lB.d.cts → object-CtPYTIvy.d.cts}

@@ -13,6 +13,8 @@ declare function isEmptyObject(obj: Record<string, unknown>): boolean;
  * runtime reconstruction on the Readable.
  */
 declare function findAncestorInSet(path: string, set: ReadonlySet<string>): string | undefined;
+/** `path` itself if it is in `set`, else its nearest ancestor in `set` ({@link findAncestorInSet}). */
+declare function selfOrAncestor(path: string, set: ReadonlySet<string>): string | undefined;
 /**
  * Reads a dot-path (or its segments) off a nested plain object: `undefined`
  * past a missing step, or a step that is not a plain object (arrays are not
@@ -27,4 +29,4 @@ declare function getPath(row: Record<string, unknown>, path: string | readonly s
  */
 declare function deletePath(target: Record<string, unknown>, path: string | readonly string[]): void;
 //#endregion
-export { isPlainObject as a, isEmptyObject as i, findAncestorInSet as n, getPath as r, deletePath as t };
+export { isPlainObject as a, isEmptyObject as i, findAncestorInSet as n, selfOrAncestor as o, getPath as r, deletePath as t };

package/dist/{object-DSN0h9lB.d.mts → object-CtPYTIvy.d.mts}

@@ -13,6 +13,8 @@ declare function isEmptyObject(obj: Record<string, unknown>): boolean;
  * runtime reconstruction on the Readable.
  */
 declare function findAncestorInSet(path: string, set: ReadonlySet<string>): string | undefined;
+/** `path` itself if it is in `set`, else its nearest ancestor in `set` ({@link findAncestorInSet}). */
+declare function selfOrAncestor(path: string, set: ReadonlySet<string>): string | undefined;
 /**
  * Reads a dot-path (or its segments) off a nested plain object: `undefined`
  * past a missing step, or a step that is not a plain object (arrays are not
@@ -27,4 +29,4 @@ declare function getPath(row: Record<string, unknown>, path: string | readonly s
  */
 declare function deletePath(target: Record<string, unknown>, path: string | readonly string[]): void;
 //#endregion
-export { isPlainObject as a, isEmptyObject as i, findAncestorInSet as n, getPath as r, deletePath as t };
+export { isPlainObject as a, isEmptyObject as i, findAncestorInSet as n, selfOrAncestor as o, getPath as r, deletePath as t };

package/dist/object-Djg28csK.cjs

@@ -0,0 +1,101 @@
+//#region src/shared/object.ts
+/**
+* Plain object: prototype is `Object.prototype` or `null` — never a class
+* instance (`Date`, `Uint8Array`, `ObjectId`, …) and never an array.
+* Browser-safe; shared by the write paths, the HTTP shape gate and the client.
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/** Zero-allocation emptiness check for a plain object (`{}` → `true`). */
+function isEmptyObject(obj) {
+	for (const _ in obj) return false;
+	return true;
+}
+/**
+* Finds the nearest ancestor of `path` that belongs to `set`.
+* Used by both the build pipeline (in `_classifyFields`) and
+* runtime reconstruction on the Readable.
+*/
+function findAncestorInSet(path, set) {
+	let pos = path.length;
+	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+		const ancestor = path.slice(0, pos);
+		if (set.has(ancestor)) return ancestor;
+	}
+}
+/** `path` itself if it is in `set`, else its nearest ancestor in `set` ({@link findAncestorInSet}). */
+function selfOrAncestor(path, set) {
+	return set.has(path) ? path : findAncestorInSet(path, set);
+}
+/** Splits a dot-path once; an already split path is used as-is. */
+function segmentsOf(path) {
+	return typeof path === "string" ? path.split(".") : path;
+}
+/**
+* Reads a dot-path (or its segments) off a nested plain object: `undefined`
+* past a missing step, or a step that is not a plain object (arrays are not
+* descended into — no positional indexing).
+* @since 0.1.141
+*/
+function getPath(row, path) {
+	let current = row;
+	for (const seg of segmentsOf(path)) {
+		if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+		current = current[seg];
+	}
+	return current;
+}
+/**
+* Deletes a dot-path (or its segments) from a nested plain object; a no-op
+* when an intermediate step is missing or not a plain object.
+* @since 0.1.141
+*/
+function deletePath(target, path) {
+	const segments = segmentsOf(path);
+	let current = target;
+	for (let i = 0; i < segments.length - 1; i++) {
+		if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+		current = current[segments[i]];
+	}
+	if (current !== null && typeof current === "object" && !Array.isArray(current)) delete current[segments[segments.length - 1]];
+}
+//#endregion
+Object.defineProperty(exports, "deletePath", {
+	enumerable: true,
+	get: function() {
+		return deletePath;
+	}
+});
+Object.defineProperty(exports, "findAncestorInSet", {
+	enumerable: true,
+	get: function() {
+		return findAncestorInSet;
+	}
+});
+Object.defineProperty(exports, "getPath", {
+	enumerable: true,
+	get: function() {
+		return getPath;
+	}
+});
+Object.defineProperty(exports, "isEmptyObject", {
+	enumerable: true,
+	get: function() {
+		return isEmptyObject;
+	}
+});
+Object.defineProperty(exports, "isPlainObject", {
+	enumerable: true,
+	get: function() {
+		return isPlainObject;
+	}
+});
+Object.defineProperty(exports, "selfOrAncestor", {
+	enumerable: true,
+	get: function() {
+		return selfOrAncestor;
+	}
+});

package/dist/object-TkiJQ-Dp.mjs

@@ -0,0 +1,66 @@
+//#region src/shared/object.ts
+/**
+* Plain object: prototype is `Object.prototype` or `null` — never a class
+* instance (`Date`, `Uint8Array`, `ObjectId`, …) and never an array.
+* Browser-safe; shared by the write paths, the HTTP shape gate and the client.
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/** Zero-allocation emptiness check for a plain object (`{}` → `true`). */
+function isEmptyObject(obj) {
+	for (const _ in obj) return false;
+	return true;
+}
+/**
+* Finds the nearest ancestor of `path` that belongs to `set`.
+* Used by both the build pipeline (in `_classifyFields`) and
+* runtime reconstruction on the Readable.
+*/
+function findAncestorInSet(path, set) {
+	let pos = path.length;
+	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+		const ancestor = path.slice(0, pos);
+		if (set.has(ancestor)) return ancestor;
+	}
+}
+/** `path` itself if it is in `set`, else its nearest ancestor in `set` ({@link findAncestorInSet}). */
+function selfOrAncestor(path, set) {
+	return set.has(path) ? path : findAncestorInSet(path, set);
+}
+/** Splits a dot-path once; an already split path is used as-is. */
+function segmentsOf(path) {
+	return typeof path === "string" ? path.split(".") : path;
+}
+/**
+* Reads a dot-path (or its segments) off a nested plain object: `undefined`
+* past a missing step, or a step that is not a plain object (arrays are not
+* descended into — no positional indexing).
+* @since 0.1.141
+*/
+function getPath(row, path) {
+	let current = row;
+	for (const seg of segmentsOf(path)) {
+		if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+		current = current[seg];
+	}
+	return current;
+}
+/**
+* Deletes a dot-path (or its segments) from a nested plain object; a no-op
+* when an intermediate step is missing or not a plain object.
+* @since 0.1.141
+*/
+function deletePath(target, path) {
+	const segments = segmentsOf(path);
+	let current = target;
+	for (let i = 0; i < segments.length - 1; i++) {
+		if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+		current = current[segments[i]];
+	}
+	if (current !== null && typeof current === "object" && !Array.isArray(current)) delete current[segments[segments.length - 1]];
+}
+//#endregion
+export { isPlainObject as a, isEmptyObject as i, findAncestorInSet as n, selfOrAncestor as o, getPath as r, deletePath as t };

package/dist/rel.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_nested_writer = require("./nested-writer-DYsRxZ5f.cjs");
-const require_relation_loader = require("./relation-loader-CgJ8bK6X.cjs");
+const require_nested_writer = require("./nested-writer-xfQwxplL.cjs");
+const require_relation_loader = require("./relation-loader-CBPY6kM7.cjs");
+exports.applyPatchNestedTo = require_nested_writer.applyPatchNestedTo;
 exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom;
 exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo;
 exports.batchInsertNestedVia = require_nested_writer.batchInsertNestedVia;
@@ -14,6 +15,8 @@ exports.checkDepthOverflow = require_nested_writer.checkDepthOverflow;
 exports.findFKForRelation = require_nested_writer.findFKForRelation;
 exports.findRemoteFK = require_nested_writer.findRemoteFK;
 exports.loadRelationsImpl = require_relation_loader.loadRelationsImpl;
+exports.planNestedFromVia = require_nested_writer.planNestedFromVia;
+exports.planPatchNestedTo = require_nested_writer.planPatchNestedTo;
 exports.preValidateNestedFrom = require_nested_writer.preValidateNestedFrom;
 exports.resolveRelationTargetTable = require_nested_writer.resolveRelationTargetTable;
 exports.validateBatch = require_nested_writer.validateBatch;

package/dist/rel.d.cts

@@ -1,6 +1,6 @@
-import { Dt as TWriteTableResolver, It as BaseDbAdapter, Mt as TableMetadata, St as TTableResolver, q as TDbRelation, un as TGenericLogger, z as TDbForeignKey } from "./buckets-Bv4pah66.cjs";
+import { B as TDbForeignKey, Bt as BaseDbAdapter, Et as TTableResolver, It as TableMetadata, J as TDbRelation, hn as TGenericLogger, jt as TWriteTableResolver, m as AtscriptDbWritable, p as AtscriptDbTableLike } from "./buckets-Ba5lP_o9.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-DQ_nRsV9.cjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-JTEyZzVd.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";
 
@@ -40,7 +40,9 @@ interface TNestedWriterHost {
   _extractRecordFilter(payload: Record<string, unknown>): FilterExpr;
   findOne(query: {
     filter: FilterExpr;
-    controls: Record<string, never>;
+    controls: {
+      $select?: string[];
+    };
   }): Promise<Record<string, unknown> | null>;
 }
 /**
@@ -75,27 +77,91 @@ declare function batchInsertNestedVia(host: TNestedWriterHost, originals: Array<
  */
 declare function batchReplaceNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
 /**
- * Batch-replaces FROM dependents after the main replace.
+ * 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.
  */
-declare function batchReplaceNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+declare function batchReplaceNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number, plan?: TNestedFromViaPlan): Promise<void>;
 /**
  * Handles VIA (M:N) relations during replace.
  */
 declare function batchReplaceNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
 /**
- * Batch-patches TO dependencies before the main patch.
- * Reads FK values from DB if not present in the payload.
+ * The FROM / VIA nested writes of a batch, validated by
+ * {@link planNestedFromVia} before the main write (since 0.1.143).
+ */
+interface TNestedFromViaPlan {
+  /**
+   * Per FROM nav field: the {@link pkTupleKey}s of the keyed children that
+   * exist under the parent naming them. Their writes must match (a child
+   * re-parented meanwhile → `CONFLICT`, rolled back).
+   */
+  readonly owned: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/**
+ * 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.
+ */
+declare function planNestedFromVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, mode: "patch" | "replace"): Promise<TNestedFromViaPlan>;
+/** One TO relation's nested patches, planned before the main patch — see {@link planPatchNestedTo}. */
+interface TNestedToPatchPlan {
+  navField: string;
+  targetTable: AtscriptDbTableLike & AtscriptDbWritable;
+  /** `index` = position of the source item in the batch. */
+  entries: Array<{
+    index: number;
+    patch: Record<string, unknown>;
+  }>;
+}
+/**
+ * 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`.
+ */
+declare function planPatchNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, targets?: ReadonlyArray<Record<string, unknown> | null | undefined>): Promise<TNestedToPatchPlan[]>;
+/**
+ * Applies the TO patches {@link planPatchNestedTo} planned — after the main
+ * patch, only for the items it matched (`matched[i]`; all when omitted).
+ */
+declare function applyPatchNestedTo(plans: ReadonlyArray<TNestedToPatchPlan>, maxDepth: number, depth: number, matched?: ReadonlyArray<boolean>): Promise<void>;
+/**
+ * Batch-patches TO dependencies: {@link planPatchNestedTo} +
+ * {@link applyPatchNestedTo} in one step (the table itself plans before and
+ * applies after its main patch).
  */
 declare function batchPatchNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
 /**
  * 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.
  */
-declare function batchPatchNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+declare function batchPatchNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number, plan?: TNestedFromViaPlan): Promise<void>;
 /**
  * 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.
  */
-declare function batchPatchNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+declare function batchPatchNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number, plan?: TNestedFromViaPlan): Promise<void>;
 //#endregion
-export { type TNestedWriterHost, type TRelationLoaderHost, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };
+export { type TNestedFromViaPlan, type TNestedToPatchPlan, type TNestedWriterHost, type TRelationLoaderHost, applyPatchNestedTo, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, planNestedFromVia, planPatchNestedTo, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/rel.d.mts

@@ -1,6 +1,6 @@
-import { Dt as TWriteTableResolver, It as BaseDbAdapter, Mt as TableMetadata, St as TTableResolver, q as TDbRelation, un as TGenericLogger, z as TDbForeignKey } from "./buckets-CjL7F-hp.mjs";
+import { B as TDbForeignKey, Bt as BaseDbAdapter, Et as TTableResolver, It as TableMetadata, J as TDbRelation, hn as TGenericLogger, jt as TWriteTableResolver, m as AtscriptDbWritable, p as AtscriptDbTableLike } from "./buckets-BlJ4cdlr.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-B59to_dG.mjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-MTwzaSGA.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 
@@ -40,7 +40,9 @@ interface TNestedWriterHost {
   _extractRecordFilter(payload: Record<string, unknown>): FilterExpr;
   findOne(query: {
     filter: FilterExpr;
-    controls: Record<string, never>;
+    controls: {
+      $select?: string[];
+    };
   }): Promise<Record<string, unknown> | null>;
 }
 /**
@@ -75,27 +77,91 @@ declare function batchInsertNestedVia(host: TNestedWriterHost, originals: Array<
  */
 declare function batchReplaceNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
 /**
- * Batch-replaces FROM dependents after the main replace.
+ * 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.
  */
-declare function batchReplaceNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+declare function batchReplaceNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number, plan?: TNestedFromViaPlan): Promise<void>;
 /**
  * Handles VIA (M:N) relations during replace.
  */
 declare function batchReplaceNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
 /**
- * Batch-patches TO dependencies before the main patch.
- * Reads FK values from DB if not present in the payload.
+ * The FROM / VIA nested writes of a batch, validated by
+ * {@link planNestedFromVia} before the main write (since 0.1.143).
+ */
+interface TNestedFromViaPlan {
+  /**
+   * Per FROM nav field: the {@link pkTupleKey}s of the keyed children that
+   * exist under the parent naming them. Their writes must match (a child
+   * re-parented meanwhile → `CONFLICT`, rolled back).
+   */
+  readonly owned: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/**
+ * 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.
+ */
+declare function planNestedFromVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, mode: "patch" | "replace"): Promise<TNestedFromViaPlan>;
+/** One TO relation's nested patches, planned before the main patch — see {@link planPatchNestedTo}. */
+interface TNestedToPatchPlan {
+  navField: string;
+  targetTable: AtscriptDbTableLike & AtscriptDbWritable;
+  /** `index` = position of the source item in the batch. */
+  entries: Array<{
+    index: number;
+    patch: Record<string, unknown>;
+  }>;
+}
+/**
+ * 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`.
+ */
+declare function planPatchNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, targets?: ReadonlyArray<Record<string, unknown> | null | undefined>): Promise<TNestedToPatchPlan[]>;
+/**
+ * Applies the TO patches {@link planPatchNestedTo} planned — after the main
+ * patch, only for the items it matched (`matched[i]`; all when omitted).
+ */
+declare function applyPatchNestedTo(plans: ReadonlyArray<TNestedToPatchPlan>, maxDepth: number, depth: number, matched?: ReadonlyArray<boolean>): Promise<void>;
+/**
+ * Batch-patches TO dependencies: {@link planPatchNestedTo} +
+ * {@link applyPatchNestedTo} in one step (the table itself plans before and
+ * applies after its main patch).
  */
 declare function batchPatchNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
 /**
  * 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.
  */
-declare function batchPatchNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+declare function batchPatchNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number, plan?: TNestedFromViaPlan): Promise<void>;
 /**
  * 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.
  */
-declare function batchPatchNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+declare function batchPatchNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number, plan?: TNestedFromViaPlan): Promise<void>;
 //#endregion
-export { type TNestedWriterHost, type TRelationLoaderHost, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };
+export { type TNestedFromViaPlan, type TNestedToPatchPlan, type TNestedWriterHost, type TRelationLoaderHost, applyPatchNestedTo, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, planNestedFromVia, planPatchNestedTo, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/rel.mjs

@@ -1,3 +1,3 @@
-import { t as loadRelationsImpl } from "./relation-loader-CuhEBzFU.mjs";
-import { _ as resolveRelationTargetTable, a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, n as batchInsertNestedTo, o as batchPatchNestedVia, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-BO3vhbkP.mjs";
-export { batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };
+import { t as loadRelationsImpl } from "./relation-loader-D9XuXaMv.mjs";
+import { C as findRemoteFK, S as findFKForRelation, a as batchPatchNestedFrom, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, o as batchPatchNestedTo, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, w as resolveRelationTargetTable } from "./nested-writer-CnOOAehr.mjs";
+export { applyPatchNestedTo, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, planNestedFromVia, planPatchNestedTo, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/{relation-helpers-B59to_dG.d.mts → relation-helpers-JTEyZzVd.d.cts}

@@ -1,4 +1,4 @@
-import { q as TDbRelation, z as TDbForeignKey } from "./buckets-CjL7F-hp.mjs";
+import { B as TDbForeignKey, J as TDbRelation } from "./buckets-Ba5lP_o9.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-helpers-DQ_nRsV9.d.cts → relation-helpers-MTwzaSGA.d.mts}

@@ -1,4 +1,4 @@
-import { q as TDbRelation, z as TDbForeignKey } from "./buckets-Bv4pah66.cjs";
+import { B as TDbForeignKey, J as TDbRelation } from "./buckets-BlJ4cdlr.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-loader-CgJ8bK6X.cjs → relation-loader-CBPY6kM7.cjs}

@@ -1,4 +1,4 @@
-const require_nested_writer = require("./nested-writer-DYsRxZ5f.cjs");
+const require_nested_writer = require("./nested-writer-xfQwxplL.cjs");
 //#region src/rel/relation-loader.ts
 var relation_loader_exports = /* @__PURE__ */ require("./plugin.cjs").__exportAll({
 	ensureSelectIncludesFields: () => ensureSelectIncludesFields,

package/dist/{relation-loader-CuhEBzFU.mjs → relation-loader-D9XuXaMv.mjs}

@@ -1,4 +1,4 @@
-import { _ as resolveRelationTargetTable, g as findRemoteFK, h as findFKForRelation } from "./nested-writer-BO3vhbkP.mjs";
+import { C as findRemoteFK, S as findFKForRelation, w as resolveRelationTargetTable } from "./nested-writer-CnOOAehr.mjs";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {

package/dist/sync.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DTkkeu5b.cjs");
-const require_column_diff = require("./column-diff-CfPNcP6e.cjs");
+const require_column_diff = require("./column-diff-D_Kyuh0S.cjs");
 //#region src/schema/table-option-diff.ts
 /**
 * Computes the difference between desired and existing table options.

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { G as TDbObjectKind, Lt as DbSpace, R as TDbFieldMeta, _t as TReferencingForeignKey, gt as TPrimaryKeyChange, it as TEnsureTableOptions, nt as TDerivedChangeReason, ot as TExistingForeignKey, st as TExistingTableOption, un as TGenericLogger, xt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-Bv4pah66.cjs";
-import { a as TTableSnapshot, c as TViewSnapshot, d as computeTableHash, f as computeTableSnapshot, h as snapshotToExistingTableOptions, i as TForeignKeySnapshot, l as canonicalizeQueryNode, m as snapshotToExistingColumns, o as TViewColumnSnapshot, p as computeViewSnapshot, r as TFieldSnapshot, s as TViewJoinSnapshot, t as computeColumnDiff, u as computeSchemaHash } from "./column-diff-DiBbXyLA.cjs";
+import { B as TDbForeignKey, K as TDbObjectKind, Tt as TTableOptionDiff, Vt as DbSpace, at as TDerivedChangeReason, bt as TReferencingForeignKey, hn as TGenericLogger, lt as TExistingForeignKey, st as TEnsureTableOptions, ut as TExistingTableOption, yt as TPrimaryKeyChange, z as TDbFieldMeta } from "./buckets-Ba5lP_o9.cjs";
+import { a as TTableSnapshot, c as TViewSnapshot, d as computeTableHash, f as computeTableSnapshot, h as snapshotToExistingTableOptions, i as TForeignKeySnapshot, l as canonicalizeQueryNode, m as snapshotToExistingColumns, o as TViewColumnSnapshot, p as computeViewSnapshot, r as TFieldSnapshot, s as TViewJoinSnapshot, t as computeColumnDiff, u as computeSchemaHash } from "./column-diff-BlGxPobU.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
-import { G as TDbObjectKind, Lt as DbSpace, R as TDbFieldMeta, _t as TReferencingForeignKey, gt as TPrimaryKeyChange, it as TEnsureTableOptions, nt as TDerivedChangeReason, ot as TExistingForeignKey, st as TExistingTableOption, un as TGenericLogger, xt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-CjL7F-hp.mjs";
-import { a as TTableSnapshot, c as TViewSnapshot, d as computeTableHash, f as computeTableSnapshot, h as snapshotToExistingTableOptions, i as TForeignKeySnapshot, l as canonicalizeQueryNode, m as snapshotToExistingColumns, o as TViewColumnSnapshot, p as computeViewSnapshot, r as TFieldSnapshot, s as TViewJoinSnapshot, t as computeColumnDiff, u as computeSchemaHash } from "./column-diff-n-k5KY0u.mjs";
+import { B as TDbForeignKey, K as TDbObjectKind, Tt as TTableOptionDiff, Vt as DbSpace, at as TDerivedChangeReason, bt as TReferencingForeignKey, hn as TGenericLogger, lt as TExistingForeignKey, st as TEnsureTableOptions, ut as TExistingTableOption, yt as TPrimaryKeyChange, z as TDbFieldMeta } from "./buckets-BlJ4cdlr.mjs";
+import { a as TTableSnapshot, c as TViewSnapshot, d as computeTableHash, f as computeTableSnapshot, h as snapshotToExistingTableOptions, i as TForeignKeySnapshot, l as canonicalizeQueryNode, m as snapshotToExistingColumns, o as TViewColumnSnapshot, p as computeViewSnapshot, r as TFieldSnapshot, s as TViewJoinSnapshot, t as computeColumnDiff, u as computeSchemaHash } from "./column-diff-PqA_edXA.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.mjs

@@ -1,5 +1,5 @@
 import { r as DbError } from "./db-error-D5uilS_A.mjs";
-import { Z as aliasTargetOf, a as hasForeignKeyChanges, c as computeTableHash, d as snapshotToExistingColumns, f as snapshotToExistingTableOptions, i as fkKey, l as computeTableSnapshot, o as canonicalizeQueryNode, p as viewSnapshotSources, r as computeForeignKeyDiff, rt as NoopLogger, s as computeSchemaHash, t as computeColumnDiff, u as computeViewSnapshot } from "./column-diff-CmFNXV8C.mjs";
+import { a as hasForeignKeyChanges, c as computeTableHash, d as snapshotToExistingColumns, f as snapshotToExistingTableOptions, i as fkKey, l as computeTableSnapshot, o as canonicalizeQueryNode, p as viewSnapshotSources, r as computeForeignKeyDiff, s as computeSchemaHash, st as NoopLogger, t as computeColumnDiff, tt as aliasTargetOf, u as computeViewSnapshot } from "./column-diff-e2oHc71_.mjs";
 //#region src/schema/table-option-diff.ts
 /**
 * Computes the difference between desired and existing table options.