@atscript/db 0.1.164 → 0.1.165

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { a as aggregateExpressionsNotSupported, c as invalidQuery, d as spaceClosedError, l as isConflict, n as CasMismatchError, o as aggregateFailure, r as DbError, s as bucketTimeZoneUnavailable, t as CasExhaustedError, u as isRetryableDbError } from "./db-error-hraC12B9.mjs";
-import { $ as narrowerFilterOps, B as acceptedOperatorsHint, C as ALL_VIEW_CAPABILITIES, E as createFailureCollector, F as geoIndexNotFoundMessage, G as classifyQueryPath, H as bucketSourceVerdict, I as searchIndexNotFoundMessage, J as guardAggregate, K as collectQueryPaths, L as vectorIndexNotFoundMessage, M as NativeIntegrity, N as AtscriptDbReadable, O as fkColumns, P as resolveDesignType, Q as guardQuery, R as ADAPTER_FILTER_REASON, S as ALL_ISOLATION_LEVELS, St as NoopLogger, T as createChangeRecorder, U as canFilterLeaf, V as assertGeoPoint, W as checkHavingKeys, X as guardPath, Y as guardFilter, Z as guardPaths, _ as isVersionExemptPatch, _t as isBucketableField, at as UniquSelect, b as ApplicationIntegrity, bt as normalizeComputedSelect, ct as defaultFulltextIndex, dt as splitFulltextFields, et as sortFieldNames, ft as TableMetadata, g as AtscriptDbTable, gt as aliasTargetOf, h as isViewType, it as FieldMappingStrategy, j as IntegrityStrategy, k as fkKey, lt as describeFulltext, m as isAtscriptDbView, mt as isGeoPointType, n as isColumnTypeChanged, nt as RelationalFieldMapper, ot as numericOperandProblem, p as AtscriptDbView, pt as isGeoIndexableType, q as groupSourceVerdict, rt as DocumentFieldMapper, st as INTEGER_REGEX_OP, tt as unsupportedOperatorMessage, ut as searchTermInteger, v as assertNoVersionWrites, vt as isJsonValueField, w as BaseDbAdapter, x as ALL_BUCKET_UNITS, xt as resolveCalendarBuckets, y as decomposePatch, yt as jsonValueAncestor, z as ENCRYPTED_REASON } from "./column-diff-BfNIlMwX.mjs";
-import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-DsS9UQVB.mjs";
-import { A as hasRelationOp, C as REL_FILTER_MAX_DEPTH, D as containsRelationFilter, E as andFilters, G as evaluateExpr, H as tableNameOf, K as isFieldRef, P as relationStaticFilter, S as uniqueKeyTuple, T as ResolvedRelationFilter, j as isResolvedRelationFilter, k as forEachResolvedRelation, q as translateQueryTree, w as REL_FILTER_MAX_NODES } from "./nested-writer-ClUX0DB0.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-DuDWsIdQ.mjs";
+import { $ as guardQuery, A as fkKey, B as ENCRYPTED_REASON, C as ALL_ISOLATION_LEVELS, Ct as resolveCalendarBuckets, D as createFailureCollector, E as createChangeRecorder, F as resolveDesignType, G as checkHavingKeys, H as assertGeoPoint, I as geoIndexNotFoundMessage, J as groupSourceVerdict, K as classifyQueryPath, L as searchIndexNotFoundMessage, M as IntegrityStrategy, N as NativeIntegrity, P as AtscriptDbReadable, Q as guardPaths, R as vectorIndexNotFoundMessage, S as ALL_BUCKET_UNITS, St as normalizeComputedSelect, T as BaseDbAdapter, Tt as nestDottedWith, U as bucketSourceVerdict, V as acceptedOperatorsHint, W as canFilterLeaf, X as guardFilter, Y as guardAggregate, Z as guardPath, _ as isVersionExemptPatch, at as FieldMappingStrategy, b as fkLookupTargetOf, bt as isJsonValueField, ct as INTEGER_REGEX_OP, dt as resolveFulltextIndex, et as narrowerFilterOps, ft as searchTermInteger, g as AtscriptDbTable, gt as isGeoPointType, h as isViewType, ht as isGeoIndexableType, it as DocumentFieldMapper, k as fkColumns, lt as defaultFulltextIndex, m as isAtscriptDbView, mt as TableMetadata, n as isColumnTypeChanged, nt as unsupportedOperatorMessage, ot as UniquSelect, p as AtscriptDbView, pt as splitFulltextFields, q as collectQueryPaths, rt as RelationalFieldMapper, st as numericOperandProblem, tt as sortFieldNames, ut as describeFulltext, v as assertNoVersionWrites, vt as aliasTargetOf, w as ALL_VIEW_CAPABILITIES, wt as NoopLogger, x as ApplicationIntegrity, xt as jsonValueAncestor, y as decomposePatch, yt as isBucketableField, z as ADAPTER_FILTER_REASON } from "./column-diff-9pF0d8JP.mjs";
+import { a as aggregateExpressionsNotSupported, c as constraintViolation, d as isRetryableDbError, f as spaceClosedError, l as invalidQuery, n as CasMismatchError, o as aggregateFailure, r as DbError, s as bucketTimeZoneUnavailable, t as CasExhaustedError, u as isConflict } from "./db-error-BMy4-OWq.mjs";
+import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-CmtSNIHm.mjs";
+import { D as ResolvedRelationFilter, E as REL_FILTER_MAX_NODES, I as relationStaticFilter, J as isFieldRef, M as hasRelationOp, N as isResolvedRelationFilter, O as andFilters, T as REL_FILTER_MAX_DEPTH, W as tableNameOf, Y as translateQueryTree, j as forEachResolvedRelation, k as containsRelationFilter, q as evaluateExpr, w as uniqueKeyTuple } from "./nested-writer-BraWjS8a.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, d as soleUnionMember, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-UpgPhwvH.mjs";
 import { n as isServerStampedOnUpdate, t as SERVER_STAMPED_ON_UPDATE_KEYS } from "./server-stamped-BoP56K9M.mjs";
 import { a as searchMemberKind, s as DB_ENTITY_ANNOTATIONS } from "./search-fields-BPNsxrCk.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, s as stableJson, t as deletePath } from "./object-PQ1J8jri.mjs";
