@voltro/database 0.74.0 → 0.76.0

package/dist/index.d.ts

@@ -4791,6 +4791,8 @@ export declare const isStagingTableName: (name: string) => boolean;
  */
 export declare const isTableReactive: (tableName: string) => boolean;
 
+export declare const isTransactionAbortedError: (e: unknown) => e is TransactionAbortedError;
+
 /**
  * Dialect-agnostic: does this error, anywhere down its `cause` chain, carry a
  * contention signal any supported engine emits? The mutation runner replays
@@ -5011,6 +5013,8 @@ export declare interface MakeStoreOptions {
     readonly cdcConfig?: CdcConfig;
 }
 
+export declare const makeTransactionAbortTracker: (isFatal: (error: unknown) => boolean, label?: string) => TransactionAbortTracker;
+
 export declare const many: (target: TableRef, options?: {
     readonly foreignKey?: string;
     readonly sourceKey?: string;
@@ -7130,6 +7134,8 @@ export declare interface RewriteOptions extends EachOptions {
      * addition to the columns the patch itself changes. A JSON column cannot be
      * compared by value on every dialect, so a rewrite of one guards on what
      * you name here — an `updatedAt`, a `version` — rather than on the document.
+     * Temporal comparisons retain the database's full precision, even though
+     * the callback's Date values only represent milliseconds.
      */
     readonly guard?: ReadonlyArray<string>;
     /**
@@ -7274,6 +7280,28 @@ export declare const runRetryingTransaction: <A>(spec: DialectTransactionSpec &
     readonly body: (conn: TransactionConnectionContext, attempt: number) => Promise<A>;
 }) => Promise<A>;
 
+/**
+ * `DataStore.savepoint` for a transactional view — ONE algorithm for every
+ * dialect; the view supplies only how to send one statement on its transaction
+ * and which spelling its engine uses.
+ *
+ * It used to exist on the postgres view alone, while the message a caught
+ * failure raises (`TransactionAbortedError`) names it as THE way to tolerate a
+ * failing statement — so on three dialects, and through the store a handler
+ * holds on all four, the advice pointed at a method that was `undefined`.
+ *
+ * `RELEASE` on success is not optional housekeeping: an unreleased savepoint
+ * keeps a subtransaction alive for the rest of the transaction. SQL Server has
+ * no release — a saved point simply ends with the transaction.
+ */
+export declare const runSavepoint: <A>(input: {
+    readonly tracker: TransactionAbortTracker;
+    readonly name: string;
+    /** Send one framework-authored statement on the view's transaction. */
+    readonly exec: (statement: string) => Promise<unknown>;
+    readonly spelling: "standard" | "mssql";
+}, fn: () => Promise<A>) => Promise<A>;
+
 /**
  * THE entry point every dialect store's `transactional()` — and postgres'
  * `runInNamespace()` — routes through.
@@ -8787,6 +8815,50 @@ export declare const timestampMs: Schema.Schema<Date, number>;
  */
 export declare const timestampMsOrNull: Schema.Schema<Date | null, number | null>;
 
+/**
+ * `transactional()`'s work caught a statement failure the engine had already
+ * made fatal to the transaction, and returned normally. Nothing was committed —
+ * not even the statements that succeeded before it.
+ *
+ * Raised instead of resolving, because a resolved `transactional()` is read as
+ * "these writes are in the table", and here none are. The swallowed failure is
+ * the `cause`.
+ */
+export declare class TransactionAbortedError extends Error {
+    readonly swallowed: unknown;
+    readonly _tag: "TransactionAborted";
+    constructor(label: string, swallowed: unknown);
+}
+
+/**
+ * Records, for one transactional view, the first statement failure the engine
+ * made fatal to the transaction — the value `abortedBy()` reports.
+ *
+ * ONE implementation for every dialect view; the dialect supplies only
+ * `isFatal`, because which failures end a transaction IS the dialect's (postgres:
+ * any statement the server rejected; InnoDB: a deadlock, which rolls the whole
+ * transaction back, while most other errors roll back only the statement).
+ *
+ * A failure inside `savepoint()` is not recorded: the savepoint's own rollback
+ * leaves the transaction usable, which is the entire point of taking one. A
+ * failure of that rollback IS recorded — the transaction is then unusable.
+ */
+export declare interface TransactionAbortTracker {
+    /**
+     * Send one statement — given as a THUNK, so that after a fatal failure it is
+     * not sent at all (a promise would already be on the wire). Records a fatal
+     * rejection outside a savepoint.
+     */
+    track<T>(send: () => Promise<T>): Promise<T>;
+    /** Run `fn` as a savepoint body: failures inside it are the savepoint's. */
+    inSavepoint<A>(fn: () => Promise<A>): Promise<A>;
+    /** Record a failure directly (a savepoint rollback that did not succeed). */
+    record(error: unknown): void;
+    abortedBy(): {
+        readonly error: unknown;
+    } | undefined;
+}
+
 /**
  * A store's per-transaction `DataStore` view: buffers the ChangeEvents its
  * writes produce and drains them to the parent emitter only once the
@@ -8794,6 +8866,21 @@ export declare const timestampMsOrNull: Schema.Schema<Date | null, number | null
  */
 export declare interface TransactionalViewHandle {
     commitEvents(): void;
+    /**
+     * The first statement failure the ENGINE took as fatal to this transaction,
+     * when the caller caught it and carried on. Absent on a dialect where a failed
+     * statement leaves the transaction usable (mysql, sqlite): there a caught
+     * failure is an ordinary, committable outcome.
+     *
+     * Postgres is the dialect that needs it. A failed statement aborts the whole
+     * transaction; every later statement fails with 25P02, and COMMIT is then
+     * executed AS A ROLLBACK — without raising. Before this existed, a work
+     * callback that caught one failure and returned normally made
+     * `transactional()` resolve, and nothing it wrote was in the table.
+     */
+    abortedBy?(): {
+        readonly error: unknown;
+    } | undefined;
 }
 
 /**