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

package/README.md

@@ -1,395 +1,215 @@
 # @nestjs-transactional/outbox
 
-[![npm version](https://img.shields.io/npm/v/%40nestjs-transactional%2Foutbox/alpha?style=flat-square&label=npm)](https://www.npmjs.com/package/@nestjs-transactional/outbox)
+[![npm version](https://img.shields.io/npm/v/%40nestjs-transactional%2Foutbox?style=flat-square&label=npm)](https://www.npmjs.com/package/@nestjs-transactional/outbox)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/igorgolovanov/nestjs-transactional/blob/main/LICENSE)
 
-Persistent Event Publication Registry for NestJS — an ORM-agnostic core
-that brings Spring Modulith-equivalent delivery guarantees to the
-`@nestjs-transactional` family of packages.
+The transactional outbox for NestJS — a persistent Event Publication
+Registry, modelled on Spring Modulith's.
 
-## Overview
+In-process event handlers have one failure mode you cannot design
+around: if the process dies between the commit and the handler, the
+event is gone. This package writes one row per handler per event, in the
+same transaction as your business data. A worker picks the rows up
+afterwards, retries what fails, and resumes what a restart interrupted.
 
-`@TransactionalEventsHandler` from `@nestjs-transactional/cqrs` provides
-phase-based dispatching (like Spring Framework core): handlers fire
-`AFTER_COMMIT`, `BEFORE_COMMIT`, `AFTER_ROLLBACK`, or `AFTER_COMPLETION`.
-That covers a lot, but it is purely in-memory — if the process dies
-between commit and handler invocation, the event is lost.
+Either both happen or neither does. That is the whole point.
 
-`outbox` closes that gap. It gives you:
+This package is storage-agnostic — it ships the SPI, the worker, the
+operator APIs and an in-memory implementation for tests, but no
+production backend. Add
+[`@nestjs-transactional/outbox-typeorm`](https://www.npmjs.com/package/@nestjs-transactional/outbox-typeorm)
+for that. It builds on
+[`@nestjs-transactional/core`](https://www.npmjs.com/package/@nestjs-transactional/core),
+integrates with
+[`@nestjs-transactional/cqrs`](https://www.npmjs.com/package/@nestjs-transactional/cqrs),
+and can forward events to a broker through
+[`@nestjs-transactional/outbox-microservices`](https://www.npmjs.com/package/@nestjs-transactional/outbox-microservices).
 
-- A persistent **Event Publication Registry** — every handler
-  invocation is logged atomically with the business transaction.
-- **Retry on process restart** — publications that were not acknowledged
-  before shutdown are replayed on next startup.
-- **Lifecycle states**: `PUBLISHED`, `PROCESSING`, `COMPLETED`, `FAILED`,
-  `RESUBMITTED`.
-- **Staleness monitor** — detects publications stuck in `PROCESSING`.
-- **Failed / Incomplete / Completed** query APIs for operators.
-- **Completion modes**: `UPDATE`, `DELETE`, `ARCHIVE`.
-
-This package only defines types, the repository SPI, the in-memory
-reference implementation (for tests), and the Nest module wiring. It
-does **not** ship a production persistence backend — that lives in a
-sibling package such as `@nestjs-transactional/outbox-typeorm`.
-
-## Installation
+## Install
 
 ```bash
-pnpm add @nestjs-transactional/core @nestjs-transactional/outbox
-# plus a persistence backend, e.g.:
-pnpm add @nestjs-transactional/outbox-typeorm
+pnpm add @nestjs-transactional/outbox @nestjs-transactional/core
+pnpm add @nestjs-transactional/outbox-typeorm   # a persistence backend
 ```
 
-Peer dependencies: `@nestjs/common`, `@nestjs/core`, `reflect-metadata`,
-`rxjs`.
-
-## Usage
-
-### 1. Module wiring
+## Quick start
 
-`OutboxModule.forRoot()` provides global infrastructure (registry,
-serializer, processor, recovery). `OutboxModule.forFeature([...])`
-declares the event classes a feature module owns — matches
-`TypeOrmModule.forFeature(...)` ergonomics.
-
-```typescript
+```ts
 import { Module } from '@nestjs/common';
 import { TransactionalModule } from '@nestjs-transactional/core';
 import { OutboxModule, OutboxProcessingModule } from '@nestjs-transactional/outbox';
+import { typeOrmEventPublicationRepositoryProvider } from '@nestjs-transactional/outbox-typeorm';
 
 @Module({
   imports: [
-    // isGlobal: true is REQUIRED so outbox providers can see
-    // TransactionManager across module boundaries.
-    TransactionalModule.forRoot({
-      isGlobal: true,
-      adapters: [/* your adapter registrations */],
-    }),
+    // Must be global: outbox providers resolve TransactionManager
+    // across module boundaries.
+    TransactionalModule.forRoot({ isGlobal: true }),
+    TypeOrmTransactionalModule.forRoot(),
+    OutboxTypeOrmModule.forRoot(),
+
     OutboxModule.forRoot({
+      // Without this, the in-memory repository stays installed and
+      // nothing is ever persisted. See the note below.
+      repository: typeOrmEventPublicationRepositoryProvider(),
       republishOnStartup: true,
-      processor: { pollingInterval: 1000, batchSize: 100 },
-      staleness: { processing: 60_000, monitorInterval: 30_000 },
-      // repository: { provide: EVENT_PUBLICATION_REPOSITORY, useClass: TypeOrmEventPublicationRepository },
     }),
-    // Import OutboxProcessingModule ONLY in worker processes — not in
-    // API-only apps that merely publish events.
-    OutboxProcessingModule,
-    // Register the event classes this module emits / consumes.
-    OutboxModule.forFeature([OrderPlacedEvent, OrderShippedEvent]),
-  ],
-})
-export class AppModule {}
-```
-
-#### Modular pattern (multiple feature modules)
-
-Distribute event registrations to the modules that own them:
-
-```typescript
-@Module({
-  imports: [OutboxModule.forFeature([OrderPlacedEvent, OrderCancelledEvent])],
-  providers: [OrderService],
-})
-export class OrderModule {}
 
-@Module({
-  imports: [OutboxModule.forFeature([InventoryReservedEvent])],
-  providers: [InventoryService],
-})
-export class InventoryModule {}
+    // Event classes this module owns. Feature modules normally call
+    // forFeature for their own events.
+    OutboxModule.forFeature([OrderPlacedEvent]),
 
-@Module({
-  imports: [
-    TransactionalModule.forRoot({ isGlobal: true /* ... */ }),
-    OutboxModule.forRoot({ republishOnStartup: true /* ... */ }),
-    OrderModule,
-    InventoryModule,
+    // ONLY in worker processes. An API that merely publishes events
+    // must not import this.
+    OutboxProcessingModule,
   ],
 })
 export class AppModule {}
 ```
 
-Multiple `forFeature` calls accumulate into the singleton
-`EventTypeRegistry` provided by `forRoot`. Each event class can only
-be registered once — duplicates throw at bootstrap with the offending
-class name:
+> **Pass `repository`.** `OutboxModule.forRoot()` falls back to
+> `InMemoryEventPublicationRepository` when the option is missing. Your
+> application starts, publishes, and handles events perfectly — and
+> loses every one of them on restart, with nothing in the database and
+> no error anywhere.
 
-```
-Error: Event type 'OrderPlacedEvent' already registered.
-Each event type can only be registered once — check for duplicate
-entries across OutboxModule.forFeature() calls.
-```
-
-`OutboxModule.forFeature([])` is accepted as a no-op (matches
-`TypeOrmModule.forFeature([])`).
-
-### 2. Declaring a handler
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import {
-  type IOutboxEventHandler,
-  OutboxEventsHandler,
-} from '@nestjs-transactional/outbox';
+Declare a handler:
 
+```ts
 @Injectable()
 @OutboxEventsHandler(OrderPlacedEvent)
-export class InventoryReservationHandler
-  implements IOutboxEventHandler<OrderPlacedEvent>
-{
-  async handle(event: OrderPlacedEvent): Promise<void> {
-    // Runs inside a fresh REQUIRES_NEW transaction, only after the
-    // publishing transaction has committed. Retried on exception,
-    // resumable across restarts.
+export class ChargeCustomer implements IOutboxEventHandler<OrderPlacedEvent> {
+  async handle(event: OrderPlacedEvent) {
+    // Invoked by the worker, in its own transaction. Throwing marks the
+    // publication FAILED, leaving it for retry or an operator.
+    await this.payments.charge(event.orderId);
   }
 }
 ```
 
-The decorator accepts either rest params or an options object:
-
-```typescript
-// Short form — defaults (newTransaction: true).
-@OutboxEventsHandler(OrderPlacedEvent, OrderCancelledEvent)
-
-// Long form — explicit options.
-@OutboxEventsHandler({
-  events: [OrderPlacedEvent],
-  id: 'inventory.reservation',  // stable base id, see "Listener ids" below
-  newTransaction: false,        // skip the REQUIRES_NEW wrapper
-})
-```
-
-See ADR-014 for the rationale behind the class-level shape.
-
-### 3. Publishing events
+Publish from inside a transaction:
 
-```typescript
-import { Injectable } from '@nestjs/common';
-import { Transactional } from '@nestjs-transactional/core';
-import { OutboxEventPublisher } from '@nestjs-transactional/outbox';
-
-@Injectable()
-export class PlaceOrderHandler {
-  constructor(private readonly outbox: OutboxEventPublisher) {}
-
-  @Transactional()
-  async handle(command: PlaceOrder): Promise<void> {
-    // ...persist business data in the same transaction...
-    await this.outbox.publish(new OrderPlacedEvent(command.orderId));
-  }
+```ts
+@Transactional()
+async placeOrder(dto: PlaceOrderDto) {
+  const order = await this.orders.save(dto);
+  await this.publisher.publish(new OrderPlacedEvent(order.id));
+  return order; // publication rows commit with the order, or not at all
 }
 ```
 
-### 4. Operator APIs
-
-```typescript
-const failed = await this.failedEventPublications.findAll();
-await this.failedEventPublications.resubmit(
-  ResubmissionOptions.defaults().withBatchSize(50).withMaxAttempts(3),
-);
-await this.completedEventPublications.purge(new Date(Date.now() - 30 * 24 * 60 * 60 * 1000));
-```
-
-## Listener ids
-
-Every stored publication carries a `listenerId` string that identifies
-which handler class should deliver it. The scanner composes the id as:
-
-```
-${baseId}#${EventName}
+## Lifecycle
+
+A publication moves through five states:
+
+`PUBLISHED` → `PROCESSING` → `COMPLETED`, or `FAILED` → `RESUBMITTED`
+back to `PROCESSING`.
+
+The worker polls for ready rows and then **claims** each one with a
+single conditional `UPDATE`. That claim, not the poll, is what makes
+concurrent workers safe: two workers may fetch the same row, but only
+one wins the claim and the loser moves on without invoking the handler.
+So scaling out costs a wasted read, never a duplicate dispatch
+([DD-025](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/dd/025-claim-atomicity-obligation.md)).
+
+Completed rows can be kept (`UPDATE`, the default), deleted, or moved to
+an archive table — `completionMode`. Kept rows need purging eventually;
+`CompletedEventPublications.purge(olderThan)` does it.
+
+## Operating it
+
+```ts
+OutboxModule.forRoot({
+  repository: typeOrmEventPublicationRepositoryProvider(),
+  republishOnStartup: true,
+  processor: {
+    pollingInterval: 1000, // end-to-end latency is dominated by this
+    batchSize: 100,
+    maxConcurrent: 10,
+    // How long shutdown waits for an in-flight batch. Keep it under
+    // your platform's grace period; 0 disables the wait.
+    shutdownTimeout: 10_000,
+  },
+  // Flip publications stuck in a non-terminal state to FAILED. 0 = off.
+  staleness: { processing: 60_000, monitorInterval: 30_000 },
+  // Automatic retry, off unless you ask for it. maxAttempts counts the
+  // first delivery, so 3 means the original plus two retries.
+  retry: { maxAttempts: 3, baseDelay: 1_000, factor: 2, maxDelay: 300_000 },
+});
 ```
 
-- **No explicit `id`**: baseId is the class name. Example:
-  `InventoryReservationHandler#OrderPlacedEvent`.
-- **With `options.id`**: baseId is the supplied string. Example:
-  `inventory.reservation#OrderPlacedEvent`.
-
-A class that handles multiple event types produces one id per event.
-Renaming the class without supplying an explicit `id` breaks delivery
-for every stored publication under the old id — set `options.id` when
-you want stability across renames.
-
-## Externalization (advanced)
-
-> The `EventExternalizer` SPI lives in this package. The
-> `@nestjs/microservices` `ClientProxy`-backed implementation ships
-> as a separate package —
-> [`@nestjs-transactional/outbox-microservices`](../outbox-microservices).
-> Without an externalizer bound, `@Externalized` mappings are
-> recorded but never delivered to a broker — local outbox listeners
-> still run.
->
-> Architecture and design rationale:
-> [ADR-015](../../docs/adr/015-event-externalization-architecture.md),
-> [`docs/architecture/event-externalization.md`](../../docs/architecture/event-externalization.md).
-> Reliability caveat for the `@nestjs/microservices`-backed
-> implementation:
-> [ADR-016](../../docs/adr/016-externalization-reliability-semantics.md).
-
-`@Externalized` marks an event class for delivery to an external
-message broker (Kafka topic, RabbitMQ exchange, NATS subject, ...) in
-addition to local outbox listeners. The processor invokes the bound
-`EventExternalizer` AFTER the local listener has succeeded — single
-unit atomicity (DD-019): if either step fails, the publication is
-recorded as `FAILED` and can be resubmitted via `FailedEventPublications`.
-
-```typescript
-import { Externalized } from '@nestjs-transactional/outbox';
-
-@Externalized<OrderPlacedEvent>({
-  target: 'orders.placed',                       // broker-side destination
-  routingKey: (e) => e.tenantId,                 // optional, brokers that support it
-  headers: (e) => ({ 'x-tenant': e.tenantId }),  // static record OR callback
-  client: 'KAFKA_CLIENT',                        // optional ClientProxy token
-})
-export class OrderPlacedEvent {
-  constructor(
-    readonly orderId: string,
-    readonly tenantId: string,
-  ) {}
-}
-```
+Shutdown is drained, not cut off: `OutboxProcessingModule` awaits the
+batch already running before NestJS tears down the DataSource, so a
+publication is not stranded mid-transition.
 
-Bind a concrete externalizer under the `EVENT_EXTERNALIZER` token —
-this is normally done by an extension package (`outbox-microservices`).
-Custom implementations can register the same way:
+Retry is opt-in because Spring Modulith has none either — recovery is
+otherwise an operator action. A publication that exhausts its attempts
+stays `FAILED`; there is no separate dead-letter state, and it remains
+visible and resubmittable
+([DD-026](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/dd/026-automatic-retry-policy.md)).
 
-```typescript
-import { EVENT_EXTERNALIZER, type EventExternalizer } from '@nestjs-transactional/outbox';
+Three injectable APIs for operators, matching Spring Modulith's:
 
-@Module({
-  providers: [
-    {
-      provide: EVENT_EXTERNALIZER,
-      useClass: MyCustomExternalizer, // implements EventExternalizer
-    },
-  ],
-})
-export class MyAppModule {}
+```ts
+await failed.findAll({ minAge: 60_000 }); // triage
+await failed.resubmit({ maxAttempts: 5 }); // retry by hand
+await incomplete.count(); // anything not COMPLETED
+await completed.purge(olderThan); // retention
 ```
 
-The processor only invokes the externalizer when BOTH a binding under
-`EVENT_EXTERNALIZER` exists AND the event class carries an
-`@Externalized` mapping — keep one without the other if you only need
-half the contract (e.g. metadata-only mappings during a rollout, or a
-generic externalizer that resolves targets some other way). Inspect
-the resolved mapping at runtime via `ExternalizationRegistry`:
-
-```typescript
-import { ExternalizationRegistry } from '@nestjs-transactional/outbox';
+## Listener ids
 
-@Injectable()
-export class MyDiagnostics {
-  constructor(private readonly externalization: ExternalizationRegistry) {}
+Each publication row is keyed by `${baseId}#${EventName}`, where
+`baseId` defaults to the handler's class name. Renaming the class
+therefore orphans any stored publication for it. Pass an explicit id
+when that is a risk:
 
-  isExternalized(typeName: string): boolean {
-    return this.externalization.has(typeName);
-  }
-}
+```ts
+@OutboxEventsHandler({ events: [OrderPlacedEvent], id: 'Billing.charge' })
 ```
 
-Errors raised by the externalizer are wrapped in `ExternalizationError`
-(carrying `eventType`, `target`, and the underlying cause) and surface
-on the publication's `failureReason` for operator visibility.
+## Testing
 
-## Testing utilities
+The `/testing` subpath ships an in-memory repository and fluent
+assertions, so outbox behaviour is testable without a database:
 
-Exported via the `/testing` subpath for assertions about which events
-the code under test published. Mirrors Spring Modulith's
-`PublishedEvents` / `AssertablePublishedEvents`.
-
-```typescript
+```ts
 import {
-  PublishedEvents,
   AssertablePublishedEvents,
+  InMemoryEventPublicationRepository,
 } from '@nestjs-transactional/outbox/testing';
 
-describe('PlaceOrder', () => {
-  let app: TestingModule;
-  let assertablePublishedEvents: AssertablePublishedEvents;
-
-  beforeEach(async () => {
-    app = await Test.createTestingModule({
-      imports: [
-        TransactionalModule.forRoot({ isGlobal: true /* ... */ }),
-        OutboxModule.forRoot({}),
-        OutboxModule.forFeature([OrderPlacedEvent]),
-      ],
-      providers: [
-        PlaceOrderService,
-        PublishedEvents,
-        AssertablePublishedEvents,
-      ],
-    }).compile();
-    await app.init();
-    assertablePublishedEvents = app.get(AssertablePublishedEvents);
-  });
-
-  it('publishes OrderPlacedEvent for the placed order', async () => {
-    const service = app.get(PlaceOrderService);
-    await service.place('order-123');
-
-    const view = await assertablePublishedEvents.contains(OrderPlacedEvent);
-    view.matching((e) => e.orderId, 'order-123').hasSize(1);
-  });
-
-  it('publishes nothing when validation rejects the command', async () => {
-    const service = app.get(PlaceOrderService);
-    await service.placeInvalid().catch(() => undefined);
-
-    await assertablePublishedEvents.doesNotContain(OrderPlacedEvent);
-  });
-});
+(await assertable.contains(OrderPlacedEvent))
+  .matching((e) => e.orderId, 'o-1')
+  .hasSize(1);
+
+// The negative path matters just as much: after a rollback, the
+// in-memory repository has removed the publication.
+await assertable.doesNotContain(OrderCancelledEvent);
 ```
 
-`PublishedEvents.ofType(EventType)` returns a fluent `PublishedEventsView`
-for read-only inspection (`.get()`, `.count()`,
-`.matching(predicate)`, `.matching(getter, expected)`).
-`AssertablePublishedEvents.contains(EventType)` is the assertion-first
-counterpart — it throws `PublishedEventsAssertionError` when zero
-events match, and returns an `AssertionView` whose `.matching(...)`
-and `.hasSize(...)` operate synchronously over the already-fetched
-events.
-
-The utilities read through the wired `EventPublicationRepository`
-implementation, so the default `InMemoryEventPublicationRepository`
-works out of the box for unit-level tests. Integration tests that use
-`@nestjs-transactional/outbox-typeorm` with a real Postgres get the
-same API for free.
-
-## Worked examples
-
-- [`basic-outbox`](../../examples/basic-outbox) — `@OutboxEventsHandler` + `OutboxEventPublisher`, in-memory test repository.
-- [`basic-typeorm-outbox`](../../examples/basic-typeorm-outbox) — production-shape outbox with Postgres, atomicity proven via testcontainers.
-- [`multi-datasource-outbox`](../../examples/multi-datasource-outbox) — per-DS `event_publication` tables (ADR-019 multi-`forRoot`).
-- [`shared-database-modular-monolith`](../../examples/shared-database-modular-monolith) — one Postgres, multi-schema, per-module outbox stacks.
-- [`saga-pattern`](../../examples/saga-pattern) — choreographed multi-step business saga over outbox events.
-- [`audit-logging`](../../examples/audit-logging) — cross-DS audit trail with idempotency on the consumer.
-- [`e-commerce-orders`](../../examples/e-commerce-orders) — three-bounded-context flagship wired through outbox integration events.
-
-Full catalogue: [examples/README.md](../../examples/README.md).
-
-## Status
-
-Alpha. Public API may change between 0.x releases. Current
-functionality is exercised end-to-end through the
-[Tier 1–5 example library](../../examples/README.md).
-
-Design notes:
-[`docs/roadmap/README.md`](../../docs/roadmap/README.md),
-[`docs/adr/006-outbox-pattern.md`](../../docs/adr/006-outbox-pattern.md).
-
-## Inspired by Spring Modulith
-
-The design follows
-[Spring Modulith's Event Publication Registry](https://docs.spring.io/spring-modulith/reference/events.html)
-closely — lifecycle states, `@ApplicationModuleListener` semantics,
-completion modes, and staleness monitoring all map one-to-one. The
-deviations from Spring Modulith are limited to what is needed to fit
-the Node.js / NestJS runtime (async workers instead of thread pools,
-AsyncLocalStorage for transaction context, NestJS DI conventions,
-class-level handler decorators aligned with `@nestjs/cqrs`
-conventions — see ADR-014).
+## Sending events to a broker
+
+`@Externalized` marks an event for forwarding after its local handlers
+complete. The `EVENT_EXTERNALIZER` SPI is transport-agnostic;
+`outbox-microservices` implements it over `@nestjs/microservices`.
+**Read that package's reliability note before relying on it in
+production** — `ClientProxy.emit()` cannot report broker-side failure,
+so a publication can be marked `COMPLETED` when nothing reached the
+broker
+([ADR-016](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/adr/016-externalization-reliability-semantics.md)).
+
+## Documentation
+
+- [Getting started and full docs](https://github.com/igorgolovanov/nestjs-transactional#readme)
+- [Architecture: the outbox pattern](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/architecture/outbox-pattern.md)
+- [Migrating to the outbox](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/guides/migrating-to-outbox.md)
+- [One `forRoot` per dataSource (ADR-019)](https://github.com/igorgolovanov/nestjs-transactional/blob/main/docs/adr/019-outbox-multi-forroot-pattern.md)
+- Runnable examples:
+  [`basic-outbox`](https://github.com/igorgolovanov/nestjs-transactional/tree/main/examples/basic-outbox),
+  [`saga-pattern`](https://github.com/igorgolovanov/nestjs-transactional/tree/main/examples/saga-pattern),
+  [`audit-logging`](https://github.com/igorgolovanov/nestjs-transactional/tree/main/examples/audit-logging),
+  [`graceful-shutdown`](https://github.com/igorgolovanov/nestjs-transactional/tree/main/examples/graceful-shutdown)
 
 ## License
 

package/dist/api/failed-event-publications.js.map

@@ -1 +1 @@
-{"version":3,"file":"failed-event-publications.js","sourceRoot":"","sources":["../../src/api/failed-event-publications.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAEpD,6FAGoD;AAEpD,oEAAgE;AAChE,wEAAoE;AAGpE;;;;GAIG;AAEI,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAGf;IAFnB,YAEmB,UAAsC;QAAtC,eAAU,GAAV,UAAU,CAA4B;IACtD,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,OAGb;QACC,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QAClD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ,CACZ,UAA+B,0CAAmB,CAAC,QAAQ,EAAE;QAE7D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;YAC9C,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,WAAW,EAAE,OAAO,CAAC,qBAAqB,IAAI,SAAS;SACxD,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAClF,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAEvD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,sCAAiB,CAAC,WAAW,EAAE;gBACxE,oBAAoB,EAAE,IAAI,IAAI,EAAE;aACjC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,SAAS,CAAC,MAAM,CAAC;IAC1B,CAAC;CACF,CAAA;AAtDY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,2DAA4B,CAAC,CAAA;;GAF5B,uBAAuB,CAsDnC"}
+{"version":3,"file":"failed-event-publications.js","sourceRoot":"","sources":["../../src/api/failed-event-publications.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAEpD,6FAGoD;AAEpD,oEAAgE;AAChE,wEAAoE;AAEpE;;;;GAIG;AAEI,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAGf;IAFnB,YAEmB,UAAsC;QAAtC,eAAU,GAAV,UAAU,CAA4B;IACtD,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,OAGb;QACC,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QAClD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ,CAAC,UAA+B,0CAAmB,CAAC,QAAQ,EAAE;QAC1E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;YAC9C,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,WAAW,EAAE,OAAO,CAAC,qBAAqB,IAAI,SAAS;SACxD,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAClF,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAEvD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,sCAAiB,CAAC,WAAW,EAAE;gBACxE,oBAAoB,EAAE,IAAI,IAAI,EAAE;aACjC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,SAAS,CAAC,MAAM,CAAC;IAC1B,CAAC;CACF,CAAA;AApDY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,2DAA4B,CAAC,CAAA;;GAF5B,uBAAuB,CAoDnC"}

package/dist/api/incomplete-event-publications.js

@@ -52,8 +52,7 @@ let IncompleteEventPublications = class IncompleteEventPublications {
         const toProcess = filtered.slice(0, options.batchSize);
         let resubmitted = 0;
         for (const pub of toProcess) {
-            if (pub.status === publication_status_1.PublicationStatus.FAILED ||
-                pub.status === publication_status_1.PublicationStatus.PUBLISHED) {
+            if (pub.status === publication_status_1.PublicationStatus.FAILED || pub.status === publication_status_1.PublicationStatus.PUBLISHED) {
                 await this.repository.updateStatus(pub.id, publication_status_1.PublicationStatus.RESUBMITTED, {
                     lastResubmissionDate: new Date(),
                 });

package/dist/api/incomplete-event-publications.js.map

@@ -1 +1 @@
-{"version":3,"file":"incomplete-event-publications.js","sourceRoot":"","sources":["../../src/api/incomplete-event-publications.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAEpD,6FAGoD;AAEpD,oEAAgE;AAChE,wEAAoE;AAGpE;;;;;;;GAOG;AAEI,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;IAGnB;IAFnB,YAEmB,UAAsC;QAAtC,eAAU,GAAV,UAAU,CAA4B;IACtD,CAAC;IAEJ,gEAAgE;IAChE,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;IAC1C,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,KAAK;QACT,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;QAC1D,OAAO,UAAU,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,8BAA8B,CAClC,UAA+B,0CAAmB,CAAC,QAAQ,EAAE;QAE7D,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;QAE1D,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QAC1F,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAEvD,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,IACE,GAAG,CAAC,MAAM,KAAK,sCAAiB,CAAC,MAAM;gBACvC,GAAG,CAAC,MAAM,KAAK,sCAAiB,CAAC,SAAS,EAC1C,CAAC;gBACD,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,sCAAiB,CAAC,WAAW,EAAE;oBACxE,oBAAoB,EAAE,IAAI,IAAI,EAAE;iBACjC,CAAC,CAAC;gBACH,WAAW,EAAE,CAAC;YAChB,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;CACF,CAAA;AA/CY,kEAA2B;sCAA3B,2BAA2B;IADvC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,2DAA4B,CAAC,CAAA;;GAF5B,2BAA2B,CA+CvC"}
+{"version":3,"file":"incomplete-event-publications.js","sourceRoot":"","sources":["../../src/api/incomplete-event-publications.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAEpD,6FAGoD;AAEpD,oEAAgE;AAChE,wEAAoE;AAEpE;;;;;;;GAOG;AAEI,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;IAGnB;IAFnB,YAEmB,UAAsC;QAAtC,eAAU,GAAV,UAAU,CAA4B;IACtD,CAAC;IAEJ,gEAAgE;IAChE,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;IAC1C,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,KAAK;QACT,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;QAC1D,OAAO,UAAU,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,8BAA8B,CAClC,UAA+B,0CAAmB,CAAC,QAAQ,EAAE;QAE7D,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;QAE1D,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QAC1F,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAEvD,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,IAAI,GAAG,CAAC,MAAM,KAAK,sCAAiB,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,sCAAiB,CAAC,SAAS,EAAE,CAAC;gBAC1F,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,sCAAiB,CAAC,WAAW,EAAE;oBACxE,oBAAoB,EAAE,IAAI,IAAI,EAAE;iBACjC,CAAC,CAAC;gBACH,WAAW,EAAE,CAAC;YAChB,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;CACF,CAAA;AA5CY,kEAA2B;sCAA3B,2BAA2B;IADvC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,2DAA4B,CAAC,CAAA;;GAF5B,2BAA2B,CA4CvC"}

package/dist/decorators/outbox-events-handler.decorator.d.ts

@@ -76,7 +76,7 @@ export interface OutboxEventsHandlerMetadata {
  * `Reflect.defineMetadata`. The actual registration happens at
  * application bootstrap via `OutboxListenerScanner`.
  *
- * **Multi-dataSource (Phase 14.3.1).** The scanner walks every
+ * **Multi-dataSource.** The scanner walks every
  * per-dataSource `EventTypeRegistry` and routes the handler to the
  * `OutboxListenerRegistry` whose dataSource owns the decorated
  * events — automatic, no decorator option required. A handler

package/dist/decorators/outbox-events-handler.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"outbox-events-handler.decorator.js","sourceRoot":"","sources":["../../src/decorators/outbox-events-handler.decorator.ts"],"names":[],"mappings":";;;AA+FA,kDAeC;AAmCD,wEAKC;AAtJD,4BAA0B;AAI1B;;;;;;;;;GASG;AACU,QAAA,8BAA8B,GAAG,MAAM,CAAC,gCAAgC,CAAC,CAAC;AAiFvF,SAAgB,mBAAmB,CACjC,GAAG,IAA2C;IAE9C,MAAM,QAAQ,GAAgC,eAAe,CAAC,IAAI,CAAC,CAAC;IAEpE,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,yDAAyD;YACvD,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAAc,EAAQ,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,sCAA8B,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,IAA2C;IAE3C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO;YACL,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;YAC/B,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI;SAC/C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,IAAc;QAC1B,cAAc,EAAE,IAAI;KACrB,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,SAAkB;IACzC,OAAO,CACL,SAAS,KAAK,IAAI;QAClB,OAAO,SAAS,KAAK,QAAQ;QAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACzB,OAAO,SAAS,KAAK,UAAU;QAC/B,QAAQ,IAAI,SAAS,CACtB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,8BAA8B,CAC5C,MAAc;IAEd,MAAM,KAAK,GAAY,OAAO,CAAC,WAAW,CAAC,sCAA8B,EAAE,MAAM,CAAC,CAAC;IACnF,OAAO,KAAgD,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"outbox-events-handler.decorator.js","sourceRoot":"","sources":["../../src/decorators/outbox-events-handler.decorator.ts"],"names":[],"mappings":";;;AA+FA,kDAeC;AAiCD,wEAKC;AApJD,4BAA0B;AAI1B;;;;;;;;;GASG;AACU,QAAA,8BAA8B,GAAG,MAAM,CAAC,gCAAgC,CAAC,CAAC;AAiFvF,SAAgB,mBAAmB,CACjC,GAAG,IAA2C;IAE9C,MAAM,QAAQ,GAAgC,eAAe,CAAC,IAAI,CAAC,CAAC;IAEpE,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,yDAAyD;YACvD,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAAc,EAAQ,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,sCAA8B,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,IAA2C;IAClE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO;YACL,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;YAC/B,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI;SAC/C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,IAAc;QAC1B,cAAc,EAAE,IAAI;KACrB,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,SAAkB;IACzC,OAAO,CACL,SAAS,KAAK,IAAI;QAClB,OAAO,SAAS,KAAK,QAAQ;QAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACzB,OAAO,SAAS,KAAK,UAAU;QAC/B,QAAQ,IAAI,SAAS,CACtB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,8BAA8B,CAC5C,MAAc;IAEd,MAAM,KAAK,GAAY,OAAO,CAAC,WAAW,CAAC,sCAA8B,EAAE,MAAM,CAAC,CAAC;IACnF,OAAO,KAAgD,CAAC;AAC1D,CAAC"}

package/dist/dispatcher/data-source-outbox-publisher.d.ts

@@ -1,7 +1,7 @@
 import type { EventPublicationRegistry } from '../registry/event-publication-registry';
 import type { OutboxListenerRegistry } from '../registry/listener-registry';
 /**
- * Per-dataSource publisher (Phase 14.3). Owns the per-transaction
+ * Per-dataSource publisher. Owns the per-transaction
  * buffer, lifecycle hook registration, and delegate calls into the
  * `EventPublicationRegistry` bound to a single dataSource.
  *
@@ -60,8 +60,7 @@ export declare class DataSourceOutboxPublisher {
      * — `transactionManager.registerBeforeCommit` is NOT used because it
      * always targets "the first active transaction on the context",
      * which is the wrong target when multiple dataSources have live
-     * transactions in the same async stack (Phase 14.2 cross-DS
-     * simultaneous scenario).
+     * transactions in the same async stack.
      */
     scheduleForPublication(event: unknown): void;
     private ensureActiveTransaction;

package/dist/dispatcher/data-source-outbox-publisher.js

@@ -4,7 +4,7 @@ exports.DataSourceOutboxPublisher = void 0;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs-transactional/core");
 /**
- * Per-dataSource publisher (Phase 14.3). Owns the per-transaction
+ * Per-dataSource publisher. Owns the per-transaction
  * buffer, lifecycle hook registration, and delegate calls into the
  * `EventPublicationRegistry` bound to a single dataSource.
  *
@@ -85,8 +85,7 @@ class DataSourceOutboxPublisher {
      * — `transactionManager.registerBeforeCommit` is NOT used because it
      * always targets "the first active transaction on the context",
      * which is the wrong target when multiple dataSources have live
-     * transactions in the same async stack (Phase 14.2 cross-DS
-     * simultaneous scenario).
+     * transactions in the same async stack.
      */
     scheduleForPublication(event) {
         const tx = core_1.TransactionContext.getActiveTransactionByDataSource(this.dataSource);