@nestjs-transactional/core 1.0.0-alpha.0

package/dist/module/transactional.module.js

@@ -0,0 +1,374 @@
+"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 TransactionalModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const transactional_methods_bootstrap_1 = require("../bootstrap/transactional-methods.bootstrap");
+const transaction_context_view_1 = require("../context/transaction-context-view");
+const transactional_interceptor_1 = require("../interceptor/transactional.interceptor");
+const adapter_registry_1 = require("../manager/adapter.registry");
+const transaction_manager_1 = require("../manager/transaction.manager");
+const transaction_observer_1 = require("../observability/transaction-observer");
+const token_utils_1 = require("../tokens/token-utils");
+const ASYNC_OPTIONS_TOKEN = (id) => Symbol(`TRANSACTIONAL_ASYNC_OPTIONS[${id}]`);
+const ASYNC_REGISTRATION_TOKEN = (id) => Symbol(`TRANSACTIONAL_ASYNC_REGISTRATION[${id}]`);
+/**
+ * NestJS module that wires the core transactional runtime:
+ * {@link AdapterRegistry}, {@link TransactionManager}, and (by
+ * default) the global {@link TransactionalInterceptor}. ADR-018
+ * shape — multi-dataSource deployments call {@link forRoot} once per
+ * dataSource. Static class storage coordinates singletons across
+ * calls (mirrors Phase 14.3.2 `OutboxModule` per ADR-019).
+ *
+ * The first call registers the process-wide infrastructure; subsequent
+ * calls only contribute per-dataSource providers. Adapter-specific
+ * registration (TypeORM, Prisma, ...) is handled by the integration
+ * package's `forFeature` helper — this module only provides the
+ * adapter-agnostic infrastructure.
+ */
+let TransactionalModule = class TransactionalModule {
+    static { TransactionalModule_1 = this; }
+    /**
+     * @internal
+     * Process-wide map of adapter-bearing `forRoot` calls, keyed by
+     * `adapter.dataSourceName`. Used for dedup of duplicate dataSource
+     * registrations at module-definition time. The {@link AdapterRegistry}
+     * itself is populated imperatively by per-DS adapter providers
+     * (factory side effect) — this Map exists for `forRoot`-call-time
+     * coordination only.
+     *
+     * Tests that build multiple modules sequentially MUST call
+     * {@link resetForTesting} between cases.
+     */
+    static registrations = new Map();
+    /**
+     * @internal
+     * `true` once any `forRoot` (or `forRootAsync`) call has run.
+     * First-call-special providers (singletons, interceptor, methods
+     * bootstrap, observers) are only registered when this is `false` at
+     * the start of a call.
+     *
+     * Tracked separately from {@link registrations} because the
+     * shorthand `forRoot({})` (no adapter) still registers
+     * infrastructure but contributes nothing to the Map. Q5 invariant:
+     * a second `forRoot({})` after infrastructure is already registered
+     * throws — the first call already wired everything; the second has
+     * nothing to add.
+     */
+    static infrastructureRegistered = false;
+    /**
+     * @internal
+     * Counter for `forRootAsync`-only token uniqueness. Not strictly
+     * needed for `Symbol()` (each call returns a unique symbol
+     * regardless of description), but keeping a numeric id makes
+     * provider names deterministic in error messages.
+     */
+    static asyncCounter = 0;
+    /**
+     * Test-only — drop every registration so a subsequent `forRoot`
+     * starts from a clean slate. Mirrors the pattern used with
+     * `OutboxModule.resetForTesting` and `EntitiesMetadataStorage` in
+     * `@nestjs/typeorm` test suites.
+     *
+     * Production code should never call this. Calling at runtime after
+     * the module has been initialised does NOT clear the provider tree
+     * NestJS already built — it only affects subsequent `forRoot` calls.
+     *
+     * @internal
+     */
+    static resetForTesting() {
+        this.registrations.clear();
+        this.infrastructureRegistered = false;
+        this.asyncCounter = 0;
+    }
+    /**
+     * Synchronous registration. Each call registers one dataSource's
+     * adapter (or, with `adapter` omitted, only the process-wide
+     * infrastructure for an integration package's `forFeature` to write
+     * into).
+     *
+     * @example Single-adapter
+     * ```ts
+     * TransactionalModule.forRoot({ isGlobal: true, adapter })
+     * ```
+     *
+     * @example Multi-adapter (multiple calls)
+     * ```ts
+     * TransactionalModule.forRoot({ isGlobal: true, adapter: defaultAdapter }),
+     * TransactionalModule.forRoot({ adapter: billingAdapter }),
+     * TransactionalModule.forRoot({ adapter: inventoryAdapter }),
+     * ```
+     *
+     * @example Infrastructure-only (TypeORM forFeature handles adapters)
+     * ```ts
+     * TransactionalModule.forRoot({ isGlobal: true }),
+     * TypeOrmTransactionalModule.forFeature({ dataSource }),
+     * ```
+     */
+    static forRoot(options = {}) {
+        const isFirst = !this.infrastructureRegistered;
+        const adapter = options.adapter;
+        if (adapter !== undefined) {
+            const ds = adapter.dataSourceName;
+            if (this.registrations.has(ds)) {
+                throw new Error(`TransactionalModule.forRoot — dataSource '${ds}' already registered. ` +
+                    `dataSource names must be unique across forRoot calls. ` +
+                    `If this is a test, call TransactionalModule.resetForTesting() between cases.`);
+            }
+            this.registrations.set(ds, {
+                adapterName: adapter.name,
+                instanceName: ds,
+                adapter,
+            });
+        }
+        else if (!isFirst) {
+            throw new Error(`TransactionalModule.forRoot({}) called without adapter, but infrastructure ` +
+                `has already been registered by an earlier forRoot call. Pass an adapter to ` +
+                `register an additional dataSource, or omit this call entirely. ` +
+                `If this is a test, call TransactionalModule.resetForTesting() between cases.`);
+        }
+        if (!isFirst && options.observers !== undefined) {
+            throw new Error(`TransactionalModule.forRoot({ observers }) — observers can only be passed in ` +
+                `the first forRoot call. Subsequent calls must omit the observers field.`);
+        }
+        const providers = [];
+        const exportTokens = [];
+        if (adapter !== undefined) {
+            providers.push(...buildPerDataSourceProviders(adapter));
+            exportTokens.push(...buildPerDataSourceExports(adapter.dataSourceName));
+        }
+        if (isFirst) {
+            this.infrastructureRegistered = true;
+            // ADAPTER_REGISTRY factory closes over the static `registrations`
+            // Map. By the time NestJS resolves this factory, every synchronous
+            // `forRoot` body has run and the Map is fully populated. Pattern
+            // mirrors Phase 14.3.2 `OutboxModule` per ADR-019.
+            providers.push({
+                provide: adapter_registry_1.ADAPTER_REGISTRY,
+                useFactory: () => buildRegistryFromStaticStorage(TransactionalModule_1),
+            });
+            providers.push({
+                provide: adapter_registry_1.AdapterRegistry,
+                useExisting: adapter_registry_1.ADAPTER_REGISTRY,
+            });
+            providers.push(transaction_manager_1.TransactionManager);
+            if (options.observers !== undefined) {
+                providers.push({
+                    provide: transaction_observer_1.TRANSACTION_OBSERVERS,
+                    useValue: [...options.observers],
+                });
+            }
+            if (options.registerInterceptor !== false) {
+                providers.push({
+                    provide: core_1.APP_INTERCEPTOR,
+                    useClass: transactional_interceptor_1.TransactionalInterceptor,
+                });
+            }
+            if (options.registerMethodsBootstrap !== false) {
+                providers.push(transactional_methods_bootstrap_1.TransactionalMethodsBootstrap);
+            }
+            exportTokens.push(transaction_manager_1.TransactionManager, adapter_registry_1.ADAPTER_REGISTRY, adapter_registry_1.AdapterRegistry);
+        }
+        return {
+            module: TransactionalModule_1,
+            global: options.isGlobal ?? true,
+            imports: [core_1.DiscoveryModule],
+            providers,
+            exports: exportTokens,
+        };
+    }
+    /**
+     * Asynchronous registration. Each call registers one dataSource's
+     * adapter (resolved asynchronously via `useFactory`). Multi-DS
+     * deployments call `forRootAsync` once per dataSource.
+     *
+     * **Per-DS DI token limitation**: per-DS tokens
+     * (`getTransactionalAdapterToken(ds)`, etc.) are NOT registered
+     * for `forRootAsync` calls because the dataSource identifier is
+     * only known after the async factory runs, while NestJS provider
+     * tokens must be declared statically. If per-DS injection matters,
+     * use sync `forRoot({ adapter })` instead — build the adapter
+     * configuration through your own async logic before reaching the
+     * module imports.
+     *
+     * `forRootAsync` still works for `AdapterRegistry`-based access
+     * (`@Transactional({ dataSource })`,
+     * `getCurrentEntityManager(dataSource)`,
+     * `manager.run({ dataSource })`) — those route through the registry,
+     * which is populated by the async factory's side effect via
+     * `AdapterRegistry.register(...)`.
+     *
+     * @example
+     * ```ts
+     * TransactionalModule.forRootAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config: ConfigService) => ({
+     *     adapter: buildAdapterFromConfig(config),
+     *   }),
+     * });
+     * ```
+     */
+    static forRootAsync(options) {
+        const isFirst = !this.infrastructureRegistered;
+        const id = this.asyncCounter++;
+        const asyncToken = ASYNC_OPTIONS_TOKEN(id);
+        const registrationToken = ASYNC_REGISTRATION_TOKEN(id);
+        // forRootAsync cannot dedup at call time (dataSource name unknown
+        // until factory runs). The eager-registration factory below calls
+        // AdapterRegistry.register at provider-resolution time; duplicate
+        // dataSources propagate as registry-level overwrites at runtime
+        // rather than module-build-time errors. This is the documented
+        // limitation that pushes per-DS-injection-needs to sync forRoot.
+        const asyncOptionsProvider = {
+            provide: asyncToken,
+            useFactory: options.useFactory,
+            inject: options.inject ? [...options.inject] : undefined,
+        };
+        const adapterEagerRegistrationProvider = {
+            provide: registrationToken,
+            useFactory: (opts, registry) => {
+                if (opts.adapter !== undefined) {
+                    registry.register({
+                        adapterName: opts.adapter.name,
+                        instanceName: opts.adapter.dataSourceName,
+                        adapter: opts.adapter,
+                    });
+                }
+                return true;
+            },
+            inject: [asyncToken, adapter_registry_1.ADAPTER_REGISTRY],
+        };
+        const providers = [
+            asyncOptionsProvider,
+            adapterEagerRegistrationProvider,
+        ];
+        const exportTokens = [];
+        if (isFirst) {
+            this.infrastructureRegistered = true;
+            // forRootAsync's `AdapterRegistry` is built fresh and the
+            // eager-registration factory below mutates it via
+            // `register(...)`. Ordering: NestJS resolves the registry
+            // factory, then the eager-registration factory whose `inject`
+            // depends on it — so by the time consumers read the registry,
+            // every adapter has been registered.
+            providers.push({
+                provide: adapter_registry_1.ADAPTER_REGISTRY,
+                useFactory: () => new adapter_registry_1.AdapterRegistry(),
+            });
+            providers.push({
+                provide: adapter_registry_1.AdapterRegistry,
+                useExisting: adapter_registry_1.ADAPTER_REGISTRY,
+            });
+            providers.push(transaction_manager_1.TransactionManager);
+            // First-call-only observers honoring (Q2 invariant). The async
+            // factory may return `observers` — only the first forRootAsync's
+            // observers are wired; subsequent calls' observers are ignored
+            // (we cannot throw at call time because the value is only known
+            // after the factory runs).
+            providers.push({
+                provide: transaction_observer_1.TRANSACTION_OBSERVERS,
+                useFactory: (opts) => opts.observers ? [...opts.observers] : [],
+                inject: [asyncToken],
+            });
+            if (options.registerInterceptor !== false) {
+                providers.push({
+                    provide: core_1.APP_INTERCEPTOR,
+                    useClass: transactional_interceptor_1.TransactionalInterceptor,
+                });
+            }
+            if (options.registerMethodsBootstrap !== false) {
+                providers.push(transactional_methods_bootstrap_1.TransactionalMethodsBootstrap);
+            }
+            exportTokens.push(transaction_manager_1.TransactionManager, adapter_registry_1.ADAPTER_REGISTRY, adapter_registry_1.AdapterRegistry);
+        }
+        return {
+            module: TransactionalModule_1,
+            global: options.isGlobal ?? true,
+            imports: [core_1.DiscoveryModule, ...(options.imports ?? [])],
+            providers,
+            exports: exportTokens,
+        };
+    }
+};
+exports.TransactionalModule = TransactionalModule;
+exports.TransactionalModule = TransactionalModule = TransactionalModule_1 = __decorate([
+    (0, common_1.Module)({})
+], TransactionalModule);
+/**
+ * Per-dataSource DI providers for ADR-018's token-based access pattern.
+ * Each adapter-bearing `forRoot` call registers, for the supplied
+ * adapter:
+ *
+ * - `getTransactionalAdapterToken(ds)` — `useValue` the adapter
+ *   directly. The {@link AdapterRegistry}'s population is handled by
+ *   the first-call factory (which closes over the static
+ *   `registrations` Map and walks every entry at resolution time);
+ *   per-DS adapter providers therefore do NOT need to inject the
+ *   registry — they would not see it across multi-call DI scopes
+ *   without `isGlobal: true`.
+ * - `getTransactionContextToken(ds)` — a {@link TransactionContextView}
+ *   pre-bound to the dataSource. Sync — the dataSource name is known
+ *   at call time.
+ * - `getTransactionManagerToken(ds)` — `useExisting` alias to the
+ *   class-token {@link TransactionManager}. Per-call dataSource
+ *   selection still goes through `manager.run({ dataSource })`; this
+ *   token exists for symmetry with `@nestjs/typeorm`'s per-dataSource
+ *   injection pattern (DD-022).
+ *
+ * `useExisting: TransactionManager` here works without cross-module
+ * import because each DynamicModule with `module: TransactionalModule`
+ * shares a class-token resolution within the parent module's DI tree
+ * once at least one of them registers the class. For consumer modules
+ * to reach `TransactionManager` and `AdapterRegistry`, set
+ * `isGlobal: true` on the first `forRoot` call (the typical pattern).
+ */
+function buildPerDataSourceProviders(adapter) {
+    const ds = adapter.dataSourceName;
+    return [
+        {
+            provide: (0, token_utils_1.getTransactionalAdapterToken)(ds),
+            useValue: adapter,
+        },
+        {
+            provide: (0, token_utils_1.getTransactionContextToken)(ds),
+            useValue: new transaction_context_view_1.TransactionContextView(ds),
+        },
+        {
+            provide: (0, token_utils_1.getTransactionManagerToken)(ds),
+            useExisting: transaction_manager_1.TransactionManager,
+        },
+    ];
+}
+/**
+ * Build a fresh {@link AdapterRegistry} populated from the static
+ * `registrations` Map on {@link TransactionalModule}. Called by the
+ * first-`forRoot`'s `ADAPTER_REGISTRY` factory at provider-resolution
+ * time — by then every synchronous `forRoot` body has populated the
+ * Map. Pattern mirrors Phase 14.3.2 `OutboxModule` per ADR-019.
+ *
+ * @internal
+ */
+function buildRegistryFromStaticStorage(moduleClass) {
+    const registry = new adapter_registry_1.AdapterRegistry();
+    // The Map is `private static` — read it through a structural cast.
+    const registrations = moduleClass.registrations;
+    for (const reg of registrations.values()) {
+        registry.register(reg);
+    }
+    return registry;
+}
+function buildPerDataSourceExports(ds) {
+    return [
+        (0, token_utils_1.getTransactionalAdapterToken)(ds),
+        (0, token_utils_1.getTransactionContextToken)(ds),
+        (0, token_utils_1.getTransactionManagerToken)(ds),
+    ];
+}
+//# sourceMappingURL=transactional.module.js.map

