@nestjs-transactional/core 1.0.0-alpha.0

package/dist/context/transaction.context.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionContext = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const errors_1 = require("../types/errors");
+const als = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * Thin façade over `AsyncLocalStorage` that carries the active
+ * {@link TransactionContextStore} across async boundaries. This is the
+ * foundation of the module — every decorator, interceptor, and adapter helper
+ * ultimately asks this class whether a transaction is live on the current
+ * async chain.
+ *
+ * **Internal Map key format**: `${adapterName}:${instanceName}` (composite)
+ * for historical reasons and cross-package compatibility — typeorm
+ * helpers, the CQRS dispatcher, and the outbox publisher all consume
+ * this format directly via {@link getActiveTransaction}. The composite
+ * key is also the format `TransactionManager` writes under.
+ *
+ * **Public dataSource-name access**:
+ * {@link getActiveTransactionByDataSource} provides dataSource-name
+ * lookup for Phase 14.2+ multi-adapter consumers — it scans the Map
+ * for the entry whose `adapterInstanceName === dataSource`. Both
+ * access patterns coexist; future cleanup is possible once
+ * cross-package consumers migrate to the dataSource-name lookup and
+ * no backwards-compatibility constraints remain.
+ */
+class TransactionContext {
+    /**
+     * Run `fn` inside a transaction context scope.
+     *
+     * - If there is no active store on the current async chain, a new store is
+     *   created (empty active-transaction map, `correlationId`, current time)
+     *   and installed for the duration of `fn`.
+     * - If there is already an active store, `fn` is executed directly — the
+     *   existing store is reused. The `correlationId` argument is ignored in
+     *   that case; the outermost scope owns the correlation id.
+     *
+     * Propagates the value resolved (or error thrown) by `fn`.
+     */
+    static run(correlationId, fn) {
+        if (als.getStore() !== undefined) {
+            return fn();
+        }
+        const store = {
+            activeTransactions: new Map(),
+            correlationId,
+            startedAt: new Date(),
+        };
+        return als.run(store, fn);
+    }
+    /** Return the active store, or `undefined` if called outside any run() scope. */
+    static getStore() {
+        return als.getStore();
+    }
+    /** Return the active transaction registered under `adapterInstanceName`, or `undefined`. */
+    static getActiveTransaction(adapterInstanceName) {
+        return als.getStore()?.activeTransactions.get(adapterInstanceName);
+    }
+    /**
+     * Return the active transaction whose adapter instance was
+     * registered under the given dataSource name (DD-020 / DD-023).
+     * Scans the active-transactions Map for the entry whose
+     * `adapterInstanceName === dataSource`.
+     *
+     * Returns the first match — there is exactly one active transaction
+     * per dataSource by construction (multiple adapters sharing the
+     * same dataSource name is rejected at the registry level by
+     * {@link AdapterRegistry.getByDataSource}).
+     *
+     * Used by {@link TransactionContextView} and by smart-facade
+     * publishers to answer "is there an active transaction for *my*
+     * dataSource?" without needing to know the adapter type that owns
+     * the dataSource.
+     */
+    static getActiveTransactionByDataSource(dataSource) {
+        const store = als.getStore();
+        if (store === undefined) {
+            return undefined;
+        }
+        for (const tx of store.activeTransactions.values()) {
+            if (tx.adapterInstanceName === dataSource) {
+                return tx;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Register `tx` under `adapterInstanceName` on the current store.
+     *
+     * @throws {IllegalTransactionStateError} If called outside of a run() scope.
+     *   Adapters must not attempt to register a transaction without a
+     *   surrounding context — doing so would leak the transaction state.
+     */
+    static setActiveTransaction(adapterInstanceName, tx) {
+        const store = als.getStore();
+        if (store === undefined) {
+            throw new errors_1.IllegalTransactionStateError('Cannot set active transaction outside of TransactionContext.run()');
+        }
+        store.activeTransactions.set(adapterInstanceName, tx);
+    }
+    /**
+     * Remove the active transaction registered under `adapterInstanceName`.
+     * Idempotent: a no-op when no store is active or the instance is not
+     * registered, so that adapter cleanup paths can call it unconditionally.
+     */
+    static removeActiveTransaction(adapterInstanceName) {
+        als.getStore()?.activeTransactions.delete(adapterInstanceName);
+    }
+}
+exports.TransactionContext = TransactionContext;
+//# sourceMappingURL=transaction.context.js.map

package/dist/context/transaction.context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.context.js","sourceRoot":"","sources":["../../src/context/transaction.context.ts"],"names":[],"mappings":";;;AAAA,uDAAqD;AAErD,4CAA+D;AAwD/D,MAAM,GAAG,GAAG,IAAI,oCAAiB,EAA2B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,kBAAkB;IAC7B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,GAAG,CAAI,aAAqB,EAAE,EAAoB;QACvD,IAAI,GAAG,CAAC,QAAQ,EAAE,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;QACD,MAAM,KAAK,GAA4B;YACrC,kBAAkB,EAAE,IAAI,GAAG,EAA6B;YACxD,aAAa;YACb,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;QACF,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,QAAQ;QACb,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAED,4FAA4F;IAC5F,MAAM,CAAC,oBAAoB,CAAC,mBAA2B;QACrD,OAAO,GAAG,CAAC,QAAQ,EAAE,EAAE,kBAAkB,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,gCAAgC,CACrC,UAAkB;QAElB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,kBAAkB,CAAC,MAAM,EAAE,EAAE,CAAC;YACnD,IAAI,EAAE,CAAC,mBAAmB,KAAK,UAAU,EAAE,CAAC;gBAC1C,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CAAC,mBAA2B,EAAE,EAAqB;QAC5E,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,qCAA4B,CACpC,mEAAmE,CACpE,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;IACxD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,uBAAuB,CAAC,mBAA2B;QACxD,GAAG,CAAC,QAAQ,EAAE,EAAE,kBAAkB,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACjE,CAAC;CACF;AA3FD,gDA2FC"}

package/dist/decorators/inject-decorators.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Inject the per-dataSource `TransactionManager`. Sugar over
+ * `@Inject(getTransactionManagerToken(dataSource))` for IDE
+ * discoverability — matches `@nestjs/typeorm`'s
+ * `@InjectRepository(Entity, dataSource?)` ergonomics (DD-022).
+ *
+ * Default `dataSource` is `'default'`, so single-adapter consumers
+ * write `@InjectTransactionManager()` exactly where they would have
+ * written `@Inject(TransactionManager)` before.
+ *
+ * @example
+ * ```ts
+ * class BillingService {
+ *   constructor(
+ *     @InjectTransactionManager()
+ *     private readonly txManager: TransactionManager,
+ *     @InjectTransactionManager('billing')
+ *     private readonly billingTxManager: TransactionManager,
+ *   ) {}
+ * }
+ * ```
+ */
+export declare const InjectTransactionManager: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `TransactionContext`. See
+ * {@link InjectTransactionManager} for ergonomics.
+ */
+export declare const InjectTransactionContext: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `TransactionAdapter` instance. Useful
+ * for advanced consumers that need to call adapter-specific methods
+ * not exposed through `TransactionManager`. See
+ * {@link InjectTransactionManager} for ergonomics.
+ */
+export declare const InjectTransactionalAdapter: (dataSource?: string) => ParameterDecorator;
+//# sourceMappingURL=inject-decorators.d.ts.map

package/dist/decorators/inject-decorators.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectTransactionalAdapter = exports.InjectTransactionContext = exports.InjectTransactionManager = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("../tokens/constants");
+const token_utils_1 = require("../tokens/token-utils");
+/**
+ * Inject the per-dataSource `TransactionManager`. Sugar over
+ * `@Inject(getTransactionManagerToken(dataSource))` for IDE
+ * discoverability — matches `@nestjs/typeorm`'s
+ * `@InjectRepository(Entity, dataSource?)` ergonomics (DD-022).
+ *
+ * Default `dataSource` is `'default'`, so single-adapter consumers
+ * write `@InjectTransactionManager()` exactly where they would have
+ * written `@Inject(TransactionManager)` before.
+ *
+ * @example
+ * ```ts
+ * class BillingService {
+ *   constructor(
+ *     @InjectTransactionManager()
+ *     private readonly txManager: TransactionManager,
+ *     @InjectTransactionManager('billing')
+ *     private readonly billingTxManager: TransactionManager,
+ *   ) {}
+ * }
+ * ```
+ */
+const InjectTransactionManager = (dataSource = constants_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getTransactionManagerToken)(dataSource));
+exports.InjectTransactionManager = InjectTransactionManager;
+/**
+ * Inject the per-dataSource `TransactionContext`. See
+ * {@link InjectTransactionManager} for ergonomics.
+ */
+const InjectTransactionContext = (dataSource = constants_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getTransactionContextToken)(dataSource));
+exports.InjectTransactionContext = InjectTransactionContext;
+/**
+ * Inject the per-dataSource `TransactionAdapter` instance. Useful
+ * for advanced consumers that need to call adapter-specific methods
+ * not exposed through `TransactionManager`. See
+ * {@link InjectTransactionManager} for ergonomics.
+ */
+const InjectTransactionalAdapter = (dataSource = constants_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getTransactionalAdapterToken)(dataSource));
+exports.InjectTransactionalAdapter = InjectTransactionalAdapter;
+//# sourceMappingURL=inject-decorators.js.map

