@zudojs/transactions 1.2.1 → 1.3.0

package/README.md

@@ -17,9 +17,9 @@ npm install @zudojs/transactions
 ## Quick Start
 
 ```typescript
-import { createTransactionManager } from "@zudojs/transactions";
+import { createTransactionManager, type TransactionManager } from "@zudojs/transactions";
 
-const manager = createTransactionManager({ adapter: databaseAdapter });
+const manager: TransactionManager = createTransactionManager({ adapter: databaseAdapter });
 
 // `run` opens a transaction, commits on success, rolls back on a throw.
 const orderId = await manager.run(async (transaction) => {
@@ -166,6 +166,15 @@ the transaction.
   `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`.
+- A finished transaction is never joined. `afterCommit`/`afterRollback`
+  callbacks and hooks run in the scope that enclosed the transaction (the
+  outer transaction of a `requires_new`, otherwise none), and
+  `manager.getCurrent()`, `getCurrentHandle()`, `currentTransactionHandle()`
+  and `begin()` all read the scope through `currentTransaction()`, which
+  ignores a committed, rolled-back or failed transaction still held by the
+  context. Work started from an after-commit callback, or by a timer armed
+  inside the callback that fires after the commit, therefore starts a new
+  root transaction instead of a participant on a closed one.
 - `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.

package/dist/adapter/adapter.core.d.ts

@@ -16,4 +16,3 @@ export declare function createInMemoryAdapter(): TransactionAdapter;
  * Create an adapter with custom capabilities.
  */
 export declare function createAdapter(implementation: TransactionAdapter, capabilities: TransactionAdapterCapabilities): TransactionAdapter;
-//# sourceMappingURL=adapter.core.d.ts.map

package/dist/adapter/adapter.core.js

@@ -80,4 +80,3 @@ export function createAdapter(implementation, capabilities) {
         capabilities: Object.freeze(capabilities),
     };
 }
-//# sourceMappingURL=adapter.core.js.map

package/dist/adapter/index.d.ts

@@ -4,4 +4,3 @@
  * @module adapter
  */
 export { createInMemoryAdapter, createAdapter } from "./adapter.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.js

@@ -4,4 +4,3 @@
  * @module adapter
  */
 export { createInMemoryAdapter, createAdapter } from "./adapter.core.js";
-//# sourceMappingURL=index.js.map

package/dist/context/context.core.d.ts

@@ -3,6 +3,7 @@
  *
  * @module context/context
  */
+import type { Transaction } from "../transactionTypes/transaction.interface.js";
 import type { TransactionContext } from "../transactionTypes/transactionAdapter.js";
 /**
  * Create a transaction context backed by AsyncLocalStorage.
@@ -16,4 +17,17 @@ export declare function getDefaultContext(): TransactionContext;
  * Reset the default context (useful for testing).
  */
 export declare function resetDefaultContext(): void;
-//# sourceMappingURL=context.core.d.ts.map
+/**
+ * The transaction in scope for the current async execution: the context's
+ * stored transaction unless it has already committed, rolled back or
+ * failed.
+ *
+ * A store outlives the transaction it holds. Work started while the store
+ * is active (`afterCommit` callbacks, timers armed inside the callback,
+ * jobs queued from it) inherits it, and `context.get()` then hands back a
+ * finished transaction that a new `run()` would join as a participant and
+ * fail on. The manager consults this instead, so such work starts afresh.
+ *
+ * @param context - The context to read; defaults to the default context.
+ */
+export declare function currentTransaction(context?: TransactionContext): Transaction | undefined;

package/dist/context/context.core.js

@@ -4,6 +4,7 @@
  * @module context/context
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isTerminal } from "../transaction/transactionStateMachine.js";
 /**
  * Create a transaction context backed by AsyncLocalStorage.
  */
