@voltro/database 0.41.0 → 0.42.0

package/dist/index.d.ts

@@ -765,6 +765,19 @@ export declare const chunkRowsForInsert: <T extends Record<string, unknown>>(row
  */
 export declare const claimPendingAttribution: (key: string) => WriteAttribution | undefined;
 
+/**
+ * Classify a driver failure — already flattened by `extractDbCause` — into the
+ * safe facts above, or `undefined` when it is not a constraint violation at all
+ * (a deadlock, a dead connection, a timeout, a syntax error).
+ *
+ * `operation` is the write the framework was performing. It is consulted for
+ * ONE thing: sqlite reports both FK directions as the same bare
+ * `FOREIGN KEY constraint failed` with no name and no column, so a delete that
+ * trips it is `foreignKeyInUse` and an insert is `foreignKey`. Every other
+ * dialect states the direction itself and the operation is not consulted.
+ */
+export declare const classifyConstraintViolation: (dbCause: Record<string, unknown>, operation?: string) => ConstraintFacts | undefined;
+
 /** Wipe — used by tests + the dev-loop hot-reload. */
 export declare const clearEnumRenames: () => void;
 
@@ -1865,6 +1878,48 @@ export declare interface ConnectionIdentityInput {
     readonly database?: string | undefined;
 }
 
+/**
+ * The SAFE facts about a constraint violation: which rule, and the NAME of the
+ * constraint / column it fired on. Never a value, and never the driver's
+ * sentence.
+ *
+ * That exclusion is the whole design, and it is measured, not cautious:
+ *
+ *   - postgres attaches `detail: "Failing row contains (t4, l1, null, null,
+ *     null)."` to a not-null and a check violation — **the entire row**, every
+ *     column, including anything a table marked `.sensitive()`.
+ *   - mysql/mariadb: `Duplicate entry 's1' for key 'tasks.slug'`.
+ *   - mssql: `The duplicate key value is (s1).` and, on truncation,
+ *     `Truncated value: '…'`.
+ *
+ * So "just pass the driver message through" is not a smaller version of this —
+ * it is a different feature, one that ships row contents to whoever provoked
+ * the error. A constraint NAME is schema, the same class of fact the framework
+ * already puts on the wire in `TableValidationFailed.table`; a row is data.
+ *
+ * Everything here is captured as an anchored identifier group out of the
+ * driver text — never a slice of it — so a regex that fails to match yields
+ * `undefined` rather than a sentence that happens to contain a value.
+ */
+export declare interface ConstraintFacts {
+    readonly kind: ConstraintKind;
+    /** The constraint / index name, when the dialect names one. */
+    readonly constraint?: string;
+    /** The column, when the dialect names one instead of (or beside) a constraint. */
+    readonly column?: string;
+}
+
+/**
+ * Which integrity rule the database refused on.
+ *
+ * `foreignKey` and `foreignKeyInUse` are the two DIRECTIONS of one constraint
+ * and mean opposite things to a caller — "the row you pointed at does not
+ * exist" vs "you may not remove this row, others still point at it". A UI
+ * branches differently on each, so they are separate members rather than one
+ * member plus a string a caller would have to grep.
+ */
+export declare type ConstraintKind = 'foreignKey' | 'foreignKeyInUse' | 'unique' | 'notNull' | 'check';
+
 /** Case-insensitive substring match on a text column. Non-indexable —
  *  always evaluated as an unindexed leaf (the matcher's pre-filter only
  *  recognizes eq/in/range). Lowers to `ILIKE '%…%'` on Postgres. */
@@ -2970,6 +3025,8 @@ export declare const expires: () => MixinDefinition<{
  */
 export declare const externalChangeEvent: (event: ChangeEvent, attribution?: Partial<ChangeEventMeta>) => ChangeEvent;
 
+export declare const extractDbCause: (err: unknown) => Record<string, unknown>;
+
 /** The subset of `@voltro/logger`'s logger this module needs. Structural so
  *  this package keeps its browser-safe import surface. */
 export declare interface FallbackLogger {
@@ -3518,6 +3575,15 @@ export declare const isFieldDecryptionError: (e: unknown) => e is FieldDecryptio
 /** Type-guard for the discovery walker. */
 export declare const isFileMigration: (value: unknown) => value is FileMigration;
 
+/**
+ * Foreign-key violation, either direction, across every dialect. Derived from
+ * `classifyConstraintViolation` rather than re-listing the codes: this
+ * predicate and the classifier disagreeing is invisible until a tenant-FK
+ * failure quietly stops being typed, and mssql already spent a release in
+ * exactly that state (547 was read off `.code`, where it never appears).
+ */
+export declare const isForeignKeyViolation: (dbCause: Record<string, unknown>) => boolean;
+
 /** True when `name` is a live table the framework / its runtime engines create
  *  but no user schema declares — never plan a drop for it. */
 export declare const isFrameworkOwnedLiveTable: (name: string) => boolean;
@@ -3531,6 +3597,18 @@ export declare const isLocalFirst: (table: LocalFirstMarked) => boolean;
 
 export declare const isMigrationDefinition: (value: unknown) => value is MigrationDefinition;
 
+/**
+ * MySQL and MariaDB. They share a driver, a quoting style and most of a
+ * grammar — and they are NOT interchangeable in DDL.
+ *
+ * The one that has already cost us: **MySQL/InnoDB silently discards a
+ * column-inline `REFERENCES` clause** (parsed, thrown away, no warning, CREATE
+ * succeeds), while MariaDB honours it and creates the constraint. Measured on
+ * mysql 8.4 and mariadb 11. Anything referential that this family emits has to
+ * be table-level to work on both.
+ */
+export declare const isMysqlFamily: (dialect: DialectId) => boolean;
+
 /**
  * True when the connection string points at a Neon serverless-postgres host
  * (`*.neon.tech` / `*.neon.build`, including the `-pooler` endpoints). Neon's
@@ -3546,6 +3624,15 @@ export declare const isNull: <RowOf = Record<string, unknown>, K extends keyof R
 
 export declare const isPrimaryKeyConflictError: (err: unknown) => err is PrimaryKeyConflictError;
 
+/** A query cancelled for exceeding the `statementTimeoutMs` deadline, across
+ *  dialects: pg `57014` (query_canceled — what `statement_timeout` raises),
+ *  MySQL `3024` (ER_QUERY_TIMEOUT), MariaDB `1969` (ER_STATEMENT_TIMEOUT), mssql
+ *  `ETIMEOUT` (tedious request timeout), sqlite `SQLITE_INTERRUPT`. NOT a
+ *  transient error — a re-run just repeats the runaway, so it must not retry
+ *  (`servePipeline`'s transient set deliberately excludes it). Lets a consumer /
+ *  observability layer name the failure instead of reading an opaque SqlError. */
+export declare const isQueryTimeout: (dbCause: Record<string, unknown>) => boolean;
+
 /** Is this ciphertext in the OLD raw encoding? Used by `voltro db encrypt-column`
  *  to normalise a column without touching rows that are already current. Answers
  *  `undefined` when the two forms coincide (a numeric column, or a value that