@zudojs/transactions 0.0.1 → 1.0.0

package/README.md

@@ -13,28 +13,99 @@ npm install @zudojs/transactions
 ```typescript
 import { createTransactionManager } from "@zudojs/transactions";
 
-const manager = createTransactionManager({
-  adapter: databaseAdapter,
+const manager = createTransactionManager({ adapter: databaseAdapter });
+
+// `run` opens a transaction, commits on success, rolls back on a throw.
+const orderId = await manager.run(async (transaction) => {
+  await insertOrder(transaction);
+  await insertLineItems(transaction);
+  return "o_1";
 });
 
-await manager.run(async (tx) => {
-  await tx.execute("INSERT INTO users ...");
-  await tx.execute("INSERT INTO profiles ...");
+// A nested `run` joins the enclosing transaction rather than completing it.
+await manager.run(async () => {
+  await manager.run(async (participant) => {
+    // participant.kind === "participant"; committing it is a no-op, and a
+    // throw here marks the enclosing transaction rollback-only.
+  });
+});
+
+// Retries replay the whole unit of work.
+await manager.run(handler, {
+  retry: {
+    attempts: 3,
+    backoff: "exponential",
+    delay: 50,
+    shouldRetry: (error) => isSerializationFailure(error),
+  },
+});
+```
+
+## Propagation
+
+| Mode            | Transaction in progress      | None in progress         |
+| --------------- | ---------------------------- | ------------------------ |
+| `required`      | joins it as a participant    | opens a new one          |
+| `requires_new`  | suspends it, opens a new one | opens a new one          |
+| `nested`        | opens a savepoint on it      | opens a new one          |
+| `supports`      | joins it as a participant    | runs non-transactionally |
+| `not_supported` | suspends it                  | runs non-transactionally |
+| `mandatory`     | joins it as a participant    | throws                   |
+| `never`         | throws                       | runs non-transactionally |
+
+## Lifecycle events
+
+Pass `onEvent` to observe the lifecycle. Each event names a member of
+`TRANSACTION_EVENTS` and carries the transaction id, a timestamp and the
+elapsed duration:
+
+```typescript
+const manager = createTransactionManager({
+  adapter,
+  onEvent: (event) => metrics.increment(event.type, { id: event.transactionId }),
 });
 ```
 
+Emitted: `started`, `committing`, `committed`, `rolling_back`, `rolled_back`,
+`failed` and `timed_out`. A throwing observer is ignored rather than failing
+the transaction.
+
+## Errors
+
+| Condition                              | Error                          |
+| -------------------------------------- | ------------------------------ |
+| Transaction outlived its `timeout`      | `TransactionTimeoutError`      |
+| Marked rollback-only, then committed    | `TransactionRollbackError`     |
+| Adapter lacks the requested isolation   | `TransactionIsolationError`    |
+| Adapter lacks another requested feature | `TransactionCapabilityError`   |
+| Savepoint create/rollback/release fails | `SavepointError`               |
+| Propagation precondition violated       | `TransactionPropagationError`  |
+| Operation invalid for the current state | `TransactionStateError`        |
+| Adapter refused the commit              | `TransactionCommitError`       |
+| Adapter itself failed                   | `TransactionAdapterError`      |
+
 ## Features
 
-- Transaction state machine
-- AsyncLocalStorage context propagation
-- Savepoints for nested transactions
+- Transaction state machine with enforced transitions
+- AsyncLocalStorage context propagation, with suspension
+- Savepoints for nested transactions, released on commit
 - Before/after hooks
-- Adapter abstraction for multiple databases
-- Automatic rollback on errors
+- Adapter abstraction with capability enforcement
+- Retry with fixed or exponential backoff
+- Rollback-only and timeout semantics
+- Lifecycle events for observability
+
+## Safety Notes
+
+- The rollback-only flag is read **before** the adapter is asked to commit, so
+  a transaction marked rollback-only — including one that timed out — is rolled
+  back and `commit()` rejects. A rollback can never be reported as a commit.
+- 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.
 
 ## Use Cases
 
 - Database transaction management
-- Distributed transaction coordination
 - Unit of Work pattern
 - Audit logging with transaction context

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

