@zudojs/transactions 1.1.0 → 1.1.1

package/README.md

@@ -2,6 +2,12 @@
 
 Transaction lifecycle and coordination with state machine, AsyncLocalStorage context propagation, savepoints, hooks, and adapter abstraction.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-transactions](https://zudojs.oyinlola.site/docs/packages-transactions) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-transactions.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -105,6 +111,12 @@ the transaction.
 - 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.
+- Releasing a savepoint is not a commit. `afterCommit` and `afterRollback`
+  callbacks registered inside a `nested` block, and `hooks.afterCommit` for the
+  savepoint, move to the enclosing transaction on release. They run only when
+  the outermost transaction commits (or, for `afterRollback`, rolls back). A
+  savepoint that is itself rolled back runs its `afterRollback` callbacks at
+  once and discards its `afterCommit` callbacks.
 - `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

package/dist/manager/manager.commit.js

@@ -98,6 +98,13 @@ export async function commitTransaction(transaction, adapter, hooks, emit = noop
     if (hooks?.beforeCommit)
         await hooks.beforeCommit({ transaction });
     emit(TRANSACTION_EVENTS.COMMITTING, transaction);
+    if (hooks?.afterCommit && transaction.kind === "savepoint") {
+        // Releasing a savepoint is not a commit. Registered as a callback, the
+        // hook is deferred with the savepoint's own callbacks and fires only if
+        // the outermost transaction commits.
+        const afterCommit = hooks.afterCommit;
+        transaction.afterCommit(() => afterCommit({ transaction }));
+    }
     try {
         await adapterCommit(transaction, adapter);
         await transaction.commit();
@@ -119,8 +126,9 @@ export async function commitTransaction(transaction, adapter, hooks, emit = noop
             error: new AggregateError(callbackErrors, "after-commit callback failures"),
         });
     }
-    if (hooks?.afterCommit)
+    if (hooks?.afterCommit && transaction.kind !== "savepoint") {
         await hooks.afterCommit({ transaction });
+    }
 }
 /**
  * Rollback a transaction with hooks and adapter coordination.

package/dist/manager/manager.propagation.js

@@ -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");
+    const child = createTransaction(opts, parent.id, "savepoint", parent);
     if (hooks?.beforeBegin)
         await hooks.beforeBegin({ transaction: child });
     const savepoint = `sp_${child.id}`;

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

@@ -9,6 +9,8 @@ import type { TransactionKind } from "../transactionTypes/transactionState.js";
  * @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.
+ * @param parent - The enclosing transaction of a savepoint. Its callbacks
+ *   are deferred to `parent` on release instead of running.
  */
-export declare function createTransaction(options?: TransactionOptions, parentId?: string, kind?: TransactionKind): Transaction;
+export declare function createTransaction(options?: TransactionOptions, parentId?: string, kind?: TransactionKind, parent?: Transaction): Transaction;
 //# sourceMappingURL=transaction.core.d.ts.map

package/dist/transaction/transaction.core.js

@@ -5,6 +5,7 @@ import { randomBytes } from "node:crypto";
 import { TransactionRollbackError, TransactionStateError, } from "../transactionErrors/transactionError.types.js";
 import { canTransition, createTransitionFunction, } from "./transactionStateMachine.js";
 import { attachInternals } from "./transaction.internal.js";
+import { deferCallbacksToParent } from "./transaction.savepoint.js";
 /**
  * Generate a unique transaction ID.
  */
@@ -30,8 +31,10 @@ async function runCallbacks(callbacks) {
  * @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.
+ * @param parent - The enclosing transaction of a savepoint. Its callbacks
+ *   are deferred to `parent` on release instead of running.
  */
-export function createTransaction(options = {}, parentId, kind = "root") {
+export function createTransaction(options = {}, parentId, kind = "root", parent) {
     let state = "pending";
     let rollbackOnly = false;
     let rollbackOnlyReason;
@@ -91,6 +94,10 @@ export function createTransaction(options = {}, parentId, kind = "root") {
             }
             transition("committing");
             transition("committed");
+            if (kind === "savepoint" && parent !== undefined) {
+                deferCallbacksToParent(parent, afterCommitCallbacks, afterRollbackCallbacks);
+                return;
+            }
             afterRollbackCallbacks.length = 0;
             // The commit stands whatever the callbacks do; their failures are
             // kept for the manager to report instead of being dropped.

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

@@ -0,0 +1,24 @@
+/**
+ * Savepoint callback deferral.
+ *
+ * Releasing a savepoint is not a commit: the enclosing transaction can still
+ * roll back and discard everything the savepoint did. Callbacks registered on
+ * a savepoint therefore move to its parent when the savepoint is released,
+ * the same way a participant registers straight on the transaction it
+ * joined. They run once the outermost transaction settles: `afterCommit`
+ * when it commits, `afterRollback` when it rolls back.
+ *
+ * @module transaction/transaction.savepoint
+ */
+import type { Transaction } from "../transactionTypes/transaction.interface.js";
+/**
+ * Move a released savepoint's pending callbacks onto its parent.
+ *
+ * Both arrays are emptied: the callbacks now belong to the parent.
+ *
+ * @param parent - The transaction the savepoint was created on.
+ * @param afterCommit - The savepoint's pending after-commit callbacks.
+ * @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

@@ -0,0 +1,29 @@
+/**
+ * Savepoint callback deferral.
+ *
+ * Releasing a savepoint is not a commit: the enclosing transaction can still
+ * roll back and discard everything the savepoint did. Callbacks registered on
+ * a savepoint therefore move to its parent when the savepoint is released,
+ * the same way a participant registers straight on the transaction it
+ * joined. They run once the outermost transaction settles: `afterCommit`
+ * when it commits, `afterRollback` when it rolls back.
+ *
+ * @module transaction/transaction.savepoint
+ */
+/**
+ * Move a released savepoint's pending callbacks onto its parent.
+ *
+ * Both arrays are emptied: the callbacks now belong to the parent.
+ *
+ * @param parent - The transaction the savepoint was created on.
+ * @param afterCommit - The savepoint's pending after-commit callbacks.
+ * @param afterRollback - The savepoint's pending after-rollback callbacks.
+ */
+export function deferCallbacksToParent(parent, afterCommit, afterRollback) {
+    for (const callback of afterCommit.splice(0))
+        parent.afterCommit(callback);
+    for (const callback of afterRollback.splice(0)) {
+        parent.afterRollback(callback);
+    }
+}
+//# sourceMappingURL=transaction.savepoint.js.map

package/dist/transactionErrors/index.d.ts

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

package/dist/transactionErrors/index.js

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

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

@@ -1,15 +1,9 @@
 /**
  * Base transaction error class.
+ *
+ * Owned by `@zudojs/errors` (round 10 INF-16) and re-exported here, so
+ * `instanceof TransactionError` matches whichever package a caller imports
+ * it from. Name, constructor, `code` defaults and category are unchanged.
  */
-import { BaseError, ErrorCode, type ErrorMetadata } from "@zudojs/errors";
-/**
- * Base error for all transaction-related failures.
- */
-export declare class TransactionError extends BaseError {
-    constructor(message: string, options?: {
-        readonly code?: ErrorCode;
-        readonly metadata?: ErrorMetadata;
-        readonly cause?: unknown;
-    });
-}
+export { TransactionError, type TransactionErrorOptions } from "@zudojs/errors";
 //# sourceMappingURL=transactionError.base.d.ts.map

package/dist/transactionErrors/transactionError.base.js

@@ -1,19 +1,9 @@
 /**
  * Base transaction error class.
+ *
+ * Owned by `@zudojs/errors` (round 10 INF-16) and re-exported here, so
+ * `instanceof TransactionError` matches whichever package a caller imports
+ * it from. Name, constructor, `code` defaults and category are unchanged.
  */
-import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
-/**
- * Base error for all transaction-related failures.
- */
-export class TransactionError extends BaseError {
-    constructor(message, options) {
-        super(message, {
-            code: options?.code ?? ErrorCode.OPERATION_FAILED,
-            category: ErrorCategory.DATABASE,
-            severity: ErrorSeverity.ERROR,
-            metadata: options?.metadata,
-            cause: options?.cause,
-        });
-    }
-}
+export { TransactionError } from "@zudojs/errors";
 //# sourceMappingURL=transactionError.base.js.map

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

@@ -1,74 +1,9 @@
 /**
  * Specific transaction error subclasses.
+ *
+ * Owned by `@zudojs/errors` (round 10 INF-16) and re-exported here with the
+ * same names, constructor signatures and codes, so `instanceof` checks match
+ * across both import paths.
  */
-import { TransactionError } from "./transactionError.base.js";
-/**
- * Transaction is in an invalid state for the requested operation.
- */
-export declare class TransactionStateError extends TransactionError {
-    constructor(state: string, operation: string);
-}
-/**
- * Transaction exceeded its timeout.
- */
-export declare class TransactionTimeoutError extends TransactionError {
-    constructor(transactionId: string, timeoutMs: number);
-}
-/**
- * Transaction commit failed.
- */
-export declare class TransactionCommitError extends TransactionError {
-    constructor(transactionId: string, cause?: unknown);
-}
-/**
- * Transaction rollback failed.
- */
-export declare class TransactionRollbackError extends TransactionError {
-    constructor(transactionId: string, options?: {
-        readonly cause?: unknown;
-        readonly originalError?: unknown;
-    });
-}
-/**
- * The underlying adapter threw an error.
- */
-export declare class TransactionAdapterError extends TransactionError {
-    constructor(message: string, cause?: unknown);
-}
-/**
- * Propagation strategy violation.
- */
-export declare class TransactionPropagationError extends TransactionError {
-    constructor(message: string);
-}
-/**
- * Required isolation level is not supported by the adapter.
- */
-export declare class TransactionIsolationError extends TransactionError {
-    constructor(level: string);
-}
-/**
- * Savepoint operation failed.
- */
-export declare class SavepointError extends TransactionError {
-    constructor(message: string, cause?: unknown);
-}
-/**
- * A transaction is required but none exists.
- */
-export declare class TransactionRequiredError extends TransactionError {
-    constructor();
-}
-/**
- * A transaction exists but none was expected.
- */
-export declare class TransactionUnexpectedError extends TransactionError {
-    constructor();
-}
-/**
- * The adapter does not support the requested capability.
- */
-export declare class TransactionCapabilityError extends TransactionError {
-    constructor(capability: string);
-}
+export { TransactionStateError, TransactionTimeoutError, TransactionCommitError, TransactionRollbackError, TransactionAdapterError, TransactionPropagationError, TransactionIsolationError, SavepointError, TransactionRequiredError, TransactionUnexpectedError, TransactionCapabilityError, } from "@zudojs/errors";
 //# sourceMappingURL=transactionError.types.d.ts.map

package/dist/transactionErrors/transactionError.types.js

@@ -1,129 +1,9 @@
 /**
  * Specific transaction error subclasses.
+ *
+ * Owned by `@zudojs/errors` (round 10 INF-16) and re-exported here with the
+ * same names, constructor signatures and codes, so `instanceof` checks match
+ * across both import paths.
  */
-import { ErrorCode } from "@zudojs/errors";
-import { TransactionError } from "./transactionError.base.js";
-/**
- * Transaction is in an invalid state for the requested operation.
- */
-export class TransactionStateError extends TransactionError {
-    constructor(state, operation) {
-        super(`Cannot ${operation} transaction in state "${state}"`, {
-            code: ErrorCode.LIFECYCLE_STATE,
-            metadata: { state, operation },
-        });
-    }
-}
-/**
- * Transaction exceeded its timeout.
- */
-export class TransactionTimeoutError extends TransactionError {
-    constructor(transactionId, timeoutMs) {
-        super(`Transaction "${transactionId}" timed out after ${timeoutMs}ms`, {
-            code: ErrorCode.TIMEOUT,
-            metadata: { transactionId, timeoutMs },
-        });
-    }
-}
-/**
- * Transaction commit failed.
- */
-export class TransactionCommitError extends TransactionError {
-    constructor(transactionId, cause) {
-        super(`Transaction "${transactionId}" commit failed`, {
-            code: ErrorCode.DATABASE_TRANSACTION,
-            cause,
-            metadata: { transactionId },
-        });
-    }
-}
-/**
- * Transaction rollback failed.
- */
-export class TransactionRollbackError extends TransactionError {
-    constructor(transactionId, options) {
-        super(`Transaction "${transactionId}" rollback failed`, {
-            code: ErrorCode.DATABASE_TRANSACTION,
-            cause: options?.cause,
-            metadata: {
-                transactionId,
-                originalError: options?.originalError instanceof Error
-                    ? options.originalError.message
-                    : String(options?.originalError ?? "unknown"),
-            },
-        });
-    }
-}
-/**
- * The underlying adapter threw an error.
- */
-export class TransactionAdapterError extends TransactionError {
-    constructor(message, cause) {
-        super(message, {
-            code: ErrorCode.ADAPTER_OPERATION_FAILED,
-            cause,
-        });
-    }
-}
-/**
- * Propagation strategy violation.
- */
-export class TransactionPropagationError extends TransactionError {
-    constructor(message) {
-        super(message, { code: ErrorCode.VALIDATION_FAILED });
-    }
-}
-/**
- * Required isolation level is not supported by the adapter.
- */
-export class TransactionIsolationError extends TransactionError {
-    constructor(level) {
-        super(`Isolation level "${level}" is not supported by the adapter`, {
-            code: ErrorCode.VALIDATION_FAILED,
-            metadata: { level },
-        });
-    }
-}
-/**
- * Savepoint operation failed.
- */
-export class SavepointError extends TransactionError {
-    constructor(message, cause) {
-        super(message, {
-            code: ErrorCode.OPERATION_FAILED,
-            cause,
-        });
-    }
-}
-/**
- * A transaction is required but none exists.
- */
-export class TransactionRequiredError extends TransactionError {
-    constructor() {
-        super("A transaction is required but none exists", {
-            code: ErrorCode.PRECONDITION_FAILED,
-        });
-    }
-}
-/**
- * A transaction exists but none was expected.
- */
-export class TransactionUnexpectedError extends TransactionError {
-    constructor() {
-        super("A transaction already exists but none was expected", {
-            code: ErrorCode.CONFLICT,
-        });
-    }
-}
-/**
- * The adapter does not support the requested capability.
- */
-export class TransactionCapabilityError extends TransactionError {
-    constructor(capability) {
-        super(`Adapter does not support: ${capability}`, {
-            code: ErrorCode.NOT_IMPLEMENTED,
-            metadata: { capability },
-        });
-    }
-}
+export { TransactionStateError, TransactionTimeoutError, TransactionCommitError, TransactionRollbackError, TransactionAdapterError, TransactionPropagationError, TransactionIsolationError, SavepointError, TransactionRequiredError, TransactionUnexpectedError, TransactionCapabilityError, } from "@zudojs/errors";
 //# sourceMappingURL=transactionError.types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/transactions",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "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.0.1"
+    "@zudojs/errors": "1.1.0"
   },
   "engines": {
     "node": ">=24.0.0"