package/dist/decorators/inject-decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-decorators.js","sourceRoot":"","sources":["../../src/decorators/inject-decorators.ts"],"names":[],"mappings":";;;AAAA,2CAAwC;AAExC,mDAA+D;AAC/D,uDAI+B;AAE/B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACI,MAAM,wBAAwB,GAAG,CACtC,aAAqB,oCAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,wCAA0B,EAAC,UAAU,CAAC,CAAC,CAAC;AAF3D,QAAA,wBAAwB,4BAEmC;AAExE;;;GAGG;AACI,MAAM,wBAAwB,GAAG,CACtC,aAAqB,oCAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,wCAA0B,EAAC,UAAU,CAAC,CAAC,CAAC;AAF3D,QAAA,wBAAwB,4BAEmC;AAExE;;;;;GAKG;AACI,MAAM,0BAA0B,GAAG,CACxC,aAAqB,oCAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,0CAA4B,EAAC,UAAU,CAAC,CAAC,CAAC;AAF7D,QAAA,0BAA0B,8BAEmC"}

package/dist/decorators/transactional.decorator.d.ts

@@ -0,0 +1,64 @@
+import type { ExtendedTransactionOptions } from '../types/transaction-options';
+/**
+ * Metadata key under which {@link Transactional} stores its options on a
+ * target (a method's function object or a class constructor). Exposed for
+ * advanced introspection; most code should use
+ * {@link getTransactionalMetadata}.
+ */
+export declare const TRANSACTIONAL_METADATA: unique symbol;
+/**
+ * Shape of the metadata attached by {@link Transactional}. Currently an
+ * alias for {@link ExtendedTransactionOptions} — kept as a distinct name so
+ * the decorator's public surface is self-documenting and so decorator-only
+ * options can be added later without touching the manager's options type.
+ */
+export type TransactionalMetadata = ExtendedTransactionOptions;
+/**
+ * Mark a method or a class as transactional.
+ *
+ * **Metadata-only**: this decorator does NOT wrap the method at decoration
+ * time. The actual wrapping is performed at runtime by the three coordinated
+ * mechanisms described in ADR-005 — `TransactionalInterceptor` for
+ * request-boundary handlers, `TransactionalMethodsBootstrap` for regular
+ * `@Injectable` providers, and `CqrsHandlerWrapper` for CQRS handlers.
+ *
+ * Usage:
+ * - As a method decorator, the metadata is written onto `descriptor.value`
+ *   (the method function).
+ * - As a class decorator, the metadata is written onto the class
+ *   constructor. Downstream wrapping mechanisms treat every method of the
+ *   class as transactional with these options (unless a method has its own
+ *   `@Transactional` which overrides).
+ *
+ * Default propagation is {@link PropagationMode.REQUIRED}.
+ */
+export declare function Transactional(options?: Partial<TransactionalMetadata>): MethodDecorator & ClassDecorator;
+/**
+ * Alias for `@Transactional({ readOnly: true })`. Use on query methods that
+ * must not mutate state. Options are applied first and the `readOnly: true`
+ * flag is overlaid on top, so callers cannot turn it off from here — use
+ * `@Transactional` directly if that is the intent.
+ */
+export declare const ReadOnly: (options?: Partial<TransactionalMetadata>) => MethodDecorator & ClassDecorator;
+/**
+ * Alias for `@Transactional({ adapterInstance })`. Targets a specific
+ * adapter instance, for multi-datasource setups:
+ *
+ * ```ts
+ * @TransactionalOn('billing')
+ * async issueInvoice() { ... }
+ * ```
+ *
+ * The `adapterInstance` argument overrides any `adapterInstance` set in the
+ * options object.
+ */
+export declare const TransactionalOn: (adapterInstance: string, options?: Partial<TransactionalMetadata>) => MethodDecorator & ClassDecorator;
+/**
+ * Read the {@link TransactionalMetadata} stored by {@link Transactional} on
+ * `target`. Returns `undefined` when the target was not decorated.
+ *
+ * @param target - A class constructor (for class-level metadata) or a
+ *   method function (for method-level metadata).
+ */
+export declare function getTransactionalMetadata(target: object): TransactionalMetadata | undefined;
+//# sourceMappingURL=transactional.decorator.d.ts.map