@@ -533,7 +533,7 @@ var DbSpace = class {
 		return target;
 	}
 	_scanFkLookupTarget(tableName) {
-		for (const table of this._allTables) if (table.tableName === tableName) return { count: (filter) => table.count({ filter }) };
+		for (const table of this._allTables) if (table.tableName === tableName) return fkLookupTargetOf(table);
 	}
 };
 if (typeof Symbol.asyncDispose === "symbol") DbSpace.prototype[Symbol.asyncDispose] = function() {
@@ -544,12 +544,14 @@ if (typeof Symbol.asyncDispose === "symbol") DbSpace.prototype[Symbol.asyncDispo
 /**
 * Whether `value` is a compiled type a `DbSpace` accepts: an annotated type
 * whose own declaration carries `@db.table`, `@db.view` or `@db.view.for`.
-* A `@db.alias` type is not one, and neither is a plain `export type X = Table`
-* or a field typed with a table (`customer: Customer`) — since 0.1.141 the
-* entity annotations stay on the declaring interface instead of travelling
-* with every reference.
+* A `@db.alias` type is not one, and neither is a field typed with a table
+* (`customer: Customer`) — since 0.1.141 the entity annotations stay on the
+* declaring interface instead of travelling with every reference. A plain
+* `export type X = Table` is `Table` itself (@atscript/typescript 0.2), so it
+* passes.
 *
-* Filters a module namespace before a sync:
+* Filters a module namespace before a sync (a type listed under two export
+* names is synced once):
 * `syncSchema(db, Object.values(models).filter(isDbEntityType))`.
 * @since 0.1.141
 */
@@ -558,4 +560,4 @@ function isDbEntityType(value) {
 	return DB_ENTITY_ANNOTATIONS.some((name) => value.metadata.has(name));
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, NoopLogger, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, RelationalFieldMapper, ResolvedRelationFilter, SERVER_STAMPED_ON_UPDATE_KEYS, TableMetadata, UniquSelect, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createChangeRecorder, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, fkKey, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isServerStampedOnUpdate, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, stableJson, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, NoopLogger, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, RelationalFieldMapper, ResolvedRelationFilter, SERVER_STAMPED_ON_UPDATE_KEYS, TableMetadata, UniquSelect, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, constraintViolation, containsRelationFilter, createChangeRecorder, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, fkKey, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isServerStampedOnUpdate, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, nestDottedWith, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, resolveFulltextIndex, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, soleUnionMember, sortFieldNames, splitFulltextFields, stableJson, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/{nested-writer-ClUX0DB0.mjs → nested-writer-BraWjS8a.mjs}

@@ -1,4 +1,4 @@
-import { c as invalidQuery, i as DepthLimitExceededError, r as DbError } from "./db-error-hraC12B9.mjs";
+import { i as DepthLimitExceededError, l as invalidQuery, r as DbError } from "./db-error-BMy4-OWq.mjs";
 import { a as isPlainObject, r as getPath } from "./object-PQ1J8jri.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
 import { isRelationOp } from "@uniqu/core";
@@ -740,10 +740,18 @@ function keyTupleString(source, fields, plain = false) {
 * 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
-	}));
+	return errors.map((err) => {
+		const out = {
+			...err,
+			path: err.path ? `${prefix}.${err.path}` : prefix
+		};
+		const params = err.params;
+		if (params && Array.isArray(params.fields)) out.params = {
+			...params,
+			fields: params.fields.map((f) => `${prefix}.${String(f)}`)
+		};
+		return out;
+	});
 }
 /**
 * Wraps an async nested operation and prefixes error paths with the nav field context.
@@ -758,41 +766,184 @@ async function wrapNestedError(navField, fn) {
 	}
 }
 /**
-* 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.
+* Rethrows a write's constraint error normalized against the table's
+* metadata (see {@link normalizeWriteError}); anything else as is.
 */
