@nestjs-transactional/core 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Golovanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# @nestjs-transactional/core
+
+[![npm version](https://img.shields.io/npm/v/%40nestjs-transactional%2Fcore/alpha?style=flat-square&label=npm)](https://www.npmjs.com/package/@nestjs-transactional/core)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/igorgolovanov/nestjs-transactional/blob/main/LICENSE)
+
+Core primitives for declarative Spring-style transaction management
+in NestJS.
+
+## Overview
+
+The adapter-agnostic foundation of the `@nestjs-transactional` family:
+
+- `TransactionContext` — `AsyncLocalStorage`-backed carrier that
+  propagates the active transaction across `await` boundaries.
+- `TransactionManager` — runtime with the full Spring propagation
+  semantics (`REQUIRED`, `REQUIRES_NEW`, `NESTED`, `SUPPORTS`,
+  `NOT_SUPPORTED`, `NEVER`, `MANDATORY`) plus `rollbackFor` /
+  `noRollbackFor` rules and before / after commit / rollback hooks.
+- `@Transactional()`, `@ReadOnly()`, `@TransactionalOn(instance)`
+  decorators — metadata-only; runtime wrapping is performed by the
+  three coordinated mechanisms documented in
+  [ADR-005](../../docs/adr/005-method-wrapping-strategy.md).
+- `TransactionalInterceptor` — wires `@Transactional` on controllers,
+  resolvers, gateways, and microservice handlers via `APP_INTERCEPTOR`.
+- `TransactionalModule.forRoot` / `forRootAsync` — module wiring,
+  one call per dataSource (multi-`forRoot` pattern, see
+  [ADR-019](../../docs/adr/019-outbox-multi-forroot-pattern.md)).
+- `TransactionAdapter<THandle>` SPI — the port for ORM-specific
+  adapters.
+- `InMemoryTransactionAdapter` (via the `@nestjs-transactional/core/testing`
+  subpath) — drop-in adapter for unit tests.
+
+This package does not depend on any concrete ORM. Install
+`@nestjs-transactional/typeorm` for TypeORM integration, or implement
+your own adapter against the `TransactionAdapter` interface.
+
+## Installation
+
+```bash
+pnpm add @nestjs-transactional/core reflect-metadata
+```
+
+Load `reflect-metadata` once at the application entry point (same as
+for NestJS itself).
+
+## Quick start
+
+In typical use this package is imported via an integration package
+(like `@nestjs-transactional/typeorm`) which registers the adapter
+into the `AdapterRegistry` automatically. The minimal application
+shape is:
+
+```ts
+import { Module } from '@nestjs/common';
+import { TransactionalModule } from '@nestjs-transactional/core';
+import { TypeOrmTransactionalModule } from '@nestjs-transactional/typeorm';
+// ...your TypeORM config
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({ /* ... */ }),
+
+    // Infrastructure-only forRoot — registers TransactionManager,
+    // AdapterRegistry, and the interceptor. No `adapter` here; the
+    // integration package below registers it.
+    TransactionalModule.forRoot({ isGlobal: true }),
+
+    // Integration package registers `TypeOrmTransactionAdapter`
+    // for the default dataSource.
+    TypeOrmTransactionalModule.forRoot(),
+  ],
+})
+export class AppModule {}
+```
+
+`@Transactional()` on any controller handler, query handler, or
+service method is then wrapped in a transaction automatically:
+
+```ts
+import { Controller, Get, Param } from '@nestjs/common';
+import { Transactional } from '@nestjs-transactional/core';
+
+@Controller('orders')
+export class OrdersController {
+  constructor(private readonly orders: OrdersService) {}
+
+  @Get(':id')
+  @Transactional()
+  async findOne(@Param('id') id: string) {
+    return this.orders.findById(id);
+  }
+}
+```
+
+### Direct adapter registration (custom backends)
+
+When implementing a new `TransactionAdapter` (Prisma, Mongoose, ...),
+pass it to `forRoot` directly:
+
+```ts
+import { TransactionalModule, type TransactionAdapter } from '@nestjs-transactional/core';
+
+const myAdapter: TransactionAdapter = /* ... */;
+
+@Module({
+  imports: [
+    TransactionalModule.forRoot({
+      isGlobal: true,
+      adapter: myAdapter,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+For multi-dataSource setups, call `forRoot` once per dataSource —
+each call registers exactly one adapter under its dataSource name.
+
+## Decorator options
+
+```ts
+import {
+  Transactional,
+  ReadOnly,
+  TransactionalOn,
+  PropagationMode,
+} from '@nestjs-transactional/core';
+
+class ReportsService {
+  // Explicit propagation + isolation.
+  @Transactional({
+    propagation: PropagationMode.REQUIRES_NEW,
+    isolation: 'SERIALIZABLE',
+    timeout: 10_000,
+  })
+  async rebuildReport() { /* ... */ }
+
+  // Shorthand for { readOnly: true }.
+  @ReadOnly()
+  async exportCsv() { /* ... */ }
+
+  // Rollback rules — commit on `ValidationError`, roll back on others.
+  @Transactional({ noRollbackFor: [ValidationError] })
+  async processBatch() { /* ... */ }
+
+  // Target a specific dataSource in multi-DataSource setups.
+  @TransactionalOn('billing')
+  async chargeCard() { /* ... */ }
+}
+```
+
+Propagation semantics:
+
+| Mode | Active outer transaction | No outer transaction |
+| --- | --- | --- |
+| `REQUIRED` (default) | join | start new |
+| `REQUIRES_NEW` | suspend + start new, then resume | start new |
+| `NESTED` | run inside a savepoint | start new |
+| `SUPPORTS` | join | run without transaction |
+| `NOT_SUPPORTED` | suspend + run without transaction, then resume | run without transaction |
+| `NEVER` | throw `IllegalTransactionStateError` | run without transaction |
+| `MANDATORY` | join | throw `IllegalTransactionStateError` |
+
+## Async module configuration
+
+```ts
+import { TransactionalModule } from '@nestjs-transactional/core';
+
+@Module({
+  imports: [
+    TransactionalModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        adapter: buildAdapterFromConfig(config),
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`isGlobal` and `registerInterceptor` remain static top-level flags —
+they must be known at module definition time. The async factory
+returns the per-call configuration (`adapter` and any other
+runtime-resolved options).
+
+## Lifecycle hooks
+
+Register hooks from inside a transactional method — they fire on the
+current transaction:
+
+```ts
+import { TransactionManager } from '@nestjs-transactional/core';
+
+export class OrdersService {
+  constructor(private readonly manager: TransactionManager) {}
+
+  @Transactional()
+  async placeOrder(payload: PlaceOrderDto) {
+    const order = await this.orders.insert(payload);
+
+    this.manager.registerAfterCommit(async () => {
+      // Fires only after the adapter commits. Never on rollback.
+      await this.analytics.trackOrderPlaced(order.id);
+    });
+
+    this.manager.registerAfterRollback(async (error) => {
+      // Receives the error that caused the rollback.
+      await this.metrics.recordFailedOrder(order.id, error);
+    });
+
+    return order;
+  }
+}
+```
+
+Hook errors are caught and logged via NestJS `Logger` — they do not
+affect the transaction outcome or prevent sibling hooks from running.
+
+## Testing
+
+`InMemoryTransactionAdapter` from the `/testing` subpath gives
+adapter-level observability without a real database:
+
+```ts
+import { InMemoryTransactionAdapter } from '@nestjs-transactional/core/testing';
+import { TransactionalModule } from '@nestjs-transactional/core';
+
+const adapter = new InMemoryTransactionAdapter();
+
+const moduleRef = await Test.createTestingModule({
+  imports: [
+    TransactionalModule.forRoot({ isGlobal: true, adapter }),
+  ],
+}).compile();
+
+// After exercising the code under test:
+expect(adapter.committedTransactions).toHaveLength(1);
+expect(adapter.rolledBackTransactions).toHaveLength(0);
+expect(adapter.savepointsReleased).toHaveLength(0);
+```
+
+`adapter.reset()` clears all observation arrays between tests when
+you keep a single adapter instance across cases. For multi-DS test
+setups, pass distinct dataSource names to the constructor:
+
+```ts
+const billing = new InMemoryTransactionAdapter('billing');
+const inventory = new InMemoryTransactionAdapter('inventory');
+```
+
+## Worked examples
+
+- [`basic-transactional`](../../examples/basic-transactional) —
+  `@Transactional()` on a plain service.
+- [`testing-patterns`](../../examples/testing-patterns) —
+  `InMemoryTransactionAdapter` from `core/testing` plus the outbox /
+  integration test layers.
+
+Full catalogue: [examples/README.md](../../examples/README.md).
+
+## Status
+
+Alpha. Public API may change between 0.x releases.

package/dist/bootstrap/transactional-methods.bootstrap.d.ts

@@ -0,0 +1,42 @@
+import 'reflect-metadata';
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { TransactionManager } from '../manager/transaction.manager';
+/**
+ * `OnApplicationBootstrap` service that wraps every `@Transactional()`
+ * method on a plain `@Injectable()` provider with
+ * `TransactionManager.run(...)`.
+ *
+ * This is the second of the three coordinated wrapping mechanisms
+ * described in ADR-005:
+ *
+ * 1. {@link import('../interceptor/transactional.interceptor').TransactionalInterceptor}
+ *    — for controller / resolver / gateway request-boundary handlers.
+ * 2. This class — for regular `@Injectable` services.
+ * 3. `CqrsHandlerWrapper` (in `@nestjs-transactional/cqrs`) — for CQRS
+ *    command / query / event handlers.
+ *
+ * Skip rules:
+ * - CQRS handler classes (detected via `@nestjs/cqrs` metadata keys) are
+ *   left alone so their wrapping goes through `CqrsHandlerWrapper`.
+ * - Methods already marked with {@link WRAPPED_MARKER} are left alone
+ *   (safety net against double-wrap).
+ *
+ * Metadata lookup priority: method-level `@Transactional` overrides
+ * class-level. Classes with only class-level `@Transactional` apply the
+ * same options to every method that doesn't carry its own metadata.
+ *
+ * Registered by `TransactionalModule.forRoot` unless the caller sets
+ * `registerMethodsBootstrap: false`.
+ */
+export declare class TransactionalMethodsBootstrap implements OnApplicationBootstrap {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly manager;
+    private readonly logger;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, manager: TransactionManager);
+    onApplicationBootstrap(): void;
+    private isCqrsHandler;
+    private wrapMethod;
+}
+//# sourceMappingURL=transactional-methods.bootstrap.d.ts.map

package/dist/bootstrap/transactional-methods.bootstrap.js

@@ -0,0 +1,129 @@
+"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);
+};
+var TransactionalMethodsBootstrap_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalMethodsBootstrap = void 0;
+require("reflect-metadata");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const transactional_decorator_1 = require("../decorators/transactional.decorator");
+const markers_1 = require("../internal/markers");
+const transaction_manager_1 = require("../manager/transaction.manager");
+/**
+ * Metadata keys set by `@nestjs/cqrs`'s handler decorators. Mirrored here
+ * so the bootstrap skips CQRS handler classes — they are wrapped by
+ * `CqrsHandlerWrapper` in `@nestjs-transactional/cqrs`, which knows how
+ * to apply per-kind defaults (read-only queries, etc.). Double-wrapping
+ * is additionally guarded via `WRAPPED_MARKER`.
+ */
+const CQRS_HANDLER_KEYS = [
+    '__commandHandler__',
+    '__queryHandler__',
+    '__eventsHandler__',
+];
+/**
+ * `OnApplicationBootstrap` service that wraps every `@Transactional()`
+ * method on a plain `@Injectable()` provider with
+ * `TransactionManager.run(...)`.
+ *
+ * This is the second of the three coordinated wrapping mechanisms
+ * described in ADR-005:
+ *
+ * 1. {@link import('../interceptor/transactional.interceptor').TransactionalInterceptor}
+ *    — for controller / resolver / gateway request-boundary handlers.
+ * 2. This class — for regular `@Injectable` services.
+ * 3. `CqrsHandlerWrapper` (in `@nestjs-transactional/cqrs`) — for CQRS
+ *    command / query / event handlers.
+ *
+ * Skip rules:
+ * - CQRS handler classes (detected via `@nestjs/cqrs` metadata keys) are
+ *   left alone so their wrapping goes through `CqrsHandlerWrapper`.
+ * - Methods already marked with {@link WRAPPED_MARKER} are left alone
+ *   (safety net against double-wrap).
+ *
+ * Metadata lookup priority: method-level `@Transactional` overrides
+ * class-level. Classes with only class-level `@Transactional` apply the
+ * same options to every method that doesn't carry its own metadata.
+ *
+ * Registered by `TransactionalModule.forRoot` unless the caller sets
+ * `registerMethodsBootstrap: false`.
+ */
+let TransactionalMethodsBootstrap = TransactionalMethodsBootstrap_1 = class TransactionalMethodsBootstrap {
+    discovery;
+    metadataScanner;
+    manager;
+    logger = new common_1.Logger(TransactionalMethodsBootstrap_1.name);
+    constructor(discovery, metadataScanner, manager) {
+        this.discovery = discovery;
+        this.metadataScanner = metadataScanner;
+        this.manager = manager;
+    }
+    onApplicationBootstrap() {
+        const providers = this.discovery.getProviders();
+        let wrappedCount = 0;
+        for (const wrapper of providers) {
+            if (wrapper.instance === null || wrapper.instance === undefined)
+                continue;
+            if (typeof wrapper.metatype !== 'function')
+                continue;
+            const metatype = wrapper.metatype;
+            if (this.isCqrsHandler(metatype))
+                continue;
+            const instance = wrapper.instance;
+            const prototype = Object.getPrototypeOf(instance);
+            if (prototype === null)
+                continue;
+            const classMetadata = (0, transactional_decorator_1.getTransactionalMetadata)(metatype);
+            const methodNames = this.metadataScanner.getAllMethodNames(prototype);
+            const methods = prototype;
+            const host = instance;
+            for (const methodName of methodNames) {
+                const protoMethod = methods[methodName];
+                if (typeof protoMethod !== 'function')
+                    continue;
+                const metadata = (0, transactional_decorator_1.getTransactionalMetadata)(protoMethod) ?? classMetadata;
+                if (metadata === undefined)
+                    continue;
+                const currentMethod = host[methodName];
+                if (typeof currentMethod !== 'function')
+                    continue;
+                if (Reflect.getMetadata(markers_1.WRAPPED_MARKER, currentMethod) === true)
+                    continue;
+                if (this.wrapMethod(host, methodName, currentMethod, instance, metadata)) {
+                    wrappedCount++;
+                }
+            }
+        }
+        this.logger.log(`Wrapped ${wrappedCount} @Transactional method${wrappedCount === 1 ? '' : 's'}`);
+    }
+    isCqrsHandler(metatype) {
+        return CQRS_HANDLER_KEYS.some((key) => Reflect.hasMetadata(key, metatype));
+    }
+    wrapMethod(host, methodName, currentMethod, instance, metadata) {
+        const boundOriginal = currentMethod.bind(instance);
+        const manager = this.manager;
+        const wrapped = (...args) => manager.run(metadata, () => Promise.resolve(boundOriginal(...args)));
+        Reflect.defineMetadata(markers_1.WRAPPED_MARKER, true, wrapped);
+        Reflect.defineMetadata(transactional_decorator_1.TRANSACTIONAL_METADATA, metadata, wrapped);
+        host[methodName] = wrapped;
+        this.logger.debug(`Wrapped ${instance.constructor.name}.${methodName} ` +
+            `(propagation=${metadata.propagation ?? 'REQUIRED'})`);
+        return true;
+    }
+};
+exports.TransactionalMethodsBootstrap = TransactionalMethodsBootstrap;
+exports.TransactionalMethodsBootstrap = TransactionalMethodsBootstrap = TransactionalMethodsBootstrap_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_1.MetadataScanner,
+        transaction_manager_1.TransactionManager])
+], TransactionalMethodsBootstrap);
+//# sourceMappingURL=transactional-methods.bootstrap.js.map

