turbine-orm 0.81.0 → 0.90.0

package/dist/transaction-state.d.ts

@@ -0,0 +1,342 @@
+/**
+ * turbine-orm, the state one open transaction shares
+ *
+ * Everything a `$transaction` hands out (table accessors, raw SQL, nested
+ * `$transaction` blocks, streams) runs on ONE pooled connection. This module
+ * owns what those share:
+ *
+ *   - whether the transaction is still open. Once it settles, a `tx` that was
+ *     captured somewhere (an un-awaited promise, an `async` `forEach`, a timer)
+ *     must not send anything: its connection is back in the pool and may
+ *     already be running another request's transaction.
+ *   - the first statement failure. PostgreSQL aborts a transaction at its first
+ *     error and answers the COMMIT that follows with `ROLLBACK`; that failure is
+ *     what the caller needs to see as the cause.
+ *   - savepoint blocks. Savepoints are a stack on the connection, so two blocks
+ *     open at once would share it and a rollback in one would undo the other.
+ *     Blocks that share a parent therefore run one at a time, and a statement
+ *     at the parent's level waits for a block opened before it.
+ *   - what is still running: statements on the wire (what a cancel request
+ *     stops, and what a ROLLBACK must wait for) and work started but not
+ *     settled (which, when the callback returns, means a missing `await`).
+ *   - whether the server's transaction is already aborted. On PostgreSQL a
+ *     failed statement leaves the transaction ignoring every statement until a
+ *     rollback to a savepoint set before it, so a statement sent then is
+ *     refused here, with the failure that caused it, instead of coming back as
+ *     an untyped SQLSTATE 25P02 that no retry would recognise.
+ *   - which `tx` a statement came through. A nested block's callback gets its
+ *     own handle, and a statement through an OUTER handle from inside the
+ *     block is refused: it would run in the block's savepoint and be undone
+ *     with it.
+ *   - transaction-control SQL on the raw paths, which is refused (see
+ *     {@link TransactionState.runRaw}).
+ *
+ * A leaf (errors.ts, the zero-import transaction-control.ts, and type-only
+ * imports), so query/ can reach it without an import edge back to client.ts: a QueryInterface inside a transaction holds
+ * only its pool, and that pool carries this state under
+ * {@link TRANSACTION_STATE}.
+ */
+import type { Dialect } from './dialect.js';
+import { ValidationError } from './errors.js';
+import type { PgCompatPoolClient, PgCompatQueryResult } from './pg-types.js';
+/** The key a transaction-scoped pool carries its {@link TransactionState} under. */
+export declare const TRANSACTION_STATE: unique symbol;
+/** How a transaction ended, phrased to complete "This transaction ...". */
+export type TransactionEnd = 'has ended' | 'committed' | 'was rolled back' | 'timed out';
+/** The API that opened a transaction, which its error messages name. */
+export type TransactionApi = '$transaction' | 'transaction';
+type SavepointDialect = Pick<Dialect, 'capabilities' | 'savepointStatement' | 'releaseSavepointStatement' | 'rollbackToSavepointStatement'>;
+/**
+ * One level of savepoint nesting: the transaction itself, or an open block.
+ * Also what a `tx` handle is bound to (see {@link TransactionState.run}), so it
+ * is exported as an opaque token: nothing outside this file reads its fields.
+ */
+export interface TransactionScope {
+    readonly state: TransactionState;
+    /** The frame this one is nested in (undefined for the transaction). */
+    readonly parent: TransactionScope | undefined;
+    /**
+     * True for the transaction and for a block `tx.$transaction` handed its own
+     * `tx`; false for the savepoint one multi-statement write runs in, which has
+     * no handle of its own and is part of the handle that issued the write.
+     */
+    readonly handle: boolean;
+    /** Settles when every block registered on this frame's child slot is done. */
+    tail: Promise<void>;
+    /** Blocks registered on {@link tail} that have not finished. */
+    children: number;
+    /** The tick at which this frame's savepoint was set (0 for the transaction). */
+    readonly openedAt: number;
+    /** True from the moment the frame's savepoint is set until it is released or rolled back. */
+    open: boolean;
+}
+export interface TransactionStateOptions {
+    /** The API that opened the transaction (default `$transaction`). */
+    api?: TransactionApi;
+    /**
+     * True for a transaction the CALLER opened (`$transaction`, `$withSession`).
+     * Multi-statement writes inside one get a savepoint of their own, so a
+     * failure part way through cannot leave half of the write behind in a
+     * transaction that goes on to commit. An internal transaction (a nested
+     * write's own BEGIN/COMMIT) is atomic already and gets none.
+     */
+    userTransaction?: boolean;
+}
+export declare class TransactionState {
+    readonly client: PgCompatPoolClient;
+    private readonly dialect;
+    /** True when multi-statement writes run inside their own savepoint (see {@link withSavepoint}). */
+    readonly savepointWrites: boolean;
+    private endedAs;
+    private failure;
+    /** A statement cut short that may still have run: the transaction must roll back (see {@link abort}). */
+    private aborted;
+    /**
+     * The server's own error that left the PostgreSQL transaction in its aborted
+     * state, until a rollback to a savepoint set before it. Only recorded where
+     * a failed statement aborts the transaction (see {@link abortsOnError}) and
+     * only for a failure the SERVER reported: a client-side error (a value the
+     * driver could not serialize) never reached the transaction and changes
+     * nothing about what it will accept.
+     */
+    private dead;
+    /** True where one failed statement makes the server ignore the rest of the transaction (PostgreSQL). */
+    private readonly abortsOnError;
+    /** The lexical rules for finding transaction-control SQL in raw text, or undefined where none apply (PowDB). */
+    private readonly controlSyntax;
+    private tick;
+    private savepointCount;
+    private readonly root;
+    /** Frames whose SAVEPOINT is set and not yet released or rolled back, outermost first. */
+    private readonly openFrames;
+    /** Statements sent on the connection that have not answered yet. */
+    private onWire;
+    /** Statements and savepoint blocks started through the transaction that have not settled. */
+    private started;
+    private idleWaiters;
+    /** Settles at the first {@link end}, releasing anything still queued behind a block. */
+    private readonly endedSignal;
+    private signalEnded;
+    private readonly api;
+    constructor(client: PgCompatPoolClient, dialect: SavepointDialect, options?: TransactionStateOptions);
+    /** Whether the transaction has settled (see {@link end}). */
+    get ended(): boolean;
+    /**
+     * The first statement failure not undone by a savepoint rollback, if any.
+     * Where the server aborted the transaction, the failure that did it: that is
+     * the one a retry decision follows.
+     */
+    get firstFailure(): unknown;
+    /** The scope of the transaction itself: what the `tx` handed to the callback is bound to. */
+    get rootScope(): TransactionScope;
+    /** Why the transaction must roll back instead of committing (see {@link abort}), if it must. */
+    get abortedWith(): unknown;
+    /**
+     * Whether a statement or savepoint block started through the transaction is
+     * still running. True when the callback settles means work it started was
+     * not awaited.
+     */
+    get busy(): boolean;
+    /** Whether a statement is on the wire right now (what a cancel request would stop). */
+    get running(): boolean;
+    /**
+     * Run the transaction's callback. Statements and blocks it starts are then
+     * known to sit at the transaction's top level, which is what lets a block
+     * whose async context was lost be told apart from a sibling.
+     */
+    enter<R>(fn: () => R): R;
+    /**
+     * Resolve `true` once no statement is on the wire, or `false` after `ms`.
+     * Called after {@link end}, when nothing new can be sent.
+     */
+    whenIdle(ms: number): Promise<boolean>;
+    /**
+     * Mark the transaction settled. Called as soon as the callback settles,
+     * BEFORE the COMMIT or ROLLBACK, and again with the outcome; from the first
+     * call on every statement issued through the transaction is refused.
+     */
+    end(how: TransactionEnd): void;
+    /** Throw the closed-transaction error when the transaction has settled. */
+    assertOpen(): void;
+    /**
+     * Run a statement issued THROUGH the transaction (an accessor, raw SQL, a
+     * stream): refused once the transaction has settled, and its failure recorded
+     * as a candidate cause for a later ROLLBACK-at-COMMIT.
+     *
+     * `scope` is the handle the statement came through (the transaction's own
+     * `tx`, or the one a nested block's callback received). A statement through
+     * an OUTER handle from inside an open block is refused: it would run in the
+     * block's savepoint and be undone with it.
+     *
+     * A statement issued while a savepoint block started before it at the same
+     * level is still open waits for that block. Sent at once it would run inside
+     * the block's savepoint and be undone if the block rolled back, after it had
+     * already reported success.
+     *
+     * On PostgreSQL a statement sent after one failed is not sent at all: the
+     * server would ignore it (SQLSTATE 25P02) and the failure that caused that
+     * would be lost. `recovery` marks the one statement that is sent regardless,
+     * a rollback to a savepoint the caller set by hand (see {@link runRaw}).
+     */
+    run<T>(statement: () => Promise<T>, scope?: TransactionScope, recovery?: boolean): Promise<T>;
+    /**
+     * {@link run} for a statement the caller wrote (`tx.raw`, `tx.rawUnsafe`,
+     * `tx.sql`, the connection `$connection()` and `transaction()` hand out).
+     *
+     * Transaction-control SQL is refused with E003 before anything is sent.
+     * `COMMIT`, `ROLLBACK` or `BEGIN` ends or reshapes the transaction behind the
+     * state that tracks it, so later writes would autocommit and the callback's
+     * own throw would keep them. A savepoint of the caller's own sits on the
+     * connection's stack beside the ones Turbine sets, so those are refused too
+     * inside `$transaction`, where `tx.$transaction(...)` is the savepoint.
+     *
+     * The raw `transaction()` API has no such block, so `SAVEPOINT`, `RELEASE`
+     * and `ROLLBACK TO` stay available there: the only way to recover from a
+     * failed statement without losing the transaction. A `ROLLBACK TO` is also
+     * the one statement sent while the transaction is aborted, and when it
+     * succeeds the abort is over.
+     */
+    runRaw<T>(sql: unknown, statement: () => Promise<T>, scope?: TransactionScope): Promise<T>;
+    /**
+     * Check raw SQL for transaction control without sending it: throws E003 for
+     * a statement the caller may not send, and answers whether the text rolls
+     * back to a savepoint (the one control statement that is allowed to run in an
+     * aborted transaction).
+     */
+    screenRaw(sql: unknown): boolean;
+    /** Put one statement on the wire, counted for {@link whenIdle} and recorded on failure. */
+    private send;
+    /** Record `err` as the first failure, unless one is already recorded. */
+    noteFailure(err: unknown): void;
+    /** Record `err` as what aborted the server's transaction, unless something already did. */
+    private noteDead;
+    /**
+     * Mark the transaction as one that must not commit, because of `err`: a
+     * statement timed out and was cancelled, and whether it ran cannot be
+     * relied on. The server aborts the transaction when the cancel lands, but a
+     * cancel that arrives after the statement finished does nothing, and a
+     * COMMIT would then keep it. A rollback to a savepoint set before the
+     * statement clears the mark, as it clears the failure.
+     *
+     * Statements after it are refused like those after any failed statement: the
+     * transaction cannot commit, so there is nothing to send them for.
+     */
+    abort(err: unknown): void;
+    /**
+     * Refuse a statement the PostgreSQL transaction would ignore, with the
+     * failure that aborted it. The same error a COMMIT in this state gets
+     * ({@link rolledBackError}), so a deadlock, serialization conflict or lock
+     * wait that was caught and followed by one more statement is still the
+     * retryable class `$retry` looks for.
+     */
+    private assertNotAborted;
+    /** The caller rolled back to a savepoint of their own and the server accepted it: the abort is over. */
+    private clearAbort;
+    /**
+     * Refuse `what` issued through `scope` when the async context it was issued
+     * from is inside a block opened through a handle nested under `scope`.
+     *
+     * `tx.$transaction(async (inner) => { await tx.users.update(...) })` sends
+     * the update through the OUTER handle, but the connection is inside the
+     * block's savepoint, so a throw from the block would undo an update the
+     * caller placed outside it. The block's callback has its own handle for work
+     * inside it. A context this state cannot see (a timer created before the
+     * transaction, a callback API that drops the async context) is not refused:
+     * it cannot be told apart from a statement at the right level.
+     */
+    private assertNotFromInsideBlock;
+    /**
+     * Run `block` inside a savepoint: released when it resolves, rolled back to
+     * when it rejects, so the rest of the transaction is unaffected either way.
+     *
+     * Blocks that share a parent run one at a time. A savepoint is a position on
+     * the connection's one stack, so a block that opened second sits inside the
+     * first: rolling the first back would discard the second even after it had
+     * released and reported success. A block started from INSIDE another block's
+     * callback is nested under it and does not wait.
+     *
+     * A block whose callback swallowed a statement failure resolves normally,
+     * but PostgreSQL refuses to RELEASE a savepoint inside an aborted
+     * transaction. That case rolls the savepoint back and rejects with the same
+     * rolled-back error a COMMIT gets, carrying the failure as `cause`, so the
+     * outer transaction stays usable.
+     *
+     * This is the savepoint of ONE multi-statement write, which belongs to the
+     * handle that issued it. {@link withBlock} is a block the caller opened.
+     */
+    withSavepoint<R>(block: () => Promise<R>): Promise<R>;
+    /**
+     * Run `block` as a nested `tx.$transaction(...)`: a savepoint (see
+     * {@link withSavepoint}) whose callback receives a handle of its own, bound to
+     * the scope it is given. `caller` is the handle `$transaction` was called on.
+     */
+    withBlock<R>(block: (scope: TransactionScope) => Promise<R>, caller: TransactionScope): Promise<R>;
+    private openSavepoint;
+    /** The recorded failure, when it happened after `frame`'s savepoint was set. */
+    private failureSince;
+    /**
+     * What stops `frame` from being released: a statement cut short by its
+     * timeout, or (on PostgreSQL) a failure the server aborted the savepoint for,
+     * either one after the savepoint was set.
+     */
+    private doomedSince;
+    private rollbackTo;
+    /**
+     * A savepoint statement: refused once settled, failures recorded and typed.
+     * Typed INSIDE the statement, so the failure the state records is the Turbine
+     * error and not the driver's.
+     */
+    private control;
+}
+/** The state carried by a transaction-scoped pool, or undefined for any other pool. */
+export declare function transactionStateOf(pool: unknown): TransactionState | undefined;
+/**
+ * Run a multi-statement operation as one unit inside the caller's transaction.
+ *
+ * When `pool` belongs to a transaction the caller opened (`$transaction`,
+ * `$withSession`), `operation` runs inside its own savepoint: if it throws
+ * part way through, the statements it already ran are rolled back and the
+ * caller's transaction carries on as if the operation had never started. On
+ * any other pool (no transaction, or Turbine's own implicit transaction, which
+ * is atomic already) it simply runs `operation`.
+ *
+ * Every user-facing write that issues more than one statement inside a
+ * transaction already goes through this from `TransactionClient`'s accessors
+ * (nested creates and updates, lookup-first upserts); call it from any new
+ * multi-statement operation that can be reached some other way.
+ */
+export declare function withSavepoint<R>(pool: unknown, operation: () => Promise<R>): Promise<R>;
+/**
+ * Send COMMIT and refuse to report success when the server rolled back instead.
+ *
+ * PostgreSQL answers COMMIT in an aborted transaction with the command tag
+ * `ROLLBACK` and no error. Other engines never set `command` on a COMMIT
+ * result, so the check is inert for them.
+ */
+export declare function commitTransaction(client: {
+    query(text: string): Promise<PgCompatQueryResult>;
+}, commitSql: string, firstFailure?: unknown, api?: TransactionApi): Promise<void>;
+/** Whether a COMMIT result reports that the server rolled the transaction back. */
+export declare function commitWasRolledBack(result: {
+    command?: string;
+} | null | undefined): boolean;
+/**
+ * The error for work that was rolled back although the caller expected it to
+ * commit (a transaction) or be kept (a savepoint block).
+ *
+ * A retryable first failure (deadlock, serialization conflict, lock not
+ * available) keeps its class, so `$retry` and `isRetryable` checks retry the
+ * whole transaction, which is the documented response to all three. Anything
+ * else is a {@link TransactionRolledBackError} (E019) with the first failure as
+ * `cause`: nothing was committed, and the server did the rolling back.
+ */
+export declare function rolledBackError(firstFailure: unknown, scope: 'transaction' | 'savepoint' | 'statement', api?: TransactionApi): Error;
+/** The error for a statement sent through a transaction that has settled. */
+export declare function closedTransactionError(how: TransactionEnd, api?: TransactionApi): ValidationError;
+/**
+ * The error for a callback that returned while work it started through the
+ * transaction was still running. Committing then would save whatever part of
+ * that work had run, so the transaction is rolled back instead.
+ */
+export declare function unawaitedWorkError(api: TransactionApi): ValidationError;
+export {};