-async function enrichFkViolation(meta, fn) {
+async function normalizeWriteErrors(meta, tableName, fn) {
 	try {
 		return await fn();
 	} catch (error) {
-		if (error instanceof 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 DbError("FK_VIOLATION", errors.length > 0 ? errors : error.errors);
-		}
-		throw error;
+		throw normalizeWriteError(meta, tableName, error);
 	}
 }
 /**
-* Wraps a delete operation: catches native `FK_VIOLATION` errors (e.g. SQLite
-* RESTRICT) and re-throws as `CONFLICT` (409) with a descriptive message.
+* The table layer's constraint-error normaliser (since 0.1.165). An adapter
+* reports a unique / foreign-key violation with whatever the engine told it
+* ({@link constraintViolation}: columns, constraint / index name); this
+* resolves that against the table's indexes and foreign keys into ONE entry
+* per logical field of the violated constraint, each with a `code`
+* (`UNIQUE` / `FK_MISSING` / `FK_RESTRICT`), `params` and the engine's raw
+* text in `details`.
+*
+* An `FK_VIOLATION` with no hint and no path (an adapter that can't tell
+* which key failed) lists every foreign-key field, `params.ambiguous: true`.
+* Errors already normalized, or of other codes, pass through unchanged.
+*/
+function normalizeWriteError(meta, tableName, error) {
+	if (!(error instanceof DbError)) return error;
+	const raw = rawText(error);
+	if (error.code === "FK_VIOLATION" && error.hint?.referencedBy) return new DbError("FK_VIOLATION", [fkRestrictEntry(tableName, {
+		op: "update",
+		referencedBy: error.hint.referencedBy,
+		details: raw
+	})]);
+	if (error.hint && error.code === "CONFLICT") return new DbError("CONFLICT", uniqueEntries(meta, error.hint, raw));
+	if (error.code === "FK_VIOLATION" && (error.hint || error.errors.every((e) => !e.path))) return new DbError("FK_VIOLATION", fkEntries(meta, error.hint, raw));
+	return error;
+}
+/**
+* Wraps a delete: a native foreign-key refusal (`FK_VIOLATION`, e.g. a
+* RESTRICT) is rethrown as `CONFLICT` (409) with one `FK_RESTRICT` entry —
+* `params { table, referencedBy? }`, the engine text in `details`.
 */
 async function remapDeleteFkViolation(tableName, fn) {
 	try {
 		return await fn();
 	} catch (error) {
-		if (error instanceof DbError && error.code === "FK_VIOLATION") throw new DbError("CONFLICT", [{
-			path: tableName,
-			message: `Cannot delete from "${tableName}": referenced by child records (RESTRICT)`
-		}]);
+		if (error instanceof DbError && error.code === "FK_VIOLATION") throw new DbError("CONFLICT", [fkRestrictEntry(tableName, {
+			referencedBy: error.hint?.referencedBy,
+			details: rawText(error)
+		})]);
 		throw error;
 	}
 }
+/** The engine text an adapter error carries (its first entry's `details`, else its message). */
+function rawText(error) {
+	return error.errors[0]?.details ?? error.errors[0]?.message ?? error.message;
+}
+/** Whether `names` is exactly the column `set` (in any order). */
+function sameColumns(names, set) {
+	return names.length === set.size && names.every((n) => set.has(n));
+}
+/** A physical column's logical path (the column itself when unmapped). */
+function logicalPath(meta, column) {
+	return meta.physicalToPath.get(column) ?? column;
+}
+/**
+* The `FK_RESTRICT` entry of a write blocked by referencing rows — a delete
+* (default) or an update of a referenced key. One source for the native
+* refusal and the application-level RESTRICT check.
+* @internal
+*/
+function fkRestrictEntry(tableName, opts = {}) {
+	const { referencedBy, count, details, fields } = opts;
+	return {
+		path: tableName,
+		message: `Cannot ${opts.op === "update" ? "update" : "delete from"} "${tableName}": referenced by ${referencedBy === void 0 ? "child records" : `${count === void 0 ? "records" : `${count} record(s)`} in "${referencedBy}"${fields ? ` (${fields.join(", ")})` : ""}`} (RESTRICT)`,
+		code: "FK_RESTRICT",
+		params: {
+			table: tableName,
+			...referencedBy === void 0 ? {} : { referencedBy },
+			...fields ? { fields: [...fields] } : {}
+		},
+		...details === void 0 ? {} : { details }
+	};
+}
+/**
+* The `FK_MISSING` entries of one foreign key: one per field, the same
+* message on each. @internal
+*/
+function fkMissingEntries(fields, target, details, ambiguous) {
+	const message = fields.length === 1 ? `References a non-existent record in "${target}"` : `"${fields.join("\", \"")}" reference a non-existent record in "${target}"`;
+	return fields.map((path) => ({
+		path,
+		message,
+		code: "FK_MISSING",
+		params: {
+			fields: [...fields],
+			target,
+			...ambiguous ? { ambiguous: true } : {}
+		},
+		...details === void 0 ? {} : { details }
+	}));
+}
+function uniqueEntries(meta, hint, raw) {
+	const resolved = resolveUnique(meta, hint);
+	const fields = resolved?.fields ?? [];
+	if (fields.length === 0) return [{
+		path: "",
+		message: "Value must be unique",
+		code: "UNIQUE",
+		params: hint.name ? { index: hint.name } : {},
+		details: raw
+	}];
+	const message = fields.length === 1 ? "Value must be unique" : `The combination of "${fields.join("\", \"")}" must be unique`;
+	const params = {
+		...resolved?.index ? { index: resolved.index } : {},
+		fields: [...fields]
+	};
+	return fields.map((path) => ({
+		path,
+		message,
+		code: "UNIQUE",
+		params,
+		details: raw
+	}));
+}
+/** The unique key a hint names — by name, then by its exact column set. */
+function resolveUnique(meta, hint) {
+	const logical = (column) => logicalPath(meta, column);
+	if (hint.primaryKey) return {
+		index: "primaryKey",
+		fields: [...meta.primaryKeys]
+	};
+	const uniques = [...meta.indexes.values()].filter((i) => i.type === "unique");
+	if (hint.name) {
+		const named = uniques.find((i) => i.key === hint.name || i.name === hint.name);
+		if (named) return {
+			index: named.name,
+			fields: named.fields.map((f) => logical(f.name))
+		};
+	}
+	if (!hint.columns?.length) return void 0;
+	const columns = new Set(hint.columns);
+	const sameSet = (names) => sameColumns(names, columns);
+	const byColumns = uniques.find((i) => sameSet(i.fields.map((f) => f.name)));
+	if (byColumns) return {
+		index: byColumns.name,
+		fields: byColumns.fields.map((f) => logical(f.name))
+	};
+	if (meta.primaryKeys.length > 0 && sameSet(meta.primaryKeys.map((k) => meta.physicalPath(k)))) return {
+		index: "primaryKey",
+		fields: [...meta.primaryKeys]
+	};
+	return { fields: hint.columns.map(logical) };
+}
+function fkEntries(meta, hint, raw) {
+	const fks = [...meta.foreignKeys.values()];
+	const physical = (fk) => fk.physicalFields ?? fk.fields;
+	const columns = hint?.columns;
+	if (columns?.length) {
+		const set = new Set(columns);
+		const fk = fks.find((f) => sameColumns(physical(f), set)) ?? fks.find((f) => physical(f).includes(columns[0]));
+		if (fk) return fkMissingEntries(fk.fields, fk.targetTable, raw);
+		const fields = columns.map((c) => logicalPath(meta, c));
+		return fields.map((path) => ({
+			path,
+			message: "References a non-existent record",
+			code: "FK_MISSING",
+			params: { fields },
+			details: raw
+		}));
+	}
+	const all = fks.flatMap((fk) => fkMissingEntries(fk.fields, fk.targetTable, raw, fks.length > 1));
+	return all.length > 0 ? all : [{
+		path: "",
+		message: "References a non-existent record",
+		code: "FK_MISSING",
+		details: raw
+	}];
+}
 //#endregion
 //#region src/rel/nested-writer.ts
 /** A TO relation's target table and the local → target foreign key. */
@@ -1581,4 +1732,4 @@ async function viaReplace(via, targets, parentPK, maxDepth, depth) {
 	await viaLinkTargets(via, targets, parentPK, maxDepth, depth);
 }
 //#endregion
-export { hasRelationOp as A, resolveRelationTargetTable as B, REL_FILTER_MAX_DEPTH as C, containsRelationFilter as D, andFilters as E, resolveRelationFilterTree as F, evaluateExpr as G, tableNameOf as H, compositeKey as I, viewExprNullable as J, isFieldRef as K, findFKEntryForRelation as L, noteRelationFilter as M, relGuardState as N, createRelationFilterHost as O, relationStaticFilter as P, findFKForRelation as R, uniqueKeyTuple as S, ResolvedRelationFilter as T, computeOf as U, slicePerGroup as V, computedOperands as W, walkViewExpr as Y, remapDeleteFkViolation as _, batchPatchNestedFrom as a, rowMatchesKey as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, enrichFkViolation as g, validateBatch as h, batchInsertNestedVia as i, isResolvedRelationFilter as j, forEachResolvedRelation as k, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, translateQueryTree as q, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, findRowsByKeys as v, REL_FILTER_MAX_NODES as w, sameKey as x, pkTupleKey as y, findRemoteFK as z };
+export { createRelationFilterHost as A, findFKForRelation as B, sameKey as C, ResolvedRelationFilter as D, REL_FILTER_MAX_NODES as E, relGuardState as F, computeOf as G, resolveRelationTargetTable as H, relationStaticFilter as I, isFieldRef as J, computedOperands as K, resolveRelationFilterTree as L, hasRelationOp as M, isResolvedRelationFilter as N, andFilters as O, noteRelationFilter as P, compositeKey as R, rowMatchesKey as S, REL_FILTER_MAX_DEPTH as T, slicePerGroup as U, findRemoteFK as V, tableNameOf as W, viewExprNullable as X, translateQueryTree as Y, walkViewExpr as Z, fkRestrictEntry as _, batchPatchNestedFrom as a, findRowsByKeys as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, fkMissingEntries as g, validateBatch as h, batchInsertNestedVia as i, forEachResolvedRelation as j, containsRelationFilter as k, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, evaluateExpr as q, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, normalizeWriteErrors as v, uniqueKeyTuple as w, pkTupleKey as x, remapDeleteFkViolation as y, findFKEntryForRelation as z };

package/dist/{nested-writer-yCy6wGuN.cjs → nested-writer-DOvdbYG-.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-DmF1_xrz.cjs");
+const require_db_error = require("./db-error-G3sgvL87.cjs");
 const require_object = require("./object-GjsuPNqo.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
@@ -740,10 +740,18 @@ function keyTupleString(source, fields, plain = false) {
 * 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
-	}));
+	return errors.map((err) => {
+		const out = {
+			...err,
+			path: err.path ? `${prefix}.${err.path}` : prefix
+		};
+		const params = err.params;
+		if (params && Array.isArray(params.fields)) out.params = {
+			...params,
+			fields: params.fields.map((f) => `${prefix}.${String(f)}`)
+		};
+		return out;
+	});
 }
 /**
 * Wraps an async nested operation and prefixes error paths with the nav field context.
@@ -758,41 +766,184 @@ async function wrapNestedError(navField, fn) {
 	}
 }
 /**
-* 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.
+* Rethrows a write's constraint error normalized against the table's
+* metadata (see {@link normalizeWriteError}); anything else as is.
 */