package/dist/bootstrap/transactional-methods.bootstrap.js.map

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

package/dist/context/transaction-context-view.d.ts

@@ -0,0 +1,38 @@
+import { type ActiveTransaction } from './transaction.context';
+/**
+ * Per-dataSource read-only view over {@link TransactionContext}'s active
+ * transaction Map (DD-022). Bound to a single dataSource name at
+ * construction; consumers ask "is there an active transaction for *my*
+ * dataSource?" without typing the name twice.
+ *
+ * Mutations (set / remove) intentionally do NOT live on this surface —
+ * they remain on `TransactionContext` and are the domain of
+ * {@link TransactionManager} alone. The view is a thin lookup helper
+ * to keep the per-dataSource inject-decorator surface (DD-022)
+ * meaningful without duplicating the lifecycle API.
+ *
+ * Wired by `TransactionalModule.forRoot` under
+ * `getTransactionContextToken(dataSource)`. Inject via
+ * `@InjectTransactionContext(dataSource?)`.
+ */
+export declare class TransactionContextView {
+    readonly dataSource: string;
+    /**
+     * @param dataSource - Public dataSource name this view is bound to.
+     *   `'default'` for the single-adapter case.
+     */
+    constructor(dataSource: string);
+    /**
+     * Return the active transaction for the bound dataSource, or
+     * `undefined` if none is active. Equivalent to calling
+     * `TransactionContext.getActiveTransactionByDataSource(this.dataSource)`.
+     */
+    getActiveTransaction(): ActiveTransaction | undefined;
+    /**
+     * Predicate convenience over {@link getActiveTransaction}. Useful for
+     * smart-facade publishers (DD-024) that branch on whether the bound
+     * dataSource is the one currently running a transaction.
+     */
+    hasActiveTransaction(): boolean;
+}
+//# sourceMappingURL=transaction-context-view.d.ts.map