package/dist/decorators/transactional.decorator.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalOn = exports.ReadOnly = exports.TRANSACTIONAL_METADATA = void 0;
+exports.Transactional = Transactional;
+exports.getTransactionalMetadata = getTransactionalMetadata;
+const propagation_1 = require("../types/propagation");
+/**
+ * Metadata key under which {@link Transactional} stores its options on a
+ * target (a method's function object or a class constructor). Exposed for
+ * advanced introspection; most code should use
+ * {@link getTransactionalMetadata}.
+ */
+exports.TRANSACTIONAL_METADATA = Symbol('TRANSACTIONAL_METADATA');
+/**
+ * Mark a method or a class as transactional.
+ *
+ * **Metadata-only**: this decorator does NOT wrap the method at decoration
+ * time. The actual wrapping is performed at runtime by the three coordinated
+ * mechanisms described in ADR-005 — `TransactionalInterceptor` for
+ * request-boundary handlers, `TransactionalMethodsBootstrap` for regular
+ * `@Injectable` providers, and `CqrsHandlerWrapper` for CQRS handlers.
+ *
+ * Usage:
+ * - As a method decorator, the metadata is written onto `descriptor.value`
+ *   (the method function).
+ * - As a class decorator, the metadata is written onto the class
+ *   constructor. Downstream wrapping mechanisms treat every method of the
+ *   class as transactional with these options (unless a method has its own
+ *   `@Transactional` which overrides).
+ *
+ * Default propagation is {@link PropagationMode.REQUIRED}.
+ */
+function Transactional(options = {}) {
+    const metadata = {
+        propagation: propagation_1.PropagationMode.REQUIRED,
+        ...options,
+    };
+    const decorator = (target, _propertyKey, descriptor) => {
+        const methodTarget = descriptor?.value;
+        if (typeof methodTarget === 'function') {
+            Reflect.defineMetadata(exports.TRANSACTIONAL_METADATA, metadata, methodTarget);
+        }
+        else {
+            Reflect.defineMetadata(exports.TRANSACTIONAL_METADATA, metadata, target);
+        }
+    };
+    return decorator;
+}
+/**
+ * Alias for `@Transactional({ readOnly: true })`. Use on query methods that
+ * must not mutate state. Options are applied first and the `readOnly: true`
+ * flag is overlaid on top, so callers cannot turn it off from here — use
+ * `@Transactional` directly if that is the intent.
+ */
+const ReadOnly = (options = {}) => Transactional({ ...options, readOnly: true });
+exports.ReadOnly = ReadOnly;
+/**
+ * Alias for `@Transactional({ adapterInstance })`. Targets a specific
+ * adapter instance, for multi-datasource setups:
+ *
+ * ```ts
+ * @TransactionalOn('billing')
+ * async issueInvoice() { ... }
+ * ```
+ *
+ * The `adapterInstance` argument overrides any `adapterInstance` set in the
+ * options object.
+ */
+const TransactionalOn = (adapterInstance, options = {}) => Transactional({ ...options, adapterInstance });
+exports.TransactionalOn = TransactionalOn;
+/**
+ * Read the {@link TransactionalMetadata} stored by {@link Transactional} on
+ * `target`. Returns `undefined` when the target was not decorated.
+ *
+ * @param target - A class constructor (for class-level metadata) or a
+ *   method function (for method-level metadata).
+ */
+function getTransactionalMetadata(target) {
+    const value = Reflect.getMetadata(exports.TRANSACTIONAL_METADATA, target);
+    return value;
+}
+//# sourceMappingURL=transactional.decorator.js.map

