@zudojs/transactions 0.1.0 → 1.1.0

package/dist/manager/manager.core.js

@@ -3,89 +3,168 @@
  *
  * @module manager/manager
  */
-import { createTransaction } from "../transaction/transaction.core.js";
-import { TransactionAdapterError, TransactionRollbackError, } from "../transactionErrors/transactionError.types.js";
-import { handlePropagation } from "./manager.propagation.js";
+import { getDefaultContext } from "../context/context.core.js";
+import { internals } from "../transaction/transaction.internal.js";
+import { isTerminal } from "../transaction/transactionStateMachine.js";
+import { TransactionRollbackError } from "../transactionErrors/transactionError.types.js";
 import { commitTransaction, rollbackTransaction } from "./manager.commit.js";
+import { resolvePropagation, suspendsTransaction, } from "./manager.propagation.js";
+import { withRetry } from "./manager.retry.js";
+import { createEmitter, TRANSACTION_EVENTS } from "./manager.events.js";
+/** Whether a transaction can no longer change state. */
+function isFinished(transaction) {
+    return isTerminal(transaction.state);
+}
 /**
  * Create a transaction manager.
  */
 export function createTransactionManager(options) {
-    const { adapter, hooks } = options;
-    const resolveContext = () => {
-        if (options.context)
-            return options.context;
-        const mod = require("../context/context.core.js");
-        return mod.getDefaultContext();
-    };
+    const { adapter, hooks, registry } = options;
+    const context = options.context ?? getDefaultContext();
+    const emit = createEmitter(options.onEvent);
+    /** Timers armed for owned transactions, cleared when they complete. */
+    const timers = new Map();
+    /** Whether the manager completes this handle (root or savepoint). */
+    function owns(transaction) {
+        return transaction.kind === "root" || transaction.kind === "savepoint";
+    }
+    /**
+     * Arms the timeout for an owned transaction.
+     *
+     * `begin()` used to validate `timeout` against the adapter's capabilities
+     * and then ignore it — only `run()` armed a timer — so a transaction
+     * opened by hand never timed out.
+     */
+    function armTimeout(transaction) {
+        const timeout = transaction.options.timeout;
+        if (!timeout || timeout <= 0)
+            return;
+        const timer = setTimeout(() => {
+            timers.delete(transaction.id);
+            internals(transaction)._markTimedOut();
+            transaction.markRollbackOnly("timeout");
+            emit(TRANSACTION_EVENTS.TIMED_OUT, transaction);
+        }, timeout);
+        timers.set(transaction.id, timer);
+    }
+    /** Clears the timer and registry entry of a completed owned transaction. */
+    function release(transaction) {
+        if (!owns(transaction))
+            return;
+        const timer = timers.get(transaction.id);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timers.delete(transaction.id);
+        }
+        registry?.unregister(transaction.id);
+    }
     return {
+        /**
+         * Begin a transaction, applying the requested propagation mode.
+         *
+         * With the default `required` propagation inside an existing transaction
+         * this returns a participant: a handle that observes the enclosing
+         * transaction but never commits it.
+         */
         async begin(opts) {
-            const context = resolveContext();
-            const current = context.get();
-            if (current) {
-                return handlePropagation(current, opts?.propagation ?? "required", opts, adapter, context, hooks);
-            }
-            const transaction = createTransaction(opts);
-            if (hooks?.beforeBegin)
-                await hooks.beforeBegin({ transaction });
-            try {
-                const handle = await adapter.begin(opts);
-                transaction._setHandle(handle);
-                transaction._transition("active");
-            }
-            catch (error) {
-                transaction._transition("failed");
-                throw new TransactionAdapterError("Failed to begin transaction", error);
-            }
-            if (hooks?.afterBegin)
-                await hooks.afterBegin({ transaction });
-            if (opts?.timeout && opts.timeout > 0) {
-                const timer = setTimeout(() => {
-                    transaction._markTimedOut();
-                    transaction.markRollbackOnly("timeout");
-                }, opts.timeout);
-                const clearTimer = () => clearTimeout(timer);
-                transaction.afterCommit(async () => clearTimer());
-                transaction.afterRollback(async () => clearTimer());
+            const propagation = opts?.propagation ?? "required";
+            const current = suspendsTransaction(propagation)
+                ? undefined
+                : context.get();
+            const transaction = await resolvePropagation(propagation, {
+                current,
+                opts,
+                adapter,
+                hooks,
+                emit,
+            });
+            if (owns(transaction)) {
+                registry?.register(transaction);
+                armTimeout(transaction);
             }
             return transaction;
         },
+        /**
+         * Run a callback inside a transaction, committing or rolling back around it.
+         *
+         * Only a transaction this call opened is completed here: joining an
+         * enclosing transaction must not commit it, and a failure inside a
+         * participant marks the enclosing transaction rollback-only instead.
+         */
         async run(callback, opts) {
-            const context = resolveContext();
-            const transaction = await this.begin(opts);
-            return context.run(transaction, async () => {
-                try {
-                    const result = await callback(transaction);
-                    if (transaction.state === "active") {
+            // A failed attempt that only JOINED an enclosing transaction has not
+            // been rolled back — it marked the enclosing transaction rollback-only
+            // — so replaying it would repeat its side effects inside a transaction
+            // that can no longer commit. Retry only attempts this call owned.
+            let joined = false;
+            const retry = opts?.retry;
+            const retryOptions = retry === undefined
+                ? undefined
+                : {
+                    ...retry,
+                    shouldRetry: (error, attempt) => !joined && (retry.shouldRetry?.(error, attempt) ?? true),
+                };
+            return withRetry(retryOptions, async () => {
+                const transaction = await this.begin(opts);
+                joined = transaction.kind === "participant";
+                const body = async () => {
+                    try {
+                        const result = await callback(transaction);
                         await this.commit(transaction);
+                        return result;
                     }
-                    return result;
-                }
-                catch (error) {
-                    if (transaction.state === "active" ||
-                        transaction.state === "committing") {
+                    catch (error) {
                         try {
                             await this.rollback(transaction, error);
                         }
                         catch (rollbackError) {
+                            if (rollbackError instanceof TransactionRollbackError)
+                                throw error;
                             throw new TransactionRollbackError(transaction.id, {
                                 cause: rollbackError,
                                 originalError: error,
                             });
                         }
+                        throw error;
                     }
-                    throw error;
-                }
+                    finally {
+                        release(transaction);
+                    }
+                };
+                return transaction.kind === "none"
+                    ? context.exit(body)
+                    : context.run(transaction, body);
             });
         },
+        /**
+         * Commit a transaction. Participants and committed transactions are no-ops.
+         *
+         * Completing a transaction opened with `begin()` also releases its
+         * timeout timer and registry entry; both used to be released only by
+         * `run()`, so hand-managed transactions stayed in the registry forever.
+         */
         async commit(transaction) {
-            return commitTransaction(transaction, adapter, hooks);
+            try {
+                await commitTransaction(transaction, adapter, hooks, emit);
+            }
+            finally {
+                if (isFinished(transaction))
+                    release(transaction);
+            }
         },
+        /** Roll back a transaction, or mark the joined transaction rollback-only. */
         async rollback(transaction, reason) {
-            return rollbackTransaction(transaction, adapter, reason, hooks);
+            try {
+                await rollbackTransaction(transaction, adapter, reason, hooks, emit);
+            }
+            finally {
+                if (isFinished(transaction))
+                    release(transaction);
+            }
         },
+        /** The transaction in scope for the current async execution, if any. */
         getCurrent() {
-            return resolveContext().get();
+            return context.get();
         },
     };
 }

package/dist/manager/manager.events.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Transaction lifecycle event emission.
+ *
+ * `TRANSACTION_EVENTS`, `TransactionEvent` and `TransactionEventHandler` were
+ * exported from the package barrel from the beginning and nothing ever
+ * produced one. This module is what produces them: the manager threads an
+ * emitter through begin, commit and rollback, so an observer sees the same
+ * lifecycle the state machine does.
+ *
+ * @module manager/manager.events
+ */
+import type { Transaction } from "../transactionTypes/transaction.interface.js";
+import type { TransactionEvent, TransactionEventHandler } from "../transactionTypes/transactionHooks.js";
+import { TRANSACTION_EVENTS } from "../transactionTypes/transactionHooks.js";
+/** Emits lifecycle events, or does nothing when no handler was supplied. */
+export type TransactionEmitter = (type: TransactionEvent["type"], transaction: Transaction, error?: unknown) => void;
+/** An emitter that discards everything. */
+export declare const noopEmitter: TransactionEmitter;
+/**
+ * Build an emitter around a handler.
+ *
+ * A throwing observer must not take the transaction down with it, so handler
+ * failures are swallowed the same way a throwing error listener is elsewhere
+ * in the framework.
+ *
+ * @param handler - The observer, or undefined to disable emission.
+ * @returns An emitter.
+ */
+export declare function createEmitter(handler: TransactionEventHandler | undefined): TransactionEmitter;
+export { TRANSACTION_EVENTS };
+//# sourceMappingURL=manager.events.d.ts.map

package/dist/manager/manager.events.js

@@ -0,0 +1,45 @@
+/**
+ * Transaction lifecycle event emission.
+ *
+ * `TRANSACTION_EVENTS`, `TransactionEvent` and `TransactionEventHandler` were
+ * exported from the package barrel from the beginning and nothing ever
+ * produced one. This module is what produces them: the manager threads an
+ * emitter through begin, commit and rollback, so an observer sees the same
+ * lifecycle the state machine does.
+ *
+ * @module manager/manager.events
+ */
+import { TRANSACTION_EVENTS } from "../transactionTypes/transactionHooks.js";
+/** An emitter that discards everything. */
+export const noopEmitter = () => { };
+/**
+ * Build an emitter around a handler.
+ *
+ * A throwing observer must not take the transaction down with it, so handler
+ * failures are swallowed the same way a throwing error listener is elsewhere
+ * in the framework.
+ *
+ * @param handler - The observer, or undefined to disable emission.
+ * @returns An emitter.
+ */
+export function createEmitter(handler) {
+    if (!handler)
+        return noopEmitter;
+    return (type, transaction, error) => {
+        const event = {
+            type,
+            transactionId: transaction.id,
+            timestamp: Date.now(),
+            duration: Date.now() - transaction.startedAt,
+            ...(error === undefined ? {} : { error }),
+        };
+        try {
+            handler(event);
+        }
+        catch {
+            // An observer is not allowed to fail the transaction it observes.
+        }
+    };
+}
+export { TRANSACTION_EVENTS };
+//# sourceMappingURL=manager.events.js.map

package/dist/manager/manager.propagation.d.ts

@@ -1,15 +1,43 @@
 /**
  * Transaction propagation strategies.
  *
+ * Both branches matter: what a mode does when a transaction is already in
+ * progress, and what it does when none is. Handling only the first branch is
+ * how `mandatory` silently starts a transaction instead of demanding one.
+ *
  * @module manager/manager.propagation
  */
-import type { Transaction } from "../transactionTypes/transaction.interface.js";
-import type { TransactionOptions } from "../transactionTypes/transaction.interface.js";
+import type { Transaction, TransactionOptions } from "../transactionTypes/transaction.interface.js";
 import type { TransactionAdapter } from "../transactionTypes/transactionAdapter.js";
-import type { TransactionContext } from "../transactionTypes/transactionAdapter.js";
 import type { TransactionHooks } from "../transactionTypes/transactionHooks.js";
+import type { TransactionPropagation } from "../transactionTypes/transactionState.js";
+import type { TransactionEmitter } from "./manager.events.js";
+/** Everything a propagation branch may need. */
+export interface PropagationContext {
+    readonly current: Transaction | undefined;
+    readonly opts: TransactionOptions | undefined;
+    readonly adapter: TransactionAdapter;
+    readonly hooks: TransactionHooks | undefined;
+    /** Lifecycle event emitter. Defaults to discarding events. */
+    readonly emit?: TransactionEmitter;
+}
 /**
- * Handle transaction propagation when a transaction already exists.
+ * Open a root transaction against the adapter and make it active.
+ *
+ * @param context - The propagation context.
+ * @param parentId - Enclosing transaction id, when nested.
+ * @returns An active transaction owning an adapter handle.
+ */
+export declare function beginRoot(context: PropagationContext, parentId?: string): Promise<Transaction>;
+/**
+ * Resolve a propagation mode to a transaction handle.
+ *
+ * @param propagation - The requested mode.
+ * @param context - The propagation context.
+ * @returns The handle the caller should use.
+ * @throws {TransactionPropagationError} when the mode's precondition fails.
  */
-export declare function handlePropagation(current: Transaction, propagation: string, opts: TransactionOptions | undefined, adapter: TransactionAdapter, context: TransactionContext, hooks?: TransactionHooks): Promise<Transaction>;
+export declare function resolvePropagation(propagation: TransactionPropagation, context: PropagationContext): Promise<Transaction>;
+/** Whether a propagation mode runs its body outside any transaction. */
+export declare function suspendsTransaction(propagation: TransactionPropagation): boolean;
 //# sourceMappingURL=manager.propagation.d.ts.map

package/dist/manager/manager.propagation.js

@@ -1,56 +1,122 @@
 /**
  * Transaction propagation strategies.
  *
+ * Both branches matter: what a mode does when a transaction is already in
+ * progress, and what it does when none is. Handling only the first branch is
+ * how `mandatory` silently starts a transaction instead of demanding one.
+ *
  * @module manager/manager.propagation
  */
 import { createTransaction } from "../transaction/transaction.core.js";
-import { TransactionPropagationError } from "../transactionErrors/transactionError.types.js";
+import { createNonTransactional, createParticipant, } from "../transaction/transaction.participant.js";
+import { connectionHandle, internals, } from "../transaction/transaction.internal.js";
+import { SavepointError, TransactionCapabilityError, TransactionPropagationError, } from "../transactionErrors/transactionError.types.js";
+import { assertAdapterSupports } from "./manager.capabilities.js";
+import { noopEmitter, TRANSACTION_EVENTS } from "./manager.events.js";
+/**
+ * Open a root transaction against the adapter and make it active.
+ *
+ * @param context - The propagation context.
+ * @param parentId - Enclosing transaction id, when nested.
+ * @returns An active transaction owning an adapter handle.
+ */
+export async function beginRoot(context, parentId) {
+    const { adapter, hooks, opts } = context;
+    const emit = context.emit ?? noopEmitter;
+    assertAdapterSupports(adapter, opts);
+    const transaction = createTransaction(opts, parentId, "root");
+    if (hooks?.beforeBegin)
+        await hooks.beforeBegin({ transaction });
+    try {
+        internals(transaction)._setHandle(await adapter.begin(opts));
+        internals(transaction)._transition("active");
+    }
+    catch (error) {
+        internals(transaction)._transition("failed");
+        emit(TRANSACTION_EVENTS.FAILED, transaction, error);
+        throw error;
+    }
+    emit(TRANSACTION_EVENTS.STARTED, transaction);
+    if (hooks?.afterBegin)
+        await hooks.afterBegin({ transaction });
+    return transaction;
+}
+/**
+ * Create a nested transaction backed by a savepoint on the enclosing one.
+ *
+ * @param parent - The enclosing transaction.
+ * @param context - The propagation context.
+ * @returns An active transaction whose handle names its savepoint.
+ */
+async function beginSavepoint(parent, context) {
+    const { adapter, hooks, opts } = context;
+    const emit = context.emit ?? noopEmitter;
+    if (!adapter.capabilities.savepoints || !adapter.createSavepoint) {
+        // A missing capability is a configuration mismatch, not a propagation
+        // rule violation, and TransactionCapabilityError names what is missing.
+        throw new TransactionCapabilityError("savepoints, required by nested transactions");
+    }
+    const child = createTransaction(opts, parent.id, "savepoint");
+    if (hooks?.beforeBegin)
+        await hooks.beforeBegin({ transaction: child });
+    const savepoint = `sp_${child.id}`;
+    // Always the connection: a nested run inside another nested run must
+    // create its savepoint on the connection, not on the outer savepoint.
+    const parentHandle = connectionHandle(parent);
+    try {
+        await adapter.createSavepoint(parentHandle, savepoint);
+        internals(child)._setHandle({ parent: parentHandle, savepoint });
+        internals(child)._transition("active");
+    }
+    catch (error) {
+        internals(child)._transition("failed");
+        emit(TRANSACTION_EVENTS.FAILED, child, error);
+        throw new SavepointError(`Failed to create savepoint "${savepoint}"`, error);
+    }
+    emit(TRANSACTION_EVENTS.STARTED, child);
+    if (hooks?.afterBegin)
+        await hooks.afterBegin({ transaction: child });
+    return child;
+}
 /**
- * Handle transaction propagation when a transaction already exists.
+ * Resolve a propagation mode to a transaction handle.
+ *
+ * @param propagation - The requested mode.
+ * @param context - The propagation context.
+ * @returns The handle the caller should use.
+ * @throws {TransactionPropagationError} when the mode's precondition fails.
  */
-export async function handlePropagation(current, propagation, opts, adapter, context, hooks) {
+export async function resolvePropagation(propagation, context) {
+    const { current, opts } = context;
     switch (propagation) {
         case "required":
-            return current;
-        case "requires_new": {
-            const newTxn = createTransaction(opts);
-            if (hooks?.beforeBegin)
-                await hooks.beforeBegin({ transaction: newTxn });
-            const handle = await adapter.begin(opts);
-            newTxn._setHandle(handle);
-            if (hooks?.afterBegin)
-                await hooks.afterBegin({ transaction: newTxn });
-            return newTxn;
-        }
+            return current ? createParticipant(current) : beginRoot(context);
+        case "requires_new":
+            return beginRoot(context);
         case "supports":
-            return current;
+            return current
+                ? createParticipant(current)
+                : createNonTransactional(opts);
         case "not_supported":
-            return current;
+            return createNonTransactional(opts);
         case "mandatory":
-            return current;
+            if (!current) {
+                throw new TransactionPropagationError("Propagation is 'mandatory' but no transaction is in progress");
+            }
+            return createParticipant(current);
         case "never":
-            throw new TransactionPropagationError("Transaction exists but propagation is 'never'");
+            if (current) {
+                throw new TransactionPropagationError("Transaction exists but propagation is 'never'");
+            }
+            return createNonTransactional(opts);
         case "nested":
-            return createNestedTransaction(current, opts, adapter);
+            return current ? beginSavepoint(current, context) : beginRoot(context);
         default:
-            throw new TransactionPropagationError(`Unknown propagation: ${propagation}`);
+            throw new TransactionPropagationError(`Unknown propagation: ${String(propagation)}`);
     }
 }
-/**
- * Create a nested transaction using savepoints.
- */
-async function createNestedTransaction(parent, opts, adapter) {
-    if (!adapter.capabilities.savepoints || !adapter.createSavepoint) {
-        throw new TransactionPropagationError("Nested transactions require savepoint support");
-    }
-    const child = createTransaction(opts, parent.id);
-    const savepointName = `sp_${child.id}`;
-    const handle = parent._getHandle();
-    await adapter.createSavepoint(handle, savepointName);
-    child._setHandle({
-        parent: handle,
-        savepoint: savepointName,
-    });
-    return child;
+/** Whether a propagation mode runs its body outside any transaction. */
+export function suspendsTransaction(propagation) {
+    return propagation === "not_supported" || propagation === "requires_new";
 }
 //# sourceMappingURL=manager.propagation.js.map

package/dist/manager/manager.retry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Transaction retry.
+ *
+ * `TransactionOptions.retry` has always been part of the public contract;
+ * this is what honours it. Retries re-run the whole unit of work, because a
+ * transaction that failed cannot be resumed — only replayed.
+ *
+ * @module manager/manager.retry
+ */
+import type { TransactionRetryOptions } from "../transactionTypes/transaction.interface.js";
+/**
+ * Run an operation, replaying it while retries remain.
+ *
+ * @param options - Retry configuration, or undefined for a single attempt.
+ * @param operation - The unit of work, receiving the 1-based attempt number.
+ * @returns The operation's result.
+ * @throws The last error when every attempt fails.
+ */
+export declare function withRetry<T>(options: TransactionRetryOptions | undefined, operation: (attempt: number) => Promise<T>): Promise<T>;
+//# sourceMappingURL=manager.retry.d.ts.map

package/dist/manager/manager.retry.js

@@ -0,0 +1,46 @@
+/**
+ * Transaction retry.
+ *
+ * `TransactionOptions.retry` has always been part of the public contract;
+ * this is what honours it. Retries re-run the whole unit of work, because a
+ * transaction that failed cannot be resumed — only replayed.
+ *
+ * @module manager/manager.retry
+ */
+/** Delay before a given attempt, in milliseconds. */
+function delayFor(options, attempt) {
+    const base = options.delay ?? 0;
+    if (base <= 0)
+        return 0;
+    return options.backoff === "exponential" ? base * 2 ** (attempt - 1) : base;
+}
+/**
+ * Run an operation, replaying it while retries remain.
+ *
+ * @param options - Retry configuration, or undefined for a single attempt.
+ * @param operation - The unit of work, receiving the 1-based attempt number.
+ * @returns The operation's result.
+ * @throws The last error when every attempt fails.
+ */
+export async function withRetry(options, operation) {
+    const attempts = Math.max(0, options?.attempts ?? 0) + 1;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await operation(attempt);
+        }
+        catch (error) {
+            lastError = error;
+            const isLast = attempt === attempts;
+            const retryable = options?.shouldRetry?.(error, attempt) ?? true;
+            if (isLast || !retryable)
+                break;
+            const delay = delayFor(options, attempt);
+            if (delay > 0) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=manager.retry.js.map

package/dist/transaction/index.d.ts

@@ -1,7 +1,9 @@
 /**
- * Core Transaction implementation with state machine.
- *
- * @module transaction
+ * @zudojs/transactions — Transaction Barrel
  */
 export { createTransaction } from "./transaction.core.js";
+export { createNonTransactional, createParticipant, } from "./transaction.participant.js";
+export { canTransition, createTransitionFunction, isTerminal, } from "./transactionStateMachine.js";
+export { asSavepointHandle } from "./transaction.internal.js";
+export type { SavepointHandle } from "./transaction.internal.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/transaction/index.js

@@ -1,7 +1,8 @@
 /**
- * Core Transaction implementation with state machine.
- *
- * @module transaction
+ * @zudojs/transactions — Transaction Barrel
  */
 export { createTransaction } from "./transaction.core.js";
+export { createNonTransactional, createParticipant, } from "./transaction.participant.js";
+export { canTransition, createTransitionFunction, isTerminal, } from "./transactionStateMachine.js";
+export { asSavepointHandle } from "./transaction.internal.js";
 //# sourceMappingURL=index.js.map

package/dist/transaction/transaction.core.d.ts

@@ -2,8 +2,13 @@
  * Core Transaction implementation with state machine enforcement.
  */
 import type { Transaction, TransactionOptions } from "../transactionTypes/transaction.interface.js";
+import type { TransactionKind } from "../transactionTypes/transactionState.js";
 /**
  * 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 declare function createTransaction(options?: TransactionOptions, parentId?: string): Transaction;
+export declare function createTransaction(options?: TransactionOptions, parentId?: string, kind?: TransactionKind): Transaction;
 //# sourceMappingURL=transaction.core.d.ts.map