package/dist/context/transaction-context-view.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionContextView = void 0;
+const transaction_context_1 = require("./transaction.context");
+/**
+ * Per-dataSource read-only view over {@link TransactionContext}'s active
+ * transaction Map (DD-022). Bound to a single dataSource name at
+ * construction; consumers ask "is there an active transaction for *my*
+ * dataSource?" without typing the name twice.
+ *
+ * Mutations (set / remove) intentionally do NOT live on this surface —
+ * they remain on `TransactionContext` and are the domain of
+ * {@link TransactionManager} alone. The view is a thin lookup helper
+ * to keep the per-dataSource inject-decorator surface (DD-022)
+ * meaningful without duplicating the lifecycle API.
+ *
+ * Wired by `TransactionalModule.forRoot` under
+ * `getTransactionContextToken(dataSource)`. Inject via
+ * `@InjectTransactionContext(dataSource?)`.
+ */
+class TransactionContextView {
+    dataSource;
+    /**
+     * @param dataSource - Public dataSource name this view is bound to.
+     *   `'default'` for the single-adapter case.
+     */
+    constructor(dataSource) {
+        this.dataSource = dataSource;
+    }
+    /**
+     * Return the active transaction for the bound dataSource, or
+     * `undefined` if none is active. Equivalent to calling
+     * `TransactionContext.getActiveTransactionByDataSource(this.dataSource)`.
+     */
+    getActiveTransaction() {
+        return transaction_context_1.TransactionContext.getActiveTransactionByDataSource(this.dataSource);
+    }
+    /**
+     * Predicate convenience over {@link getActiveTransaction}. Useful for
+     * smart-facade publishers (DD-024) that branch on whether the bound
+     * dataSource is the one currently running a transaction.
+     */
+    hasActiveTransaction() {
+        return this.getActiveTransaction() !== undefined;
+    }
+}
+exports.TransactionContextView = TransactionContextView;
+//# sourceMappingURL=transaction-context-view.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-context-view.js","sourceRoot":"","sources":["../../src/context/transaction-context-view.ts"],"names":[],"mappings":";;;AAAA,+DAG+B;AAE/B;;;;;;;;;;;;;;;GAeG;AACH,MAAa,sBAAsB;IAKZ;IAJrB;;;OAGG;IACH,YAAqB,UAAkB;QAAlB,eAAU,GAAV,UAAU,CAAQ;IAAG,CAAC;IAE3C;;;;OAIG;IACH,oBAAoB;QAClB,OAAO,wCAAkB,CAAC,gCAAgC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9E,CAAC;IAED;;;;OAIG;IACH,oBAAoB;QAClB,OAAO,IAAI,CAAC,oBAAoB,EAAE,KAAK,SAAS,CAAC;IACnD,CAAC;CACF;AAxBD,wDAwBC"}

