@zudojs/transactions 1.0.0 → 1.1.0

package/README.md

@@ -103,6 +103,15 @@ the transaction.
 - Committing a transaction that is not active throws rather than silently
   doing nothing. Only an already-committed transaction is a no-op.
 - A `nested` transaction rolls back to its savepoint, never to the connection.
+  Savepoints are always created on the connection, including when the
+  enclosing scope is itself a savepoint or a participant.
+- `begin()` and `run()` both honour `timeout`; completing a transaction through
+  `manager.commit()` / `manager.rollback()` releases its timer and registry entry.
+- Failures thrown by `afterCommit` callbacks never undo the commit; they are
+  reported to `hooks.onError` as an `AggregateError`.
+- `retry` replays only attempts that opened their own transaction. An attempt
+  that joined an enclosing transaction has marked it rollback-only and is not
+  replayed.
 
 ## Use Cases
 

package/dist/manager/manager.commit.js

@@ -110,6 +110,15 @@ export async function commitTransaction(transaction, adapter, hooks, emit = noop
         throw new TransactionCommitError(transaction.id, error);
     }
     emit(TRANSACTION_EVENTS.COMMITTED, transaction);
+    // afterCommit callbacks that threw did not undo the commit, but they
+    // used to fail silently. Report them without changing the outcome.
+    const callbackErrors = internals(transaction)._drainCallbackErrors();
+    if (callbackErrors.length > 0 && hooks?.onError) {
+        await hooks.onError({
+            transaction,
+            error: new AggregateError(callbackErrors, "after-commit callback failures"),
+        });
+    }
     if (hooks?.afterCommit)
         await hooks.afterCommit({ transaction });
 }

package/dist/manager/manager.core.d.ts