-async function enrichFkViolation(meta, fn) {
+async function normalizeWriteErrors(meta, tableName, 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;
+		throw normalizeWriteError(meta, tableName, error);
 	}
 }
 /**
-* Wraps a delete operation: catches native `FK_VIOLATION` errors (e.g. SQLite
-* RESTRICT) and re-throws as `CONFLICT` (409) with a descriptive message.
+* The table layer's constraint-error normaliser (since 0.1.165). An adapter
+* reports a unique / foreign-key violation with whatever the engine told it
+* ({@link constraintViolation}: columns, constraint / index name); this
+* resolves that against the table's indexes and foreign keys into ONE entry
+* per logical field of the violated constraint, each with a `code`
+* (`UNIQUE` / `FK_MISSING` / `FK_RESTRICT`), `params` and the engine's raw
+* text in `details`.
+*
+* An `FK_VIOLATION` with no hint and no path (an adapter that can't tell
+* which key failed) lists every foreign-key field, `params.ambiguous: true`.
+* Errors already normalized, or of other codes, pass through unchanged.
+*/
+function normalizeWriteError(meta, tableName, error) {
+	if (!(error instanceof require_db_error.DbError)) return error;
+	const raw = rawText(error);
+	if (error.code === "FK_VIOLATION" && error.hint?.referencedBy) return new require_db_error.DbError("FK_VIOLATION", [fkRestrictEntry(tableName, {
+		op: "update",
+		referencedBy: error.hint.referencedBy,
+		details: raw
+	})]);
+	if (error.hint && error.code === "CONFLICT") return new require_db_error.DbError("CONFLICT", uniqueEntries(meta, error.hint, raw));
+	if (error.code === "FK_VIOLATION" && (error.hint || error.errors.every((e) => !e.path))) return new require_db_error.DbError("FK_VIOLATION", fkEntries(meta, error.hint, raw));
+	return error;
+}
+/**
+* Wraps a delete: a native foreign-key refusal (`FK_VIOLATION`, e.g. a
+* RESTRICT) is rethrown as `CONFLICT` (409) with one `FK_RESTRICT` entry —
+* `params { table, referencedBy? }`, the engine text in `details`.
 */
 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)`
-		}]);
+		if (error instanceof require_db_error.DbError && error.code === "FK_VIOLATION") throw new require_db_error.DbError("CONFLICT", [fkRestrictEntry(tableName, {
+			referencedBy: error.hint?.referencedBy,
+			details: rawText(error)
+		})]);
 		throw error;
 	}
 }
+/** The engine text an adapter error carries (its first entry's `details`, else its message). */
+function rawText(error) {
+	return error.errors[0]?.details ?? error.errors[0]?.message ?? error.message;
+}
+/** Whether `names` is exactly the column `set` (in any order). */
+function sameColumns(names, set) {
+	return names.length === set.size && names.every((n) => set.has(n));
+}
+/** A physical column's logical path (the column itself when unmapped). */
+function logicalPath(meta, column) {
+	return meta.physicalToPath.get(column) ?? column;
+}
+/**
+* The `FK_RESTRICT` entry of a write blocked by referencing rows — a delete
+* (default) or an update of a referenced key. One source for the native
+* refusal and the application-level RESTRICT check.
+* @internal
+*/
+function fkRestrictEntry(tableName, opts = {}) {
+	const { referencedBy, count, details, fields } = opts;
+	return {
+		path: tableName,
+		message: `Cannot ${opts.op === "update" ? "update" : "delete from"} "${tableName}": referenced by ${referencedBy === void 0 ? "child records" : `${count === void 0 ? "records" : `${count} record(s)`} in "${referencedBy}"${fields ? ` (${fields.join(", ")})` : ""}`} (RESTRICT)`,
+		code: "FK_RESTRICT",
+		params: {
+			table: tableName,
+			...referencedBy === void 0 ? {} : { referencedBy },
+			...fields ? { fields: [...fields] } : {}
+		},
+		...details === void 0 ? {} : { details }
+	};
+}
+/**
+* The `FK_MISSING` entries of one foreign key: one per field, the same
+* message on each. @internal
+*/
+function fkMissingEntries(fields, target, details, ambiguous) {
+	const message = fields.length === 1 ? `References a non-existent record in "${target}"` : `"${fields.join("\", \"")}" reference a non-existent record in "${target}"`;
+	return fields.map((path) => ({
+		path,
+		message,
+		code: "FK_MISSING",
+		params: {
+			fields: [...fields],
+			target,
+			...ambiguous ? { ambiguous: true } : {}
+		},
+		...details === void 0 ? {} : { details }
+	}));
+}
+function uniqueEntries(meta, hint, raw) {
+	const resolved = resolveUnique(meta, hint);
+	const fields = resolved?.fields ?? [];
+	if (fields.length === 0) return [{
+		path: "",
+		message: "Value must be unique",
+		code: "UNIQUE",
+		params: hint.name ? { index: hint.name } : {},
+		details: raw
+	}];
+	const message = fields.length === 1 ? "Value must be unique" : `The combination of "${fields.join("\", \"")}" must be unique`;
+	const params = {
+		...resolved?.index ? { index: resolved.index } : {},
+		fields: [...fields]
+	};
+	return fields.map((path) => ({
+		path,
+		message,
+		code: "UNIQUE",
+		params,
+		details: raw
+	}));
+}
+/** The unique key a hint names — by name, then by its exact column set. */
+function resolveUnique(meta, hint) {
+	const logical = (column) => logicalPath(meta, column);
+	if (hint.primaryKey) return {
+		index: "primaryKey",
+		fields: [...meta.primaryKeys]
+	};
+	const uniques = [...meta.indexes.values()].filter((i) => i.type === "unique");
+	if (hint.name) {
+		const named = uniques.find((i) => i.key === hint.name || i.name === hint.name);
+		if (named) return {
+			index: named.name,
+			fields: named.fields.map((f) => logical(f.name))
+		};
+	}
+	if (!hint.columns?.length) return void 0;
+	const columns = new Set(hint.columns);
+	const sameSet = (names) => sameColumns(names, columns);
+	const byColumns = uniques.find((i) => sameSet(i.fields.map((f) => f.name)));
+	if (byColumns) return {
+		index: byColumns.name,
+		fields: byColumns.fields.map((f) => logical(f.name))
+	};
+	if (meta.primaryKeys.length > 0 && sameSet(meta.primaryKeys.map((k) => meta.physicalPath(k)))) return {
+		index: "primaryKey",
+		fields: [...meta.primaryKeys]
+	};
+	return { fields: hint.columns.map(logical) };
+}
+function fkEntries(meta, hint, raw) {
+	const fks = [...meta.foreignKeys.values()];
+	const physical = (fk) => fk.physicalFields ?? fk.fields;
+	const columns = hint?.columns;
+	if (columns?.length) {
+		const set = new Set(columns);
+		const fk = fks.find((f) => sameColumns(physical(f), set)) ?? fks.find((f) => physical(f).includes(columns[0]));
+		if (fk) return fkMissingEntries(fk.fields, fk.targetTable, raw);
+		const fields = columns.map((c) => logicalPath(meta, c));
+		return fields.map((path) => ({
+			path,
+			message: "References a non-existent record",
+			code: "FK_MISSING",
+			params: { fields },
+			details: raw
+		}));
+	}
+	const all = fks.flatMap((fk) => fkMissingEntries(fk.fields, fk.targetTable, raw, fks.length > 1));
+	return all.length > 0 ? all : [{
+		path: "",
+		message: "References a non-existent record",
+		code: "FK_MISSING",
+		details: raw
+	}];
+}
 //#endregion
 //#region src/rel/nested-writer.ts
 /** A TO relation's target table and the local → target foreign key. */