package/dist/module/transactional.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional.module.js","sourceRoot":"","sources":["../../src/module/transactional.module.ts"],"names":[],"mappings":"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"}

package/dist/observability/transaction-observer.d.ts

@@ -0,0 +1,78 @@
+import type { ExtendedTransactionOptions } from '../types/transaction-options';
+/**
+ * Context passed to {@link TransactionObserver.onTransactionStart}. Built
+ * once by {@link TransactionManager} when a new transaction begins —
+ * i.e. the adapter has produced a {@link TransactionHandle} and the entry
+ * has been registered on the active {@link TransactionContextStore}.
+ */
+export interface TransactionStartContext {
+    /** Unique identifier of the transaction (from the adapter's handle). */
+    readonly transactionId: string;
+    /** Adapter type name, e.g. `'typeorm'`. */
+    readonly adapterName: string;
+    /** Adapter instance name, e.g. `'primary'`, `'billing'`. */
+    readonly adapterInstanceName: string;
+    /** Correlation id of the surrounding {@link TransactionContextStore}. */
+    readonly correlationId: string;
+    /** Options as passed to `TransactionManager.run`. */
+    readonly options: ExtendedTransactionOptions;
+}
+/**
+ * Context passed to {@link TransactionObserver.onTransactionCommit}.
+ * Emitted after the adapter has committed; immediately before the
+ * `afterCommitHooks` run.
+ */
+export interface TransactionCommitContext extends TransactionStartContext {
+    /** Elapsed wall-clock time between transaction start and commit, in ms. */
+    readonly durationMs: number;
+    /** Number of `afterCommit` hooks registered on this transaction. */
+    readonly commitCount: number;
+}
+/**
+ * Context passed to {@link TransactionObserver.onTransactionRollback}.
+ * Emitted after the adapter has rolled back; immediately before the
+ * `afterRollbackHooks` run.
+ */
+export interface TransactionRollbackContext extends TransactionStartContext {
+    /** Elapsed wall-clock time between transaction start and rollback, in ms. */
+    readonly durationMs: number;
+    /** The error that caused the rollback — propagated to the caller afterwards. */
+    readonly error: unknown;
+    /** Number of `afterRollback` hooks registered on this transaction. */
+    readonly rollbackCount: number;
+}
+/**
+ * Observer interface for monitoring transaction lifecycle. All methods are
+ * optional so an observer can subscribe only to the events it cares about
+ * (e.g. a metrics exporter typically wires only `onTransactionCommit` /
+ * `onTransactionRollback`).
+ *
+ * Observer implementations **must not** depend on any side effect of the
+ * transactional database state, and **must not** throw to influence the
+ * outcome — {@link TransactionManager} catches observer errors and logs
+ * them via its NestJS Logger, continuing with the remaining observers.
+ * This is a monitoring hook, not a control-flow hook — use the
+ * `registerAfterCommit` / `registerAfterRollback` APIs on the manager if
+ * you need to react to the transaction outcome within the same unit of
+ * work.
+ */
+export interface TransactionObserver {
+    onTransactionStart?(ctx: TransactionStartContext): void;
+    onTransactionCommit?(ctx: TransactionCommitContext): void;
+    onTransactionRollback?(ctx: TransactionRollbackContext): void;
+}
+/**
+ * DI token under which {@link TransactionObserver} instances are
+ * registered. Wired automatically by
+ * `TransactionalModule.forRoot({ observers })`; can also be provided by
+ * user code for DI-resolved observers:
+ *
+ * ```ts
+ * providers: [
+ *   MetricsObserver,
+ *   { provide: TRANSACTION_OBSERVERS, useFactory: (m) => [m], inject: [MetricsObserver] },
+ * ]
+ * ```
+ */
+export declare const TRANSACTION_OBSERVERS: unique symbol;
+//# sourceMappingURL=transaction-observer.d.ts.map

