@nestjs-transactional/core 1.0.0-alpha.0

package/dist/tokens/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Default dataSource name used when none is specified to a token
+ * utility or inject decorator. Single-adapter consumers never need to
+ * type this string — the default argument on every helper substitutes
+ * it automatically.
+ *
+ * Multi-adapter consumers register additional dataSources by name
+ * (`'billing'`, `'inventory'`, ...). The string `'default'` is the
+ * convention for the always-present primary registration; ADR-018
+ * documents why this fixed name was chosen over alternatives like
+ * `'main'` or `'primary'`.
+ */
+export declare const DEFAULT_DATA_SOURCE_NAME = "default";
+//# sourceMappingURL=constants.d.ts.map

package/dist/tokens/constants.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DATA_SOURCE_NAME = void 0;
+/**
+ * Default dataSource name used when none is specified to a token
+ * utility or inject decorator. Single-adapter consumers never need to
+ * type this string — the default argument on every helper substitutes
+ * it automatically.
+ *
+ * Multi-adapter consumers register additional dataSources by name
+ * (`'billing'`, `'inventory'`, ...). The string `'default'` is the
+ * convention for the always-present primary registration; ADR-018
+ * documents why this fixed name was chosen over alternatives like
+ * `'main'` or `'primary'`.
+ */
+exports.DEFAULT_DATA_SOURCE_NAME = 'default';
+//# sourceMappingURL=constants.js.map

package/dist/tokens/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/tokens/constants.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACU,QAAA,wBAAwB,GAAG,SAAS,CAAC"}

package/dist/tokens/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_DATA_SOURCE_NAME } from './constants';
+export { getTransactionContextRegistryToken, getTransactionContextToken, getTransactionManagerToken, getTransactionalAdapterToken, } from './token-utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/tokens/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTransactionalAdapterToken = exports.getTransactionManagerToken = exports.getTransactionContextToken = exports.getTransactionContextRegistryToken = exports.DEFAULT_DATA_SOURCE_NAME = void 0;
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "DEFAULT_DATA_SOURCE_NAME", { enumerable: true, get: function () { return constants_1.DEFAULT_DATA_SOURCE_NAME; } });
+var token_utils_1 = require("./token-utils");
+Object.defineProperty(exports, "getTransactionContextRegistryToken", { enumerable: true, get: function () { return token_utils_1.getTransactionContextRegistryToken; } });
+Object.defineProperty(exports, "getTransactionContextToken", { enumerable: true, get: function () { return token_utils_1.getTransactionContextToken; } });
+Object.defineProperty(exports, "getTransactionManagerToken", { enumerable: true, get: function () { return token_utils_1.getTransactionManagerToken; } });
+Object.defineProperty(exports, "getTransactionalAdapterToken", { enumerable: true, get: function () { return token_utils_1.getTransactionalAdapterToken; } });
+//# sourceMappingURL=index.js.map

package/dist/tokens/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":";;;AAAA,yCAAuD;AAA9C,qHAAA,wBAAwB,OAAA;AACjC,6CAKuB;AAJrB,iIAAA,kCAAkC,OAAA;AAClC,yHAAA,0BAA0B,OAAA;AAC1B,yHAAA,0BAA0B,OAAA;AAC1B,2HAAA,4BAA4B,OAAA"}

