@happyvertical/smrt-core 0.40.69 → 0.40.70

package/dist/database.d.ts

@@ -1,4 +1,5 @@
 import { DatabaseInterface, SchemasOption } from '@happyvertical/sql';
+import { PostgresTimeoutConfig } from './postgres-timeouts.js';
 /**
  * Unified type for all database configuration formats
  *
@@ -28,6 +29,13 @@ export type DatabaseConfig = string | {
     url?: string;
     type?: 'sqlite' | 'postgres' | 'duckdb' | 'json';
     authToken?: string;
+    /**
+     * Runtime PostgreSQL timeouts for this connection (#2377). Ignored by
+     * every other engine.
+     *
+     * @see {@link PostgresTimeoutConfig}
+     */
+    timeouts?: PostgresTimeoutConfig;
     [key: string]: unknown;
 } | DatabaseInterface;
 /**

package/dist/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,GACD,iBAAiB,CAAC;AAEtB;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,8BAA8B,EAC9B,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,GAClC,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAO5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAkC5B"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,GACD,iBAAiB,CAAC;AAEtB;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,8BAA8B,EAC9B,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,GAClC,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAO5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAqC5B"}

package/dist/database.js

@@ -1,3 +1,4 @@
+import { applyPostgresRuntimeTimeouts } from "./postgres-timeouts.js";
 import { getDatabase } from "@happyvertical/sql";
 //#region src/database.ts
 /**
@@ -49,19 +50,26 @@ function isDatabaseInterface(value) {
 async function resolveDatabase(config, options = {}) {
 	const { dbid, schemas } = options;
 	if (isDatabaseInterface(config)) return config;
-	if (typeof config === "string") return getDatabase({
-		url: config,
-		schemas,
-		...config === ":memory:" ? {} : { dbid: dbid ?? `smrt:${config}` }
-	});
+	if (typeof config === "string") {
+		const isMemoryDb = config === ":memory:";
+		const bounded = applyPostgresRuntimeTimeouts({ url: config });
+		return getDatabase({
+			...bounded,
+			schemas,
+			...isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }
+		});
+	}
 	const canUseMemory = !config.type || config.type === "sqlite";
 	const dbUrl = config.url || (canUseMemory ? ":memory:" : "");
 	const isMemoryDb = dbUrl === ":memory:";
-	return getDatabase({
+	const bounded = applyPostgresRuntimeTimeouts({
 		...config,
-		url: dbUrl,
+		url: dbUrl
+	});
+	return getDatabase({
+		...bounded,
 		schemas,
-		...isMemoryDb ? {} : { dbid: dbid ?? `smrt:${dbUrl}` }
+		...isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }
 	});
 }
 //#endregion

package/dist/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","names":[],"sources":["../src/database.ts"],"sourcesContent":["/**\n * Database configuration and resolution utilities\n *\n * This module provides a unified type for database configuration options\n * and a utility function to resolve any config format to a DatabaseInterface.\n *\n * @module\n */\n\nimport type { DatabaseInterface, SchemasOption } from '@happyvertical/sql';\nimport { getDatabase } from '@happyvertical/sql';\n\n/**\n * Unified type for all database configuration formats\n *\n * Supports three formats:\n * - **String**: Connection URL (e.g., 'products.db', ':memory:', 'postgres://...')\n * - **Config object**: Full configuration with type, url, and options\n * - **DatabaseInterface**: Pre-initialized database instance\n *\n * @example\n * ```typescript\n * // String shortcut\n * const config: DatabaseConfig = 'products.db';\n *\n * // Config object\n * const config: DatabaseConfig = {\n *   type: 'sqlite',\n *   url: 'products.db',\n *   authToken: 'token'\n * };\n *\n * // Pre-initialized instance\n * const db = await getDatabase({ type: 'sqlite', url: ':memory:' });\n * const config: DatabaseConfig = db;\n * ```\n */\nexport type DatabaseConfig =\n  | string\n  | {\n      url?: string;\n      type?: 'sqlite' | 'postgres' | 'duckdb' | 'json';\n      authToken?: string;\n      [key: string]: unknown;\n    }\n  | DatabaseInterface;\n\n/**\n * Canonical declaration of the request-scoped database global.\n *\n * The value is installed by whichever package owns request scoping (today\n * `@happyvertical/smrt-users`, via its session permission context) and is read\n * by the SvelteKit runtime config that `smrt-core`'s vite plugin generates into\n * consumer apps. Both sides used to `declare global` this name independently\n * with different types — `DatabaseConfig` here, a package-private\n * `QueryableDatabase` there — and TypeScript requires merged `var` declarations\n * to be *identical*, not merely compatible. Consumers whose program contained\n * both then failed to type-check (#2342).\n *\n * `smrt-core` owns the declaration because it is the base package every other\n * SMRT package and consumer already depends on. Writers should keep assigning a\n * live `DatabaseInterface`; it satisfies `DatabaseConfig` through that arm of\n * the union. Never redeclare this global elsewhere.\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __smrtGetRequestScopedDatabase:\n    | (() => DatabaseConfig | undefined)\n    | undefined;\n}\n\n/**\n * Type guard to check if a value is a DatabaseInterface instance\n *\n * @param value - Value to check\n * @returns True if value has query() and close() methods\n *\n * @example\n * ```typescript\n * if (isDatabaseInterface(config)) {\n *   // config is DatabaseInterface\n *   await config.query('SELECT 1');\n * }\n * ```\n */\nexport function isDatabaseInterface(\n  value: unknown,\n): value is DatabaseInterface {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'query' in value &&\n    typeof (value as { query: unknown }).query === 'function'\n  );\n}\n\n/**\n * Options for resolving a database configuration\n */\nexport interface ResolveDatabaseOptions {\n  /**\n   * Cache key for connection pooling.\n   * If provided, the same dbid returns the same cached connection.\n   */\n  dbid?: string;\n\n  /**\n   * Optional pre-generated schemas to pass to the database adapter.\n   *\n   * Intended for explicit tooling and test utilities that bootstrap schema\n   * ahead of runtime. Core runtime no longer passes these automatically.\n   */\n  schemas?: SchemasOption;\n}\n\n/**\n * Resolve any DatabaseConfig format to a DatabaseInterface instance\n *\n * This utility function normalizes the three config formats:\n * 1. **String URL**: Passed to getDatabase() with auto-detected type\n * 2. **Config object**: Passed to getDatabase() directly\n * 3. **DatabaseInterface**: Returned as-is\n *\n * @param config - Database configuration in any supported format\n * @param options - Resolution options (dbid for caching, optional explicit schemas)\n * @returns Promise resolving to a DatabaseInterface instance\n *\n * @example\n * ```typescript\n * // String URL\n * const db = await resolveDatabase('products.db');\n *\n * // Config object\n * const db = await resolveDatabase({\n *   type: 'postgres',\n *   url: 'postgres://localhost/mydb'\n * });\n *\n * // Pre-initialized instance (returned as-is)\n * const existingDb = await getDatabase({ url: ':memory:' });\n * const db = await resolveDatabase(existingDb);\n * console.log(db === existingDb); // true\n * ```\n */\nexport async function resolveDatabase(\n  config: DatabaseConfig,\n  options: ResolveDatabaseOptions = {},\n): Promise<DatabaseInterface> {\n  const { dbid, schemas } = options;\n\n  // Already a DatabaseInterface instance - return as-is\n  if (isDatabaseInterface(config)) {\n    return config;\n  }\n\n  // String URL shortcut\n  if (typeof config === 'string') {\n    const isMemoryDb = config === ':memory:';\n    return getDatabase({\n      url: config,\n      schemas,\n      ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${config}` }),\n    });\n  }\n\n  // Config object\n  // Only default to :memory: for SQLite (or unspecified type which defaults to SQLite)\n  // Other adapters (json, postgres, duckdb) require explicit URLs\n  const canUseMemory = !config.type || config.type === 'sqlite';\n  const dbUrl = config.url || (canUseMemory ? ':memory:' : '');\n  const isMemoryDb = dbUrl === ':memory:';\n  // `config` is the loosely-typed config-object variant of `DatabaseConfig`\n  // (it carries an open `[key: string]: unknown` index for adapter-specific\n  // options). Cast the merged options to `getDatabase`'s own parameter type at\n  // this boundary; the adapter validates the concrete shape at runtime.\n  return getDatabase({\n    ...config,\n    url: dbUrl,\n    schemas,\n    ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${dbUrl}` }),\n  } as Parameters<typeof getDatabase>[0]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAqFA,SAAgB,oBACd,OAC4B;CAC5B,OACE,UAAU,QACV,OAAO,UAAU,YACjB,WAAW,SACX,OAAQ,MAA6B,UAAU;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,eAAsB,gBACpB,QACA,UAAkC,CAAC,GACP;CAC5B,MAAM,EAAE,MAAM,YAAY;CAG1B,IAAI,oBAAoB,MAAM,GAC5B,OAAO;CAIT,IAAI,OAAO,WAAW,UAEpB,OAAO,YAAY;EACjB,KAAK;EACL;EACA,GAJiB,WAAW,aAIX,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,SAAS;CACzD,CAAC;CAMH,MAAM,eAAe,CAAC,OAAO,QAAQ,OAAO,SAAS;CACrD,MAAM,QAAQ,OAAO,QAAQ,eAAe,aAAa;CACzD,MAAM,aAAa,UAAU;CAK7B,OAAO,YAAY;EACjB,GAAG;EACH,KAAK;EACL;EACA,GAAI,aAAa,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,QAAQ;CACxD,CAAsC;AACxC"}
+{"version":3,"file":"database.js","names":[],"sources":["../src/database.ts"],"sourcesContent":["/**\n * Database configuration and resolution utilities\n *\n * This module provides a unified type for database configuration options\n * and a utility function to resolve any config format to a DatabaseInterface.\n *\n * @module\n */\n\nimport type { DatabaseInterface, SchemasOption } from '@happyvertical/sql';\nimport { getDatabase } from '@happyvertical/sql';\nimport {\n  applyPostgresRuntimeTimeouts,\n  type PostgresTimeoutConfig,\n} from './postgres-timeouts.js';\n\n/**\n * Unified type for all database configuration formats\n *\n * Supports three formats:\n * - **String**: Connection URL (e.g., 'products.db', ':memory:', 'postgres://...')\n * - **Config object**: Full configuration with type, url, and options\n * - **DatabaseInterface**: Pre-initialized database instance\n *\n * @example\n * ```typescript\n * // String shortcut\n * const config: DatabaseConfig = 'products.db';\n *\n * // Config object\n * const config: DatabaseConfig = {\n *   type: 'sqlite',\n *   url: 'products.db',\n *   authToken: 'token'\n * };\n *\n * // Pre-initialized instance\n * const db = await getDatabase({ type: 'sqlite', url: ':memory:' });\n * const config: DatabaseConfig = db;\n * ```\n */\nexport type DatabaseConfig =\n  | string\n  | {\n      url?: string;\n      type?: 'sqlite' | 'postgres' | 'duckdb' | 'json';\n      authToken?: string;\n      /**\n       * Runtime PostgreSQL timeouts for this connection (#2377). Ignored by\n       * every other engine.\n       *\n       * @see {@link PostgresTimeoutConfig}\n       */\n      timeouts?: PostgresTimeoutConfig;\n      [key: string]: unknown;\n    }\n  | DatabaseInterface;\n\n/**\n * Canonical declaration of the request-scoped database global.\n *\n * The value is installed by whichever package owns request scoping (today\n * `@happyvertical/smrt-users`, via its session permission context) and is read\n * by the SvelteKit runtime config that `smrt-core`'s vite plugin generates into\n * consumer apps. Both sides used to `declare global` this name independently\n * with different types — `DatabaseConfig` here, a package-private\n * `QueryableDatabase` there — and TypeScript requires merged `var` declarations\n * to be *identical*, not merely compatible. Consumers whose program contained\n * both then failed to type-check (#2342).\n *\n * `smrt-core` owns the declaration because it is the base package every other\n * SMRT package and consumer already depends on. Writers should keep assigning a\n * live `DatabaseInterface`; it satisfies `DatabaseConfig` through that arm of\n * the union. Never redeclare this global elsewhere.\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __smrtGetRequestScopedDatabase:\n    | (() => DatabaseConfig | undefined)\n    | undefined;\n}\n\n/**\n * Type guard to check if a value is a DatabaseInterface instance\n *\n * @param value - Value to check\n * @returns True if value has query() and close() methods\n *\n * @example\n * ```typescript\n * if (isDatabaseInterface(config)) {\n *   // config is DatabaseInterface\n *   await config.query('SELECT 1');\n * }\n * ```\n */\nexport function isDatabaseInterface(\n  value: unknown,\n): value is DatabaseInterface {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'query' in value &&\n    typeof (value as { query: unknown }).query === 'function'\n  );\n}\n\n/**\n * Options for resolving a database configuration\n */\nexport interface ResolveDatabaseOptions {\n  /**\n   * Cache key for connection pooling.\n   * If provided, the same dbid returns the same cached connection.\n   */\n  dbid?: string;\n\n  /**\n   * Optional pre-generated schemas to pass to the database adapter.\n   *\n   * Intended for explicit tooling and test utilities that bootstrap schema\n   * ahead of runtime. Core runtime no longer passes these automatically.\n   */\n  schemas?: SchemasOption;\n}\n\n/**\n * Resolve any DatabaseConfig format to a DatabaseInterface instance\n *\n * This utility function normalizes the three config formats:\n * 1. **String URL**: Passed to getDatabase() with auto-detected type\n * 2. **Config object**: Passed to getDatabase() directly\n * 3. **DatabaseInterface**: Returned as-is\n *\n * @param config - Database configuration in any supported format\n * @param options - Resolution options (dbid for caching, optional explicit schemas)\n * @returns Promise resolving to a DatabaseInterface instance\n *\n * @example\n * ```typescript\n * // String URL\n * const db = await resolveDatabase('products.db');\n *\n * // Config object\n * const db = await resolveDatabase({\n *   type: 'postgres',\n *   url: 'postgres://localhost/mydb'\n * });\n *\n * // Pre-initialized instance (returned as-is)\n * const existingDb = await getDatabase({ url: ':memory:' });\n * const db = await resolveDatabase(existingDb);\n * console.log(db === existingDb); // true\n * ```\n */\nexport async function resolveDatabase(\n  config: DatabaseConfig,\n  options: ResolveDatabaseOptions = {},\n): Promise<DatabaseInterface> {\n  const { dbid, schemas } = options;\n\n  // Already a DatabaseInterface instance - return as-is\n  if (isDatabaseInterface(config)) {\n    return config;\n  }\n\n  // String URL shortcut\n  if (typeof config === 'string') {\n    const isMemoryDb = config === ':memory:';\n    // The dbid is derived from the *bounded* URL so two configurations that\n    // differ only in their PostgreSQL timeouts cannot share one pool (#2377).\n    const bounded = applyPostgresRuntimeTimeouts({ url: config });\n    return getDatabase({\n      ...bounded,\n      schemas,\n      ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }),\n    } as Parameters<typeof getDatabase>[0]);\n  }\n\n  // Config object\n  // Only default to :memory: for SQLite (or unspecified type which defaults to SQLite)\n  // Other adapters (json, postgres, duckdb) require explicit URLs\n  const canUseMemory = !config.type || config.type === 'sqlite';\n  const dbUrl = config.url || (canUseMemory ? ':memory:' : '');\n  const isMemoryDb = dbUrl === ':memory:';\n  const bounded = applyPostgresRuntimeTimeouts({ ...config, url: dbUrl });\n  // `config` is the loosely-typed config-object variant of `DatabaseConfig`\n  // (it carries an open `[key: string]: unknown` index for adapter-specific\n  // options). Cast the merged options to `getDatabase`'s own parameter type at\n  // this boundary; the adapter validates the concrete shape at runtime.\n  return getDatabase({\n    ...bounded,\n    schemas,\n    ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }),\n  } as Parameters<typeof getDatabase>[0]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgGA,SAAgB,oBACd,OAC4B;CAC5B,OACE,UAAU,QACV,OAAO,UAAU,YACjB,WAAW,SACX,OAAQ,MAA6B,UAAU;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,eAAsB,gBACpB,QACA,UAAkC,CAAC,GACP;CAC5B,MAAM,EAAE,MAAM,YAAY;CAG1B,IAAI,oBAAoB,MAAM,GAC5B,OAAO;CAIT,IAAI,OAAO,WAAW,UAAU;EAC9B,MAAM,aAAa,WAAW;EAG9B,MAAM,UAAU,6BAA6B,EAAE,KAAK,OAAO,CAAC;EAC5D,OAAO,YAAY;GACjB,GAAG;GACH;GACA,GAAI,aAAa,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,QAAQ,MAAM;EAC9D,CAAsC;CACxC;CAKA,MAAM,eAAe,CAAC,OAAO,QAAQ,OAAO,SAAS;CACrD,MAAM,QAAQ,OAAO,QAAQ,eAAe,aAAa;CACzD,MAAM,aAAa,UAAU;CAC7B,MAAM,UAAU,6BAA6B;EAAE,GAAG;EAAQ,KAAK;CAAM,CAAC;CAKtE,OAAO,YAAY;EACjB,GAAG;EACH;EACA,GAAI,aAAa,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,QAAQ,MAAM;CAC9D,CAAsC;AACxC"}

package/dist/db-errors.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Driver-error classification for the persistence path (#2366).
+ *
+ * `@happyvertical/sql` does not normalize driver errors: every adapter catches
+ * the driver failure and rethrows
+ * `DatabaseError('Failed to upsert record into table', { …, originalError })`,
+ * where `originalError` is the **string** produced by the SDK's `formatDbError`
+ * (`"<driver message>, code=<driver code>, detail=…, hint=…"`). The typed
+ * message therefore carries none of the constraint wording, which is why
+ * matching on `error.message` alone silently stopped recognizing constraint
+ * violations and let {@link ErrorUtils.withRetry} retry them.
+ *
+ * This module walks the whole causal chain — `cause`, `context.originalError`
+ * (Error *or* formatted string), `originalError`, `details.causeMessages`, and
+ * `AggregateError.errors` — collecting every driver code and message it finds,
+ * then classifies on the codes first (PostgreSQL SQLSTATE, SQLite result
+ * codes, Node network errno) and only falls back to dialect wording for DuckDB,
+ * which reports no machine-readable code.
+ *
+ * The classification separates two independent questions:
+ * - `deterministic` — a retry cannot change the outcome (constraint violation,
+ *   bad input syntax, aborted transaction, missing table). Fail fast.
+ * - `retryable` — a retry plausibly can succeed (serialization failure,
+ *   deadlock, lock timeout, connection loss, `SQLITE_BUSY`).
+ *
+ * They are not complements: `kind: 'unknown'` means "no opinion", leaving the
+ * caller's own default policy in charge.
+ *
+ * @module
+ */
+/** Coarse classification of a database driver failure. */
+export type DatabaseErrorKind = 'unique_violation' | 'not_null_violation' | 'foreign_key_violation' | 'check_violation' | 'exclusion_violation' | 'invalid_input' | 'aborted_transaction' | 'undefined_object' | 'insufficient_privilege' | 'syntax_error' | 'transient' | 'unknown';
+/** Structured result of {@link classifyDatabaseError}. */
+export interface DatabaseErrorClassification {
+    /** What kind of failure this is, or `'unknown'` when nothing matched. */
+    kind: DatabaseErrorKind;
+    /** True when retrying cannot change the outcome. */
+    deterministic: boolean;
+    /** True when retrying plausibly can succeed. */
+    retryable: boolean;
+    /** PostgreSQL SQLSTATE recovered from the chain, when present. */
+    sqlstate?: string;
+    /** Raw driver code that produced the classification, when present. */
+    driverCode?: string;
+    /** Every driver code found anywhere in the chain, in discovery order. */
+    driverCodes: readonly string[];
+    /**
+     * Every message found anywhere in the chain, in discovery order. Includes
+     * the SDK's formatted `originalError` strings and the driver's own
+     * `detail`/`hint` fields, which carry the PostgreSQL
+     * `Key (col)=(value) already exists.` line used for column recovery.
+     */
+    driverMessages: readonly string[];
+    /**
+     * Column named directly by the driver (`node-postgres` sets `error.column`
+     * on a `23502`), when one was reported. More reliable than parsing it back
+     * out of the message.
+     */
+    column?: string;
+    /** Constraint named directly by the driver (`error.constraint`). */
+    constraint?: string;
+}
+/**
+ * Classifies a raw dialect message. Exposed so
+ * `SmrtObject.classifyConstraintError()` and this module share one set of
+ * regexes rather than drifting apart.
+ */
+export declare function classifyDialectMessage(message: string): DatabaseErrorKind;
+/**
+ * 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.
+ */
+export declare function classifyDatabaseError(error: unknown): DatabaseErrorClassification;
+/**
+ * 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.
+ */
+export declare function isDeterministicDatabaseError(error: unknown): boolean;
+/** True when the failure is contention or availability and may clear. */
+export declare function isTransientDatabaseError(error: unknown): boolean;
+/** True when a unique or primary-key constraint was violated. */
+export declare function isUniqueViolationError(error: unknown): boolean;
+/** True when a NOT NULL constraint was violated. */
+export declare function isNotNullViolationError(error: unknown): boolean;
+/**
+ * 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.
+ */
+export declare function isAbortedTransactionError(error: unknown): boolean;
+//# sourceMappingURL=db-errors.d.ts.map

package/dist/db-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-errors.d.ts","sourceRoot":"","sources":["../src/db-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,oBAAoB,GACpB,uBAAuB,GACvB,iBAAiB,GACjB,qBAAqB,GACrB,eAAe,GACf,qBAAqB,GACrB,kBAAkB,GAClB,wBAAwB,GACxB,cAAc,GACd,WAAW,GACX,SAAS,CAAC;AAEd,0DAA0D;AAC1D,MAAM,WAAW,2BAA2B;IAC1C,yEAAyE;IACzE,IAAI,EAAE,iBAAiB,CAAC;IACxB,oDAAoD;IACpD,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAgWD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAMzE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,2BAA2B,CA6G7B;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED,oDAAoD;AACpD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWjE"}

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