@@ -38,4 +39,20 @@ export function getDefaultContext() {
 export function resetDefaultContext() {
     defaultContext = undefined;
 }
-//# sourceMappingURL=context.core.js.map
+/**
+ * The transaction in scope for the current async execution: the context's
+ * stored transaction unless it has already committed, rolled back or
+ * failed.
+ *
+ * A store outlives the transaction it holds. Work started while the store
+ * is active (`afterCommit` callbacks, timers armed inside the callback,
+ * jobs queued from it) inherits it, and `context.get()` then hands back a
+ * finished transaction that a new `run()` would join as a participant and
+ * fail on. The manager consults this instead, so such work starts afresh.
+ *
+ * @param context - The context to read; defaults to the default context.
+ */
+export function currentTransaction(context = getDefaultContext()) {
+    const transaction = context.get();
+    return transaction && !isTerminal(transaction.state) ? transaction : undefined;
+}

package/dist/context/context.handle.d.ts

@@ -28,9 +28,9 @@ export declare function getTransactionHandle<THandle = unknown>(transaction: Tra
  *
  * Uses the default context unless one is supplied; pass the same context
  * the manager was created with when it was given a custom one (or call the
- * manager's `getCurrentHandle()`).
+ * manager's `getCurrentHandle()`). A finished transaction still held by
+ * the store yields `undefined`; see `currentTransaction`.
  *
  * @typeParam THandle - The handle type your adapter's `begin()` returns.
  */
 export declare function currentTransactionHandle<THandle = unknown>(context?: TransactionContext): THandle | undefined;
-//# sourceMappingURL=context.handle.d.ts.map

package/dist/context/context.handle.js

@@ -4,7 +4,7 @@
  * @module context/context.handle
  */
 import { connectionHandle } from "../transaction/transaction.internal.js";
-import { getDefaultContext } from "./context.core.js";
+import { currentTransaction, getDefaultContext } from "./context.core.js";
 /**
  * The adapter handle a transaction runs on: whatever the adapter's
  * `begin()` returned (for example a database client or connection bound to
@@ -30,12 +30,12 @@ export function getTransactionHandle(transaction) {
  *
  * Uses the default context unless one is supplied; pass the same context
  * the manager was created with when it was given a custom one (or call the
- * manager's `getCurrentHandle()`).
+ * manager's `getCurrentHandle()`). A finished transaction still held by
+ * the store yields `undefined`; see `currentTransaction`.
  *
  * @typeParam THandle - The handle type your adapter's `begin()` returns.
  */
 export function currentTransactionHandle(context = getDefaultContext()) {
-    const transaction = context.get();
+    const transaction = currentTransaction(context);
     return transaction ? getTransactionHandle(transaction) : undefined;
 }
-//# sourceMappingURL=context.handle.js.map

package/dist/context/index.d.ts

@@ -3,6 +3,5 @@
  *
  * @module context
  */
-export { createTransactionContext, getDefaultContext, resetDefaultContext, } from "./context.core.js";
+export { createTransactionContext, currentTransaction, getDefaultContext, resetDefaultContext, } from "./context.core.js";
 export { getTransactionHandle, currentTransactionHandle, } from "./context.handle.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/context/index.js

@@ -3,6 +3,5 @@
  *
  * @module context
  */
-export { createTransactionContext, getDefaultContext, resetDefaultContext, } from "./context.core.js";
+export { createTransactionContext, currentTransaction, getDefaultContext, resetDefaultContext, } from "./context.core.js";
 export { getTransactionHandle, currentTransactionHandle, } from "./context.handle.js";
-//# sourceMappingURL=index.js.map

package/dist/hooks/hooks.core.d.ts

@@ -8,4 +8,3 @@ import type { TransactionHooks } from "../transactionTypes/transactionHooks.js";
  * Merge multiple hook sets into one. Later hooks run after earlier ones.
  */
 export declare function mergeHooks(...hookSets: readonly TransactionHooks[]): TransactionHooks;
-//# sourceMappingURL=hooks.core.d.ts.map

package/dist/hooks/hooks.core.js

@@ -75,4 +75,3 @@ export function mergeHooks(...hookSets) {
     }
     return merged;
 }
-//# sourceMappingURL=hooks.core.js.map

package/dist/hooks/index.d.ts

@@ -4,4 +4,3 @@
  * @module hooks
  */
 export { mergeHooks } from "./hooks.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.js

@@ -4,4 +4,3 @@
  * @module hooks
  */
 export { mergeHooks } from "./hooks.core.js";
-//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -17,4 +17,3 @@ export * from "./hooks/index.js";
 export * from "./registry/index.js";
 export * from "./utils/index.js";
 export { createTransactionManager, createEmitter, type TransactionEmitter, type TransactionManagerOptions, } from "./manager/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -17,4 +17,3 @@ export * from "./hooks/index.js";
 export * from "./registry/index.js";
 export * from "./utils/index.js";
 export { createTransactionManager, createEmitter, } from "./manager/index.js";
-//# sourceMappingURL=index.js.map

package/dist/manager/index.d.ts

@@ -11,4 +11,3 @@ export { assertAdapterSupports } from "./manager.capabilities.js";
 export { withRetry } from "./manager.retry.js";
 export { createEmitter } from "./manager.events.js";
 export type { TransactionEmitter } from "./manager.events.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/manager/index.js

@@ -9,4 +9,3 @@ export { resolvePropagation, suspendsTransaction, } from "./manager.propagation.
 export { assertAdapterSupports } from "./manager.capabilities.js";
 export { withRetry } from "./manager.retry.js";
 export { createEmitter } from "./manager.events.js";
-//# sourceMappingURL=index.js.map

package/dist/manager/manager.capabilities.d.ts

@@ -23,4 +23,3 @@ import type { TransactionAdapter } from "../transactionTypes/transactionAdapter.
  * @throws {TransactionCapabilityError} when another capability is missing.
  */
 export declare function assertAdapterSupports(adapter: TransactionAdapter, options: TransactionOptions | undefined): void;
-//# sourceMappingURL=manager.capabilities.d.ts.map

package/dist/manager/manager.capabilities.js

@@ -38,4 +38,3 @@ export function assertAdapterSupports(adapter, options) {
         throw new TransactionCapabilityError("transaction timeouts");
     }
 }
-//# sourceMappingURL=manager.capabilities.js.map

package/dist/manager/manager.commit.d.ts

@@ -39,4 +39,3 @@ export declare function commitTransaction(transaction: Transaction, adapter: Tra
  * @throws {TransactionRollbackError} when the adapter refuses the rollback.
  */
 export declare function rollbackTransaction(transaction: Transaction, adapter: TransactionAdapter, reason?: unknown, hooks?: TransactionHooks, emit?: TransactionEmitter): Promise<void>;
-//# sourceMappingURL=manager.commit.d.ts.map

package/dist/manager/manager.commit.js

@@ -126,7 +126,10 @@ export async function commitTransaction(transaction, adapter, hooks, emit = noop
         });
     }
     if (hooks?.afterCommit && transaction.kind !== "savepoint") {
-        await hooks.afterCommit({ transaction });
+        // Detached: the transaction is finished, so work the hook starts must
+        // not inherit its context (see TransactionInternals._detach).
+        const afterCommit = hooks.afterCommit;
+        await internals(transaction)._detach(() => afterCommit({ transaction }));
     }
 }
 /**
@@ -171,7 +174,8 @@ export async function rollbackTransaction(transaction, adapter, reason, hooks, e
         });
     }
     emit(TRANSACTION_EVENTS.ROLLED_BACK, transaction, reason);
-    if (hooks?.afterRollback)
-        await hooks.afterRollback({ transaction });
+    if (hooks?.afterRollback) {
+        const afterRollback = hooks.afterRollback;
+        await internals(transaction)._detach(() => afterRollback({ transaction }));
+    }
 }
-//# sourceMappingURL=manager.commit.js.map

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

@@ -3,9 +3,9 @@
  *
  * @module manager/manager
  */