package/dist/decorators/transactional.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional.decorator.js","sourceRoot":"","sources":["../../src/decorators/transactional.decorator.ts"],"names":[],"mappings":";;;AAsCA,sCAsBC;AAoCD,4DAGC;AAnGD,sDAAuD;AAGvD;;;;;GAKG;AACU,QAAA,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAUvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,aAAa,CAC3B,UAA0C,EAAE;IAE5C,MAAM,QAAQ,GAA0B;QACtC,WAAW,EAAE,6BAAe,CAAC,QAAQ;QACrC,GAAG,OAAO;KACX,CAAC;IAEF,MAAM,SAAS,GAAqC,CAClD,MAAc,EACd,YAA8B,EAC9B,UAA+B,EACzB,EAAE;QACR,MAAM,YAAY,GAAY,UAAU,EAAE,KAAK,CAAC;QAChD,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;YACvC,OAAO,CAAC,cAAc,CAAC,8BAAsB,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;QACzE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,cAAc,CAAC,8BAAsB,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACI,MAAM,QAAQ,GAAG,CACtB,UAA0C,EAAE,EACV,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAFxE,QAAA,QAAQ,YAEgE;AAErF;;;;;;;;;;;GAWG;AACI,MAAM,eAAe,GAAG,CAC7B,eAAuB,EACvB,UAA0C,EAAE,EACV,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,OAAO,EAAE,eAAe,EAAE,CAAC,CAAC;AAHzE,QAAA,eAAe,mBAG0D;AAEtF;;;;;;GAMG;AACH,SAAgB,wBAAwB,CAAC,MAAc;IACrD,MAAM,KAAK,GAAY,OAAO,CAAC,WAAW,CAAC,8BAAsB,EAAE,MAAM,CAAC,CAAC;IAC3E,OAAO,KAA0C,CAAC;AACpD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export * from './types/propagation';
+export * from './types/isolation';
+export * from './types/transaction-handle';
+export * from './types/transaction-options';
+export * from './types/transaction-adapter';
+export * from './types/domain-event';
+export * from './types/errors';
+export * from './context/transaction.context';
+export * from './context/transaction-context-view';
+export * from './manager/adapter.registry';
+export * from './manager/transaction.manager';
+export * from './decorators/transactional.decorator';
+export * from './decorators/inject-decorators';
+export * from './tokens';
+export * from './interceptor/transactional.interceptor';
+export * from './bootstrap/transactional-methods.bootstrap';
+export * from './module/transactional.module';
+export * from './observability/transaction-observer';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/propagation"), exports);
+__exportStar(require("./types/isolation"), exports);
+__exportStar(require("./types/transaction-handle"), exports);
+__exportStar(require("./types/transaction-options"), exports);
+__exportStar(require("./types/transaction-adapter"), exports);
+__exportStar(require("./types/domain-event"), exports);
+__exportStar(require("./types/errors"), exports);
+__exportStar(require("./context/transaction.context"), exports);
+__exportStar(require("./context/transaction-context-view"), exports);
+__exportStar(require("./manager/adapter.registry"), exports);
+__exportStar(require("./manager/transaction.manager"), exports);
+__exportStar(require("./decorators/transactional.decorator"), exports);
+__exportStar(require("./decorators/inject-decorators"), exports);
+__exportStar(require("./tokens"), exports);
+__exportStar(require("./interceptor/transactional.interceptor"), exports);
+__exportStar(require("./bootstrap/transactional-methods.bootstrap"), exports);
+__exportStar(require("./module/transactional.module"), exports);
+__exportStar(require("./observability/transaction-observer"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,oDAAkC;AAClC,6DAA2C;AAC3C,8DAA4C;AAC5C,8DAA4C;AAC5C,uDAAqC;AACrC,iDAA+B;AAE/B,gEAA8C;AAC9C,qEAAmD;AACnD,6DAA2C;AAC3C,gEAA8C;AAE9C,uEAAqD;AACrD,iEAA+C;AAE/C,2CAAyB;AAEzB,0EAAwD;AACxD,8EAA4D;AAC5D,gEAA8C;AAE9C,uEAAqD"}

package/dist/interceptor/transactional.interceptor.d.ts

@@ -0,0 +1,28 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { type Observable } from 'rxjs';
+import { TransactionManager } from '../manager/transaction.manager';
+/**
+ * NestJS interceptor that wraps a request-boundary handler in a transaction
+ * when the handler (or its controller class) carries `@Transactional()`
+ * metadata.
+ *
+ * Registered at the request boundary via `APP_INTERCEPTOR`. It is one of
+ * the three coordinated wrapping mechanisms described in ADR-005 — the
+ * other two are `TransactionalMethodsBootstrap` (for plain `@Injectable`
+ * services) and `CqrsHandlerWrapper` (for CQRS handlers).
+ *
+ * Metadata lookup: method-level `@Transactional` overrides class-level.
+ * If neither is present the handler is passed through without any
+ * transactional wrapping.
+ *
+ * Not exported from the package's public API — consumers enable it via
+ * `TransactionalModule.forRoot`.
+ */
+export declare class TransactionalInterceptor implements NestInterceptor {
+    private readonly manager;
+    private readonly reflector;
+    constructor(manager: TransactionManager, reflector: Reflector);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//# sourceMappingURL=transactional.interceptor.d.ts.map

package/dist/interceptor/transactional.interceptor.js

@@ -0,0 +1,56 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const rxjs_1 = require("rxjs");
+const transactional_decorator_1 = require("../decorators/transactional.decorator");
+const transaction_manager_1 = require("../manager/transaction.manager");
+/**
+ * NestJS interceptor that wraps a request-boundary handler in a transaction
+ * when the handler (or its controller class) carries `@Transactional()`
+ * metadata.
+ *
+ * Registered at the request boundary via `APP_INTERCEPTOR`. It is one of
+ * the three coordinated wrapping mechanisms described in ADR-005 — the
+ * other two are `TransactionalMethodsBootstrap` (for plain `@Injectable`
+ * services) and `CqrsHandlerWrapper` (for CQRS handlers).
+ *
+ * Metadata lookup: method-level `@Transactional` overrides class-level.
+ * If neither is present the handler is passed through without any
+ * transactional wrapping.
+ *
+ * Not exported from the package's public API — consumers enable it via
+ * `TransactionalModule.forRoot`.
+ */
+let TransactionalInterceptor = class TransactionalInterceptor {
+    manager;
+    reflector;
+    constructor(manager, reflector) {
+        this.manager = manager;
+        this.reflector = reflector;
+    }
+    intercept(context, next) {
+        const metadata = this.reflector.getAllAndOverride(transactional_decorator_1.TRANSACTIONAL_METADATA, [context.getHandler(), context.getClass()]);
+        if (metadata === undefined) {
+            return next.handle();
+        }
+        return (0, rxjs_1.defer)(() => this.manager.run(metadata, () => (0, rxjs_1.firstValueFrom)(next.handle())));
+    }
+};
+exports.TransactionalInterceptor = TransactionalInterceptor;
+exports.TransactionalInterceptor = TransactionalInterceptor = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [transaction_manager_1.TransactionManager,
+        core_1.Reflector])
+], TransactionalInterceptor);
+//# sourceMappingURL=transactional.interceptor.js.map

