@happyvertical/smrt-core 0.40.69 → 0.41.0

package/dist/db-errors.js

@@ -0,0 +1,382 @@
+//#region src/db-errors.ts
+/** Maximum chain depth walked, guarding against pathological nesting. */
+var MAX_CHAIN_DEPTH = 12;
+/** `formatDbError` renders driver codes as `code=<value>` inside its string. */
+var FORMATTED_CODE_PATTERN = /(?:^|[\s,;([{])code=([A-Za-z0-9_]+)/g;
+/**
+* PostgreSQL SQLSTATE codes whose failure is fully determined by the statement
+* and its data. Retrying re-executes the same deterministic rejection.
+*/
+var DETERMINISTIC_SQLSTATES = /* @__PURE__ */ new Map([
+	["23000", "check_violation"],
+	["23001", "foreign_key_violation"],
+	["23502", "not_null_violation"],
+	["23503", "foreign_key_violation"],
+	["23505", "unique_violation"],
+	["23514", "check_violation"],
+	["23P01", "exclusion_violation"],
+	["22001", "invalid_input"],
+	["22003", "invalid_input"],
+	["22007", "invalid_input"],
+	["22008", "invalid_input"],
+	["22023", "invalid_input"],
+	["22P02", "invalid_input"],
+	["22P03", "invalid_input"],
+	["25P02", "aborted_transaction"],
+	["42501", "insufficient_privilege"],
+	["42601", "syntax_error"],
+	["42703", "undefined_object"],
+	["42804", "invalid_input"],
+	["42883", "undefined_object"],
+	["42P01", "undefined_object"],
+	["42P07", "undefined_object"],
+	["42P10", "undefined_object"],
+	["3D000", "undefined_object"],
+	["3F000", "undefined_object"]
+]);
+/**
+* PostgreSQL SQLSTATE codes describing a contention or availability failure.
+* The same statement may well succeed on a later attempt.
+*/
+var TRANSIENT_SQLSTATES = /* @__PURE__ */ new Set([
+	"25P03",
+	"40001",
+	"40003",
+	"40P01",
+	"53200",
+	"53300",
+	"55P03",
+	"57014",
+	"57P01",
+	"57P02",
+	"57P03",
+	"58030",
+	"08000",
+	"08001",
+	"08003",
+	"08004",
+	"08006",
+	"08007",
+	"08P01"
+]);
+/**
+* SQLite extended result codes. `better-sqlite3`/`node:sqlite` frequently
+* report the bare `SQLITE_CONSTRAINT` parent code, so the constraint sub-kind
+* is resolved from the message instead (see {@link classifyDialectMessage}).
+*/
+var DETERMINISTIC_SQLITE_CODES = /* @__PURE__ */ new Map([
+	["SQLITE_CONSTRAINT_UNIQUE", "unique_violation"],
+	["SQLITE_CONSTRAINT_PRIMARYKEY", "unique_violation"],
+	["SQLITE_CONSTRAINT_ROWID", "unique_violation"],
+	["SQLITE_CONSTRAINT_NOTNULL", "not_null_violation"],
+	["SQLITE_CONSTRAINT_FOREIGNKEY", "foreign_key_violation"],
+	["SQLITE_CONSTRAINT_CHECK", "check_violation"],
+	["SQLITE_CONSTRAINT_TRIGGER", "check_violation"],
+	["SQLITE_MISMATCH", "invalid_input"],
+	["SQLITE_RANGE", "invalid_input"],
+	["SQLITE_TOOBIG", "invalid_input"],
+	["SQLITE_READONLY", "insufficient_privilege"],
+	["SQLITE_AUTH", "insufficient_privilege"]
+]);
+/** SQLite result codes that clear once contention or a lock resolves. */
+var TRANSIENT_SQLITE_CODES = /* @__PURE__ */ new Set([
+	"SQLITE_BUSY",
+	"SQLITE_BUSY_SNAPSHOT",
+	"SQLITE_BUSY_TIMEOUT",
+	"SQLITE_LOCKED",
+	"SQLITE_LOCKED_SHAREDCACHE",
+	"SQLITE_PROTOCOL"
+]);
+/** Node/libuv socket errno values raised when a pooled connection drops. */
+var TRANSIENT_NETWORK_CODES = /* @__PURE__ */ new Set([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ECONNABORTED",
+	"EPIPE",
+	"ETIMEDOUT",
+	"ENETUNREACH",
+	"ENETRESET",
+	"EHOSTUNREACH",
+	"EAI_AGAIN",
+	"ENOTFOUND"
+]);
+/**
+* Dialect wording, in precedence order. Only DuckDB has no machine-readable
+* code, but SQLite's bare `SQLITE_CONSTRAINT` and PostgreSQL errors that have
+* lost their code through string formatting are recovered here too.
+*
+* NOT NULL is tested before UNIQUE because DuckDB phrases both with the same
+* `Constraint Error … violates` shape, and foreign-key/check wording must not
+* be mistaken for a unique violation (#1578).
+*/
+var DIALECT_MESSAGE_RULES = [
+	{
+		kind: "aborted_transaction",
+		pattern: /current transaction is aborted/i
+	},
+	{
+		kind: "not_null_violation",
+		pattern: /NOT NULL constraint failed|null value in column .* violates not-null/i
+	},
+	{
+		kind: "foreign_key_violation",
+		pattern: /violates foreign key constraint|FOREIGN KEY constraint failed/i
+	},
+	{
+		kind: "check_violation",
+		pattern: /violates check constraint|CHECK constraint failed/i
+	},
+	{
+		kind: "unique_violation",
+		pattern: /UNIQUE constraint failed|violates unique constraint|violates primary key constraint|duplicate key value violates/i
+	},
+	{
+		kind: "invalid_input",
+		pattern: /invalid input syntax for type|value too long for type/i
+	},
+	{
+		kind: "undefined_object",
+		pattern: /no such table|no such column|(?:relation|column|table|function) "[^"]*" does not exist/i
+	},
+	{
+		kind: "transient",
+		pattern: /database is locked|database table is locked|connection terminated|server closed the connection|too many clients|deadlock detected|could not serialize access/i
+	}
+];
+/** SMRT-level codes that already express a driver classification. */
+var SMRT_CODE_KINDS = /* @__PURE__ */ new Map([["VALIDATION_UNIQUE_CONSTRAINT", "unique_violation"], ["DB_CONSTRAINT_VIOLATION", "check_violation"]]);
+/**
+* Reporting precedence among deterministic kinds, most specific first.
+*
+* `aborted_transaction` ranks last on purpose: PostgreSQL reports `25P02` for
+* every statement issued after the transaction already failed, so a chain
+* carrying both it and the constraint that caused the abort must name the
+* constraint. Every kind here is non-retryable, so ranking changes only what
+* is reported, never whether the operation is retried.
+*/
+var DETERMINISTIC_KIND_RANK = /* @__PURE__ */ new Map([
+	["unique_violation", 0],
+	["not_null_violation", 1],
+	["foreign_key_violation", 2],
+	["check_violation", 3],
+	["exclusion_violation", 4],
+	["invalid_input", 5],
+	["undefined_object", 6],
+	["insufficient_privilege", 7],
+	["syntax_error", 8],
+	["aborted_transaction", 9]
+]);
+function rankKind(kind) {
+	return DETERMINISTIC_KIND_RANK.get(kind) ?? Number.MAX_SAFE_INTEGER;
+}
+function pushUnique(collection, value) {
+	if (typeof value !== "string") return;
+	const entry = value.trim();
+	if (entry && !collection.includes(entry)) collection.push(entry);
+}
+function pushCode(signals, value) {
+	pushUnique(signals.codes, value);
+}
+function pushMessage(signals, value) {
+	if (typeof value !== "string") return;
+	const message = value.trim();
+	if (!message || signals.messages.includes(message)) return;
+	signals.messages.push(message);
+	FORMATTED_CODE_PATTERN.lastIndex = 0;
+	let match = FORMATTED_CODE_PATTERN.exec(message);
+	while (match) {
+		pushCode(signals, match[1]);
+		match = FORMATTED_CODE_PATTERN.exec(message);
+	}
+}
+/**
+* Walks an error's causal chain, collecting every driver code and message.
+*
+* Visits `cause`, `context.originalError`, `originalError`,
+* `details.causeMessage`/`details.causeMessages` and `AggregateError.errors`,
+* because the SDK, core and consumer wrappers each nest the driver error
+* differently. Cycles and depth are bounded.
+*/
+function collectChainSignals(error) {
+	const signals = {
+		codes: [],
+		messages: [],
+		columns: [],
+		constraints: []
+	};
+	const seen = /* @__PURE__ */ new Set();
+	const pending = [{
+		value: error,
+		depth: 0
+	}];
+	while (pending.length > 0) {
+		const entry = pending.pop();
+		if (!entry) break;
+		const { value, depth } = entry;
+		if (value === null || value === void 0 || depth > MAX_CHAIN_DEPTH) continue;
+		if (typeof value === "string") {
+			pushMessage(signals, value);
+			continue;
+		}
+		if (typeof value !== "object" || seen.has(value)) continue;
+		seen.add(value);
+		const node = value;
+		pushCode(signals, node.code);
+		pushCode(signals, node.sqlState);
+		pushCode(signals, node.sqlstate);
+		pushMessage(signals, node.message);
+		pushMessage(signals, node.detail);
+		pushMessage(signals, node.hint);
+		pushUnique(signals.columns, node.column);
+		pushUnique(signals.constraints, node.constraint);
+		const details = node.details;
+		if (details && typeof details === "object") {
+			pushMessage(signals, details.causeMessage);
+			if (Array.isArray(details.causeMessages)) for (const causeMessage of details.causeMessages) pushMessage(signals, causeMessage);
+		}
+		const context = node.context;
+		const next = [
+			node.cause,
+			node.originalError,
+			context && typeof context === "object" ? context.originalError : void 0
+		];
+		for (const child of next) if (child !== null && child !== void 0) pending.push({
+			value: child,
+			depth: depth + 1
+		});
+		if (Array.isArray(node.errors)) for (const child of node.errors) pending.push({
+			value: child,
+			depth: depth + 1
+		});
+	}
+	return signals;
+}
+/**
+* Classifies a raw dialect message. Exposed so
+* `SmrtObject.classifyConstraintError()` and this module share one set of
+* regexes rather than drifting apart.
+*/
+function classifyDialectMessage(message) {
+	if (!message) return "unknown";
+	for (const rule of DIALECT_MESSAGE_RULES) if (rule.pattern.test(message)) return rule.kind;
+	return "unknown";
+}
+function isSqlState(code) {
+	return /^[0-9A-Z]{5}$/.test(code);
+}
+/**
+* Classifies a database failure by walking its causal chain.
+*
+* Codes win over wording: a PostgreSQL SQLSTATE or SQLite result code is
+* authoritative, and dialect message matching only runs when no code in the
+* chain was recognized (DuckDB, or an error already flattened to a string).
+*
+* Constraint violations are reported ahead of `aborted_transaction` so a chain
+* carrying both surfaces the root cause rather than the downstream symptom;
+* both are deterministic, so retry behavior is identical either way.
+*
+* @param error - Any thrown value. Non-database errors classify as `'unknown'`.
+* @returns The structured classification; never throws.
+*/
+function classifyDatabaseError(error) {
+	const signals = collectChainSignals(error);
+	const sqlstate = signals.codes.find((code) => isSqlState(code) && (DETERMINISTIC_SQLSTATES.has(code) || TRANSIENT_SQLSTATES.has(code)));
+	const base = {
+		driverCodes: signals.codes,
+		driverMessages: signals.messages,
+		...sqlstate ? { sqlstate } : {},
+		...signals.columns[0] ? { column: signals.columns[0] } : {},
+		...signals.constraints[0] ? { constraint: signals.constraints[0] } : {}
+	};
+	const deterministicCandidates = [];
+	for (const code of signals.codes) {
+		const kind = DETERMINISTIC_SQLSTATES.get(code) ?? DETERMINISTIC_SQLITE_CODES.get(code) ?? SMRT_CODE_KINDS.get(code) ?? (code === "SQLITE_CONSTRAINT" ? signals.messages.map(classifyDialectMessage).find((candidate) => DETERMINISTIC_KIND_RANK.has(candidate)) ?? "check_violation" : void 0);
+		if (kind) deterministicCandidates.push({
+			code,
+			kind
+		});
+	}
+	if (deterministicCandidates.length > 0) {
+		const best = deterministicCandidates.reduce((winner, candidate) => rankKind(candidate.kind) < rankKind(winner.kind) ? candidate : winner);
+		return {
+			...base,
+			kind: best.kind,
+			deterministic: true,
+			retryable: false,
+			driverCode: best.code
+		};
+	}
+	for (const code of signals.codes) {
+		if (TRANSIENT_SQLSTATES.has(code) || TRANSIENT_SQLITE_CODES.has(code)) return {
+			...base,
+			kind: "transient",
+			deterministic: false,
+			retryable: true,
+			driverCode: code
+		};
+		if (TRANSIENT_NETWORK_CODES.has(code)) return {
+			...base,
+			kind: "transient",
+			deterministic: false,
+			retryable: true,
+			driverCode: code
+		};
+	}
+	const messageKinds = signals.messages.map(classifyDialectMessage).filter((kind) => kind !== "unknown");
+	const deterministicFromMessage = messageKinds.filter((kind) => DETERMINISTIC_KIND_RANK.has(kind)).sort((left, right) => rankKind(left) - rankKind(right))[0];
+	if (deterministicFromMessage) return {
+		...base,
+		kind: deterministicFromMessage,
+		deterministic: true,
+		retryable: false
+	};
+	if (messageKinds.includes("transient")) return {
+		...base,
+		kind: "transient",
+		deterministic: false,
+		retryable: true
+	};
+	return {
+		...base,
+		kind: "unknown",
+		deterministic: false,
+		retryable: false
+	};
+}
+/**
+* True when retrying the statement cannot change the outcome.
+*
+* Used by {@link ErrorUtils.withRetry} to fail fast instead of burning the
+* full 500 + 1000 + 2000 ms backoff on a constraint violation.
+*/
+function isDeterministicDatabaseError(error) {
+	return classifyDatabaseError(error).deterministic;
+}
+/** True when the failure is contention or availability and may clear. */
+function isTransientDatabaseError(error) {
+	return classifyDatabaseError(error).retryable;
+}
+/** True when a unique or primary-key constraint was violated. */
+function isUniqueViolationError(error) {
+	return classifyDatabaseError(error).kind === "unique_violation";
+}
+/** True when a NOT NULL constraint was violated. */
+function isNotNullViolationError(error) {
+	return classifyDatabaseError(error).kind === "not_null_violation";
+}
+/**
+* True when the failure came from running inside an already-aborted
+* PostgreSQL transaction (SQLSTATE `25P02`).
+*
+* Detected independently of {@link DatabaseErrorKind} so a chain that also
+* carries the root constraint code still answers `true` here.
+*/
+function isAbortedTransactionError(error) {
+	const signals = collectChainSignals(error);
+	if (signals.codes.includes("25P02")) return true;
+	return signals.messages.some((message) => /current transaction is aborted/i.test(message));
+}
+//#endregion
+export { classifyDatabaseError, classifyDialectMessage, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isTransientDatabaseError, isUniqueViolationError };
+
+//# sourceMappingURL=db-errors.js.map

package/dist/db-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-errors.js","names":[],"sources":["../src/db-errors.ts"],"sourcesContent":["/**\n * Driver-error classification for the persistence path (#2366).\n *\n * `@happyvertical/sql` does not normalize driver errors: every adapter catches\n * the driver failure and rethrows\n * `DatabaseError('Failed to upsert record into table', { …, originalError })`,\n * where `originalError` is the **string** produced by the SDK's `formatDbError`\n * (`\"<driver message>, code=<driver code>, detail=…, hint=…\"`). The typed\n * message therefore carries none of the constraint wording, which is why\n * matching on `error.message` alone silently stopped recognizing constraint\n * violations and let {@link ErrorUtils.withRetry} retry them.\n *\n * This module walks the whole causal chain — `cause`, `context.originalError`\n * (Error *or* formatted string), `originalError`, `details.causeMessages`, and\n * `AggregateError.errors` — collecting every driver code and message it finds,\n * then classifies on the codes first (PostgreSQL SQLSTATE, SQLite result\n * codes, Node network errno) and only falls back to dialect wording for DuckDB,\n * which reports no machine-readable code.\n *\n * The classification separates two independent questions:\n * - `deterministic` — a retry cannot change the outcome (constraint violation,\n *   bad input syntax, aborted transaction, missing table). Fail fast.\n * - `retryable` — a retry plausibly can succeed (serialization failure,\n *   deadlock, lock timeout, connection loss, `SQLITE_BUSY`).\n *\n * They are not complements: `kind: 'unknown'` means \"no opinion\", leaving the\n * caller's own default policy in charge.\n *\n * @module\n */\n\n/** Coarse classification of a database driver failure. */\nexport type DatabaseErrorKind =\n  | 'unique_violation'\n  | 'not_null_violation'\n  | 'foreign_key_violation'\n  | 'check_violation'\n  | 'exclusion_violation'\n  | 'invalid_input'\n  | 'aborted_transaction'\n  | 'undefined_object'\n  | 'insufficient_privilege'\n  | 'syntax_error'\n  | 'transient'\n  | 'unknown';\n\n/** Structured result of {@link classifyDatabaseError}. */\nexport interface DatabaseErrorClassification {\n  /** What kind of failure this is, or `'unknown'` when nothing matched. */\n  kind: DatabaseErrorKind;\n  /** True when retrying cannot change the outcome. */\n  deterministic: boolean;\n  /** True when retrying plausibly can succeed. */\n  retryable: boolean;\n  /** PostgreSQL SQLSTATE recovered from the chain, when present. */\n  sqlstate?: string;\n  /** Raw driver code that produced the classification, when present. */\n  driverCode?: string;\n  /** Every driver code found anywhere in the chain, in discovery order. */\n  driverCodes: readonly string[];\n  /**\n   * Every message found anywhere in the chain, in discovery order. Includes\n   * the SDK's formatted `originalError` strings and the driver's own\n   * `detail`/`hint` fields, which carry the PostgreSQL\n   * `Key (col)=(value) already exists.` line used for column recovery.\n   */\n  driverMessages: readonly string[];\n  /**\n   * Column named directly by the driver (`node-postgres` sets `error.column`\n   * on a `23502`), when one was reported. More reliable than parsing it back\n   * out of the message.\n   */\n  column?: string;\n  /** Constraint named directly by the driver (`error.constraint`). */\n  constraint?: string;\n}\n\n/** Maximum chain depth walked, guarding against pathological nesting. */\nconst MAX_CHAIN_DEPTH = 12;\n\n/** `formatDbError` renders driver codes as `code=<value>` inside its string. */\nconst FORMATTED_CODE_PATTERN = /(?:^|[\\s,;([{])code=([A-Za-z0-9_]+)/g;\n\n/**\n * PostgreSQL SQLSTATE codes whose failure is fully determined by the statement\n * and its data. Retrying re-executes the same deterministic rejection.\n */\nconst DETERMINISTIC_SQLSTATES = new Map<string, DatabaseErrorKind>([\n  // Class 23 — integrity constraint violation\n  ['23000', 'check_violation'], // integrity_constraint_violation (generic)\n  ['23001', 'foreign_key_violation'], // restrict_violation\n  ['23502', 'not_null_violation'],\n  ['23503', 'foreign_key_violation'],\n  ['23505', 'unique_violation'],\n  ['23514', 'check_violation'],\n  // An EXCLUDE constraint is not a unique index: the conflicting rows differ on\n  // the constrained columns and merely overlap under the operator. Reporting it\n  // as `unique_violation` would make `save()` raise\n  // VALIDATION_UNIQUE_CONSTRAINT naming a field that did not collide, so it\n  // keeps its own kind and stays on the generic DatabaseError path.\n  ['23P01', 'exclusion_violation'],\n  // Class 22 — data exception (bad literal, overflow, bad uuid cast)\n  ['22001', 'invalid_input'], // string_data_right_truncation\n  ['22003', 'invalid_input'], // numeric_value_out_of_range\n  ['22007', 'invalid_input'], // invalid_datetime_format\n  ['22008', 'invalid_input'], // datetime_field_overflow\n  ['22023', 'invalid_input'], // invalid_parameter_value\n  ['22P02', 'invalid_input'], // invalid_text_representation — the bad-uuid case\n  ['22P03', 'invalid_input'], // invalid_binary_representation\n  // Class 25 — invalid transaction state. Only `25P02` belongs here:\n  // `25P03 idle_in_transaction_session_timeout` means the server *terminated\n  // the session*, which is a connection-level failure a fresh connection can\n  // survive, so it lives in TRANSIENT_SQLSTATES instead. Calling it\n  // deterministic would both block that retry and make\n  // `isAbortedTransactionError()` report a timed-out session as an OIDC race\n  // conflict in the profiles coordinator.\n  ['25P02', 'aborted_transaction'], // in_failed_sql_transaction\n  // Class 42 — syntax error or access rule violation\n  ['42501', 'insufficient_privilege'],\n  ['42601', 'syntax_error'],\n  ['42703', 'undefined_object'], // undefined_column\n  ['42804', 'invalid_input'], // datatype_mismatch\n  ['42883', 'undefined_object'], // undefined_function\n  ['42P01', 'undefined_object'], // undefined_table\n  ['42P07', 'undefined_object'], // duplicate_table\n  // invalid_column_reference — \"no unique or exclusion constraint matching the\n  // ON CONFLICT specification\". A conflict target that does not match a real\n  // unique index is a schema defect, not contention; retrying it four times\n  // only delays the report (see epic #2382 finding A4).\n  ['42P10', 'undefined_object'],\n  ['3D000', 'undefined_object'], // invalid_catalog_name\n  ['3F000', 'undefined_object'], // invalid_schema_name\n]);\n\n/**\n * PostgreSQL SQLSTATE codes describing a contention or availability failure.\n * The same statement may well succeed on a later attempt.\n */\nconst TRANSIENT_SQLSTATES = new Set([\n  '25P03', // idle_in_transaction_session_timeout — the session was terminated\n  '40001', // serialization_failure\n  '40003', // statement_completion_unknown\n  '40P01', // deadlock_detected\n  '53200', // out_of_memory\n  '53300', // too_many_connections\n  '55P03', // lock_not_available\n  '57014', // query_canceled\n  '57P01', // admin_shutdown\n  '57P02', // crash_shutdown\n  '57P03', // cannot_connect_now\n  '58030', // io_error\n  '08000', // connection_exception\n  '08001', // sqlclient_unable_to_establish_sqlconnection\n  '08003', // connection_does_not_exist\n  '08004', // sqlserver_rejected_establishment_of_sqlconnection\n  '08006', // connection_failure\n  '08007', // transaction_resolution_unknown\n  '08P01', // protocol_violation\n]);\n\n/**\n * SQLite extended result codes. `better-sqlite3`/`node:sqlite` frequently\n * report the bare `SQLITE_CONSTRAINT` parent code, so the constraint sub-kind\n * is resolved from the message instead (see {@link classifyDialectMessage}).\n */\nconst DETERMINISTIC_SQLITE_CODES = new Map<string, DatabaseErrorKind>([\n  ['SQLITE_CONSTRAINT_UNIQUE', 'unique_violation'],\n  ['SQLITE_CONSTRAINT_PRIMARYKEY', 'unique_violation'],\n  ['SQLITE_CONSTRAINT_ROWID', 'unique_violation'],\n  ['SQLITE_CONSTRAINT_NOTNULL', 'not_null_violation'],\n  ['SQLITE_CONSTRAINT_FOREIGNKEY', 'foreign_key_violation'],\n  ['SQLITE_CONSTRAINT_CHECK', 'check_violation'],\n  ['SQLITE_CONSTRAINT_TRIGGER', 'check_violation'],\n  ['SQLITE_MISMATCH', 'invalid_input'],\n  ['SQLITE_RANGE', 'invalid_input'],\n  ['SQLITE_TOOBIG', 'invalid_input'],\n  ['SQLITE_READONLY', 'insufficient_privilege'],\n  ['SQLITE_AUTH', 'insufficient_privilege'],\n]);\n\n/** SQLite result codes that clear once contention or a lock resolves. */\nconst TRANSIENT_SQLITE_CODES = new Set([\n  'SQLITE_BUSY',\n  'SQLITE_BUSY_SNAPSHOT',\n  'SQLITE_BUSY_TIMEOUT',\n  'SQLITE_LOCKED',\n  'SQLITE_LOCKED_SHAREDCACHE',\n  'SQLITE_PROTOCOL',\n]);\n\n/** Node/libuv socket errno values raised when a pooled connection drops. */\nconst TRANSIENT_NETWORK_CODES = new Set([\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'ECONNABORTED',\n  'EPIPE',\n  'ETIMEDOUT',\n  'ENETUNREACH',\n  'ENETRESET',\n  'EHOSTUNREACH',\n  'EAI_AGAIN',\n  'ENOTFOUND',\n]);\n\n/**\n * Dialect wording, in precedence order. Only DuckDB has no machine-readable\n * code, but SQLite's bare `SQLITE_CONSTRAINT` and PostgreSQL errors that have\n * lost their code through string formatting are recovered here too.\n *\n * NOT NULL is tested before UNIQUE because DuckDB phrases both with the same\n * `Constraint Error … violates` shape, and foreign-key/check wording must not\n * be mistaken for a unique violation (#1578).\n */\nconst DIALECT_MESSAGE_RULES: ReadonlyArray<{\n  kind: DatabaseErrorKind;\n  pattern: RegExp;\n}> = [\n  {\n    kind: 'aborted_transaction',\n    pattern: /current transaction is aborted/i,\n  },\n  {\n    kind: 'not_null_violation',\n    pattern:\n      /NOT NULL constraint failed|null value in column .* violates not-null/i,\n  },\n  {\n    // SQLite reports `FOREIGN KEY constraint failed` under the bare\n    // `SQLITE_CONSTRAINT` parent code, so without this arm the sub-kind\n    // recovery below would mislabel every SQLite FK failure.\n    kind: 'foreign_key_violation',\n    pattern: /violates foreign key constraint|FOREIGN KEY constraint failed/i,\n  },\n  {\n    kind: 'check_violation',\n    pattern: /violates check constraint|CHECK constraint failed/i,\n  },\n  {\n    kind: 'unique_violation',\n    pattern:\n      /UNIQUE constraint failed|violates unique constraint|violates primary key constraint|duplicate key value violates/i,\n  },\n  {\n    kind: 'invalid_input',\n    pattern: /invalid input syntax for type|value too long for type/i,\n  },\n  {\n    // Deliberately narrow: a bare /does not exist/ matches far too much to be\n    // safe as a fail-fast signal.\n    kind: 'undefined_object',\n    pattern:\n      /no such table|no such column|(?:relation|column|table|function) \"[^\"]*\" does not exist/i,\n  },\n  {\n    kind: 'transient',\n    pattern:\n      /database is locked|database table is locked|connection terminated|server closed the connection|too many clients|deadlock detected|could not serialize access/i,\n  },\n];\n\n/** SMRT-level codes that already express a driver classification. */\nconst SMRT_CODE_KINDS = new Map<string, DatabaseErrorKind>([\n  ['VALIDATION_UNIQUE_CONSTRAINT', 'unique_violation'],\n  ['DB_CONSTRAINT_VIOLATION', 'check_violation'],\n]);\n\n/**\n * Reporting precedence among deterministic kinds, most specific first.\n *\n * `aborted_transaction` ranks last on purpose: PostgreSQL reports `25P02` for\n * every statement issued after the transaction already failed, so a chain\n * carrying both it and the constraint that caused the abort must name the\n * constraint. Every kind here is non-retryable, so ranking changes only what\n * is reported, never whether the operation is retried.\n */\nconst DETERMINISTIC_KIND_RANK = new Map<DatabaseErrorKind, number>([\n  ['unique_violation', 0],\n  ['not_null_violation', 1],\n  ['foreign_key_violation', 2],\n  ['check_violation', 3],\n  ['exclusion_violation', 4],\n  ['invalid_input', 5],\n  ['undefined_object', 6],\n  ['insufficient_privilege', 7],\n  ['syntax_error', 8],\n  ['aborted_transaction', 9],\n]);\n\nfunction rankKind(kind: DatabaseErrorKind): number {\n  return DETERMINISTIC_KIND_RANK.get(kind) ?? Number.MAX_SAFE_INTEGER;\n}\n\ninterface ChainSignals {\n  codes: string[];\n  messages: string[];\n  columns: string[];\n  constraints: string[];\n}\n\nfunction pushUnique(collection: string[], value: unknown): void {\n  if (typeof value !== 'string') return;\n  const entry = value.trim();\n  if (entry && !collection.includes(entry)) {\n    collection.push(entry);\n  }\n}\n\nfunction pushCode(signals: ChainSignals, value: unknown): void {\n  pushUnique(signals.codes, value);\n}\n\nfunction pushMessage(signals: ChainSignals, value: unknown): void {\n  if (typeof value !== 'string') return;\n  const message = value.trim();\n  if (!message || signals.messages.includes(message)) return;\n  signals.messages.push(message);\n\n  // `formatDbError` folds the driver's own `code` into its string, so the\n  // machine-readable classification survives even after stringification.\n  FORMATTED_CODE_PATTERN.lastIndex = 0;\n  let match = FORMATTED_CODE_PATTERN.exec(message);\n  while (match) {\n    pushCode(signals, match[1]);\n    match = FORMATTED_CODE_PATTERN.exec(message);\n  }\n}\n\n/**\n * Walks an error's causal chain, collecting every driver code and message.\n *\n * Visits `cause`, `context.originalError`, `originalError`,\n * `details.causeMessage`/`details.causeMessages` and `AggregateError.errors`,\n * because the SDK, core and consumer wrappers each nest the driver error\n * differently. Cycles and depth are bounded.\n */\nfunction collectChainSignals(error: unknown): ChainSignals {\n  const signals: ChainSignals = {\n    codes: [],\n    messages: [],\n    columns: [],\n    constraints: [],\n  };\n  const seen = new Set<unknown>();\n  const pending: Array<{ value: unknown; depth: number }> = [\n    { value: error, depth: 0 },\n  ];\n\n  while (pending.length > 0) {\n    const entry = pending.pop();\n    if (!entry) break;\n    const { value, depth } = entry;\n    if (value === null || value === undefined || depth > MAX_CHAIN_DEPTH) {\n      continue;\n    }\n\n    if (typeof value === 'string') {\n      pushMessage(signals, value);\n      continue;\n    }\n    if (typeof value !== 'object' || seen.has(value)) continue;\n    seen.add(value);\n\n    const node = value as {\n      code?: unknown;\n      sqlState?: unknown;\n      sqlstate?: unknown;\n      message?: unknown;\n      detail?: unknown;\n      hint?: unknown;\n      column?: unknown;\n      constraint?: unknown;\n      cause?: unknown;\n      context?: { originalError?: unknown } | unknown;\n      originalError?: unknown;\n      details?: unknown;\n      errors?: unknown;\n    };\n\n    pushCode(signals, node.code);\n    pushCode(signals, node.sqlState);\n    pushCode(signals, node.sqlstate);\n    pushMessage(signals, node.message);\n    // `node-postgres` surfaces the PostgreSQL error fields as properties. On\n    // the direct INSERT path nothing stringifies them into the message, so the\n    // column would otherwise be unrecoverable (`error.detail` carries\n    // \"Key (sku)=(s1) already exists.\" for a 23505; `error.column` names the\n    // column outright for a 23502).\n    pushMessage(signals, node.detail);\n    pushMessage(signals, node.hint);\n    pushUnique(signals.columns, node.column);\n    pushUnique(signals.constraints, node.constraint);\n\n    const details = node.details as\n      | { causeMessage?: unknown; causeMessages?: unknown }\n      | undefined;\n    if (details && typeof details === 'object') {\n      pushMessage(signals, details.causeMessage);\n      if (Array.isArray(details.causeMessages)) {\n        for (const causeMessage of details.causeMessages) {\n          pushMessage(signals, causeMessage);\n        }\n      }\n    }\n\n    const context = node.context as { originalError?: unknown } | undefined;\n    const next = [\n      node.cause,\n      node.originalError,\n      context && typeof context === 'object'\n        ? context.originalError\n        : undefined,\n    ];\n    for (const child of next) {\n      if (child !== null && child !== undefined) {\n        pending.push({ value: child, depth: depth + 1 });\n      }\n    }\n    if (Array.isArray(node.errors)) {\n      for (const child of node.errors) {\n        pending.push({ value: child, depth: depth + 1 });\n      }\n    }\n  }\n\n  return signals;\n}\n\n/**\n * Classifies a raw dialect message. Exposed so\n * `SmrtObject.classifyConstraintError()` and this module share one set of\n * regexes rather than drifting apart.\n */\nexport function classifyDialectMessage(message: string): DatabaseErrorKind {\n  if (!message) return 'unknown';\n  for (const rule of DIALECT_MESSAGE_RULES) {\n    if (rule.pattern.test(message)) return rule.kind;\n  }\n  return 'unknown';\n}\n\nfunction isSqlState(code: string): boolean {\n  return /^[0-9A-Z]{5}$/.test(code);\n}\n\n/**\n * Classifies a database failure by walking its causal chain.\n *\n * Codes win over wording: a PostgreSQL SQLSTATE or SQLite result code is\n * authoritative, and dialect message matching only runs when no code in the\n * chain was recognized (DuckDB, or an error already flattened to a string).\n *\n * Constraint violations are reported ahead of `aborted_transaction` so a chain\n * carrying both surfaces the root cause rather than the downstream symptom;\n * both are deterministic, so retry behavior is identical either way.\n *\n * @param error - Any thrown value. Non-database errors classify as `'unknown'`.\n * @returns The structured classification; never throws.\n */\nexport function classifyDatabaseError(\n  error: unknown,\n): DatabaseErrorClassification {\n  const signals = collectChainSignals(error);\n  const sqlstate = signals.codes.find(\n    (code) =>\n      isSqlState(code) &&\n      (DETERMINISTIC_SQLSTATES.has(code) || TRANSIENT_SQLSTATES.has(code)),\n  );\n\n  const base = {\n    driverCodes: signals.codes,\n    driverMessages: signals.messages,\n    ...(sqlstate ? { sqlstate } : {}),\n    ...(signals.columns[0] ? { column: signals.columns[0] } : {}),\n    ...(signals.constraints[0] ? { constraint: signals.constraints[0] } : {}),\n  };\n\n  // Deterministic codes first: a chain that carries both a constraint code and\n  // a downstream contention code must fail fast, not retry.\n  const deterministicCandidates: Array<{\n    code: string;\n    kind: DatabaseErrorKind;\n  }> = [];\n  for (const code of signals.codes) {\n    const kind =\n      DETERMINISTIC_SQLSTATES.get(code) ??\n      DETERMINISTIC_SQLITE_CODES.get(code) ??\n      // SMRT's own typed codes: a `ValidationError` already carrying\n      // `VALIDATION_UNIQUE_CONSTRAINT` is the classified form of the same\n      // driver failure.\n      SMRT_CODE_KINDS.get(code) ??\n      // A bare `SQLITE_CONSTRAINT` carries no sub-kind; recover it from the\n      // message, which SQLite always phrases explicitly.\n      (code === 'SQLITE_CONSTRAINT'\n        ? (signals.messages\n            .map(classifyDialectMessage)\n            .find((candidate) => DETERMINISTIC_KIND_RANK.has(candidate)) ??\n          'check_violation')\n        : undefined);\n    if (kind) deterministicCandidates.push({ code, kind });\n  }\n\n  if (deterministicCandidates.length > 0) {\n    // Rank rather than take the first discovered: an error whose chain holds\n    // both `23505` and the `25P02` it caused must report the root constraint,\n    // not the downstream symptom.\n    const best = deterministicCandidates.reduce((winner, candidate) =>\n      rankKind(candidate.kind) < rankKind(winner.kind) ? candidate : winner,\n    );\n    return {\n      ...base,\n      kind: best.kind,\n      deterministic: true,\n      retryable: false,\n      driverCode: best.code,\n    };\n  }\n\n  for (const code of signals.codes) {\n    if (TRANSIENT_SQLSTATES.has(code) || TRANSIENT_SQLITE_CODES.has(code)) {\n      return {\n        ...base,\n        kind: 'transient',\n        deterministic: false,\n        retryable: true,\n        driverCode: code,\n      };\n    }\n    if (TRANSIENT_NETWORK_CODES.has(code)) {\n      return {\n        ...base,\n        kind: 'transient',\n        deterministic: false,\n        retryable: true,\n        driverCode: code,\n      };\n    }\n  }\n\n  // No recognized code anywhere — fall back to dialect wording. This is the\n  // only path DuckDB ever takes.\n  const messageKinds = signals.messages\n    .map(classifyDialectMessage)\n    .filter((kind) => kind !== 'unknown');\n  const deterministicFromMessage = messageKinds\n    .filter((kind) => DETERMINISTIC_KIND_RANK.has(kind))\n    .sort((left, right) => rankKind(left) - rankKind(right))[0];\n  if (deterministicFromMessage) {\n    return {\n      ...base,\n      kind: deterministicFromMessage,\n      deterministic: true,\n      retryable: false,\n    };\n  }\n  if (messageKinds.includes('transient')) {\n    return {\n      ...base,\n      kind: 'transient',\n      deterministic: false,\n      retryable: true,\n    };\n  }\n\n  return {\n    ...base,\n    kind: 'unknown',\n    deterministic: false,\n    retryable: false,\n  };\n}\n\n/**\n * True when retrying the statement cannot change the outcome.\n *\n * Used by {@link ErrorUtils.withRetry} to fail fast instead of burning the\n * full 500 + 1000 + 2000 ms backoff on a constraint violation.\n */\nexport function isDeterministicDatabaseError(error: unknown): boolean {\n  return classifyDatabaseError(error).deterministic;\n}\n\n/** True when the failure is contention or availability and may clear. */\nexport function isTransientDatabaseError(error: unknown): boolean {\n  return classifyDatabaseError(error).retryable;\n}\n\n/** True when a unique or primary-key constraint was violated. */\nexport function isUniqueViolationError(error: unknown): boolean {\n  return classifyDatabaseError(error).kind === 'unique_violation';\n}\n\n/** True when a NOT NULL constraint was violated. */\nexport function isNotNullViolationError(error: unknown): boolean {\n  return classifyDatabaseError(error).kind === 'not_null_violation';\n}\n\n/**\n * True when the failure came from running inside an already-aborted\n * PostgreSQL transaction (SQLSTATE `25P02`).\n *\n * Detected independently of {@link DatabaseErrorKind} so a chain that also\n * carries the root constraint code still answers `true` here.\n */\nexport function isAbortedTransactionError(error: unknown): boolean {\n  const signals = collectChainSignals(error);\n  // `25P02` only. `25P03` is a terminated session, not a failed transaction,\n  // and reporting it here would make the profiles coordinator treat an\n  // idle-timeout disconnect as a provisioning race conflict.\n  if (signals.codes.includes('25P02')) {\n    return true;\n  }\n  return signals.messages.some((message) =>\n    /current transaction is aborted/i.test(message),\n  );\n}\n"],"mappings":"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"}

package/dist/decorators/index.d.ts

@@ -142,6 +142,32 @@ export interface RelationshipFieldOptions extends FieldOptions {
     through?: string;
     /** Relationship type */
     type?: 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany';
+    /**
+     * What happens to this row when the referenced object is deleted (#2371).
+     *
+     * SMRT emits no DB-level `FOREIGN KEY` constraints, so this is enforced by
+     * `SmrtObject.delete()` in the application layer rather than by the engine:
+     *
+     * - `'CASCADE'` — this row is deleted with the target.
+     * - `'SET NULL'` — this column is set to `NULL`. The field must be nullable;
+     *   declaring it on a `required` field throws `ConfigurationError`.
+     * - `'RESTRICT'` — deleting the target throws `DatabaseError` while any row
+     *   still points at it.
+     *
+     * When omitted, a column that is part of this class's `conflictColumns`
+     * (junction and association rows, which are *identified* by the reference)
+     * defaults to `CASCADE`; every other column is left untouched on delete.
+     * `@tenantId()` fields are the one exception: `smrt-tenancy` leads a
+     * tenant-scoped class's default `conflictColumns` with the tenant column,
+     * but that column scopes ownership rather than identifying the row, so it
+     * is never defaulted to `CASCADE` — deleting a `Tenant` must not cascade
+     * through every tenant-scoped table.
+     *
+     * Cascaded rows are removed set-based: their `beforeDelete`/`afterDelete`
+     * hooks and interceptors do not run and no change-feed entry is written, the
+     * same as a database-level `ON DELETE CASCADE`.
+     */
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
 }
 /**
  * Options specific to cross-package references.
@@ -217,9 +243,34 @@ export declare function field(options?: FieldOptions | NumericFieldOptions | Tex
  * For cross-package foreign keys, use a plain `string` property instead to avoid
  * circular dependencies between packages.
  *
- * @param relatedClass - The target class constructor (or class name string)
+ * **No DDL constraint is emitted.** SMRT generates no `FOREIGN KEY` clause on
+ * any engine — the relationship is enforced by the framework, not the database
+ * (#2371). What that buys you is `loadRelated()`, eager `include:` loading, and
+ * the `onDelete` behaviour applied by `SmrtObject.delete()`:
+ *
+ * ```typescript
+ * @foreignKey(Order, { onDelete: 'CASCADE' })   // deleted with the order
+ * orderId: string = '';
+ *
+ * @foreignKey(Customer, { onDelete: 'RESTRICT' }) // blocks the customer delete
+ * customerId: string = '';
+ * ```
+ *
+ * Without an `onDelete`, a column that is part of this class's
+ * `conflictColumns` defaults to `CASCADE` (this is what cleans up junction
+ * rows); any other column is left untouched when the target is deleted.
+ *
+ * @param relatedClass - The target class constructor, its name as a string, or a
+ *   `() => Target` thunk. A thunk is **invoked at decoration time**, so its
+ *   target must already be initialized: a class from an already-evaluated module
+ *   or the decorated class itself. Use the string form for a class declared
+ *   later in the same module or reached through an import cycle — it is never
+ *   evaluated, so it cannot hit the temporal dead zone.
  * @param options - Optional field constraints (required, nullable, etc.)
  * @returns A TypeScript property decorator
+ * @throws Error when the target cannot be resolved to a class name (an empty
+ *   string, a thunk that throws — including on an uninitialized target — or a
+ *   thunk returning an anonymous value)
  *
  * @example
  * ```typescript
@@ -228,6 +279,14 @@ export declare function field(options?: FieldOptions | NumericFieldOptions | Tex
  *   // Same-package FK — enables loadRelated() and eager loading
  *   @foreignKey(Customer)
  *   customerId: string = '';
+ *
+ *   // Self-reference: the class binding exists when its decorators run
+ *   @foreignKey(() => Order)
+ *   parentOrderId: string = '';
+ *
+ *   // Declared later in this module — name string, never evaluated
+ *   @foreignKey('Invoice')
+ *   invoiceId: string = '';
  * }
  *
  * // Cross-package: use a plain string instead
@@ -246,10 +305,12 @@ export declare function foreignKey(relatedClass: string | Function, options?: Om
  *
  * Use this for relationships that point to a `SmrtObject` in a *different* package
  * (e.g. `Customer.profileId` pointing at `@happyvertical/smrt-profiles:Profile`).
- * Unlike `@foreignKey()`, this decorator does **not** emit a DDL `FOREIGN KEY`
- * constraint — cross-package classes are not visible at schema-generation time and
- * adding a constraint would force a circular package dependency. The decorated
- * property remains a plain `TEXT` column at the database level.
+ *
+ * Like `@foreignKey()`, this emits **no** DDL `FOREIGN KEY` constraint — SMRT
+ * does not emit them on any engine (#2371). The decorated property is a
+ * `UUID` column on PostgreSQL/DuckDB and `TEXT` on SQLite, matching the target's
+ * id type; pass `{ idType: 'text' }` when the target declares
+ * `@smrt({ idType: 'text' })`.
  *
  * What you get over a plain string field:
  * - The relationship is registered with the `ObjectRegistry`, so `loadRelated()`
@@ -257,6 +318,8 @@ export declare function foreignKey(relatedClass: string | Function, options?: Om
  *   manifest is loaded.
  * - Optional save-time validation (`validate: true`) confirms the referenced
  *   object exists, catching typos and stale IDs before they hit the database.
+ * - `onDelete` is honoured by `SmrtObject.delete()` when the target package's
+ *   manifest is loaded in the same runtime.
  *
  * The `qualifiedName` is a fully-qualified class identifier in the form
  * `@package/scope:ClassName` — for example `@happyvertical/smrt-profiles:Profile`.
@@ -278,7 +341,7 @@ export declare function foreignKey(relatedClass: string | Function, options?: Om
  * }
  * ```
  *
- * @see {@link foreignKey} for same-package relationships (emits FK constraint)
+ * @see {@link foreignKey} for same-package relationships
  * @see SmrtObject.loadRelated for runtime resolution
  */
 export declare function crossPackageRef(qualifiedName: string, options?: CrossPackageRefOptions): CompatiblePropertyDecorator;
@@ -303,6 +366,17 @@ export declare function crossPackageRef(qualifiedName: string, options?: CrossPa
  * `loadRelatedMany` and the generated accessor resolve the intended inverse
  * side. Without it the first matching foreign key is used.
  *
+ * **Delete behaviour is declared on the child, not here.** `@oneToMany` is a
+ * transient read-side accessor; to have children removed with their parent,
+ * put `onDelete: 'CASCADE'` on the inverse `@foreignKey` (#2371):
+ *
+ * ```typescript
+ * class OrderItem extends SmrtObject {
+ *   @foreignKey(Order, { onDelete: 'CASCADE' })
+ *   orderId: string = '';
+ * }
+ * ```
+ *
  * @param relatedClass - The class constructor of the child/related objects
  * @param options - Optional relationship options. `foreignKey` selects the
  *   inverse foreign-key field on `relatedClass` when it has more than one.

package/dist/decorators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"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"}