package/dist/tokens/token-utils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Token utilities derive deterministic DI token strings from a
+ * dataSource name. They are the foundation of the multi-adapter
+ * architecture (ADR-018) — every package binds providers under
+ * `getXxxToken(dataSource)` and every consumer injects via the same
+ * function so the strings line up exactly.
+ *
+ * Format is `${dataSource}${Component}` (camelCase concat). The
+ * default dataSource is {@link DEFAULT_DATA_SOURCE_NAME} (`'default'`)
+ * — calling `getTransactionManagerToken()` yields
+ * `'defaultTransactionManager'`. A non-default name like `'billing'`
+ * yields `'billingTransactionManager'`.
+ *
+ * Empty-string `dataSource` produces a bare component string
+ * (`getTransactionManagerToken('')` → `'TransactionManager'`). That
+ * collides with the class-token shape NestJS uses for
+ * constructor-style injection (`@Inject(TransactionManager)`), so
+ * empty strings should be treated as a programming error at the call
+ * site. The default argument exists specifically to prevent users
+ * from hitting this case accidentally.
+ */
+/**
+ * DI token for the per-dataSource `TransactionManager`.
+ *
+ * @example
+ * ```ts
+ * @Inject(getTransactionManagerToken('billing'))
+ * private readonly txManager: TransactionManager;
+ * ```
+ */
+export declare function getTransactionManagerToken(dataSource?: string): string;
+/**
+ * DI token for the per-dataSource `TransactionContext`. Each
+ * dataSource carries its own `AsyncLocalStorage` instance — see
+ * DD-023 — so cross-dataSource calls do not silently enrol into a
+ * sibling transaction.
+ */
+export declare function getTransactionContextToken(dataSource?: string): string;
+/**
+ * DI token for the per-dataSource `TransactionAdapter` instance —
+ * the concrete adapter (TypeORM, Prisma, ...) bound to the named
+ * dataSource. See DD-021.
+ */
+export declare function getTransactionalAdapterToken(dataSource?: string): string;
+/**
+ * DI token for the global `TransactionContextRegistry` — a
+ * process-wide singleton that maps dataSource names to their
+ * `TransactionContext` instances. Not parameterised by dataSource:
+ * exactly one registry per process serves all adapters.
+ */
+export declare function getTransactionContextRegistryToken(): string;
+//# sourceMappingURL=token-utils.d.ts.map

package/dist/tokens/token-utils.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTransactionManagerToken = getTransactionManagerToken;
+exports.getTransactionContextToken = getTransactionContextToken;
+exports.getTransactionalAdapterToken = getTransactionalAdapterToken;
+exports.getTransactionContextRegistryToken = getTransactionContextRegistryToken;
+const constants_1 = require("./constants");
+/**
+ * Token utilities derive deterministic DI token strings from a
+ * dataSource name. They are the foundation of the multi-adapter
+ * architecture (ADR-018) — every package binds providers under
+ * `getXxxToken(dataSource)` and every consumer injects via the same
+ * function so the strings line up exactly.
+ *
+ * Format is `${dataSource}${Component}` (camelCase concat). The
+ * default dataSource is {@link DEFAULT_DATA_SOURCE_NAME} (`'default'`)
+ * — calling `getTransactionManagerToken()` yields
+ * `'defaultTransactionManager'`. A non-default name like `'billing'`
+ * yields `'billingTransactionManager'`.
+ *
+ * Empty-string `dataSource` produces a bare component string
+ * (`getTransactionManagerToken('')` → `'TransactionManager'`). That
+ * collides with the class-token shape NestJS uses for
+ * constructor-style injection (`@Inject(TransactionManager)`), so
+ * empty strings should be treated as a programming error at the call
+ * site. The default argument exists specifically to prevent users
+ * from hitting this case accidentally.
+ */
+/**
+ * DI token for the per-dataSource `TransactionManager`.
+ *
+ * @example
+ * ```ts
+ * @Inject(getTransactionManagerToken('billing'))
+ * private readonly txManager: TransactionManager;
+ * ```
+ */
+function getTransactionManagerToken(dataSource = constants_1.DEFAULT_DATA_SOURCE_NAME) {
+    return `${dataSource}TransactionManager`;
+}
+/**
+ * DI token for the per-dataSource `TransactionContext`. Each
+ * dataSource carries its own `AsyncLocalStorage` instance — see
+ * DD-023 — so cross-dataSource calls do not silently enrol into a
+ * sibling transaction.
+ */
+function getTransactionContextToken(dataSource = constants_1.DEFAULT_DATA_SOURCE_NAME) {
+    return `${dataSource}TransactionContext`;
+}
+/**
+ * DI token for the per-dataSource `TransactionAdapter` instance —
+ * the concrete adapter (TypeORM, Prisma, ...) bound to the named
+ * dataSource. See DD-021.
+ */
+function getTransactionalAdapterToken(dataSource = constants_1.DEFAULT_DATA_SOURCE_NAME) {
+    return `${dataSource}TransactionalAdapter`;
+}
+/**
+ * DI token for the global `TransactionContextRegistry` — a
+ * process-wide singleton that maps dataSource names to their
+ * `TransactionContext` instances. Not parameterised by dataSource:
+ * exactly one registry per process serves all adapters.
+ */
+function getTransactionContextRegistryToken() {
+    return 'TransactionContextRegistry';
+}
+//# sourceMappingURL=token-utils.js.map