-import type { Transaction, TransactionOptions } from "../transactionTypes/transaction.interface.js";
 import type { TransactionAdapter, TransactionContext } from "../transactionTypes/transactionAdapter.js";
 import type { TransactionEventHandler, TransactionHooks, TransactionRegistry } from "../transactionTypes/transactionHooks.js";
+import type { TransactionManager } from "../transactionTypes/transactionManager.js";
 /** Options for creating a transaction manager. */
 export interface TransactionManagerOptions {
     readonly adapter: TransactionAdapter;
@@ -23,47 +23,12 @@ export interface TransactionManagerOptions {
 }
 /**
  * Create a transaction manager.
+ *
+ * The manager reads the transaction in scope through `currentTransaction`,
+ * so a transaction that has finished but whose context is still active
+ * (inside an `afterCommit` callback, or in a timer armed during the
+ * transaction) is never joined; a new `run()` there opens a fresh
+ * transaction. After-commit and after-rollback callbacks and hooks run in
+ * the scope that enclosed the transaction, not inside its context.
  */
-export declare function createTransactionManager(options: TransactionManagerOptions): {
-    /**
-     * 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.
-     */
-    begin(opts?: TransactionOptions): Promise<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.
-     *
-     * When the transaction times out, `transaction.signal` aborts and this
-     * stops waiting for the callback: the transaction is rolled back and
-     * the call rejects with `TransactionTimeoutError`. An error raised
-     * after a successful commit (for example by an `afterCommit` hook) is
-     * rethrown without attempting a rollback.
-     */
-    run<T>(callback: (transaction: Transaction) => Promise<T>, opts?: TransactionOptions): Promise<T>;
-    /**
-     * 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>;
-    /** The transaction in scope for the current async execution, if any. */
-    getCurrent(): Transaction | undefined;
-    /**
-     * The adapter handle (what `adapter.begin()` returned) of the
-     * transaction in scope for the current async execution, or `undefined`
-     * outside a transaction. See `getTransactionHandle`.
-     */
-    getCurrentHandle<THandle = unknown>(): THandle | undefined;
-};
-//# sourceMappingURL=manager.core.d.ts.map
+export declare function createTransactionManager(options: TransactionManagerOptions): TransactionManager;

package/dist/manager/manager.core.js

@@ -3,8 +3,8 @@
  *
  * @module manager/manager
  */
-import { getDefaultContext } from "../context/context.core.js";
-import { internals } from "../transaction/transaction.internal.js";
+import { currentTransaction, 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 { getTransactionHandle } from "../context/context.handle.js";
@@ -19,6 +19,13 @@ function isFinished(transaction) {
 }
 /**
  * Create a transaction manager.
+ *
+ * The manager reads the transaction in scope through `currentTransaction`,
+ * so a transaction that has finished but whose context is still active
+ * (inside an `afterCommit` callback, or in a timer armed during the
+ * transaction) is never joined; a new `run()` there opens a fresh
+ * transaction. After-commit and after-rollback callbacks and hooks run in
+ * the scope that enclosed the transaction, not inside its context.
  */
 export function createTransactionManager(options) {
     const { adapter, hooks, registry } = options;
@@ -70,15 +77,20 @@ export function createTransactionManager(options) {
          */
         async begin(opts) {
             const propagation = opts?.propagation ?? "required";
-            const current = suspendsTransaction(propagation)
-                ? undefined
-                : context.get();
+            const enclosing = currentTransaction(context);
+            const current = suspendsTransaction(propagation) ? undefined : enclosing;
+            // Post-completion work returns to whatever enclosed this transaction:
+            // the outer transaction of a `requires_new`, or no transaction at all.
+            const detach = enclosing
+                ? (work) => context.run(enclosing, work)
+                : (work) => context.exit(work);
             const transaction = await resolvePropagation(propagation, {
                 current,
                 opts,
                 adapter,
                 hooks,
                 emit,
+                detach,
             });
             if (owns(transaction)) {
                 registry?.register(transaction);
@@ -172,9 +184,12 @@ export function createTransactionManager(options) {
                     release(transaction);
             }
         },
-        /** The transaction in scope for the current async execution, if any. */
+        /**
+         * The transaction in scope for the current async execution, if any. A
+         * finished transaction still held by the context is not in scope.
+         */
         getCurrent() {
-            return context.get();
+            return currentTransaction(context);
         },
         /**
          * The adapter handle (what `adapter.begin()` returned) of the
@@ -182,9 +197,8 @@ export function createTransactionManager(options) {
          * outside a transaction. See `getTransactionHandle`.
          */
         getCurrentHandle() {
-            const current = context.get();
+            const current = currentTransaction(context);
             return current ? getTransactionHandle(current) : undefined;
         },
     };
 }
-//# sourceMappingURL=manager.core.js.map

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

@@ -28,4 +28,3 @@ export declare const noopEmitter: TransactionEmitter;
  */
 export declare function createEmitter(handler: TransactionEventHandler | undefined): TransactionEmitter;
 export { TRANSACTION_EVENTS };
-//# sourceMappingURL=manager.events.d.ts.map

package/dist/manager/manager.events.js

@@ -42,4 +42,3 @@ export function createEmitter(handler) {
     };
 }
 export { TRANSACTION_EVENTS };
-//# sourceMappingURL=manager.events.js.map

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

@@ -11,6 +11,7 @@ import type { Transaction, TransactionOptions } from "../transactionTypes/transa
 import type { TransactionAdapter } from "../transactionTypes/transactionAdapter.js";
 import type { TransactionHooks } from "../transactionTypes/transactionHooks.js";
 import type { TransactionPropagation } from "../transactionTypes/transactionState.js";
+import { type TransactionDetach } from "../transaction/transaction.internal.js";
 import type { TransactionEmitter } from "./manager.events.js";
 /** Everything a propagation branch may need. */
 export interface PropagationContext {
@@ -20,6 +21,12 @@ export interface PropagationContext {
     readonly hooks: TransactionHooks | undefined;
     /** Lifecycle event emitter. Defaults to discarding events. */
     readonly emit?: TransactionEmitter;
+    /**
+     * Runs after-commit / after-rollback work in the scope that enclosed the
+     * new transaction, so it does not inherit the finished transaction's
+     * context. Defaults to running the work in place.
+     */
+    readonly detach?: TransactionDetach;
 }
 /**
  * Open a root transaction against the adapter and make it active.
@@ -40,4 +47,3 @@ export declare function beginRoot(context: PropagationContext, parentId?: string
 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

@@ -9,7 +9,7 @@
  */
 import { createTransaction } from "../transaction/transaction.core.js";
 import { createNonTransactional, createParticipant, } from "../transaction/transaction.participant.js";
-import { connectionHandle, internals, } from "../transaction/transaction.internal.js";
+import { connectionHandle, internals, runInPlace, } 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";
@@ -24,7 +24,7 @@ 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");
+    const transaction = createTransaction(opts, parentId, "root", undefined, context.detach ?? runInPlace);
     if (hooks?.beforeBegin)
         await hooks.beforeBegin({ transaction });
     try {
@@ -56,7 +56,7 @@ async function beginSavepoint(parent, context) {
         // rule violation, and TransactionCapabilityError names what is missing.
         throw new TransactionCapabilityError("savepoints, required by nested transactions");
     }
-    const child = createTransaction(opts, parent.id, "savepoint", parent);
+    const child = createTransaction(opts, parent.id, "savepoint", parent, context.detach ?? runInPlace);
     if (hooks?.beforeBegin)
         await hooks.beforeBegin({ transaction: child });
     const savepoint = `sp_${child.id}`;
@@ -119,4 +119,3 @@ export async function resolvePropagation(propagation, context) {
 export function suspendsTransaction(propagation) {
     return propagation === "not_supported" || propagation === "requires_new";
 }
-//# sourceMappingURL=manager.propagation.js.map

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

@@ -17,4 +17,3 @@ import type { TransactionRetryOptions } from "../transactionTypes/transaction.in
  * @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

@@ -43,4 +43,3 @@ export async function withRetry(options, operation) {
     }
     throw lastError;
 }
-//# sourceMappingURL=manager.retry.js.map

package/dist/registry/index.d.ts

@@ -4,4 +4,3 @@
  * @module registry
  */
 export { createTransactionRegistry } from "./registry.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.js

@@ -4,4 +4,3 @@
  * @module registry
  */
 export { createTransactionRegistry } from "./registry.core.js";
-//# sourceMappingURL=index.js.map

package/dist/registry/registry.core.d.ts

@@ -8,4 +8,3 @@ import type { TransactionRegistry } from "../transactionTypes/transactionHooks.j
  * Create an in-memory transaction registry.
  */
 export declare function createTransactionRegistry(): TransactionRegistry;
-//# sourceMappingURL=registry.core.d.ts.map

package/dist/registry/registry.core.js

@@ -23,4 +23,3 @@ export function createTransactionRegistry() {
         },
     };
 }
-//# sourceMappingURL=registry.core.js.map

package/dist/transaction/index.d.ts

@@ -6,4 +6,3 @@ export { createNonTransactional, createParticipant, } from "./transaction.partic
 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

@@ -5,4 +5,3 @@ 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

@@ -3,6 +3,7 @@
  */
 import type { Transaction, TransactionOptions } from "../transactionTypes/transaction.interface.js";
 import type { TransactionKind } from "../transactionTypes/transactionState.js";
+import { type TransactionDetach } from "./transaction.internal.js";
 /**
  * Create a new Transaction instance.
  *
@@ -11,6 +12,7 @@ import type { TransactionKind } from "../transactionTypes/transactionState.js";
  * @param kind - How this handle relates to the adapter transaction.
  * @param parent - The enclosing transaction of a savepoint. Its callbacks
  *   are deferred to `parent` on release instead of running.
+ * @param detach - Runs after-commit / after-rollback work in the scope
+ *   that enclosed the transaction. Defaults to running it in place.
  */
-export declare function createTransaction(options?: TransactionOptions, parentId?: string, kind?: TransactionKind, parent?: Transaction): Transaction;
-//# sourceMappingURL=transaction.core.d.ts.map
+export declare function createTransaction(options?: TransactionOptions, parentId?: string, kind?: TransactionKind, parent?: Transaction, detach?: TransactionDetach): Transaction;

package/dist/transaction/transaction.core.js

@@ -4,7 +4,7 @@
 import { randomBytes } from "node:crypto";
 import { TransactionRollbackError, TransactionRollbackOnlyError, TransactionStateError, TransactionTimeoutError, } from "../transactionErrors/transactionError.types.js";
 import { canTransition, createTransitionFunction, } from "./transactionStateMachine.js";
-import { attachInternals } from "./transaction.internal.js";
+import { attachInternals, runInPlace, } from "./transaction.internal.js";
 import { deferCallbacksToParent } from "./transaction.savepoint.js";
 /**
  * Generate a unique transaction ID.
@@ -12,12 +12,15 @@ import { deferCallbacksToParent } from "./transaction.savepoint.js";
 function generateTransactionId() {
     return `txn_${randomBytes(16).toString("hex")}`;
 }
-/** Runs callbacks in order, collecting failures rather than aborting. */
-async function runCallbacks(callbacks) {
+/**
+ * Runs callbacks in order, collecting failures rather than aborting. Each
+ * runs detached from the finished transaction's context.
+ */
+async function runCallbacks(callbacks, detach) {
     const errors = [];
     for (const callback of callbacks.splice(0)) {
         try {
-            await callback();
+            await detach(callback);
         }
         catch (error) {
             errors.push(error);
@@ -33,8 +36,10 @@ async function runCallbacks(callbacks) {
  * @param kind - How this handle relates to the adapter transaction.
  * @param parent - The enclosing transaction of a savepoint. Its callbacks
  *   are deferred to `parent` on release instead of running.
+ * @param detach - Runs after-commit / after-rollback work in the scope
+ *   that enclosed the transaction. Defaults to running it in place.
  */
-export function createTransaction(options = {}, parentId, kind = "root", parent) {
+export function createTransaction(options = {}, parentId, kind = "root", parent, detach = runInPlace) {
     let state = "pending";
     let rollbackOnly = false;
     let rollbackOnlyReason;
@@ -106,7 +111,7 @@ export function createTransaction(options = {}, parentId, kind = "root", parent)
             afterRollbackCallbacks.length = 0;
             // The commit stands whatever the callbacks do; their failures are
             // kept for the manager to report instead of being dropped.
-            callbackErrors = await runCallbacks(afterCommitCallbacks);
+            callbackErrors = await runCallbacks(afterCommitCallbacks, detach);
         },
         async rollback(reason) {
             if (state === "rolled_back" || state === "failed")
@@ -120,7 +125,7 @@ export function createTransaction(options = {}, parentId, kind = "root", parent)
             transition("rolling_back");
             transition("rolled_back");
             afterCommitCallbacks.length = 0;
-            const errors = await runCallbacks(afterRollbackCallbacks);
+            const errors = await runCallbacks(afterRollbackCallbacks, detach);
             if (errors.length > 0) {
                 throw new TransactionRollbackError(id, {
                     cause: new AggregateError(errors, "after-rollback callback failures"),
@@ -154,6 +159,6 @@ export function createTransaction(options = {}, parentId, kind = "root", parent)
         },
         _getRollbackOnlyReason: () => rollbackOnlyReason,
         _drainCallbackErrors: () => callbackErrors.splice(0),
+        _detach: detach,
     });
 }
-//# sourceMappingURL=transaction.core.js.map

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

@@ -39,7 +39,23 @@ export interface TransactionInternals {
      * trace. The manager drains them and reports them to `hooks.onError`.
      */
     _drainCallbackErrors(): unknown[];
+    /**
+     * Run work in the scope that enclosed this transaction, rather than in
+     * the transaction's own context.
+     *
+     * After-commit and after-rollback callbacks and hooks run once the
+     * transaction has finished, yet they used to run with its context still
+     * active, so anything they started (a timer, a queued job) inherited a
+     * finished transaction and joined it. The manager supplies this from the
+     * context the transaction was begun in; a transaction created without a
+     * manager runs the work in place.
+     */
+    _detach<T>(work: () => Promise<T>): Promise<T>;
 }
+/** Runs post-completion work in the scope enclosing a transaction. */
+export type TransactionDetach = <T>(work: () => Promise<T>) => Promise<T>;
+/** The detach used when no manager supplied one: run the work in place. */
+export declare const runInPlace: TransactionDetach;
 /**
  * Access the manager-only surface of a transaction.
  *
@@ -82,4 +98,3 @@ export declare function connectionHandle(transaction: Transaction): unknown;
  * @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

@@ -17,6 +17,8 @@
  * steal the adapter handle.
  */
 export const TRANSACTION_INTERNALS = Symbol("zudojs.transaction.internals");
+/** The detach used when no manager supplied one: run the work in place. */
+export const runInPlace = (work) => work();
 /**
  * Access the manager-only surface of a transaction.
  *
@@ -79,4 +81,3 @@ export function asSavepointHandle(handle) {
     }
     return undefined;
 }
-//# sourceMappingURL=transaction.internal.js.map

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

@@ -28,4 +28,3 @@ export declare function createParticipant(parent: Transaction): Transaction;
  * @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

@@ -81,6 +81,7 @@ export function createParticipant(parent) {
         _markTimedOut: refuse,
         _getRollbackOnlyReason: () => internals(parent)._getRollbackOnlyReason(),
         _drainCallbackErrors: () => [],
+        _detach: (work) => internals(parent)._detach(work),
     });
     return Object.freeze(participant);
 }
@@ -99,4 +100,3 @@ export function createNonTransactional(options = {}) {
     internals(txn)._transition("active");
     return txn;
 }
-//# sourceMappingURL=transaction.participant.js.map

package/dist/transaction/transaction.savepoint.d.ts

@@ -21,4 +21,3 @@ import type { Transaction } from "../transactionTypes/transaction.interface.js";
  * @param afterRollback - The savepoint's pending after-rollback callbacks.
  */
 export declare function deferCallbacksToParent(parent: Transaction, afterCommit: Array<() => Promise<void>>, afterRollback: Array<() => Promise<void>>): void;
-//# sourceMappingURL=transaction.savepoint.d.ts.map

package/dist/transaction/transaction.savepoint.js

@@ -26,4 +26,3 @@ export function deferCallbacksToParent(parent, afterCommit, afterRollback) {
         parent.afterRollback(callback);
     }
 }
-//# sourceMappingURL=transaction.savepoint.js.map

package/dist/transaction/transactionStateMachine.d.ts

@@ -16,4 +16,3 @@ export declare function createTransitionFunction(getState: () => TransactionStat
 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

@@ -38,4 +38,3 @@ export function canTransition(from, to) {
 export function isTerminal(state) {
     return (VALID_TRANSITIONS[state]?.length ?? 0) === 0;
 }
-//# sourceMappingURL=transactionStateMachine.js.map

package/dist/transactionErrors/index.d.ts

@@ -3,4 +3,3 @@
  */
 export { TransactionError, type TransactionErrorOptions, } from "./transactionError.base.js";
 export { TransactionStateError, TransactionTimeoutError, TransactionCommitError, TransactionRollbackError, TransactionRollbackOnlyError, TransactionAdapterError, TransactionPropagationError, TransactionIsolationError, SavepointError, TransactionRequiredError, TransactionUnexpectedError, TransactionCapabilityError, } from "./transactionError.types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/transactionErrors/index.js

@@ -3,4 +3,3 @@
  */
 export { TransactionError, } from "./transactionError.base.js";
 export { TransactionStateError, TransactionTimeoutError, TransactionCommitError, TransactionRollbackError, TransactionRollbackOnlyError, TransactionAdapterError, TransactionPropagationError, TransactionIsolationError, SavepointError, TransactionRequiredError, TransactionUnexpectedError, TransactionCapabilityError, } from "./transactionError.types.js";
-//# sourceMappingURL=index.js.map

package/dist/transactionErrors/transactionError.base.d.ts

@@ -6,4 +6,3 @@
  * it from. Name, constructor, `code` defaults and category are unchanged.
  */
 export { TransactionError, type TransactionErrorOptions } from "@zudojs/errors";
-//# sourceMappingURL=transactionError.base.d.ts.map

package/dist/transactionErrors/transactionError.base.js

@@ -6,4 +6,3 @@
  * it from. Name, constructor, `code` defaults and category are unchanged.
  */
 export { TransactionError } from "@zudojs/errors";
-//# sourceMappingURL=transactionError.base.js.map

package/dist/transactionErrors/transactionError.types.d.ts

@@ -6,4 +6,3 @@
  * across both import paths.
  */
 export { TransactionStateError, TransactionTimeoutError, TransactionCommitError, TransactionRollbackError, TransactionRollbackOnlyError, TransactionAdapterError, TransactionPropagationError, TransactionIsolationError, SavepointError, TransactionRequiredError, TransactionUnexpectedError, TransactionCapabilityError, } from "@zudojs/errors";
-//# sourceMappingURL=transactionError.types.d.ts.map

package/dist/transactionErrors/transactionError.types.js

@@ -6,4 +6,3 @@
  * across both import paths.
  */
 export { TransactionStateError, TransactionTimeoutError, TransactionCommitError, TransactionRollbackError, TransactionRollbackOnlyError, TransactionAdapterError, TransactionPropagationError, TransactionIsolationError, SavepointError, TransactionRequiredError, TransactionUnexpectedError, TransactionCapabilityError, } from "@zudojs/errors";
-//# sourceMappingURL=transactionError.types.js.map

package/dist/transactionTypes/index.d.ts

@@ -6,5 +6,5 @@
 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 TransactionManager } from "./transactionManager.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/index.js

@@ -6,5 +6,5 @@
 export {} from "./transactionState.js";
 export {} from "./transaction.interface.js";
 export {} from "./transactionAdapter.js";
+export {} from "./transactionManager.js";
 export { TRANSACTION_EVENTS, } from "./transactionHooks.js";
-//# sourceMappingURL=index.js.map

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

@@ -91,4 +91,3 @@ export interface Transaction {
     /** Register a callback to run after rollback. */
     afterRollback(callback: () => Promise<void>): void;
 }
-//# sourceMappingURL=transaction.interface.d.ts.map

package/dist/transactionTypes/transaction.interface.js

@@ -4,4 +4,3 @@
  * @module transactionTypes/transaction
  */
 export {};
-//# sourceMappingURL=transaction.interface.js.map

package/dist/transactionTypes/transactionAdapter.d.ts

@@ -51,4 +51,3 @@ export interface TransactionContext {
      */
     exit<T>(callback: () => Promise<T>): Promise<T>;
 }
-//# sourceMappingURL=transactionAdapter.d.ts.map

package/dist/transactionTypes/transactionAdapter.js

@@ -4,4 +4,3 @@
  * @module transactionTypes/transactionAdapter
  */
 export {};
-//# sourceMappingURL=transactionAdapter.js.map

package/dist/transactionTypes/transactionHooks.d.ts

@@ -53,4 +53,3 @@ export interface TransactionEvent {
 }
 /** Handler for transaction events. */
 export type TransactionEventHandler = (event: TransactionEvent) => void;
-//# sourceMappingURL=transactionHooks.d.ts.map

package/dist/transactionTypes/transactionHooks.js

@@ -14,4 +14,3 @@ export const TRANSACTION_EVENTS = {
     FAILED: "transaction.failed",
     TIMED_OUT: "transaction.timed_out",
 };
-//# sourceMappingURL=transactionHooks.js.map

package/dist/transactionTypes/transactionManager.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The transaction manager contract.
+ *
+ * `createTransactionManager` returned an anonymous object type, so a
+ * consumer that wanted to hold, inject or mock a manager had to write
+ * `ReturnType<typeof createTransactionManager>`. This is that type, named.
+ *
+ * @module transactionTypes/transactionManager
+ */
+import type { Transaction, TransactionOptions } from "./transaction.interface.js";
+/**
+ * Coordinates begin, commit, rollback and context propagation for
+ * transactions opened against one adapter.
+ */
+export interface TransactionManager {
+    /**
+     * 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. A transaction opened here must be
+     * completed with `commit()` or `rollback()`.
+     */
+    begin(options?: TransactionOptions): Promise<Transaction>;
+    /**
+     * Run a callback inside a transaction, committing or rolling back around
+     * it. Only a transaction this call opened is completed here; a failure
+     * inside a participant marks the enclosing transaction rollback-only.
+     */
+    run<T>(callback: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Commit a transaction. Participants and committed transactions are
+     * no-ops; a rollback-only transaction is rolled back and the call
+     * rejects.
+     */
+    commit(transaction: Transaction): Promise<void>;
+    /** Roll back a transaction, or mark the joined transaction rollback-only. */
+    rollback(transaction: Transaction, reason?: unknown): Promise<void>;
+    /**
+     * The transaction in scope for the current async execution, if any. A
+     * transaction that has already committed, rolled back or failed is not
+     * in scope, even when its context is still the active store (for example
+     * inside an `afterCommit` callback).
+     */
+    getCurrent(): Transaction | undefined;
+    /**
+     * The adapter handle (what `adapter.begin()` returned) of the transaction
+     * in scope for the current async execution, or `undefined` outside a
+     * transaction. See `getTransactionHandle`.
+     */
+    getCurrentHandle<THandle = unknown>(): THandle | undefined;
+}

package/dist/transactionTypes/transactionManager.js

@@ -0,0 +1,10 @@
+/**
+ * The transaction manager contract.
+ *
+ * `createTransactionManager` returned an anonymous object type, so a
+ * consumer that wanted to hold, inject or mock a manager had to write
+ * `ReturnType<typeof createTransactionManager>`. This is that type, named.
+ *
+ * @module transactionTypes/transactionManager
+ */
+export {};

package/dist/transactionTypes/transactionState.d.ts

@@ -18,4 +18,3 @@ export type TransactionPropagation = "required" | "requires_new" | "supports" |
 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/transactionTypes/transactionState.js

@@ -4,4 +4,3 @@
  * @module transactionTypes/transactionState
  */
 export {};
-//# sourceMappingURL=transactionState.js.map

package/dist/utils/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { isTerminalState, isModifiable, summarizeTransaction, } from "./utils.helper.js";
 export { raceSignal } from "./utils.signal.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -5,4 +5,3 @@
  */
 export { isTerminalState, isModifiable, summarizeTransaction, } from "./utils.helper.js";
 export { raceSignal } from "./utils.signal.js";
-//# sourceMappingURL=index.js.map

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

@@ -22,4 +22,3 @@ export declare function isModifiable(transaction: Transaction): boolean;
  * Get a human-readable summary of a transaction.
  */
 export declare function summarizeTransaction(transaction: Transaction): string;
-//# sourceMappingURL=utils.helper.d.ts.map

package/dist/utils/utils.helper.js

@@ -36,4 +36,3 @@ export function summarizeTransaction(transaction) {
         .filter(Boolean)
         .join(", ");
 }
-//# sourceMappingURL=utils.helper.js.map

package/dist/utils/utils.signal.d.ts

@@ -12,4 +12,3 @@
  * rejection. Cooperative code should watch the same signal and stop.
  */
 export declare function raceSignal<T>(work: Promise<T>, signal: AbortSignal): Promise<T>;
-//# sourceMappingURL=utils.signal.d.ts.map

package/dist/utils/utils.signal.js

@@ -31,4 +31,3 @@ export function raceSignal(work, signal) {
         });
     });
 }
-//# sourceMappingURL=utils.signal.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/transactions",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Transaction lifecycle and coordination with state machine, AsyncLocalStorage context propagation, savepoints, hooks, and adapter abstraction.",
   "license": "MIT",
   "author": {
@@ -25,7 +25,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.3.1"
+    "@zudojs/errors": "1.4.0"
   },
   "engines": {
     "node": ">=24.0.0"