package/dist/observability/transaction-observer.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRANSACTION_OBSERVERS = void 0;
+/**
+ * DI token under which {@link TransactionObserver} instances are
+ * registered. Wired automatically by
+ * `TransactionalModule.forRoot({ observers })`; can also be provided by
+ * user code for DI-resolved observers:
+ *
+ * ```ts
+ * providers: [
+ *   MetricsObserver,
+ *   { provide: TRANSACTION_OBSERVERS, useFactory: (m) => [m], inject: [MetricsObserver] },
+ * ]
+ * ```
+ */
+exports.TRANSACTION_OBSERVERS = Symbol('TRANSACTION_OBSERVERS');
+//# sourceMappingURL=transaction-observer.js.map

package/dist/observability/transaction-observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-observer.js","sourceRoot":"","sources":["../../src/observability/transaction-observer.ts"],"names":[],"mappings":";;;AA2EA;;;;;;;;;;;;GAYG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC"}

package/dist/testing/in-memory.adapter.d.ts

@@ -0,0 +1,66 @@
+import type { TransactionAdapter } from '../types/transaction-adapter';
+import type { TransactionHandle } from '../types/transaction-handle';
+import type { TransactionOptions } from '../types/transaction-options';
+/**
+ * Handle emitted by {@link InMemoryTransactionAdapter}. Extends
+ * {@link TransactionHandle} with a mutable `operations` array that tests
+ * can push into to simulate a unit of work and later assert on what the
+ * adapter recorded.
+ */
+export interface InMemoryTransactionHandle extends TransactionHandle {
+    /** Mutable scratch space for callers to record simulated operations. */
+    readonly operations: unknown[];
+}
+/** A committed transaction record captured by {@link InMemoryTransactionAdapter}. */
+export interface InMemoryCommittedTransaction {
+    readonly id: string;
+    readonly operations: unknown[];
+    readonly options: TransactionOptions;
+}
+/** A rolled-back transaction record captured by {@link InMemoryTransactionAdapter}. */
+export interface InMemoryRolledBackTransaction extends InMemoryCommittedTransaction {
+    readonly error: unknown;
+}
+/** A savepoint lifecycle record captured by {@link InMemoryTransactionAdapter}. */
+export interface InMemorySavepointRecord {
+    readonly parentId: string;
+    readonly savepointId: string;
+}
+/** A rolled-back savepoint record: {@link InMemorySavepointRecord} plus the error. */
+export interface InMemoryRolledBackSavepointRecord extends InMemorySavepointRecord {
+    readonly error: unknown;
+}
+/**
+ * Adapter implementation intended for unit tests. Keeps the whole transaction
+ * lifecycle in memory and exposes observation arrays (committed, rolled back,
+ * savepoints created/released/rolled back) for assertions.
+ *
+ * Not suitable for production use — issues no real SQL, does no real
+ * persistence, and offers no isolation guarantees. Test-only.
+ *
+ * Exported through `@nestjs-transactional/core/testing`, never through the
+ * main entry point.
+ */
+export declare class InMemoryTransactionAdapter implements TransactionAdapter<InMemoryTransactionHandle> {
+    readonly name = "in-memory";
+    /**
+     * dataSource name this adapter is bound to (DD-021). Defaults to
+     * `'default'`; override via the constructor to register multiple
+     * in-memory adapters under distinct dataSource names in tests.
+     */
+    readonly dataSourceName: string;
+    constructor(dataSourceName?: string);
+    committedTransactions: InMemoryCommittedTransaction[];
+    rolledBackTransactions: InMemoryRolledBackTransaction[];
+    savepointsCreated: InMemorySavepointRecord[];
+    savepointsReleased: InMemorySavepointRecord[];
+    savepointsRolledBack: InMemoryRolledBackSavepointRecord[];
+    runInTransaction<T>(options: TransactionOptions, fn: (handle: InMemoryTransactionHandle) => Promise<T>): Promise<T>;
+    runInSavepoint<T>(parent: InMemoryTransactionHandle, fn: (handle: InMemoryTransactionHandle) => Promise<T>): Promise<T>;
+    /**
+     * Clear all observation arrays. Call between tests to avoid cross-test
+     * leakage when reusing a single adapter instance.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=in-memory.adapter.d.ts.map

package/dist/testing/in-memory.adapter.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryTransactionAdapter = void 0;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Adapter implementation intended for unit tests. Keeps the whole transaction
+ * lifecycle in memory and exposes observation arrays (committed, rolled back,
+ * savepoints created/released/rolled back) for assertions.
+ *
+ * Not suitable for production use — issues no real SQL, does no real
+ * persistence, and offers no isolation guarantees. Test-only.
+ *
+ * Exported through `@nestjs-transactional/core/testing`, never through the
+ * main entry point.
+ */
+class InMemoryTransactionAdapter {
+    name = 'in-memory';
+    /**
+     * dataSource name this adapter is bound to (DD-021). Defaults to
+     * `'default'`; override via the constructor to register multiple
+     * in-memory adapters under distinct dataSource names in tests.
+     */
+    dataSourceName;
+    constructor(dataSourceName = 'default') {
+        this.dataSourceName = dataSourceName;
+    }
+    committedTransactions = [];
+    rolledBackTransactions = [];
+    savepointsCreated = [];
+    savepointsReleased = [];
+    savepointsRolledBack = [];
+    async runInTransaction(options, fn) {
+        const handle = {
+            id: (0, node_crypto_1.randomUUID)(),
+            adapterName: this.name,
+            operations: [],
+        };
+        try {
+            const result = await fn(handle);
+            this.committedTransactions.push({
+                id: handle.id,
+                operations: handle.operations,
+                options,
+            });
+            return result;
+        }
+        catch (error) {
+            this.rolledBackTransactions.push({
+                id: handle.id,
+                operations: handle.operations,
+                options,
+                error,
+            });
+            throw error;
+        }
+    }
+    async runInSavepoint(parent, fn) {
+        const savepointId = (0, node_crypto_1.randomUUID)();
+        this.savepointsCreated.push({ parentId: parent.id, savepointId });
+        try {
+            const result = await fn(parent);
+            this.savepointsReleased.push({ parentId: parent.id, savepointId });
+            return result;
+        }
+        catch (error) {
+            this.savepointsRolledBack.push({ parentId: parent.id, savepointId, error });
+            throw error;
+        }
+    }
+    /**
+     * Clear all observation arrays. Call between tests to avoid cross-test
+     * leakage when reusing a single adapter instance.
+     */
+    reset() {
+        this.committedTransactions = [];
+        this.rolledBackTransactions = [];
+        this.savepointsCreated = [];
+        this.savepointsReleased = [];
+        this.savepointsRolledBack = [];
+    }
+}
+exports.InMemoryTransactionAdapter = InMemoryTransactionAdapter;
+//# sourceMappingURL=in-memory.adapter.js.map

package/dist/testing/in-memory.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.adapter.js","sourceRoot":"","sources":["../../src/testing/in-memory.adapter.ts"],"names":[],"mappings":";;;AAAA,6CAAyC;AAwCzC;;;;;;;;;;GAUG;AACH,MAAa,0BAA0B;IAC5B,IAAI,GAAG,WAAW,CAAC;IAE5B;;;;OAIG;IACM,cAAc,CAAS;IAEhC,YAAY,cAAc,GAAG,SAAS;QACpC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED,qBAAqB,GAAmC,EAAE,CAAC;IAC3D,sBAAsB,GAAoC,EAAE,CAAC;IAC7D,iBAAiB,GAA8B,EAAE,CAAC;IAClD,kBAAkB,GAA8B,EAAE,CAAC;IACnD,oBAAoB,GAAwC,EAAE,CAAC;IAE/D,KAAK,CAAC,gBAAgB,CACpB,OAA2B,EAC3B,EAAqD;QAErD,MAAM,MAAM,GAA8B;YACxC,EAAE,EAAE,IAAA,wBAAU,GAAE;YAChB,WAAW,EAAE,IAAI,CAAC,IAAI;YACtB,UAAU,EAAE,EAAE;SACf,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC;gBAC9B,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,OAAO;aACR,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC;gBAC/B,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,OAAO;gBACP,KAAK;aACN,CAAC,CAAC;YACH,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,MAAiC,EACjC,EAAqD;QAErD,MAAM,WAAW,GAAG,IAAA,wBAAU,GAAE,CAAC;QACjC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QAElE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YACnE,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5E,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,qBAAqB,GAAG,EAAE,CAAC;QAChC,IAAI,CAAC,sBAAsB,GAAG,EAAE,CAAC;QACjC,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC;QAC5B,IAAI,CAAC,kBAAkB,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,oBAAoB,GAAG,EAAE,CAAC;IACjC,CAAC;CACF;AA7ED,gEA6EC"}

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './in-memory.adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.js

@@ -0,0 +1,18 @@
+"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("./in-memory.adapter"), exports);
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC"}