@@ -1701,12 +1852,6 @@ Object.defineProperty(exports, "createRelationFilterHost", {
 		return createRelationFilterHost;
 	}
 });
-Object.defineProperty(exports, "enrichFkViolation", {
-	enumerable: true,
-	get: function() {
-		return enrichFkViolation;
-	}
-});
 Object.defineProperty(exports, "evaluateExpr", {
 	enumerable: true,
 	get: function() {
@@ -1737,6 +1882,18 @@ Object.defineProperty(exports, "findRowsByKeys", {
 		return findRowsByKeys;
 	}
 });
+Object.defineProperty(exports, "fkMissingEntries", {
+	enumerable: true,
+	get: function() {
+		return fkMissingEntries;
+	}
+});
+Object.defineProperty(exports, "fkRestrictEntry", {
+	enumerable: true,
+	get: function() {
+		return fkRestrictEntry;
+	}
+});
 Object.defineProperty(exports, "forEachResolvedRelation", {
 	enumerable: true,
 	get: function() {
@@ -1761,6 +1918,12 @@ Object.defineProperty(exports, "isResolvedRelationFilter", {
 		return isResolvedRelationFilter;
 	}
 });
+Object.defineProperty(exports, "normalizeWriteErrors", {
+	enumerable: true,
+	get: function() {
+		return normalizeWriteErrors;
+	}
+});
 Object.defineProperty(exports, "noteRelationFilter", {
 	enumerable: true,
 	get: function() {

package/dist/ops.cjs

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

package/dist/ops.mjs

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