@@ -6,6 +6,10 @@
 import type { TransactionAdapter, TransactionAdapterCapabilities } from "../transactionTypes/transactionAdapter.js";
 /**
  * Create an in-memory transaction adapter (useful for testing).
+ *
+ * Capabilities are declared honestly: the adapter emulates savepoints and
+ * accepts every isolation level, because it enforces none of them and so
+ * cannot fail to provide what it claims.
  */
 export declare function createInMemoryAdapter(): TransactionAdapter;
 /**

package/dist/adapter/adapter.core.js

@@ -3,36 +3,72 @@
  *
  * @module adapter/adapter
  */
+import { TransactionAdapterError } from "../transactionErrors/transactionError.types.js";
 let counter = 0;
+/** Narrows an opaque handle to an in-memory handle, or fails loudly. */
+function asHandle(handle) {
+    if (typeof handle !== "object" ||
+        handle === null ||
+        !("savepoints" in handle)) {
+        throw new TransactionAdapterError("Handle was not issued by the in-memory adapter");
+    }
+    return handle;
+}
 /**
  * Create an in-memory transaction adapter (useful for testing).
+ *
+ * Capabilities are declared honestly: the adapter emulates savepoints and
+ * accepts every isolation level, because it enforces none of them and so
+ * cannot fail to provide what it claims.
  */
 export function createInMemoryAdapter() {
     const handles = new Map();
     return {
         capabilities: Object.freeze({
-            savepoints: false,
-            nestedTransactions: false,
-            isolationLevels: ["read_committed"],
-            readOnlyTransactions: false,
-            timeouts: false,
+            savepoints: true,
+            nestedTransactions: true,
+            isolationLevels: [
+                "read_uncommitted",
+                "read_committed",
+                "repeatable_read",
+                "serializable",
+            ],
+            readOnlyTransactions: true,
+            timeouts: true,
         }),
-        async begin() {
+        async begin(_options) {
             const id = `mem_${++counter}`;
-            const handle = { id, active: true };
+            const handle = { id, active: true, savepoints: [] };
             handles.set(id, handle);
             return handle;
         },
         async commit(handle) {
-            const h = handle;
+            const h = asHandle(handle);
             h.active = false;
             handles.delete(h.id);
         },
         async rollback(handle) {
-            const h = handle;
+            const h = asHandle(handle);
             h.active = false;
             handles.delete(h.id);
         },
+        async createSavepoint(handle, name) {
+            asHandle(handle).savepoints.push(name);
+        },
+        async rollbackToSavepoint(handle, name) {
+            const h = asHandle(handle);
+            const index = h.savepoints.indexOf(name);
+            if (index === -1) {
+                throw new TransactionAdapterError(`Unknown savepoint: ${name}`);
+            }
+            h.savepoints.length = index + 1;
+        },
+        async releaseSavepoint(handle, name) {
+            const h = asHandle(handle);
+            const index = h.savepoints.indexOf(name);
+            if (index !== -1)
+                h.savepoints.splice(index, 1);
+        },
     };
 }
 /**

package/dist/context/context.core.js

@@ -16,6 +16,9 @@ export function createTransactionContext() {
         async run(transaction, callback) {
             return storage.run(transaction, callback);
         },
+        async exit(callback) {
+            return storage.exit(callback);
+        },
     };
 }
 /** Default context instance. */

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/manager/index.d.ts

@@ -4,4 +4,11 @@
  * @module manager
  */
 export { createTransactionManager, type TransactionManagerOptions, } from "./manager.core.js";
+export { commitTransaction, rollbackTransaction } from "./manager.commit.js";
+export { resolvePropagation, suspendsTransaction, } from "./manager.propagation.js";
+export type { PropagationContext } from "./manager.propagation.js";
+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

@@ -4,4 +4,9 @@
  * @module manager
  */
 export { createTransactionManager, } from "./manager.core.js";
+export { commitTransaction, rollbackTransaction } from "./manager.commit.js";
+export { resolvePropagation, suspendsTransaction, } from "./manager.propagation.js";
+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

@@ -0,0 +1,26 @@
+/**
+ * Adapter capability enforcement.
+ *
+ * Every adapter declares what it supports. Requesting something it does not
+ * provide has to fail loudly: silently running a `serializable` unit of work
+ * at the driver's default isolation is worse than not starting it.
+ *
+ * @module manager/manager.capabilities
+ */
+import type { TransactionOptions } from "../transactionTypes/transaction.interface.js";
+import type { TransactionAdapter } from "../transactionTypes/transactionAdapter.js";
+/**
+ * Assert that an adapter can honour the options a transaction requests.
+ *
+ * @param adapter - The adapter about to begin the transaction.
+ * @param options - The requested options.
+ * A capability mismatch is a configuration error, not an adapter fault, so it
+ * no longer shares `TransactionAdapterError` with genuine driver failures:
+ * `TransactionIsolationError` names the level, `TransactionCapabilityError`
+ * names the capability.
+ *
+ * @throws {TransactionIsolationError} when the isolation level is unsupported.
+ * @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

@@ -0,0 +1,41 @@
+/**
+ * Adapter capability enforcement.
+ *
+ * Every adapter declares what it supports. Requesting something it does not
+ * provide has to fail loudly: silently running a `serializable` unit of work
+ * at the driver's default isolation is worse than not starting it.
+ *
+ * @module manager/manager.capabilities
+ */
+import { TransactionCapabilityError, TransactionIsolationError, } from "../transactionErrors/transactionError.types.js";
+/**
+ * Assert that an adapter can honour the options a transaction requests.
+ *
+ * @param adapter - The adapter about to begin the transaction.
+ * @param options - The requested options.
+ * A capability mismatch is a configuration error, not an adapter fault, so it
+ * no longer shares `TransactionAdapterError` with genuine driver failures:
+ * `TransactionIsolationError` names the level, `TransactionCapabilityError`
+ * names the capability.
+ *
+ * @throws {TransactionIsolationError} when the isolation level is unsupported.
+ * @throws {TransactionCapabilityError} when another capability is missing.
+ */
+export function assertAdapterSupports(adapter, options) {
+    if (!options)
+        return;
+    const { capabilities } = adapter;
+    if (options.isolation !== undefined &&
+        !capabilities.isolationLevels.includes(options.isolation)) {
+        throw new TransactionIsolationError(options.isolation);
+    }
+    if (options.readOnly === true && !capabilities.readOnlyTransactions) {
+        throw new TransactionCapabilityError("read-only transactions");
+    }
+    if (options.timeout !== undefined &&
+        options.timeout > 0 &&
+        !capabilities.timeouts) {
+        throw new TransactionCapabilityError("transaction timeouts");
+    }
+}
+//# sourceMappingURL=manager.capabilities.js.map

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

@@ -1,17 +1,34 @@
 /**
  * Transaction commit and rollback orchestration.
  *
+ * Ordering is the whole point of this module. The rollback-only flag is read
+ * before the adapter is asked to commit, never after: once `adapter.commit()`
+ * has returned there is nothing left to decide.
+ *
  * @module manager/manager.commit
  */
 import type { Transaction } from "../transactionTypes/transaction.interface.js";
 import type { TransactionAdapter } from "../transactionTypes/transactionAdapter.js";
 import type { TransactionHooks } from "../transactionTypes/transactionHooks.js";
+import type { TransactionEmitter } from "./manager.events.js";
 /**
  * Commit a transaction with hooks and adapter coordination.
+ *
+ * A participant commits nothing — the scope that opened the transaction does
+ * that — and a non-transactional scope has no adapter to talk to. Anything
+ * else must be active: committing a transaction that was already rolled back
+ * is a programming error, not a no-op.
+ *
+ * @throws {TransactionTimeoutError} when the transaction outlived its timeout.
+ * @throws {TransactionRollbackError} when the transaction is rollback-only.
+ * @throws {TransactionStateError} when the transaction cannot be committed.
+ * @throws {TransactionCommitError} when the adapter refuses the commit.
  */
-export declare function commitTransaction(transaction: Transaction, adapter: TransactionAdapter, hooks?: TransactionHooks): Promise<void>;
+export declare function commitTransaction(transaction: Transaction, adapter: TransactionAdapter, hooks?: TransactionHooks, emit?: TransactionEmitter): Promise<void>;
 /**
  * Rollback a transaction with hooks and adapter coordination.
+ *
+ * @throws {TransactionRollbackError} when the adapter refuses the rollback.
  */
-export declare function rollbackTransaction(transaction: Transaction, adapter: TransactionAdapter, reason?: unknown, hooks?: TransactionHooks): Promise<void>;
+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

@@ -1,66 +1,154 @@
 /**
  * Transaction commit and rollback orchestration.
  *
+ * Ordering is the whole point of this module. The rollback-only flag is read
+ * before the adapter is asked to commit, never after: once `adapter.commit()`
+ * has returned there is nothing left to decide.
+ *
  * @module manager/manager.commit
  */
-import { TransactionCommitError, TransactionRollbackError, } from "../transactionErrors/transactionError.types.js";
+import { asSavepointHandle, internals, } from "../transaction/transaction.internal.js";
+import { canTransition } from "../transaction/transactionStateMachine.js";
+import { SavepointError, TransactionCommitError, TransactionRollbackError, TransactionStateError, TransactionTimeoutError, } from "../transactionErrors/transactionError.types.js";
+import { noopEmitter, TRANSACTION_EVENTS } from "./manager.events.js";
+/** Moves a transaction to `failed` when the state machine allows it. */
+function markFailed(transaction) {
+    if (canTransition(transaction.state, "failed")) {
+        internals(transaction)._transition("failed");
+    }
+}
+/** Releases a savepoint, or commits the connection for a root transaction. */
+async function adapterCommit(transaction, adapter) {
+    const handle = internals(transaction)._getHandle();
+    const savepoint = asSavepointHandle(handle);
+    if (savepoint) {
+        if (adapter.releaseSavepoint) {
+            try {
+                await adapter.releaseSavepoint(savepoint.parent, savepoint.savepoint);
+            }
+            catch (error) {
+                throw new SavepointError(`Failed to release savepoint "${savepoint.savepoint}"`, error);
+            }
+        }
+        return;
+    }
+    await adapter.commit(handle);
+}
+/** Rolls back to a savepoint, or rolls back the connection. */
+async function adapterRollback(transaction, adapter, reason) {
+    const handle = internals(transaction)._getHandle();
+    if (handle === undefined)
+        return;
+    const savepoint = asSavepointHandle(handle);
+    if (savepoint) {
+        try {
+            if (adapter.rollbackToSavepoint) {
+                await adapter.rollbackToSavepoint(savepoint.parent, savepoint.savepoint);
+            }
+            if (adapter.releaseSavepoint) {
+                await adapter.releaseSavepoint(savepoint.parent, savepoint.savepoint);
+            }
+        }
+        catch (error) {
+            throw new SavepointError(`Failed to roll back to savepoint "${savepoint.savepoint}"`, error);
+        }
+        return;
+    }
+    await adapter.rollback(handle, reason);
+}
 /**
  * Commit a transaction with hooks and adapter coordination.
+ *
+ * A participant commits nothing — the scope that opened the transaction does
+ * that — and a non-transactional scope has no adapter to talk to. Anything
+ * else must be active: committing a transaction that was already rolled back
+ * is a programming error, not a no-op.
+ *
+ * @throws {TransactionTimeoutError} when the transaction outlived its timeout.
+ * @throws {TransactionRollbackError} when the transaction is rollback-only.
+ * @throws {TransactionStateError} when the transaction cannot be committed.
+ * @throws {TransactionCommitError} when the adapter refuses the commit.
  */
-export async function commitTransaction(transaction, adapter, hooks) {
-    if (transaction.state !== "active")
+export async function commitTransaction(transaction, adapter, hooks, emit = noopEmitter) {
+    if (transaction.kind === "participant")
         return;
-    if (hooks?.beforeCommit) {
-        await hooks.beforeCommit({ transaction });
+    if (transaction.state === "committed")
+        return;
+    if (transaction.kind === "none") {
+        await transaction.commit();
+        return;
+    }
+    if (transaction.state !== "active") {
+        throw new TransactionStateError(transaction.state, "commit");
     }
-    const handle = transaction._getHandle();
+    if (transaction.isRollbackOnly()) {
+        const reason = internals(transaction)._getRollbackOnlyReason() ?? "marked rollback-only";
+        await rollbackTransaction(transaction, adapter, reason, hooks, emit);
+        // A timeout is a distinct failure from a caller marking the transaction
+        // rollback-only, and the timed-out case used to be indistinguishable
+        // because both raised TransactionRollbackError.
+        if (transaction.timedOut) {
+            emit(TRANSACTION_EVENTS.TIMED_OUT, transaction, reason);
+            throw new TransactionTimeoutError(transaction.id, transaction.options.timeout ?? 0);
+        }
+        throw new TransactionRollbackError(transaction.id, {
+            originalError: reason,
+        });
+    }
+    if (hooks?.beforeCommit)
+        await hooks.beforeCommit({ transaction });
+    emit(TRANSACTION_EVENTS.COMMITTING, transaction);
     try {
-        await adapter.commit(handle);
+        await adapterCommit(transaction, adapter);
         await transaction.commit();
     }
     catch (error) {
-        if (transaction.state === "committing") {
-            transaction._transition("failed");
-        }
-        if (hooks?.onError) {
+        markFailed(transaction);
+        emit(TRANSACTION_EVENTS.FAILED, transaction, error);
+        if (hooks?.onError)
             await hooks.onError({ transaction, error });
-        }
         throw new TransactionCommitError(transaction.id, error);
     }
-    if (hooks?.afterCommit) {
+    emit(TRANSACTION_EVENTS.COMMITTED, transaction);
+    if (hooks?.afterCommit)
         await hooks.afterCommit({ transaction });
-    }
 }
 /**
  * Rollback a transaction with hooks and adapter coordination.
+ *
+ * @throws {TransactionRollbackError} when the adapter refuses the rollback.
  */
-export async function rollbackTransaction(transaction, adapter, reason, hooks) {
+export async function rollbackTransaction(transaction, adapter, reason, hooks, emit = noopEmitter) {
+    if (transaction.kind === "participant") {
+        await transaction.rollback(reason);
+        return;
+    }
     if (transaction.state === "committed" ||
         transaction.state === "rolled_back" ||
         transaction.state === "failed") {
         return;
     }
-    if (hooks?.beforeRollback) {
+    if (hooks?.beforeRollback)
         await hooks.beforeRollback({ transaction });
-    }
-    const handle = transaction._getHandle();
+    emit(TRANSACTION_EVENTS.ROLLING_BACK, transaction, reason);
     try {
-        if (handle !== undefined) {
-            await adapter.rollback(handle, reason);
+        if (transaction.kind !== "none") {
+            await adapterRollback(transaction, adapter, reason);
         }
         await transaction.rollback(reason);
     }
     catch (error) {
-        if (hooks?.onError) {
+        markFailed(transaction);
+        emit(TRANSACTION_EVENTS.FAILED, transaction, error);
+        if (hooks?.onError)
             await hooks.onError({ transaction, error });
-        }
         throw new TransactionRollbackError(transaction.id, {
             cause: error,
             originalError: reason,
         });
     }
-    if (hooks?.afterRollback) {
+    emit(TRANSACTION_EVENTS.ROLLED_BACK, transaction, reason);
+    if (hooks?.afterRollback)
         await hooks.afterRollback({ transaction });
-    }
 }
 //# sourceMappingURL=manager.commit.js.map

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

@@ -4,23 +4,48 @@
  * @module manager/manager
  */
 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 { TransactionAdapter, TransactionContext } from "../transactionTypes/transactionAdapter.js";
+import type { TransactionEventHandler, TransactionHooks, TransactionRegistry } from "../transactionTypes/transactionHooks.js";
 /** Options for creating a transaction manager. */
 export interface TransactionManagerOptions {
     readonly adapter: TransactionAdapter;
     readonly context?: TransactionContext;
     readonly hooks?: TransactionHooks;
+    /** Optional registry notified as transactions start and finish. */
+    readonly registry?: TransactionRegistry;
+    /**
+     * Optional observer for transaction lifecycle events.
+     *
+     * Receives a {@link TransactionEvent} for each of `TRANSACTION_EVENTS`.
+     * A throwing observer is ignored rather than failing the transaction.
+     */
+    readonly onEvent?: TransactionEventHandler;
 }
 /**
  * Create a transaction manager.
  */
 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.
+     */
     run<T>(callback: (transaction: Transaction) => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    /** Commit a transaction. Participants and committed transactions are no-ops. */
     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;
 };
 //# sourceMappingURL=manager.core.d.ts.map