TxHooks

Type

Signature

type TxHooks = {
  createSavepoint(): TxHooksSavepoint;
  onCommit(callback): void;
  onRollback(callback): void;
  retryBoundary<TArgs, TResult>(fn): (...args) => TResult;
  withSavepoint<T>(fn): T;
};

core/src/tx-hooks/tx-hooks.ts:26

Buffers transaction side effects and controls their lifecycle.

Callbacks registered with onCommit run only after the caller's transaction commits; callbacks registered with onRollback run if the work they were registered in is rolled back. Each callback belongs to the innermost savepoint or retryBoundary try that was open when it was registered. Once the hooks are flushed or discarded, registering a callback, savepoints and retryBoundary tries throw, and rolling back an earlier savepoint does nothing.

The hooks follow the transaction they wrap: when its callback returns a promise, commit callbacks may return promises too and flush awaits them; when it returns a plain value, as in a driver's own synchronous transaction, commit callbacks must be synchronous.

Methods

createSavepoint()

Signature

createSavepoint(): TxHooksSavepoint;

core/src/tx-hooks/tx-hooks.ts:57

Create a manual savepoint. rollback() drops the commit callbacks registered since and runs the rollback callbacks registered since; release() keeps them.

Returns

onCommit()

Signature

onCommit(callback): void;

core/src/tx-hooks/tx-hooks.ts:37

Run callback after the transaction commits.

Commit callbacks start in registration order and run concurrently: a returned promise is awaited by flush, but not before the next callback starts. Every callback runs even if an earlier one throws, and flush then rethrows the first error. A callback registered in a savepoint or retryBoundary try that is rolled back never runs. In a synchronous transaction, a callback that returns a promise makes the flush throw after every callback has run.

Parameters

  • callback
    () => void | Promise<void>

Returns

void

onRollback()

Signature

onRollback(callback): void;

core/src/tx-hooks/tx-hooks.ts:47

Run callback if the work it was registered in is rolled back: the savepoint or retryBoundary try open at registration, or the whole transaction when the hooks are discarded.

Rollback callbacks run newest first. They must be synchronous: a returned promise is not awaited. Every callback runs even if an earlier one throws; discard rethrows the first error, while a savepoint or retryBoundary rollback ignores it.

Parameters

  • callback
    () => void

Returns

void

retryBoundary()

Signature

retryBoundary<TArgs, TResult>(fn): (...args) => TResult;

core/src/tx-hooks/tx-hooks.ts:69

Wrap a transaction callback that a driver or retry loop may call more than once, such as the callback of MongoDB's session.withTransaction.

Each call after the first rolls back what the previous try registered, then calls fn with the same arguments and returns its result. Callbacks registered before the first call are kept. A call while the previous call's fn is still running throws, or rejects when that fn returned a promise. Create one wrapper per transaction: every call after the first is treated as a rerun of the same transaction.

Type Parameters

  • TArgs
    extends unknown[]
  • TResult

Parameters

  • fn
    (...args) => TResult

Returns

(...args) => TResult

withSavepoint()

Signature

withSavepoint<T>(fn): T;

core/src/tx-hooks/tx-hooks.ts:52

Run fn inside a savepoint and return its result. Rolls back if fn throws or the promise it returns rejects, and releases otherwise.

Type Parameters

  • T

Parameters

  • fn
    (txHooks) => T

Returns

T

Used in guides

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open