@@ -41,7 +41,13 @@ export declare function createTransactionManager(options: TransactionManagerOpti
      * participant marks the enclosing transaction rollback-only instead.
      */
     run<T>(callback: (transaction: Transaction) => Promise<T>, opts?: TransactionOptions): Promise<T>;
-    /** Commit a transaction. Participants and committed transactions are no-ops. */
+    /**
+     * 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.
+     */
     commit(transaction: Transaction): Promise<void>;
     /** Roll back a transaction, or mark the joined transaction rollback-only. */
     rollback(transaction: Transaction, reason?: unknown): Promise<void>;

package/dist/manager/manager.core.js

@@ -5,11 +5,16 @@
  */
 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.
  */
@@ -17,17 +22,41 @@ export function createTransactionManager(options) {
     const { adapter, hooks, registry } = options;
     const context = options.context ?? getDefaultContext();
     const emit = createEmitter(options.onEvent);
-    /** Arms the timeout, returning a disposer that always clears the timer. */
+    /** 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 () => { };
+            return;
         const timer = setTimeout(() => {
+            timers.delete(transaction.id);
             internals(transaction)._markTimedOut();
             transaction.markRollbackOnly("timeout");
             emit(TRANSACTION_EVENTS.TIMED_OUT, transaction);
         }, timeout);
-        return () => clearTimeout(timer);
+        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 {
         /**
@@ -49,8 +78,9 @@ export function createTransactionManager(options) {
                 hooks,
                 emit,
             });
-            if (transaction.kind === "root" || transaction.kind === "savepoint") {
+            if (owns(transaction)) {
                 registry?.register(transaction);
+                armTimeout(transaction);
             }
             return transaction;
         },
@@ -62,10 +92,21 @@ export function createTransactionManager(options) {
          * participant marks the enclosing transaction rollback-only instead.
          */
         async run(callback, opts) {
-            return withRetry(opts?.retry, async () => {
+            // 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);
-                const owned = transaction.kind === "root" || transaction.kind === "savepoint";
-                const disposeTimeout = owned ? armTimeout(transaction) : () => { };
+                joined = transaction.kind === "participant";
                 const body = async () => {
                     try {
                         const result = await callback(transaction);
@@ -87,9 +128,7 @@ export function createTransactionManager(options) {
                         throw error;
                     }
                     finally {
-                        disposeTimeout();
-                        if (owned)
-                            registry?.unregister(transaction.id);
+                        release(transaction);
                     }
                 };
                 return transaction.kind === "none"
@@ -97,13 +136,31 @@ export function createTransactionManager(options) {
                     : context.run(transaction, body);
             });
         },
-        /** Commit a transaction. Participants and committed transactions are no-ops. */
+        /**
+         * 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, emit);
+            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, emit);
+            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() {

package/dist/manager/manager.propagation.js

@@ -9,7 +9,7 @@
  */
 import { createTransaction } from "../transaction/transaction.core.js";
 import { createNonTransactional, createParticipant, } from "../transaction/transaction.participant.js";
-import { internals } from "../transaction/transaction.internal.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";
@@ -60,7 +60,9 @@ async function beginSavepoint(parent, context) {
     if (hooks?.beforeBegin)
         await hooks.beforeBegin({ transaction: child });
     const savepoint = `sp_${child.id}`;
-    const parentHandle = internals(parent)._getHandle();
+    // 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 });

package/dist/transaction/transaction.core.js

@@ -38,6 +38,7 @@ export function createTransaction(options = {}, parentId, kind = "root") {
     let timedOut = false;
     const afterCommitCallbacks = [];
     const afterRollbackCallbacks = [];
+    let callbackErrors = [];
     let handle;
     const transition = createTransitionFunction(() => state, (next) => {
         state = next;
@@ -91,7 +92,9 @@ export function createTransaction(options = {}, parentId, kind = "root") {
             transition("committing");
             transition("committed");
             afterRollbackCallbacks.length = 0;
-            await runCallbacks(afterCommitCallbacks);
+            // The commit stands whatever the callbacks do; their failures are
+            // kept for the manager to report instead of being dropped.
+            callbackErrors = await runCallbacks(afterCommitCallbacks);
         },
         async rollback(reason) {
             if (state === "rolled_back" || state === "failed")
@@ -137,6 +140,7 @@ export function createTransaction(options = {}, parentId, kind = "root") {
             timedOut = true;
         },
         _getRollbackOnlyReason: () => rollbackOnlyReason,
+        _drainCallbackErrors: () => callbackErrors.splice(0),
     });
 }
 //# sourceMappingURL=transaction.core.js.map

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

@@ -31,6 +31,14 @@ export interface TransactionInternals {
     _markTimedOut(): void;
     /** The reason supplied to `markRollbackOnly`, if any. */
     _getRollbackOnlyReason(): unknown;
+    /**
+     * Take the failures collected from `afterCommit` callbacks.
+     *
+     * The transaction stays committed when a callback throws — nothing can
+     * undo the adapter commit — but the failures used to vanish without a
+     * trace. The manager drains them and reports them to `hooks.onError`.
+     */
+    _drainCallbackErrors(): unknown[];
 }
 /**
  * Access the manager-only surface of a transaction.
@@ -55,6 +63,18 @@ export interface SavepointHandle {
     /** The savepoint name created on that handle. */
     readonly savepoint: string;
 }
+/**
+ * Resolve the adapter connection a transaction runs on.
+ *
+ * A savepoint's handle names its parent connection; a participant's handle
+ * is the joined transaction's. A savepoint opened inside another savepoint
+ * used to be created against the outer *savepoint handle* rather than the
+ * connection, which no adapter can act on.
+ *
+ * @param transaction - Any transaction created by this package.
+ * @returns The connection-level adapter handle.
+ */
+export declare function connectionHandle(transaction: Transaction): unknown;
 /**
  * Narrow an adapter handle to a savepoint handle.
  *

package/dist/transaction/transaction.internal.js

@@ -48,6 +48,22 @@ export function attachInternals(transaction, operations) {
     });
     return transaction;
 }
+/**
+ * Resolve the adapter connection a transaction runs on.
+ *
+ * A savepoint's handle names its parent connection; a participant's handle
+ * is the joined transaction's. A savepoint opened inside another savepoint
+ * used to be created against the outer *savepoint handle* rather than the
+ * connection, which no adapter can act on.
+ *
+ * @param transaction - Any transaction created by this package.
+ * @returns The connection-level adapter handle.
+ */
+export function connectionHandle(transaction) {
+    const handle = internals(transaction)._getHandle();
+    const savepoint = asSavepointHandle(handle);
+    return savepoint ? savepoint.parent : handle;
+}
 /**
  * Narrow an adapter handle to a savepoint handle.
  *

package/dist/transaction/transaction.participant.js

@@ -10,7 +10,7 @@
  * @module transaction/transaction.participant
  */
 import { createTransaction } from "./transaction.core.js";
-import { internals } from "./transaction.internal.js";
+import { attachInternals, internals } from "./transaction.internal.js";
 /**
  * Create a handle that joins an in-progress transaction.
  *
@@ -18,7 +18,7 @@ import { internals } from "./transaction.internal.js";
  * @returns A participant handle delegating to `parent`.
  */
 export function createParticipant(parent) {
-    return Object.freeze({
+    const participant = {
         get id() {
             return parent.id;
         },
@@ -61,7 +61,25 @@ export function createParticipant(parent) {
         afterRollback(callback) {
             parent.afterRollback(callback);
         },
+    };
+    // A participant owns nothing, but the manager still has to reach the
+    // adapter handle of the transaction it joined: a `nested` run inside a
+    // participant scope used to throw "Transaction was not created by
+    // @zudojs/transactions" because the frozen participant carried no
+    // internals at all. Reads delegate to the joined transaction; writes
+    // are refused, since only the owner may drive its state.
+    const refuse = () => {
+        throw new TypeError("A participant does not own the transaction it joined and cannot modify it.");
+    };
+    attachInternals(participant, {
+        _setHandle: refuse,
+        _getHandle: () => internals(parent)._getHandle(),
+        _transition: refuse,
+        _markTimedOut: refuse,
+        _getRollbackOnlyReason: () => internals(parent)._getRollbackOnlyReason(),
+        _drainCallbackErrors: () => [],
     });
+    return Object.freeze(participant);
 }
 /**
  * Create a handle for a deliberately non-transactional scope.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/transactions",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Transaction lifecycle and coordination with state machine, AsyncLocalStorage context propagation, savepoints, hooks, and adapter abstraction.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,7 +25,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/errors": "1.0.1"
   },
   "engines": {
     "node": ">=24.0.0"