package/dist/interceptor/transactional.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional.interceptor.js","sourceRoot":"","sources":["../../src/interceptor/transactional.interceptor.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAKwB;AACxB,uCAAyC;AACzC,+BAA8D;AAE9D,mFAG+C;AAC/C,wEAAoE;AAEpE;;;;;;;;;;;;;;;;GAgBG;AAEI,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;IAEhB;IACA;IAFnB,YACmB,OAA2B,EAC3B,SAAoB;QADpB,YAAO,GAAP,OAAO,CAAoB;QAC3B,cAAS,GAAT,SAAS,CAAW;IACpC,CAAC;IAEJ,SAAS,CAAC,OAAyB,EAAE,IAAiB;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAC/C,gDAAsB,EACtB,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAC3C,CAAC;QAEF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,CAAC;QAED,OAAO,IAAA,YAAK,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAA,qBAAc,EAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACtF,CAAC;CACF,CAAA;AAlBY,4DAAwB;mCAAxB,wBAAwB;IADpC,IAAA,mBAAU,GAAE;qCAGiB,wCAAkB;QAChB,gBAAS;GAH5B,wBAAwB,CAkBpC"}

package/dist/internal/markers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Identity marker placed via `Reflect.defineMetadata` on methods that have
+ * been wrapped by one of the coordinated wrapping mechanisms described in
+ * ADR-005 (`TransactionalInterceptor`, `TransactionalMethodsBootstrap`,
+ * and `CqrsHandlerWrapper`). Each mechanism checks this marker before
+ * wrapping so a method is never wrapped twice.
+ *
+ * `Symbol.for` gives a process-global symbol, so multiple copies of this
+ * package in the same dependency tree still resolve to the same identity.
+ *
+ * Internal: not re-exported from the public API. The three wrapping
+ * mechanisms are the only legitimate users.
+ */
+export declare const WRAPPED_MARKER: unique symbol;
+//# sourceMappingURL=markers.d.ts.map