package/dist/context/transaction.context.d.ts

@@ -0,0 +1,114 @@
+import type { TransactionHandle } from '../types/transaction-handle';
+import type { TransactionOptions } from '../types/transaction-options';
+/**
+ * A single transaction currently live on the async context. Adapters register
+ * one of these under their `adapterInstanceName` when they begin a transaction
+ * and remove it when the transaction ends. Hooks registered on this object
+ * are fired by the manager during commit / rollback.
+ */
+export interface ActiveTransaction {
+    /** Adapter-specific opaque handle — cast by the adapter's own helpers. */
+    readonly handle: TransactionHandle;
+    /** Adapter type name (e.g. `'typeorm'`) — mirrors `handle.adapterName`. */
+    readonly adapterName: string;
+    /** Adapter instance name (e.g. `'primary'`, `'billing'`) under which it was registered. */
+    readonly adapterInstanceName: string;
+    /** Options the manager handed to the adapter when beginning this transaction. */
+    readonly options: TransactionOptions;
+    /** Wall-clock moment the transaction began, for observability. */
+    readonly startedAt: Date;
+    /** Hooks executed just before the adapter issues COMMIT. A throwing hook rolls the transaction back. */
+    readonly afterCommitHooks: (() => Promise<void>)[];
+    /** Hooks executed after a successful COMMIT. */
+    readonly afterRollbackHooks: ((error: unknown) => Promise<void>)[];
+    /** Hooks executed after a ROLLBACK; receive the error that caused the rollback. */
+    readonly beforeCommitHooks: (() => Promise<void>)[];
+    /** Correlation id inherited from the enclosing {@link TransactionContext} scope. */
+    readonly correlationId: string;
+}
+/**
+ * Per-scope state that lives on the async context. Created on the outermost
+ * {@link TransactionContext.run} call and reused by all nested ones, so that
+ * a single logical unit of work owns a single correlation id and a single
+ * registry of active transactions across adapters.
+ */
+export interface TransactionContextStore {
+    /** Active transactions keyed by `adapterInstanceName`. */
+    readonly activeTransactions: Map<string, ActiveTransaction>;
+    /** Stable correlation id for the whole scope — set by the outermost run(). */
+    readonly correlationId: string;
+    /** Wall-clock moment the scope began. */
+    readonly startedAt: Date;
+}
+/**
+ * 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.
+ */
+export declare 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<T>(correlationId: string, fn: () => Promise<T>): Promise<T>;
+    /** Return the active store, or `undefined` if called outside any run() scope. */
+    static getStore(): TransactionContextStore | undefined;
+    /** Return the active transaction registered under `adapterInstanceName`, or `undefined`. */
+    static getActiveTransaction(adapterInstanceName: string): ActiveTransaction | undefined;
+    /**
+     * 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: string): ActiveTransaction | 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: string, tx: ActiveTransaction): void;
+    /**
+     * 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: string): void;
+}
+//# sourceMappingURL=transaction.context.d.ts.map