@zudojs/transactions 0.1.0 → 1.0.0

package/dist/transaction/transaction.core.js

@@ -2,18 +2,36 @@
  * Core Transaction implementation with state machine enforcement.
  */
 import { randomBytes } from "node:crypto";
-import { TransactionStateError, TransactionCommitError, TransactionRollbackError, } from "../transactionErrors/transactionError.types.js";
-import { createTransitionFunction } from "./transactionStateMachine.js";
+import { TransactionRollbackError, TransactionStateError, } from "../transactionErrors/transactionError.types.js";
+import { canTransition, createTransitionFunction, } from "./transactionStateMachine.js";
+import { attachInternals } from "./transaction.internal.js";
 /**
  * Generate a unique transaction ID.
  */
 function generateTransactionId() {
     return `txn_${randomBytes(16).toString("hex")}`;
 }
+/** Runs callbacks in order, collecting failures rather than aborting. */
+async function runCallbacks(callbacks) {
+    const errors = [];
+    for (const callback of callbacks.splice(0)) {
+        try {
+            await callback();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    return errors;
+}
 /**
  * Create a new Transaction instance.
+ *
+ * @param options - Options the transaction was started with.
+ * @param parentId - Enclosing transaction id, for nested transactions.
+ * @param kind - How this handle relates to the adapter transaction.
  */
-export function createTransaction(options = {}, parentId) {
+export function createTransaction(options = {}, parentId, kind = "root") {
     let state = "pending";
     let rollbackOnly = false;
     let rollbackOnlyReason;
@@ -21,14 +39,11 @@ export function createTransaction(options = {}, parentId) {
     const afterCommitCallbacks = [];
     const afterRollbackCallbacks = [];
     let handle;
-    const setHandle = (h) => {
-        handle = h;
-    };
-    const getHandle = () => handle;
-    const transition = createTransitionFunction(() => state, (s) => {
-        state = s;
+    const transition = createTransitionFunction(() => state, (next) => {
+        state = next;
     });
     const metadata = new Map(options.metadata ? Object.entries(options.metadata) : []);
+    const frozenOptions = Object.freeze({ ...options });
     const id = generateTransactionId();
     const startedAt = Date.now();
     const txn = {
@@ -38,75 +53,62 @@ export function createTransaction(options = {}, parentId) {
         get parentId() {
             return parentId;
         },
+        get kind() {
+            return kind;
+        },
         get state() {
             return state;
         },
         get options() {
-            return Object.freeze({ ...options });
+            return frozenOptions;
         },
         get startedAt() {
             return startedAt;
         },
         get metadata() {
-            return metadata;
+            return new Map(metadata);
         },
         get timedOut() {
             return timedOut;
         },
+        /**
+         * Mark the transaction committed and run its after-commit callbacks.
+         *
+         * Refuses outright when the transaction is rollback-only: a caller must
+         * never be able to mistake a rollback for a commit.
+         */
         async commit() {
+            if (state === "committed")
+                return;
             if (state !== "active") {
                 throw new TransactionStateError(state, "commit");
             }
             if (rollbackOnly) {
-                await txn.rollback(rollbackOnlyReason ?? "marked rollback-only");
-                return;
+                throw new TransactionRollbackError(id, {
+                    originalError: rollbackOnlyReason ?? "marked rollback-only",
+                });
             }
             transition("committing");
-            try {
-                transition("committed");
-                for (const cb of afterCommitCallbacks) {
-                    try {
-                        await cb();
-                    }
-                    catch {
-                        /* swallow */
-                    }
-                }
-                afterCommitCallbacks.length = 0;
-                afterRollbackCallbacks.length = 0;
-            }
-            catch (error) {
-                transition("failed");
-                throw new TransactionCommitError(id, error);
-            }
+            transition("committed");
+            afterRollbackCallbacks.length = 0;
+            await runCallbacks(afterCommitCallbacks);
         },
         async rollback(reason) {
-            if (state === "committed" ||
-                state === "rolled_back" ||
-                state === "failed") {
+            if (state === "rolled_back" || state === "failed")
                 return;
+            if (state === "committed") {
+                throw new TransactionStateError(state, "rollback");
             }
-            if (state !== "active" && state !== "committing" && state !== "pending") {
+            if (!canTransition(state, "rolling_back")) {
                 throw new TransactionStateError(state, "rollback");
             }
             transition("rolling_back");
-            try {
-                transition("rolled_back");
-                for (const cb of afterRollbackCallbacks) {
-                    try {
-                        await cb();
-                    }
-                    catch {
-                        /* swallow */
-                    }
-                }
-                afterCommitCallbacks.length = 0;
-                afterRollbackCallbacks.length = 0;
-            }
-            catch (error) {
-                transition("failed");
+            transition("rolled_back");
+            afterCommitCallbacks.length = 0;
+            const errors = await runCallbacks(afterRollbackCallbacks);
+            if (errors.length > 0) {
                 throw new TransactionRollbackError(id, {
-                    cause: error,
+                    cause: new AggregateError(errors, "after-rollback callback failures"),
                     originalError: reason,
                 });
             }
@@ -125,15 +127,16 @@ export function createTransaction(options = {}, parentId) {
             afterRollbackCallbacks.push(callback);
         },
     };
-    return Object.assign(txn, {
-        /** @internal */ _setHandle: setHandle,
-        /** @internal */ _getHandle: getHandle,
-        /** @internal */ _transition: transition,
-        /** @internal */ _markTimedOut: () => {
+    return attachInternals(txn, {
+        _setHandle: (next) => {
+            handle = next;
+        },
+        _getHandle: () => handle,
+        _transition: transition,
+        _markTimedOut: () => {
             timedOut = true;
         },
-        /** @internal */ _getAfterCommitCallbacks: () => afterCommitCallbacks,
-        /** @internal */ _getAfterRollbackCallbacks: () => afterRollbackCallbacks,
+        _getRollbackOnlyReason: () => rollbackOnlyReason,
     });
 }
 //# sourceMappingURL=transaction.core.js.map

package/dist/transaction/transaction.internal.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Typed access to the manager-only surface of a Transaction.
+ *
+ * `createTransaction` attaches a handful of underscore-prefixed helpers the
+ * manager needs and consumers must not use. Routing every access through this
+ * module keeps the casts in one place, so renaming a helper is a compile
+ * error rather than a runtime `undefined is not a function`.
+ *
+ * @module transaction/transaction.internal
+ */
+import type { Transaction } from "../transactionTypes/transaction.interface.js";
+import type { TransactionState } from "../transactionTypes/transactionState.js";
+/**
+ * Key under which the internals are attached.
+ *
+ * Deliberately not re-exported from the package barrel: the manager imports
+ * this module directly, while a consumer holding only the public API has no
+ * way to name the property and therefore cannot drive the state machine or
+ * steal the adapter handle.
+ */
+export declare const TRANSACTION_INTERNALS: unique symbol;
+/** The manager-only operations attached to every transaction. */
+export interface TransactionInternals {
+    /** Store the adapter handle this transaction commits against. */
+    _setHandle(handle: unknown): void;
+    /** Read the adapter handle, if one was stored. */
+    _getHandle(): unknown;
+    /** Drive the state machine directly. */
+    _transition(state: TransactionState): void;
+    /** Record that the transaction outlived its timeout. */
+    _markTimedOut(): void;
+    /** The reason supplied to `markRollbackOnly`, if any. */
+    _getRollbackOnlyReason(): unknown;
+}
+/**
+ * Access the manager-only surface of a transaction.
+ *
+ * @param transaction - A transaction created by `createTransaction`.
+ * @returns The internal operations.
+ * @throws {TypeError} when the transaction did not come from this package.
+ */
+export declare function internals(transaction: Transaction): TransactionInternals;
+/**
+ * Attach the manager-only surface to a freshly created transaction.
+ *
+ * @param transaction - The transaction to extend.
+ * @param operations - The internal operations to attach.
+ * @returns The same transaction.
+ */
+export declare function attachInternals<T extends Transaction>(transaction: T, operations: TransactionInternals): T;
+/** A savepoint handle stored on a nested transaction. */
+export interface SavepointHandle {
+    /** The enclosing transaction's adapter handle. */
+    readonly parent: unknown;
+    /** The savepoint name created on that handle. */
+    readonly savepoint: string;
+}
+/**
+ * Narrow an adapter handle to a savepoint handle.
+ *
+ * @param handle - The handle stored on a transaction.
+ * @returns The savepoint handle, or undefined when it is a plain handle.
+ */
+export declare function asSavepointHandle(handle: unknown): SavepointHandle | undefined;
+//# sourceMappingURL=transaction.internal.d.ts.map

package/dist/transaction/transaction.internal.js

@@ -0,0 +1,66 @@
+/**
+ * Typed access to the manager-only surface of a Transaction.
+ *
+ * `createTransaction` attaches a handful of underscore-prefixed helpers the
+ * manager needs and consumers must not use. Routing every access through this
+ * module keeps the casts in one place, so renaming a helper is a compile
+ * error rather than a runtime `undefined is not a function`.
+ *
+ * @module transaction/transaction.internal
+ */
+/**
+ * Key under which the internals are attached.
+ *
+ * Deliberately not re-exported from the package barrel: the manager imports
+ * this module directly, while a consumer holding only the public API has no
+ * way to name the property and therefore cannot drive the state machine or
+ * steal the adapter handle.
+ */
+export const TRANSACTION_INTERNALS = Symbol("zudojs.transaction.internals");
+/**
+ * Access the manager-only surface of a transaction.
+ *
+ * @param transaction - A transaction created by `createTransaction`.
+ * @returns The internal operations.
+ * @throws {TypeError} when the transaction did not come from this package.
+ */
+export function internals(transaction) {
+    const carrier = transaction;
+    const found = carrier[TRANSACTION_INTERNALS];
+    if (!found) {
+        throw new TypeError("Transaction was not created by @zudojs/transactions and has no internals.");
+    }
+    return found;
+}
+/**
+ * Attach the manager-only surface to a freshly created transaction.
+ *
+ * @param transaction - The transaction to extend.
+ * @param operations - The internal operations to attach.
+ * @returns The same transaction.
+ */
+export function attachInternals(transaction, operations) {
+    Object.defineProperty(transaction, TRANSACTION_INTERNALS, {
+        value: operations,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return transaction;
+}
+/**
+ * Narrow an adapter handle to a savepoint handle.
+ *
+ * @param handle - The handle stored on a transaction.
+ * @returns The savepoint handle, or undefined when it is a plain handle.
+ */
+export function asSavepointHandle(handle) {
+    if (typeof handle === "object" &&
+        handle !== null &&
+        "savepoint" in handle &&
+        typeof handle.savepoint === "string") {
+        return handle;
+    }
+    return undefined;
+}
+//# sourceMappingURL=transaction.internal.js.map

package/dist/transaction/transaction.participant.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Participant and non-transactional transaction handles.
+ *
+ * A participant is what `required`, `supports` and `mandatory` hand back when
+ * a transaction is already in progress. It delegates every observation to the
+ * transaction it joined but owns nothing: committing it is a no-op, and
+ * rolling it back marks the enclosing transaction rollback-only rather than
+ * discarding work the enclosing scope has not finished with.
+ *
+ * @module transaction/transaction.participant
+ */
+import type { Transaction, TransactionOptions } from "../transactionTypes/transaction.interface.js";
+/**
+ * Create a handle that joins an in-progress transaction.
+ *
+ * @param parent - The transaction being joined.
+ * @returns A participant handle delegating to `parent`.
+ */
+export declare function createParticipant(parent: Transaction): Transaction;
+/**
+ * Create a handle for a deliberately non-transactional scope.
+ *
+ * Returned by `supports` and `never` when nothing is in progress, and by
+ * `not_supported` always. It moves through the normal lifecycle so callers can
+ * treat it uniformly, but never touches an adapter.
+ *
+ * @param options - Options the scope was opened with.
+ * @returns A transaction handle bound to no adapter transaction.
+ */
+export declare function createNonTransactional(options?: TransactionOptions): Transaction;
+//# sourceMappingURL=transaction.participant.d.ts.map

package/dist/transaction/transaction.participant.js

@@ -0,0 +1,81 @@
+/**
+ * Participant and non-transactional transaction handles.
+ *
+ * A participant is what `required`, `supports` and `mandatory` hand back when
+ * a transaction is already in progress. It delegates every observation to the
+ * transaction it joined but owns nothing: committing it is a no-op, and
+ * rolling it back marks the enclosing transaction rollback-only rather than
+ * discarding work the enclosing scope has not finished with.
+ *
+ * @module transaction/transaction.participant
+ */
+import { createTransaction } from "./transaction.core.js";
+import { internals } from "./transaction.internal.js";
+/**
+ * Create a handle that joins an in-progress transaction.
+ *
+ * @param parent - The transaction being joined.
+ * @returns A participant handle delegating to `parent`.
+ */
+export function createParticipant(parent) {
+    return Object.freeze({
+        get id() {
+            return parent.id;
+        },
+        get parentId() {
+            return parent.parentId;
+        },
+        get kind() {
+            return "participant";
+        },
+        get state() {
+            return parent.state;
+        },
+        get options() {
+            return parent.options;
+        },
+        get startedAt() {
+            return parent.startedAt;
+        },
+        get metadata() {
+            return parent.metadata;
+        },
+        get timedOut() {
+            return parent.timedOut;
+        },
+        /** No-op: the transaction is committed by whoever opened it. */
+        async commit() { },
+        /** Marks the joined transaction rollback-only. */
+        async rollback(reason) {
+            parent.markRollbackOnly(reason ?? "participant rolled back");
+        },
+        markRollbackOnly(reason) {
+            parent.markRollbackOnly(reason);
+        },
+        isRollbackOnly() {
+            return parent.isRollbackOnly();
+        },
+        afterCommit(callback) {
+            parent.afterCommit(callback);
+        },
+        afterRollback(callback) {
+            parent.afterRollback(callback);
+        },
+    });
+}
+/**
+ * Create a handle for a deliberately non-transactional scope.
+ *
+ * Returned by `supports` and `never` when nothing is in progress, and by
+ * `not_supported` always. It moves through the normal lifecycle so callers can
+ * treat it uniformly, but never touches an adapter.
+ *
+ * @param options - Options the scope was opened with.
+ * @returns A transaction handle bound to no adapter transaction.
+ */
+export function createNonTransactional(options = {}) {
+    const txn = createTransaction(options, undefined, "none");
+    internals(txn)._transition("active");
+    return txn;
+}
+//# sourceMappingURL=transaction.participant.js.map

package/dist/transaction/transactionStateMachine.d.ts

@@ -6,4 +6,14 @@ import type { TransactionState } from "../transactionTypes/transactionState.js";
  * Creates a state transition function for a transaction.
  */
 export declare function createTransitionFunction(getState: () => TransactionState, setState: (state: TransactionState) => void): (to: TransactionState) => void;
+/**
+ * Whether a state transition is permitted.
+ *
+ * Error handlers use this before transitioning, so a failure raised from a
+ * terminal state cannot be replaced by a TransactionStateError about the
+ * transition itself.
+ */
+export declare function canTransition(from: TransactionState, to: TransactionState): boolean;
+/** Whether a state admits no further transitions. */
+export declare function isTerminal(state: TransactionState): boolean;
 //# sourceMappingURL=transactionStateMachine.d.ts.map

package/dist/transaction/transactionStateMachine.js

@@ -4,7 +4,7 @@
 import { TransactionStateError } from "../transactionErrors/transactionError.types.js";
 /** Valid state transitions. */
 const VALID_TRANSITIONS = {
-    pending: ["active", "failed"],
+    pending: ["active", "rolling_back", "failed"],
     active: ["committing", "rolling_back", "failed"],
     committing: ["committed", "failed", "rolling_back"],
     committed: [],
@@ -18,10 +18,24 @@ const VALID_TRANSITIONS = {
 export function createTransitionFunction(getState, setState) {
     return (to) => {
         const current = getState();
-        if (!VALID_TRANSITIONS[current]?.includes(to)) {
+        if (!canTransition(current, to)) {
             throw new TransactionStateError(current, `transition to ${to}`);
         }
         setState(to);
     };
 }
+/**
+ * Whether a state transition is permitted.
+ *
+ * Error handlers use this before transitioning, so a failure raised from a
+ * terminal state cannot be replaced by a TransactionStateError about the
+ * transition itself.
+ */
+export function canTransition(from, to) {
+    return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+}
+/** Whether a state admits no further transitions. */
+export function isTerminal(state) {
+    return (VALID_TRANSITIONS[state]?.length ?? 0) === 0;
+}
 //# sourceMappingURL=transactionStateMachine.js.map

package/dist/transactionTypes/index.d.ts

@@ -3,8 +3,8 @@
  *
  * @module transactionTypes
  */
-export { type TransactionState, type TransactionPropagation, type TransactionIsolationLevel, } from "./transactionState.js";
-export { type Transaction, type TransactionOptions, type TransactionRetryOptions, } from "./transaction.interface.js";
-export { type TransactionHandle, type TransactionAdapterCapabilities, type TransactionAdapter, type Savepoint, type TransactionContext, } from "./transactionAdapter.js";
-export { type TransactionHookContext, type TransactionErrorContext, type TransactionHooks, type TransactionRegistry, type TransactionResult, TRANSACTION_EVENTS, type TransactionEvent, type TransactionEventHandler, } from "./transactionHooks.js";
+export { type TransactionState, type TransactionKind, type TransactionPropagation, type TransactionIsolationLevel, } from "./transactionState.js";
+export { type Transaction, type TransactionOptions, type TransactionRetryOptions, type TransactionRetryPredicate, } from "./transaction.interface.js";
+export { type TransactionHandle, type TransactionAdapterCapabilities, type TransactionAdapter, type TransactionContext, } from "./transactionAdapter.js";
+export { type TransactionHookContext, type TransactionErrorContext, type TransactionHooks, type TransactionRegistry, TRANSACTION_EVENTS, type TransactionEvent, type TransactionEventHandler, } from "./transactionHooks.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/transactionTypes/transaction.interface.d.ts

@@ -3,7 +3,7 @@
  *
  * @module transactionTypes/transaction
  */
-import type { TransactionState, TransactionPropagation, TransactionIsolationLevel } from "./transactionState.js";
+import type { TransactionState, TransactionKind, TransactionPropagation, TransactionIsolationLevel } from "./transactionState.js";
 /** Options for starting a transaction. */
 export interface TransactionOptions {
     /** Isolation level. */
@@ -21,6 +21,8 @@ export interface TransactionOptions {
     /** Retry configuration. */
     readonly retry?: TransactionRetryOptions;
 }
+/** Decides whether a failed attempt is worth retrying. */
+export type TransactionRetryPredicate = (error: unknown, attempt: number) => boolean;
 /** Retry configuration for transaction failures. */
 export interface TransactionRetryOptions {
     /** Maximum number of retry attempts. Defaults to 0 (no retry). */
@@ -29,6 +31,14 @@ export interface TransactionRetryOptions {
     readonly delay?: number;
     /** Backoff strategy. */
     readonly backoff?: "fixed" | "exponential";
+    /**
+     * Whether a given failure should be retried.
+     *
+     * Defaults to retrying everything. Supply a predicate to limit retries to
+     * the failures that are actually transient, such as serialization failures
+     * and deadlocks.
+     */
+    readonly shouldRetry?: TransactionRetryPredicate;
 }
 /** The core transaction interface. */
 export interface Transaction {
@@ -36,6 +46,14 @@ export interface Transaction {
     readonly id: string;
     /** Parent transaction ID (for nested transactions). */
     readonly parentId?: string;
+    /**
+     * How this handle relates to the underlying adapter transaction.
+     *
+     * A `participant` joined an enclosing transaction and must not commit it;
+     * `none` marks a non-transactional scope opened by the `supports`,
+     * `not_supported` or `never` propagation modes.
+     */
+    readonly kind: TransactionKind;
     /** Current lifecycle state. */
     readonly state: TransactionState;
     /** Options used to start this transaction. */

package/dist/transactionTypes/transactionAdapter.d.ts

@@ -37,20 +37,18 @@ export interface TransactionAdapter {
     /** Release a savepoint (optional). */
     releaseSavepoint?(handle: TransactionHandle, name: string): Promise<void>;
 }
-/** A savepoint within a transaction. */
-export interface Savepoint {
-    /** Savepoint name. */
-    readonly name: string;
-    /** Rollback to this savepoint. */
-    rollback(): Promise<void>;
-    /** Release this savepoint. */
-    release(): Promise<void>;
-}
 /** Transaction context for async propagation. */
 export interface TransactionContext {
     /** Get the current active transaction, if any. */
     get(): Transaction | undefined;
     /** Run a callback within a transaction context. */
     run<T>(transaction: Transaction, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Run a callback with no transaction in scope.
+     *
+     * Used by the `not_supported` and `requires_new` propagation modes, which
+     * must suspend an enclosing transaction rather than join it.
+     */
+    exit<T>(callback: () => Promise<T>): Promise<T>;
 }
 //# sourceMappingURL=transactionAdapter.d.ts.map

package/dist/transactionTypes/transactionHooks.d.ts

@@ -33,13 +33,6 @@ export interface TransactionRegistry {
     get(transactionId: string): Transaction | undefined;
     getActive(): readonly Transaction[];
 }
-/** Result of a transaction.run() call. */
-export interface TransactionResult<T> {
-    readonly value: T;
-    readonly transactionId: string;
-    readonly committed: boolean;
-    readonly duration: number;
-}
 /** Transaction event types. */
 export declare const TRANSACTION_EVENTS: {
     readonly STARTED: "transaction.started";

package/dist/transactionTypes/transactionState.d.ts

@@ -7,6 +7,15 @@
 export type TransactionState = "pending" | "active" | "committing" | "committed" | "rolling_back" | "rolled_back" | "failed";
 /** Transaction propagation strategies for nested calls. */
 export type TransactionPropagation = "required" | "requires_new" | "supports" | "not_supported" | "mandatory" | "never" | "nested";
+/**
+ * How a transaction handle relates to the underlying adapter transaction.
+ *
+ * The manager routes commit and rollback by kind: only a `root` owns an
+ * adapter transaction, a `participant` must never commit the transaction it
+ * joined, a `savepoint` resolves to its savepoint rather than the connection,
+ * and `none` marks a deliberately non-transactional scope.
+ */
+export type TransactionKind = "root" | "participant" | "savepoint" | "none";
 /** Database isolation levels. */
 export type TransactionIsolationLevel = "read_uncommitted" | "read_committed" | "repeatable_read" | "serializable";
 //# sourceMappingURL=transactionState.d.ts.map

package/dist/utils/utils.helper.d.ts

@@ -6,7 +6,12 @@
 import type { Transaction } from "../transactionTypes/transaction.interface.js";
 import type { TransactionState } from "../transactionTypes/transactionState.js";
 /**
- * Check if a transaction is in a terminal state (committed, rolled_back, or failed).
+ * Check if a transaction is in a terminal state.
+ *
+ * Delegates to {@link isTerminal}, which derives the answer from the state
+ * machine's transition table. This used to hardcode its own list of terminal
+ * states, so the two exported predicates could disagree the moment a state
+ * was added.
  */
 export declare function isTerminalState(state: TransactionState): boolean;
 /**

package/dist/utils/utils.helper.js

@@ -3,11 +3,17 @@
  *
  * @module utils/utils
  */
+import { isTerminal } from "../transaction/transactionStateMachine.js";
 /**
- * Check if a transaction is in a terminal state (committed, rolled_back, or failed).
+ * Check if a transaction is in a terminal state.
+ *
+ * Delegates to {@link isTerminal}, which derives the answer from the state
+ * machine's transition table. This used to hardcode its own list of terminal
+ * states, so the two exported predicates could disagree the moment a state
+ * was added.
  */
 export function isTerminalState(state) {
-    return state === "committed" || state === "rolled_back" || state === "failed";
+    return isTerminal(state);
 }
 /**
  * Check if a transaction can still be modified (active or pending).