package/dist/tokens/token-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-utils.js","sourceRoot":"","sources":["../../src/tokens/token-utils.ts"],"names":[],"mappings":";;AAiCA,gEAIC;AAQD,gEAIC;AAOD,oEAIC;AAQD,gFAEC;AAtED,2CAAuD;AAEvD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;GAQG;AACH,SAAgB,0BAA0B,CACxC,aAAqB,oCAAwB;IAE7C,OAAO,GAAG,UAAU,oBAAoB,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,0BAA0B,CACxC,aAAqB,oCAAwB;IAE7C,OAAO,GAAG,UAAU,oBAAoB,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,SAAgB,4BAA4B,CAC1C,aAAqB,oCAAwB;IAE7C,OAAO,GAAG,UAAU,sBAAsB,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kCAAkC;IAChD,OAAO,4BAA4B,CAAC;AACtC,CAAC"}

package/dist/types/domain-event.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Marker interface for domain events routed through the transactional
+ * event dispatcher. Purely structural — any value with a compatible shape
+ * satisfies it.
+ *
+ * Exists to document intent in handler and listener signatures and to keep
+ * cross-package type references consistent without importing
+ * `@nestjs/cqrs` into core.
+ */
+export interface DomainEvent {
+    /**
+     * Wall-clock time at which the event was produced. Optional: some
+     * producers may omit it and let the dispatcher stamp it when the event
+     * is enqueued.
+     */
+    readonly occurredAt?: Date;
+}
+//# sourceMappingURL=domain-event.d.ts.map

package/dist/types/domain-event.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=domain-event.js.map

package/dist/types/domain-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-event.js","sourceRoot":"","sources":["../../src/types/domain-event.ts"],"names":[],"mappings":""}