package/dist/internal/markers.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WRAPPED_MARKER = void 0;
+/**
+ * Identity marker placed via `Reflect.defineMetadata` on methods that have
+ * been wrapped by one of the coordinated wrapping mechanisms described in
+ * ADR-005 (`TransactionalInterceptor`, `TransactionalMethodsBootstrap`,
+ * and `CqrsHandlerWrapper`). Each mechanism checks this marker before
+ * wrapping so a method is never wrapped twice.
+ *
+ * `Symbol.for` gives a process-global symbol, so multiple copies of this
+ * package in the same dependency tree still resolve to the same identity.
+ *
+ * Internal: not re-exported from the public API. The three wrapping
+ * mechanisms are the only legitimate users.
+ */
+exports.WRAPPED_MARKER = Symbol.for('@nestjs-transactional/wrapped');
+//# sourceMappingURL=markers.js.map

package/dist/internal/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../src/internal/markers.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC"}

package/dist/manager/adapter.registry.d.ts

@@ -0,0 +1,103 @@
+import type { TransactionAdapter } from '../types/transaction-adapter';
+/**
+ * A single entry in the {@link AdapterRegistry}: an adapter instance bound to
+ * its type name and instance name. Used as both the input shape of
+ * {@link AdapterRegistry.register} and the element shape returned by
+ * {@link AdapterRegistry.getAll}.
+ */
+export interface AdapterRegistration {
+    /** Adapter type name, e.g. `'typeorm'`, `'prisma'`. */
+    readonly adapterName: string;
+    /** Instance name within the adapter type, e.g. `'primary'`, `'billing'`. */
+    readonly instanceName: string;
+    /** The adapter implementation registered under this (adapterName, instanceName) pair. */
+    readonly adapter: TransactionAdapter;
+}
+/**
+ * DI token for the {@link AdapterRegistry}. Consumers who need to register
+ * adapters manually (for example, integration tests or custom modules)
+ * can inject this token and call {@link AdapterRegistry.register}.
+ */
+export declare const ADAPTER_REGISTRY: unique symbol;
+/**
+ * In-memory registry of {@link TransactionAdapter} instances, keyed by
+ * `(adapterName, instanceName)`. Each adapter type (e.g. `'typeorm'`) may
+ * have multiple instances (e.g. `'primary'`, `'billing'`) — the registry
+ * keeps them separate so that `@Transactional({ adapterInstance: 'billing' })`
+ * can target a specific one.
+ *
+ * The first adapter registered becomes the default; any later registration
+ * can override the default by passing `isDefault = true`.
+ *
+ * Implementation note: the internal key format is `${adapterName}:${instanceName}`.
+ * Neither `adapterName` nor `instanceName` may contain `:` — enforced by
+ * convention, not at runtime.
+ */
+export declare class AdapterRegistry {
+    private readonly adapters;
+    private defaultAdapterName;
+    private defaultInstanceName;
+    /**
+     * Register an adapter under `(registration.adapterName, registration.instanceName)`.
+     *
+     * The first registration always becomes the default. Passing
+     * `isDefault = true` on any later registration switches the default to it.
+     *
+     * Re-registering the same pair overwrites the previously stored adapter;
+     * the default pointer is left unchanged unless `isDefault = true` is set.
+     */
+    register(registration: AdapterRegistration, isDefault?: boolean): void;
+    /**
+     * Look up an adapter by `(adapterName, instanceName)`.
+     *
+     * @throws {TransactionAdapterNotFoundError} If no adapter is registered
+     *   under that pair.
+     */
+    get(adapterName: string, instanceName: string): TransactionAdapter;
+    /**
+     * Look up an adapter by its public dataSource name (DD-020). Iterates
+     * the registered entries and returns the one whose `instanceName`
+     * matches `dataSource` — there is exactly one per dataSource by
+     * convention.
+     *
+     * If multiple registrations share the same `instanceName` across
+     * different adapter types (e.g. `typeorm:billing` AND
+     * `prisma:billing`), throws — that configuration is ambiguous and
+     * the user must disambiguate via the `adapter` + `adapterInstance`
+     * options instead.
+     *
+     * @throws {IllegalTransactionStateError} If two or more adapters share
+     *   the same dataSource name.
+     * @throws {TransactionAdapterNotFoundError} If no adapter is registered
+     *   under this dataSource.
+     */
+    getByDataSource(dataSource: string): TransactionAdapter;
+    /**
+     * Find the adapter type name (`'typeorm'`, `'prisma'`, ...) registered
+     * under the given dataSource. Used by the manager to compose the
+     * composite Map key when only the dataSource name is known.
+     *
+     * Same disambiguation rules as {@link getByDataSource}.
+     */
+    getAdapterNameByDataSource(dataSource: string): string;
+    /**
+     * Return the name of the adapter type currently marked default.
+     *
+     * @throws {IllegalTransactionStateError} If no adapter has been registered
+     *   yet — there is no default to choose.
+     */
+    getDefaultAdapterName(): string;
+    /**
+     * Return the name of the default adapter instance. Defaults to `'default'`
+     * before any adapter is registered — matches the common convention in
+     * per-ORM `forFeature({ instanceName: 'default' })` helpers.
+     */
+    getDefaultInstanceName(): string;
+    /**
+     * Return every registration as a new array. Used by bootstrap and
+     * observability code to enumerate configured adapters at runtime.
+     */
+    getAll(): AdapterRegistration[];
+    private static keyFor;
+}
+//# sourceMappingURL=adapter.registry.d.ts.map