@atscript/db 0.1.39 → 0.1.40

package/dist/plugin.mjs

@@ -1,7 +1,6 @@
-import { findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument } from "./validation-utils-DhR_mtKa.mjs";
+import { a as getAnnotationAlias, c as getParentStruct, d as validateFieldBaseType, i as validateRefArgument, l as getParentTypeName, n as hasAnyViewAnnotation, o as getDbTableOwner, r as validateQueryScope, s as getNavTargetTypeName, t as findFKFieldsPointingTo, u as refActionAnnotation } from "./validation-utils-DhjIjP1-.mjs";
 import { AnnotationSpec, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
-
-//#region packages/db/src/plugin/annotations/agg.ts
+//#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
 	sum: new AnnotationSpec({
 		description: "Declares a view field as SUM of a source column.",
@@ -59,9 +58,8 @@ const dbAggAnnotations = { agg: {
 		}
 	})
 } };
-
 //#endregion
-//#region packages/db/src/plugin/annotations/column.ts
+//#region src/plugin/annotations/column.ts
 const dbColumnAnnotations = {
 	patch: { strategy: new AnnotationSpec({
 		description: "Defines the **patching strategy** for updating nested objects.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@db.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
@@ -198,8 +196,7 @@ const dbColumnAnnotations = {
 		nodeType: ["prop"],
 		validate(token, _args, doc) {
 			const errors = [];
-			const field = token.parentNode;
-			const definition = field.getDefinition();
+			const definition = token.parentNode.getDefinition();
 			if (definition && isRef(definition)) {
 				const unwound = doc.unwindType(definition.id, definition.chain);
 				if (unwound && isPrimitive(unwound.def)) errors.push({
@@ -214,10 +211,9 @@ const dbColumnAnnotations = {
 	ignore: new AnnotationSpec({
 		description: "Excludes a field from the database schema. The field exists in the Atscript type but has no column in the DB.\n\n**Example:**\n```atscript\n@db.ignore\ndisplayName: string\n```\n",
 		nodeType: ["prop"],
-		validate(token, args, doc) {
+		validate(token, _args, _doc) {
 			const errors = [];
-			const field = token.parentNode;
-			if (field.countAnnotations("meta.id") > 0) errors.push({
+			if (token.parentNode.countAnnotations("meta.id") > 0) errors.push({
 				message: `@db.ignore cannot coexist with @meta.id — a field cannot be both a primary key and excluded from the database`,
 				severity: 1,
 				range: token.range
@@ -226,9 +222,8 @@ const dbColumnAnnotations = {
 		}
 	})
 };
-
 //#endregion
-//#region packages/db/src/plugin/annotations/index-ann.ts
+//#region src/plugin/annotations/index-ann.ts
 const dbIndexAnnotations = { index: {
 	plain: new AnnotationSpec({
 		description: "Standard (non-unique) index for query performance. Fields sharing the same index name form a composite index.\n\n**Example:**\n```atscript\n@db.index.plain \"idx_timeline\", \"desc\"\ncreatedAt: number.timestamp\n```\n",
@@ -278,9 +273,8 @@ const dbIndexAnnotations = { index: {
 		}]
 	})
 } };
-
 //#endregion
-//#region packages/db/src/plugin/annotations/rel.ts
+//#region src/plugin/annotations/rel.ts
 const dbRelAnnotations = { rel: {
 	FK: new AnnotationSpec({
 		description: "Declares a foreign key constraint on this field. The field must use a chain reference type (e.g., `User.id`) to specify the FK target.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
@@ -401,7 +395,7 @@ const dbRelAnnotations = { rel: {
 			const unwound = doc.unwindType(targetTypeName);
 			if (unwound) {
 				const targetDef = unwound.def;
-				const targetNode = isInterface(targetDef) ? targetDef : undefined;
+				const targetNode = isInterface(targetDef) ? targetDef : void 0;
 				if (!targetNode || targetNode.countAnnotations("db.table") === 0) errors.push({
 					message: `@db.rel.to target '${targetTypeName}' is not a @db.table entity`,
 					severity: 1,
@@ -421,9 +415,8 @@ const dbRelAnnotations = { rel: {
 					if (name === fieldName) continue;
 					if (prop.countAnnotations("db.rel.to") === 0) continue;
 					const propAlias = getAnnotationAlias(prop, "db.rel.to");
-					if ((alias || undefined) === (propAlias || undefined)) {
-						const otherTarget = getNavTargetTypeName(prop);
-						if (otherTarget === targetTypeName) {
+					if ((alias || void 0) === (propAlias || void 0)) {
+						if (getNavTargetTypeName(prop) === targetTypeName) {
 							errors.push({
 								message: `Duplicate @db.rel.to '${alias || targetTypeName}' — only one forward navigational property per alias`,
 								severity: 1,
@@ -434,8 +427,7 @@ const dbRelAnnotations = { rel: {
 					}
 				}
 				if (alias) {
-					const matches = findFKFieldsPointingTo(doc, struct, targetTypeName, alias);
-					if (matches.length === 0) errors.push({
+					if (findFKFieldsPointingTo(doc, struct, targetTypeName, alias).length === 0) errors.push({
 						message: `No @db.rel.FK '${alias}' found on this interface`,
 						severity: 1,
 						range: token.range
@@ -447,7 +439,7 @@ const dbRelAnnotations = { rel: {
 						severity: 1,
 						range: token.range
 					});
-else if (matches.length > 1) errors.push({
+					else if (matches.length > 1) errors.push({
 						message: `Multiple @db.rel.FK fields point to '${targetTypeName}' — add alias to disambiguate`,
 						severity: 1,
 						range: token.range
@@ -502,9 +494,8 @@ else if (matches.length > 1) errors.push({
 					if (name === fieldName) continue;
 					if (prop.countAnnotations("db.rel.from") === 0) continue;
 					const propAlias = getAnnotationAlias(prop, "db.rel.from");
-					if ((alias || undefined) === (propAlias || undefined)) {
-						const otherTarget = getNavTargetTypeName(prop);
-						if (otherTarget === targetTypeName) {
+					if ((alias || void 0) === (propAlias || void 0)) {
+						if (getNavTargetTypeName(prop) === targetTypeName) {
 							errors.push({
 								message: `Duplicate @db.rel.from '${alias || targetTypeName}' — only one inverse navigational property per alias`,
 								severity: 1,
@@ -529,15 +520,13 @@ else if (matches.length > 1) errors.push({
 				severity: 1,
 				range: token.range
 			});
-else if (matches.length > 1) errors.push({
+			else if (matches.length > 1) errors.push({
 				message: `'${targetTypeName}' has multiple @db.rel.FK fields pointing to '${thisTypeName}' — add alias`,
 				severity: 1,
 				range: token.range
 			});
-			const fieldDef = field.getDefinition();
-			if (!isArray(fieldDef) && matches.length === 1) {
-				const fkProp = matches[0].prop;
-				if (fkProp.countAnnotations("db.index.unique") === 0) errors.push({
+			if (!isArray(field.getDefinition()) && matches.length === 1) {
+				if (matches[0].prop.countAnnotations("db.index.unique") === 0) errors.push({
 					message: `@db.rel.from '${field.id}' has singular type '${targetTypeName}' (1:1) but the FK on '${targetTypeName}' is not @db.index.unique — did you mean '${targetTypeName}[]' (1:N)?`,
 					severity: 2,
 					range: token.range
@@ -564,8 +553,7 @@ else if (matches.length > 1) errors.push({
 				severity: 1,
 				range: token.range
 			});
-			const definition = field.getDefinition();
-			if (!isArray(definition)) errors.push({
+			if (!isArray(field.getDefinition())) errors.push({
 				message: "@db.rel.via requires an array type (e.g. Tag[])",
 				severity: 1,
 				range: token.range
@@ -587,7 +575,7 @@ else if (matches.length > 1) errors.push({
 				severity: 1,
 				range: args[0].range
 			});
-else if (fksToThis.length > 1) errors.push({
+			else if (fksToThis.length > 1) errors.push({
 				message: `Junction '${junctionName}' has multiple @db.rel.FK pointing to '${thisTypeName}' — not supported`,
 				severity: 1,
 				range: args[0].range
@@ -599,7 +587,7 @@ else if (fksToThis.length > 1) errors.push({
 					severity: 1,
 					range: args[0].range
 				});
-else if (fksToTarget.length > 1) errors.push({
+				else if (fksToTarget.length > 1) errors.push({
 					message: `Junction '${junctionName}' has multiple @db.rel.FK pointing to '${targetTypeName}' — not supported`,
 					severity: 1,
 					range: args[0].range
@@ -643,9 +631,8 @@ else if (fksToTarget.length > 1) errors.push({
 		}
 	})
 } };
-
 //#endregion
-//#region packages/db/src/plugin/annotations/search.ts
+//#region src/plugin/annotations/search.ts
 const dbSearchAnnotations = { search: {
 	vector: {
 		$self: new AnnotationSpec({
@@ -710,9 +697,8 @@ const dbSearchAnnotations = { search: {
 		}
 	})
 } };
-
 //#endregion
-//#region packages/db/src/plugin/annotations/table.ts
+//#region src/plugin/annotations/table.ts
 const dbTableAnnotations = {
 	table: {
 		$self: new AnnotationSpec({
@@ -745,8 +731,7 @@ const dbTableAnnotations = {
 			},
 			validate(token, _args, _doc) {
 				const errors = [];
-				const owner = token.parentNode;
-				if (owner.countAnnotations("db.table") === 0) errors.push({
+				if (token.parentNode.countAnnotations("db.table") === 0) errors.push({
 					message: "@db.table.renamed requires @db.table on the same interface",
 					severity: 1,
 					range: token.range
@@ -775,9 +760,8 @@ const dbTableAnnotations = {
 		}
 	}) }
 };
-
 //#endregion
-//#region packages/db/src/plugin/annotations/view.ts
+//#region src/plugin/annotations/view.ts
 const dbViewAnnotations = { view: {
 	$self: new AnnotationSpec({
 		description: "Marks an interface as a **database view**. Optionally takes a view name argument.\n\n**Example:**\n```atscript\n@db.view \"active_premium_users\"\n@db.view.for User\nexport interface ActivePremiumUser { ... }\n```\n",
@@ -790,8 +774,7 @@ const dbViewAnnotations = { view: {
 		},
 		validate(token, _args, _doc) {
 			const errors = [];
-			const owner = token.parentNode;
-			if (owner.countAnnotations("db.table") > 0) errors.push({
+			if (token.parentNode.countAnnotations("db.table") > 0) errors.push({
 				message: "An interface cannot be both a @db.table and a @db.view",
 				severity: 1,
 				range: token.range
@@ -809,8 +792,7 @@ const dbViewAnnotations = { view: {
 		},
 		validate(token, args, doc) {
 			const errors = [];
-			const owner = token.parentNode;
-			if (owner.countAnnotations("db.table") > 0) errors.push({
+			if (token.parentNode.countAnnotations("db.table") > 0) errors.push({
 				message: "An interface cannot be both a @db.table and a @db.view",
 				severity: 1,
 				range: token.range
@@ -952,9 +934,8 @@ const dbViewAnnotations = { view: {
 		}
 	})
 } };
-
 //#endregion
-//#region packages/db/src/plugin/index.ts
+//#region src/plugin/index.ts
 const dbPlugin = () => ({
 	name: "db",
 	config() {
@@ -984,6 +965,5 @@ const dbPlugin = () => ({
 		};
 	}
 });
-
 //#endregion
-export { dbPlugin, dbPlugin as default };
+export { dbPlugin, dbPlugin as default };

package/dist/rel.cjs

@@ -1,20 +1,20 @@
-const require_nested_writer = require('./nested-writer-BkqL7cp3.cjs');
-const require_relation_helpers = require('./relation-helpers-guFL_oRf.cjs');
-const require_relation_loader = require('./relation-loader-CpnDRf9k.cjs');
-
-exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom
-exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo
-exports.batchInsertNestedVia = require_nested_writer.batchInsertNestedVia
-exports.batchPatchNestedFrom = require_nested_writer.batchPatchNestedFrom
-exports.batchPatchNestedTo = require_nested_writer.batchPatchNestedTo
-exports.batchPatchNestedVia = require_nested_writer.batchPatchNestedVia
-exports.batchReplaceNestedFrom = require_nested_writer.batchReplaceNestedFrom
-exports.batchReplaceNestedTo = require_nested_writer.batchReplaceNestedTo
-exports.batchReplaceNestedVia = require_nested_writer.batchReplaceNestedVia
-exports.checkDepthOverflow = require_nested_writer.checkDepthOverflow
-exports.findFKForRelation = require_relation_helpers.findFKForRelation
-exports.findRemoteFK = require_relation_helpers.findRemoteFK
-exports.loadRelationsImpl = require_relation_loader.loadRelationsImpl
-exports.preValidateNestedFrom = require_nested_writer.preValidateNestedFrom
-exports.resolveRelationTargetTable = require_relation_helpers.resolveRelationTargetTable
-exports.validateBatch = require_nested_writer.validateBatch
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_relation_loader = require("./relation-loader-CRC5LcqM.cjs");
+const require_nested_writer = require("./nested-writer-BDXsDMPP.cjs");
+const require_relation_helpers = require("./relation-helpers-BYvsE1tR.cjs");
+exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom;
+exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo;
+exports.batchInsertNestedVia = require_nested_writer.batchInsertNestedVia;
+exports.batchPatchNestedFrom = require_nested_writer.batchPatchNestedFrom;
+exports.batchPatchNestedTo = require_nested_writer.batchPatchNestedTo;
+exports.batchPatchNestedVia = require_nested_writer.batchPatchNestedVia;
+exports.batchReplaceNestedFrom = require_nested_writer.batchReplaceNestedFrom;
+exports.batchReplaceNestedTo = require_nested_writer.batchReplaceNestedTo;
+exports.batchReplaceNestedVia = require_nested_writer.batchReplaceNestedVia;
+exports.checkDepthOverflow = require_nested_writer.checkDepthOverflow;
+exports.findFKForRelation = require_relation_helpers.findFKForRelation;
+exports.findRemoteFK = require_relation_helpers.findRemoteFK;
+exports.loadRelationsImpl = require_relation_loader.loadRelationsImpl;
+exports.preValidateNestedFrom = require_nested_writer.preValidateNestedFrom;
+exports.resolveRelationTargetTable = require_relation_helpers.resolveRelationTargetTable;
+exports.validateBatch = require_nested_writer.validateBatch;

package/dist/rel.d.cts

@@ -0,0 +1,119 @@
+import { A as TDbForeignKey, L as TDbRelation, Y as TTableResolver, Z as TWriteTableResolver, l as TGenericLogger, o as BaseDbAdapter, s as TableMetadata } from "./db-readable-BQQzfguJ.cjs";
+import { t as DbValidationContext } from "./db-validator-plugin-07kDiis2.cjs";
+import { FilterExpr, WithRelation } from "@uniqu/core";
+import { Validator } from "@atscript/typescript/utils";
+
+//#region src/rel/relation-loader.d.ts
+/** Host interface for the relation loader — matches AtscriptDbReadable property names. */
+interface TRelationLoaderHost {
+  readonly tableName: string;
+  readonly _meta: {
+    readonly relations: ReadonlyMap<string, TDbRelation>;
+    readonly foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  };
+  readonly _tableResolver?: TTableResolver;
+  readonly adapter: BaseDbAdapter;
+  readonly logger: TGenericLogger;
+}
+/**
+ * Loads related data for `$with` relations and attaches them to result rows.
+ */
+declare function loadRelationsImpl(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], host: TRelationLoaderHost): Promise<void>;
+//#endregion
+//#region src/rel/relation-helpers.d.ts
+/**
+ * Finds the FK entry that connects a `@db.rel.to` relation to its target.
+ */
+declare function findFKForRelation(relation: TDbRelation, foreignKeys: ReadonlyMap<string, TDbForeignKey>): {
+  localFields: string[];
+  targetFields: string[];
+} | undefined;
+/**
+ * Finds a FK on a remote table that points back to a given table name.
+ */
+declare function findRemoteFK(targetTable: {
+  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+}, thisTableName: string, alias?: string): TDbForeignKey | undefined;
+/**
+ * Resolves the target table name from a relation's target type metadata.
+ */
+declare function resolveRelationTargetTable(relation: TDbRelation): string;
+//#endregion
+//#region src/rel/nested-writer.d.ts
+/**
+ * Properties the nested writer functions need from the table instance.
+ * AtscriptDbTable satisfies this structurally — pass `this` with a cast.
+ */
+interface TNestedWriterHost {
+  readonly tableName: string;
+  readonly _meta: TableMetadata;
+  readonly _writeTableResolver?: TWriteTableResolver;
+  _findFKForRelation(relation: TDbRelation): {
+    localFields: string[];
+    targetFields: string[];
+  } | undefined;
+  _findRemoteFK(targetTable: {
+    foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
+  _extractPrimaryKeyFilter(payload: Record<string, unknown>): FilterExpr;
+  findOne(query: {
+    filter: FilterExpr;
+    controls: Record<string, never>;
+  }): Promise<Record<string, unknown> | null>;
+}
+/**
+ * Checks if any payload contains navigational data that would be silently
+ * dropped because maxDepth is 0.
+ */
+declare function checkDepthOverflow(payloads: Array<Record<string, unknown>>, maxDepth: number, meta: TableMetadata): void;
+/**
+ * Validates a batch of items using the given validator and context.
+ * Wraps per-item validation errors with array index paths for batch operations.
+ */
+declare function validateBatch(validator: Validator<any, any>, items: Array<Record<string, unknown>>, ctx: DbValidationContext): void;
+/**
+ * Pre-validates FROM children (type + FK constraints) before the main insert.
+ * Catches errors early before the parent record is committed.
+ */
+declare function preValidateNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>): Promise<void>;
+/**
+ * Batch-creates TO dependencies before the main insert.
+ */
+declare function batchInsertNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-creates FROM dependents after the main insert.
+ */
+declare function batchInsertNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, parentIds: unknown[], maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-creates VIA (M:N) targets and junction entries after the main insert.
+ */
+declare function batchInsertNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, parentIds: unknown[], maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-replaces TO dependencies before the main replace.
+ */
+declare function batchReplaceNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-replaces FROM dependents after the main replace.
+ */
+declare function batchReplaceNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): 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.
+ */
+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.
+ */
+declare function batchPatchNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-patches VIA (M:N) dependencies after the main patch.
+ * Supports patch operators: $replace, $insert, $remove, $update, $upsert.
+ */
+declare function batchPatchNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+//#endregion
+export { TNestedWriterHost, TRelationLoaderHost, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/rel.d.mts

@@ -0,0 +1,119 @@
+import { A as TDbForeignKey, L as TDbRelation, Y as TTableResolver, Z as TWriteTableResolver, l as TGenericLogger, o as BaseDbAdapter, s as TableMetadata } from "./db-readable-Bbr4CjMb.mjs";
+import { t as DbValidationContext } from "./db-validator-plugin-CiqsHTI_.mjs";
+import { Validator } from "@atscript/typescript/utils";
+import { FilterExpr, WithRelation } from "@uniqu/core";
+
+//#region src/rel/relation-loader.d.ts
+/** Host interface for the relation loader — matches AtscriptDbReadable property names. */
+interface TRelationLoaderHost {
+  readonly tableName: string;
+  readonly _meta: {
+    readonly relations: ReadonlyMap<string, TDbRelation>;
+    readonly foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  };
+  readonly _tableResolver?: TTableResolver;
+  readonly adapter: BaseDbAdapter;
+  readonly logger: TGenericLogger;
+}
+/**
+ * Loads related data for `$with` relations and attaches them to result rows.
+ */
+declare function loadRelationsImpl(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], host: TRelationLoaderHost): Promise<void>;
+//#endregion
+//#region src/rel/relation-helpers.d.ts
+/**
+ * Finds the FK entry that connects a `@db.rel.to` relation to its target.
+ */
+declare function findFKForRelation(relation: TDbRelation, foreignKeys: ReadonlyMap<string, TDbForeignKey>): {
+  localFields: string[];
+  targetFields: string[];
+} | undefined;
+/**
+ * Finds a FK on a remote table that points back to a given table name.
+ */
+declare function findRemoteFK(targetTable: {
+  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+}, thisTableName: string, alias?: string): TDbForeignKey | undefined;
+/**
+ * Resolves the target table name from a relation's target type metadata.
+ */
+declare function resolveRelationTargetTable(relation: TDbRelation): string;
+//#endregion
+//#region src/rel/nested-writer.d.ts
+/**
+ * Properties the nested writer functions need from the table instance.
+ * AtscriptDbTable satisfies this structurally — pass `this` with a cast.
+ */
+interface TNestedWriterHost {
+  readonly tableName: string;
+  readonly _meta: TableMetadata;
+  readonly _writeTableResolver?: TWriteTableResolver;
+  _findFKForRelation(relation: TDbRelation): {
+    localFields: string[];
+    targetFields: string[];
+  } | undefined;
+  _findRemoteFK(targetTable: {
+    foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
+  _extractPrimaryKeyFilter(payload: Record<string, unknown>): FilterExpr;
+  findOne(query: {
+    filter: FilterExpr;
+    controls: Record<string, never>;
+  }): Promise<Record<string, unknown> | null>;
+}
+/**
+ * Checks if any payload contains navigational data that would be silently
+ * dropped because maxDepth is 0.
+ */
+declare function checkDepthOverflow(payloads: Array<Record<string, unknown>>, maxDepth: number, meta: TableMetadata): void;
+/**
+ * Validates a batch of items using the given validator and context.
+ * Wraps per-item validation errors with array index paths for batch operations.
+ */
+declare function validateBatch(validator: Validator<any, any>, items: Array<Record<string, unknown>>, ctx: DbValidationContext): void;
+/**
+ * Pre-validates FROM children (type + FK constraints) before the main insert.
+ * Catches errors early before the parent record is committed.
+ */
+declare function preValidateNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>): Promise<void>;
+/**
+ * Batch-creates TO dependencies before the main insert.
+ */
+declare function batchInsertNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-creates FROM dependents after the main insert.
+ */
+declare function batchInsertNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, parentIds: unknown[], maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-creates VIA (M:N) targets and junction entries after the main insert.
+ */
+declare function batchInsertNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, parentIds: unknown[], maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-replaces TO dependencies before the main replace.
+ */
+declare function batchReplaceNestedTo(host: TNestedWriterHost, items: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-replaces FROM dependents after the main replace.
+ */
+declare function batchReplaceNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): 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.
+ */
+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.
+ */
+declare function batchPatchNestedFrom(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+/**
+ * Batch-patches VIA (M:N) dependencies after the main patch.
+ * Supports patch operators: $replace, $insert, $remove, $update, $upsert.
+ */
+declare function batchPatchNestedVia(host: TNestedWriterHost, originals: Array<Record<string, unknown>>, maxDepth: number, depth: number): Promise<void>;
+//#endregion
+export { type TNestedWriterHost, type TRelationLoaderHost, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/rel.mjs

@@ -1,5 +1,4 @@
-import { batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, preValidateNestedFrom, validateBatch } from "./nested-writer-NEN51mnR.mjs";
-import { findFKForRelation, findRemoteFK, resolveRelationTargetTable } from "./relation-helpers-DyBIlQnB.mjs";
-import { loadRelationsImpl } from "./relation-loader-Dv7qXYq7.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-BEOTXNcq.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, 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-Dmm1gbZV.mjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-CLasawQq.mjs";
+export { batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/{relation-helpers-guFL_oRf.cjs → relation-helpers-BYvsE1tR.cjs}

@@ -1,6 +1,7 @@
-"use strict";
-
-//#region packages/db/src/rel/relation-helpers.ts
+//#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 targetTable = resolveRelationTargetTable(relation);
 	for (const fk of foreignKeys.values()) if (relation.alias) {
@@ -12,36 +13,39 @@ function findFKForRelation(relation, foreignKeys) {
 		localFields: fk.fields,
 		targetFields: fk.targetFields
 	};
-	return undefined;
 }
+/**
+* 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;
 	}
-	return undefined;
 }
+/**
+* Resolves the target table name from a relation's target type metadata.
+*/
 function resolveRelationTargetTable(relation) {
 	const targetType = relation.targetType();
 	return targetType?.metadata?.get("db.table") || targetType?.id || "";
 }
-
 //#endregion
-Object.defineProperty(exports, 'findFKForRelation', {
-  enumerable: true,
-  get: function () {
-    return findFKForRelation;
-  }
+Object.defineProperty(exports, "findFKForRelation", {
+	enumerable: true,
+	get: function() {
+		return findFKForRelation;
+	}
+});
+Object.defineProperty(exports, "findRemoteFK", {
+	enumerable: true,
+	get: function() {
+		return findRemoteFK;
+	}
 });
-Object.defineProperty(exports, 'findRemoteFK', {
-  enumerable: true,
-  get: function () {
-    return findRemoteFK;
-  }
+Object.defineProperty(exports, "resolveRelationTargetTable", {
+	enumerable: true,
+	get: function() {
+		return resolveRelationTargetTable;
+	}
 });
-Object.defineProperty(exports, 'resolveRelationTargetTable', {
-  enumerable: true,
-  get: function () {
-    return resolveRelationTargetTable;
-  }
-});

package/dist/{relation-helpers-DyBIlQnB.mjs → relation-helpers-CLasawQq.mjs}

@@ -1,5 +1,7 @@
-
-//#region packages/db/src/rel/relation-helpers.ts
+//#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 targetTable = resolveRelationTargetTable(relation);
 	for (const fk of foreignKeys.values()) if (relation.alias) {
@@ -11,19 +13,22 @@ function findFKForRelation(relation, foreignKeys) {
 		localFields: fk.fields,
 		targetFields: fk.targetFields
 	};
-	return undefined;
 }
+/**
+* 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;
 	}
-	return undefined;
 }
+/**
+* Resolves the target table name from a relation's target type metadata.
+*/
 function resolveRelationTargetTable(relation) {
 	const targetType = relation.targetType();
 	return targetType?.metadata?.get("db.table") || targetType?.id || "";
 }
-
 //#endregion
-export { findFKForRelation, findRemoteFK, resolveRelationTargetTable };
+export { findRemoteFK as n, resolveRelationTargetTable as r, findFKForRelation as t };