package/dist/types/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Base class for all errors thrown by `@nestjs-transactional` packages.
+ * Every subclass carries a stable {@link code} suitable for structured
+ * logging, metrics, and NestJS exception filters.
+ *
+ * The constructor sets `this.name` to the subclass name via `new.target`
+ * so that stack traces identify the concrete error type rather than
+ * generic `Error`.
+ */
+export declare abstract class TransactionError extends Error {
+    /**
+     * Stable machine-readable error code. Part of the public contract —
+     * callers may rely on it for error handling; changes are breaking.
+     */
+    abstract readonly code: string;
+    constructor(message?: string);
+}
+/**
+ * Thrown when the current async context's transactional state does not
+ * satisfy the requested `PropagationMode`. Examples: `NEVER` invoked
+ * inside an active transaction; `MANDATORY` invoked outside of one; an
+ * adapter that does not support savepoints asked to run `NESTED`.
+ */
+export declare class IllegalTransactionStateError extends TransactionError {
+    readonly code = "ILLEGAL_TRANSACTION_STATE";
+}
+/**
+ * Thrown when `TransactionManager.run` is asked to use an adapter
+ * (identified by type name + instance name) that was never registered
+ * with the core `AdapterRegistry`.
+ *
+ * The message lists both identifiers and points at the likely missing
+ * module registration so the fix is obvious from the stack trace.
+ */
+export declare class TransactionAdapterNotFoundError extends TransactionError {
+    readonly code = "TRANSACTION_ADAPTER_NOT_FOUND";
+    readonly adapterName: string;
+    readonly instanceName: string;
+    constructor(adapterName: string, instanceName: string);
+}
+/**
+ * Thrown when an outbox producer fails to persist an event inside a
+ * transaction. Wrapping the underlying error lets callers distinguish
+ * outbox-write failures from business-logic errors when deciding on
+ * retry policy.
+ */
+export declare class OutboxWriteError extends TransactionError {
+    readonly code = "OUTBOX_WRITE_ERROR";
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxWriteError = exports.TransactionAdapterNotFoundError = exports.IllegalTransactionStateError = exports.TransactionError = void 0;
+/**
+ * Base class for all errors thrown by `@nestjs-transactional` packages.
+ * Every subclass carries a stable {@link code} suitable for structured
+ * logging, metrics, and NestJS exception filters.
+ *
+ * The constructor sets `this.name` to the subclass name via `new.target`
+ * so that stack traces identify the concrete error type rather than
+ * generic `Error`.
+ */
+class TransactionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+exports.TransactionError = TransactionError;
+/**
+ * Thrown when the current async context's transactional state does not
+ * satisfy the requested `PropagationMode`. Examples: `NEVER` invoked
+ * inside an active transaction; `MANDATORY` invoked outside of one; an
+ * adapter that does not support savepoints asked to run `NESTED`.
+ */
+class IllegalTransactionStateError extends TransactionError {
+    code = 'ILLEGAL_TRANSACTION_STATE';
+}
+exports.IllegalTransactionStateError = IllegalTransactionStateError;
+/**
+ * Thrown when `TransactionManager.run` is asked to use an adapter
+ * (identified by type name + instance name) that was never registered
+ * with the core `AdapterRegistry`.
+ *
+ * The message lists both identifiers and points at the likely missing
+ * module registration so the fix is obvious from the stack trace.
+ */
+class TransactionAdapterNotFoundError extends TransactionError {
+    code = 'TRANSACTION_ADAPTER_NOT_FOUND';
+    adapterName;
+    instanceName;
+    constructor(adapterName, instanceName) {
+        super(`Transaction adapter not found: ${adapterName}:${instanceName}. ` +
+            `Did you register it via the corresponding transactional module ` +
+            `(e.g. TypeOrmTransactionalModule.forFeature())?`);
+        this.adapterName = adapterName;
+        this.instanceName = instanceName;
+    }
+}
+exports.TransactionAdapterNotFoundError = TransactionAdapterNotFoundError;
+/**
+ * Thrown when an outbox producer fails to persist an event inside a
+ * transaction. Wrapping the underlying error lets callers distinguish
+ * outbox-write failures from business-logic errors when deciding on
+ * retry policy.
+ */
+class OutboxWriteError extends TransactionError {
+    code = 'OUTBOX_WRITE_ERROR';
+}
+exports.OutboxWriteError = OutboxWriteError;
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAsB,gBAAiB,SAAQ,KAAK;IAOlD,YAAY,OAAgB;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAXD,4CAWC;AAED;;;;;GAKG;AACH,MAAa,4BAA6B,SAAQ,gBAAgB;IACvD,IAAI,GAAG,2BAA2B,CAAC;CAC7C;AAFD,oEAEC;AAED;;;;;;;GAOG;AACH,MAAa,+BAAgC,SAAQ,gBAAgB;IAC1D,IAAI,GAAG,+BAA+B,CAAC;IAEvC,WAAW,CAAS;IACpB,YAAY,CAAS;IAE9B,YAAY,WAAmB,EAAE,YAAoB;QACnD,KAAK,CACH,kCAAkC,WAAW,IAAI,YAAY,IAAI;YAC/D,iEAAiE;YACjE,iDAAiD,CACpD,CAAC;QACF,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAfD,0EAeC;AAED;;;;;GAKG;AACH,MAAa,gBAAiB,SAAQ,gBAAgB;IAC3C,IAAI,GAAG,oBAAoB,CAAC;CACtC;AAFD,4CAEC"}

package/dist/types/isolation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Standard SQL transaction isolation level, expressed as a string union
+ * rather than an enum — these values mirror an external protocol, and a
+ * union keeps them treatable as plain string literals in user code.
+ *
+ * Refer to the SQL standard (ISO/IEC 9075) for the precise read-phenomena
+ * guarantees of each level. Not every adapter/database supports every
+ * level; adapters map unsupported levels to an adapter-level error.
+ */
+export type IsolationLevel = 'READ_UNCOMMITTED' | 'READ_COMMITTED' | 'REPEATABLE_READ' | 'SERIALIZABLE';
+//# sourceMappingURL=isolation.d.ts.map

package/dist/types/isolation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=isolation.js.map

package/dist/types/isolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolation.js","sourceRoot":"","sources":["../../src/types/isolation.ts"],"names":[],"mappings":""}

package/dist/types/propagation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Transaction propagation mode — how `@Transactional` behaves when invoked
+ * in the presence (or absence) of an already-active transaction.
+ *
+ * Modeled on Spring Framework's
+ * `org.springframework.transaction.annotation.Propagation`.
+ *
+ * @see https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/tx-propagation.html
+ */
+export declare enum PropagationMode {
+    /**
+     * Join the current transaction if one exists; otherwise start a new one.
+     * The default mode — the common choice for business methods that want
+     * transactional safety without caring where they are called from.
+     */
+    REQUIRED = "REQUIRED",
+    /**
+     * Always start a new transaction, suspending the current one if present.
+     * The suspended transaction resumes when the new one completes (commit or
+     * rollback).
+     *
+     * Use for operations that must succeed or fail independently of the
+     * caller's transaction — e.g. audit logging that should persist even when
+     * the caller rolls back.
+     */
+    REQUIRES_NEW = "REQUIRES_NEW",
+    /**
+     * Run inside a nested transaction using `SAVEPOINT` semantics when a
+     * transaction is active. The nested scope can be rolled back without
+     * affecting the outer transaction.
+     *
+     * Requires adapter support for savepoints. On Postgres/MySQL via TypeORM
+     * this is implemented with `SAVEPOINT` / `ROLLBACK TO SAVEPOINT`.
+     *
+     * Outside of an existing transaction, behaves like {@link REQUIRED}.
+     */
+    NESTED = "NESTED",
+    /**
+     * Join the current transaction if one exists; otherwise run
+     * non-transactionally. Useful for read-oriented operations that should
+     * participate when called from a transactional context but not start
+     * one of their own.
+     */
+    SUPPORTS = "SUPPORTS",
+    /**
+     * Run non-transactionally, suspending the current transaction if one
+     * exists. The caller's transaction resumes after the method returns.
+     */
+    NOT_SUPPORTED = "NOT_SUPPORTED",
+    /**
+     * Run non-transactionally; throw `IllegalTransactionStateError` if a
+     * transaction is active. Use as an assertion that a method must not be
+     * invoked inside a transaction.
+     */
+    NEVER = "NEVER",
+    /**
+     * Join the current transaction if one exists; throw
+     * `IllegalTransactionStateError` if not. Use as an assertion that the
+     * caller must already be inside an active transaction.
+     */
+    MANDATORY = "MANDATORY"
+}
+//# sourceMappingURL=propagation.d.ts.map

package/dist/types/propagation.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropagationMode = void 0;
+/**
+ * Transaction propagation mode — how `@Transactional` behaves when invoked
+ * in the presence (or absence) of an already-active transaction.
+ *
+ * Modeled on Spring Framework's
+ * `org.springframework.transaction.annotation.Propagation`.
+ *
+ * @see https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/tx-propagation.html
+ */
+var PropagationMode;
+(function (PropagationMode) {
+    /**
+     * Join the current transaction if one exists; otherwise start a new one.
+     * The default mode — the common choice for business methods that want
+     * transactional safety without caring where they are called from.
+     */
+    PropagationMode["REQUIRED"] = "REQUIRED";
+    /**
+     * Always start a new transaction, suspending the current one if present.
+     * The suspended transaction resumes when the new one completes (commit or
+     * rollback).
+     *
+     * Use for operations that must succeed or fail independently of the
+     * caller's transaction — e.g. audit logging that should persist even when
+     * the caller rolls back.
+     */
+    PropagationMode["REQUIRES_NEW"] = "REQUIRES_NEW";
+    /**
+     * Run inside a nested transaction using `SAVEPOINT` semantics when a
+     * transaction is active. The nested scope can be rolled back without
+     * affecting the outer transaction.
+     *
+     * Requires adapter support for savepoints. On Postgres/MySQL via TypeORM
+     * this is implemented with `SAVEPOINT` / `ROLLBACK TO SAVEPOINT`.
+     *
+     * Outside of an existing transaction, behaves like {@link REQUIRED}.
+     */
+    PropagationMode["NESTED"] = "NESTED";
+    /**
+     * Join the current transaction if one exists; otherwise run
+     * non-transactionally. Useful for read-oriented operations that should
+     * participate when called from a transactional context but not start
+     * one of their own.
+     */
+    PropagationMode["SUPPORTS"] = "SUPPORTS";
+    /**
+     * Run non-transactionally, suspending the current transaction if one
+     * exists. The caller's transaction resumes after the method returns.
+     */
+    PropagationMode["NOT_SUPPORTED"] = "NOT_SUPPORTED";
+    /**
+     * Run non-transactionally; throw `IllegalTransactionStateError` if a
+     * transaction is active. Use as an assertion that a method must not be
+     * invoked inside a transaction.
+     */
+    PropagationMode["NEVER"] = "NEVER";
+    /**
+     * Join the current transaction if one exists; throw
+     * `IllegalTransactionStateError` if not. Use as an assertion that the
+     * caller must already be inside an active transaction.
+     */
+    PropagationMode["MANDATORY"] = "MANDATORY";
+})(PropagationMode || (exports.PropagationMode = PropagationMode = {}));
+//# sourceMappingURL=propagation.js.map

package/dist/types/propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.js","sourceRoot":"","sources":["../../src/types/propagation.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,IAAY,eA0DX;AA1DD,WAAY,eAAe;IACzB;;;;OAIG;IACH,wCAAqB,CAAA;IAErB;;;;;;;;OAQG;IACH,gDAA6B,CAAA;IAE7B;;;;;;;;;OASG;IACH,oCAAiB,CAAA;IAEjB;;;;;OAKG;IACH,wCAAqB,CAAA;IAErB;;;OAGG;IACH,kDAA+B,CAAA;IAE/B;;;;OAIG;IACH,kCAAe,CAAA;IAEf;;;;OAIG;IACH,0CAAuB,CAAA;AACzB,CAAC,EA1DW,eAAe,+BAAf,eAAe,QA0D1B"}

package/dist/types/transaction-adapter.d.ts

@@ -0,0 +1,72 @@
+import type { TransactionHandle } from './transaction-handle';
+import type { TransactionOptions } from './transaction-options';
+/**
+ * Port for ORM-specific transaction execution. Core defines this interface;
+ * each ORM integration package (for example
+ * `@nestjs-transactional/typeorm`) ships a concrete implementation.
+ *
+ * Adapters are deliberately minimal. The manager handles propagation,
+ * rollback classification, hook execution, and observability. Adapters only
+ * know how to execute a function inside a fresh transaction or a nested
+ * savepoint.
+ *
+ * @typeParam THandle - The adapter-specific handle type. Defaults to the
+ *   base {@link TransactionHandle}; concrete adapters narrow this to their
+ *   own extended handle (e.g. `TypeOrmTransactionHandle`).
+ */
+export interface TransactionAdapter<THandle extends TransactionHandle = TransactionHandle> {
+    /**
+     * Adapter type identifier, e.g. `'typeorm'` or `'prisma'`. Used by the
+     * registry to route transactions to the correct adapter when
+     * `ExtendedTransactionOptions.adapter` is set.
+     */
+    readonly name: string;
+    /**
+     * Public dataSource name this adapter instance is bound to (DD-021).
+     * The single string identifier the multi-adapter API thinks in —
+     * `'default'`, `'billing'`, `'inventory'`, etc. Provided by the adapter
+     * (typically through its constructor) so consumers do not need to
+     * track adapter type and instance name separately.
+     *
+     * For backwards compatibility this is also the value used as the
+     * `instanceName` slot in {@link AdapterRegistration} when the adapter
+     * is auto-registered via `TransactionalModule.forRoot({ adapter })`.
+     */
+    readonly dataSourceName: string;
+    /**
+     * Execute `fn` inside a new transaction. The callback receives an opaque
+     * handle whose runtime type is the adapter-specific `THandle`.
+     *
+     * Contract:
+     * - If `fn` resolves, the adapter commits and returns the resolved value.
+     * - If `fn` rejects, the adapter rolls back and rethrows the error.
+     * - The adapter is responsible for transaction lifecycle only — hook
+     *   firing, propagation logic, and rollback classification are the
+     *   manager's job.
+     *
+     * @param options - Isolation, read-only flag, and timeout.
+     * @param fn - Async callback to execute inside the transaction.
+     * @returns The value resolved by `fn`.
+     */
+    runInTransaction<T>(options: TransactionOptions, fn: (handle: THandle) => Promise<T>): Promise<T>;
+    /**
+     * Execute `fn` inside a savepoint nested under `parent`. Used by the
+     * manager to implement `PropagationMode.NESTED`.
+     *
+     * Contract:
+     * - If `fn` resolves, the adapter releases the savepoint and returns
+     *   the value.
+     * - If `fn` rejects, the adapter rolls back to the savepoint and
+     *   rethrows the error.
+     * - The parent transaction is not affected by the inner rollback.
+     *
+     * Adapters that do not support savepoints should throw
+     * `IllegalTransactionStateError` with a clear, actionable message.
+     *
+     * @param parent - Handle of the enclosing transaction.
+     * @param fn - Async callback to execute inside the savepoint.
+     * @returns The value resolved by `fn`.
+     */
+    runInSavepoint<T>(parent: THandle, fn: (handle: THandle) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=transaction-adapter.d.ts.map

package/dist/types/transaction-adapter.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=transaction-adapter.js.map

package/dist/types/transaction-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-adapter.js","sourceRoot":"","sources":["../../src/types/transaction-adapter.ts"],"names":[],"mappings":""}

package/dist/types/transaction-handle.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Opaque handle returned by a `TransactionAdapter` while a transaction is
+ * active. Adapter implementations extend this interface with their own
+ * runtime fields (for example, the TypeORM adapter adds `entityManager`).
+ *
+ * Core code only sees {@link id} and {@link adapterName}; adapter-specific
+ * helpers cast to the narrower handle type to read their own fields.
+ */
+export interface TransactionHandle {
+    /**
+     * Unique identifier of this transaction, assigned by the adapter on
+     * begin. Used by observability hooks, logging, and debugging to correlate
+     * events with a single transaction lifetime.
+     */
+    readonly id: string;
+    /**
+     * Name of the adapter that owns this handle. Matches the adapter's
+     * `name` property and the key under which it is registered in the
+     * `AdapterRegistry`.
+     */
+    readonly adapterName: string;
+}
+//# sourceMappingURL=transaction-handle.d.ts.map

package/dist/types/transaction-handle.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=transaction-handle.js.map

package/dist/types/transaction-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-handle.js","sourceRoot":"","sources":["../../src/types/transaction-handle.ts"],"names":[],"mappings":""}