@nestjs-transactional/core 1.0.0-alpha.3 → 1.0.0

package/README.md

@@ -1,265 +1,204 @@
 # @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)
+[![npm version](https://img.shields.io/npm/v/%40nestjs-transactional%2Fcore?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
+Declarative transactions for NestJS, with Spring's semantics.
+
+Put `@Transactional()` on a method and everything it touches runs in
+one transaction — across `await` boundaries, without threading a
+manager through your call stack. All seven Spring propagation modes are
+implemented, including `NESTED` via savepoints.
+
+This package is ORM-agnostic and does nothing on its own: it needs an
+adapter. Most applications install
+[`@nestjs-transactional/typeorm`](https://www.npmjs.com/package/@nestjs-transactional/typeorm)
+alongside it, which also makes injected repositories transaction-aware
+automatically. For event delivery that survives a crash, add
+[`@nestjs-transactional/outbox`](https://www.npmjs.com/package/@nestjs-transactional/outbox);
+for `@nestjs/cqrs` handlers,
+[`@nestjs-transactional/cqrs`](https://www.npmjs.com/package/@nestjs-transactional/cqrs).
+
+## Install
 
 ```bash
-pnpm add @nestjs-transactional/core reflect-metadata
+pnpm add @nestjs-transactional/core @nestjs-transactional/typeorm reflect-metadata
 ```
 
-Load `reflect-metadata` once at the application entry point (same as
-for NestJS itself).
+Load `reflect-metadata` once at your entry point, as NestJS itself
+requires.
 
 ## 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({ /* ... */ }),
+    TypeOrmModule.forRoot({
+      /* ... */
+    }),
 
-    // Infrastructure-only forRoot — registers TransactionManager,
-    // AdapterRegistry, and the interceptor. No `adapter` here; the
-    // integration package below registers it.
+    // Infrastructure only: TransactionManager, AdapterRegistry, the
+    // interceptor. `isGlobal` matters — the adapter package below
+    // needs to see the registry from its own DI scope.
     TransactionalModule.forRoot({ isGlobal: true }),
 
-    // Integration package registers `TypeOrmTransactionAdapter`
-    // for the default dataSource.
+    // Registers the TypeORM adapter 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:
+That is the whole setup. Now any method — a controller handler, a
+service method, a CQRS handler — becomes transactional by decoration:
 
 ```ts
-import { Controller, Get, Param } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { Transactional } from '@nestjs-transactional/core';
 
-@Controller('orders')
-export class OrdersController {
-  constructor(private readonly orders: OrdersService) {}
-
-  @Get(':id')
+@Injectable()
+export class OrdersService {
   @Transactional()
-  async findOne(@Param('id') id: string) {
-    return this.orders.findById(id);
+  async placeOrder(dto: PlaceOrderDto): Promise<Order> {
+    const order = await this.orders.save(dto);
+    await this.stock.reserve(order); // same transaction
+    return order; // commits here; a throw rolls both back
   }
 }
 ```
 
-### Direct adapter registration (custom backends)
+## Propagation
 
-When implementing a new `TransactionAdapter` (Prisma, Mongoose, ...),
-pass it to `forRoot` directly:
+`@Transactional({ propagation })` decides what happens when a
+transactional method is called from inside another one. The default,
+`REQUIRED`, joins the caller — which is what you want almost always.
 
-```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
+| Mode | Caller has a transaction | Caller has none |
+| --- | --- | --- |
+| `REQUIRED` *(default)* | join it | start one |
+| `REQUIRES_NEW` | suspend it, run independently, resume | start one |
+| `NESTED` | run in a savepoint | start one |
+| `SUPPORTS` | join it | run without a transaction |
+| `NOT_SUPPORTED` | suspend it, run without one, resume | run without one |
+| `NEVER` | throw `IllegalTransactionStateError` | run without one |
+| `MANDATORY` | join it | throw `IllegalTransactionStateError` |
+
+`REQUIRES_NEW` is how you make a side effect survive the caller's
+rollback — an audit row that must persist even when the operation
+fails. `NESTED` gives you a partial rollback inside one transaction;
+it needs a driver with savepoint support, and the TypeORM adapter
+raises a clear error rather than silently degrading if the driver has
+none.
+
+## 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() { /* ... */ }
+  async rebuild() {}
+
+  // Roll back on anything except ValidationError.
+  @Transactional({ noRollbackFor: [ValidationError] })
+  async processBatch() {}
 
   // Shorthand for { readOnly: true }.
   @ReadOnly()
-  async exportCsv() { /* ... */ }
-
-  // Rollback rules — commit on `ValidationError`, roll back on others.
-  @Transactional({ noRollbackFor: [ValidationError] })
-  async processBatch() { /* ... */ }
+  async exportCsv() {}
 
-  // Target a specific dataSource in multi-DataSource setups.
+  // Target one dataSource in a multi-dataSource application.
   @TransactionalOn('billing')
-  async chargeCard() { /* ... */ }
+  async chargeCard() {}
 }
 ```
 
-Propagation semantics:
+Two options carry caveats worth knowing before you rely on them:
 
-| 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).
+- **`readOnly`** is enforced by the database only on Postgres-family
+  dialects, where the adapter issues `SET TRANSACTION READ ONLY`.
+  Elsewhere it documents intent and nothing rejects a write. Spring
+  treats it as a hint too. See
+  [DD-027](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/dd/027-readonly-and-timeout-semantics.md).
+- **`timeout`** is accepted by the type but **not implemented** by the
+  TypeORM adapter. It is deliberately not approximated: Postgres'
+  `statement_timeout` bounds each statement rather than the
+  transaction, so `timeout: 5000` on a method issuing four queries
+  would allow twenty seconds. It stays in the surface for adapters
+  whose driver exposes a real transaction budget.
 
-## Lifecycle hooks
+## Commit and rollback hooks
 
-Register hooks from inside a transactional method — they fire on the
-current transaction:
+Register from inside a transactional method; the hook binds to the
+transaction currently running.
 
 ```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);
+@Transactional()
+async placeOrder(dto: PlaceOrderDto) {
+  const order = await this.orders.save(dto);
 
-    this.manager.registerAfterCommit(async () => {
-      // Fires only after the adapter commits. Never on rollback.
-      await this.analytics.trackOrderPlaced(order.id);
-    });
+  // Runs only after the commit succeeds — never on rollback.
+  this.manager.registerAfterCommit(() => this.analytics.track(order.id));
 
-    this.manager.registerAfterRollback(async (error) => {
-      // Receives the error that caused the rollback.
-      await this.metrics.recordFailedOrder(order.id, error);
-    });
+  // Receives the error that caused the rollback.
+  this.manager.registerAfterRollback((error) => this.metrics.failed(error));
 
-    return order;
-  }
+  return order;
 }
 ```
 
-Hook errors are caught and logged via NestJS `Logger` — they do not
-affect the transaction outcome or prevent sibling hooks from running.
+A throwing hook is logged and swallowed: it changes neither the
+transaction's outcome nor its sibling hooks. For event handlers with
+these semantics as first-class decorators, see the `cqrs` package.
 
 ## Testing
 
-`InMemoryTransactionAdapter` from the `/testing` subpath gives
-adapter-level observability without a real database:
+`InMemoryTransactionAdapter` from the `/testing` subpath records
+commits, rollbacks and savepoints without a 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 }),
-  ],
+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:
+`adapter.reset()` clears the arrays between cases. Pass a dataSource
+name to the constructor for multi-dataSource tests.
+
+## Custom adapters
+
+To support another ORM, implement `TransactionAdapter<THandle>` and
+hand it to `forRoot` directly:
 
 ```ts
-const billing = new InMemoryTransactionAdapter('billing');
-const inventory = new InMemoryTransactionAdapter('inventory');
+TransactionalModule.forRoot({ isGlobal: true, adapter: myAdapter });
 ```
 
-## Worked examples
+One `forRoot` call registers one adapter. Multi-dataSource
+applications call it once per dataSource.
 
-- [`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.
+## Documentation
 
-Full catalogue: [examples/README.md](../../examples/README.md).
+- [Getting started and full docs](https://github.com/igorgolovanov/nestjs-transactional#readme)
+- [Architecture: core design](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/architecture/core-design.md)
+- [How methods get wrapped (ADR-005)](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/adr/005-method-wrapping-strategy.md)
+- [Known limitations](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/known-limitations.md)
+- Runnable examples:
+  [`basic-transactional`](https://github.com/igorgolovanov/nestjs-transactional/tree/main/examples/basic-transactional),
+  [`testing-patterns`](https://github.com/igorgolovanov/nestjs-transactional/tree/main/examples/testing-patterns)
 
-## Status
+## License
 
-Alpha. Public API may change between 0.x releases.
+MIT

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

@@ -1 +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"}
+{"version":3,"file":"transaction-context-view.js","sourceRoot":"","sources":["../../src/context/transaction-context-view.ts"],"names":[],"mappings":";;;AAAA,+DAAmF;AAEnF;;;;;;;;;;;;;;;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

@@ -55,7 +55,7 @@ export interface TransactionContextStore {
  *
  * **Public dataSource-name access**:
  * {@link getActiveTransactionByDataSource} provides dataSource-name
- * lookup for Phase 14.2+ multi-adapter consumers — it scans the Map
+ * lookup for 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

package/dist/context/transaction.context.js

@@ -19,7 +19,7 @@ const als = new node_async_hooks_1.AsyncLocalStorage();
  *
  * **Public dataSource-name access**:
  * {@link getActiveTransactionByDataSource} provides dataSource-name
- * lookup for Phase 14.2+ multi-adapter consumers — it scans the Map
+ * lookup for 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

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

@@ -1 +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"}
+{"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,CAAC,UAAkB;QACxD,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;AAzFD,gDAyFC"}

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

@@ -38,6 +38,11 @@ export declare function Transactional(options?: Partial<TransactionalMetadata>):
  * 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.
+ *
+ * Enforcement is per-dialect (DD-027). On Postgres-family databases
+ * `TypeOrmTransactionAdapter` issues `SET TRANSACTION READ ONLY`, so a
+ * stray write fails at the database. Elsewhere — MySQL, SQLite, ... —
+ * the flag documents intent but nothing stops the write.
  */
 export declare const ReadOnly: (options?: Partial<TransactionalMetadata>) => MethodDecorator & ClassDecorator;
 /**

package/dist/decorators/transactional.decorator.js

@@ -51,6 +51,11 @@ function Transactional(options = {}) {
  * 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.
+ *
+ * Enforcement is per-dialect (DD-027). On Postgres-family databases
+ * `TypeOrmTransactionAdapter` issues `SET TRANSACTION READ ONLY`, so a
+ * stray write fails at the database. Elsewhere — MySQL, SQLite, ... —
+ * the flag documents intent but nothing stops the write.
  */
 const ReadOnly = (options = {}) => Transactional({ ...options, readOnly: true });
 exports.ReadOnly = ReadOnly;

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

@@ -1 +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"}
+{"version":3,"file":"transactional.decorator.js","sourceRoot":"","sources":["../../src/decorators/transactional.decorator.ts"],"names":[],"mappings":";;;AAsCA,sCAsBC;AAyCD,4DAGC;AAxGD,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;;;;;;;;;;GAUG;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/module/transactional.module.d.ts

@@ -14,7 +14,7 @@ import type { TransactionAdapter } from '../types/transaction-adapter';
  *
  * Matches NestJS conventions (`TypeOrmModule`, `MongooseModule`,
  * `ClientsModule`) and aligns with `OutboxModule.forRoot` from
- * Phase 14.3.2 (ADR-019). Cross-call coordination of singletons
+ * ADR-019. Cross-call coordination of singletons
  * (`AdapterRegistry`, `TransactionManager`, `APP_INTERCEPTOR`,
  * `TransactionalMethodsBootstrap`, `TRANSACTION_OBSERVERS`) lives in
  * static class storage on {@link TransactionalModule}, mirroring
@@ -51,7 +51,7 @@ export interface TransactionalModuleOptions {
      */
     readonly adapter?: TransactionAdapter;
     /**
-     * When `true` (default — Phase 14.10), the module is registered as
+     * When `true` (default), the module is registered as
      * `@Global()` — its exports are available app-wide without being
      * re-imported. Honored per call (each `forRoot` builds its own
      * `DynamicModule` with its own `global` flag). Multi-call setups
@@ -123,7 +123,7 @@ export interface TransactionalModuleAsyncOptions extends Pick<ModuleMetadata, 'i
  * 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).
+ * calls (mirrors `OutboxModule` per ADR-019).
  *
  * The first call registers the process-wide infrastructure; subsequent
  * calls only contribute per-dataSource providers. Adapter-specific

package/dist/module/transactional.module.js

@@ -25,7 +25,7 @@ const ASYNC_REGISTRATION_TOKEN = (id) => Symbol(`TRANSACTIONAL_ASYNC_REGISTRATIO
  * 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).
+ * calls (mirrors `OutboxModule` per ADR-019).
  *
  * The first call registers the process-wide infrastructure; subsequent
  * calls only contribute per-dataSource providers. Adapter-specific
@@ -149,7 +149,7 @@ let TransactionalModule = class TransactionalModule {
             // 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.
+            // mirrors `OutboxModule` per ADR-019.
             providers.push({
                 provide: adapter_registry_1.ADAPTER_REGISTRY,
                 useFactory: () => buildRegistryFromStaticStorage(TransactionalModule_1),
@@ -245,10 +245,7 @@ let TransactionalModule = class TransactionalModule {
             },
             inject: [asyncToken, adapter_registry_1.ADAPTER_REGISTRY],
         };
-        const providers = [
-            asyncOptionsProvider,
-            adapterEagerRegistrationProvider,
-        ];
+        const providers = [asyncOptionsProvider, adapterEagerRegistrationProvider];
         const exportTokens = [];
         if (isFirst) {
             this.infrastructureRegistered = true;
@@ -274,7 +271,7 @@ let TransactionalModule = class TransactionalModule {
             // after the factory runs).
             providers.push({
                 provide: transaction_observer_1.TRANSACTION_OBSERVERS,
-                useFactory: (opts) => opts.observers ? [...opts.observers] : [],
+                useFactory: (opts) => (opts.observers ? [...opts.observers] : []),
                 inject: [asyncToken],
             });
             if (options.registerInterceptor !== false) {
@@ -351,7 +348,7 @@ function buildPerDataSourceProviders(adapter) {
  * `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.
+ * Map. Pattern mirrors `OutboxModule` per ADR-019.
  *
  * @internal
  */

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

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

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

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

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

@@ -16,16 +16,39 @@ export interface TransactionOptions {
      */
     readonly isolation?: IsolationLevel;
     /**
-     * Hint that the transaction will only issue reads. Adapters may use this
-     * to route to a read replica or to issue `SET TRANSACTION READ ONLY`.
-     * It is a hint, not an enforcement — writes may still be attempted and
-     * may be rejected by the database.
+     * Hint that the transaction will only issue reads. A hint by design,
+     * matching Spring's semantics: adapters honour it where the underlying
+     * database allows, and ignore it where it cannot be expressed
+     * (DD-027).
+     *
+     * `TypeOrmTransactionAdapter` issues `SET TRANSACTION READ ONLY` on
+     * Postgres-family dialects (`postgres`, `cockroachdb`,
+     * `aurora-postgres`), so a write inside the transaction is refused by
+     * the database. On every other dialect it is a silent no-op — notably
+     * MySQL, where the access mode can only be set as
+     * `START TRANSACTION READ ONLY` and TypeORM does not expose that
+     * moment.
+     *
+     * Only applies when the adapter actually starts the transaction: a
+     * `REQUIRED` call joining an existing read-write transaction cannot
+     * make it read-only after the fact.
      */
     readonly readOnly?: boolean;
     /**
-     * Transaction timeout in milliseconds. If the adapter supports
-     * transaction-level timeouts (e.g. `statement_timeout` on Postgres),
-     * exceeding this triggers a rollback. Omit for no timeout.
+     * Budget for the whole transaction, in milliseconds. Omit for no
+     * timeout.
+     *
+     * NOT IMPLEMENTED by `TypeOrmTransactionAdapter`, and deliberately not
+     * approximated (DD-027). TypeORM exposes no transaction-level timeout,
+     * and the nearest dialect feature — Postgres' `statement_timeout` —
+     * bounds each statement rather than the transaction, so
+     * `timeout: 5000` on a method issuing four queries would allow twenty
+     * seconds, not five. A wrong meaning under a familiar name is worse
+     * than a documented gap.
+     *
+     * The option stays in the surface as the extension point for adapters
+     * whose driver has a real transaction budget: Prisma's `$transaction`
+     * accepts exactly this.
      */
     readonly timeout?: number;
 }

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@nestjs-transactional/core",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0",
   "description": "Declarative transaction management for NestJS — core primitives (AsyncLocalStorage context, TransactionManager, @Transactional decorator, adapter port)",
   "license": "MIT",
+  "type": "commonjs",
+  "sideEffects": false,
   "author": "Igor Golovanov",
   "repository": {
     "type": "git",
-    "url": "https://github.com/igorgolovanov/nestjs-transactional.git",
+    "url": "git+https://github.com/igorgolovanov/nestjs-transactional.git",
     "directory": "packages/core"
   },
   "bugs": {
@@ -42,9 +44,15 @@
       "default": "./dist/testing/index.js"
     }
   },
+  "typesVersions": {
+    "*": {
+      "testing": [
+        "./dist/testing/index.d.ts"
+      ]
+    }
+  },
   "publishConfig": {
     "access": "public",
-    "tag": "alpha",
     "provenance": true
   },
   "peerDependencies": {
@@ -70,6 +78,9 @@
     "test:watch": "jest --watch",
     "test:cov": "jest --coverage",
     "type-check": "tsc --noEmit",
-    "lint": "eslint \"src/**/*.ts\""
+    "lint": "eslint \"src/**/*.ts\"",
+    "api:check": "api-extractor run && api-extractor run -c api-extractor.testing.json",
+    "api:update": "api-extractor run --local && api-extractor run --local -c api-extractor.testing.json",
+    "publish:check": "publint && attw --pack ."
   }
 }