@nestjs-transactional/outbox 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,396 @@
+# @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)
+[![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.
+
+## Overview
+
+`@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.
+
+`outbox` closes that gap. It gives you:
+
+- 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
+
+```bash
+pnpm add @nestjs-transactional/core @nestjs-transactional/outbox
+# plus a persistence backend, e.g.:
+pnpm add @nestjs-transactional/outbox-typeorm
+```
+
+Peer dependencies: `@nestjs/common`, `@nestjs/core`, `reflect-metadata`,
+`rxjs`.
+
+## Usage
+
+### 1. Module wiring
+
+`OutboxModule.forRoot()` provides global infrastructure (registry,
+serializer, processor, recovery). `OutboxModule.forFeature([...])`
+declares the event classes a feature module owns — matches
+`TypeOrmModule.forFeature(...)` ergonomics.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TransactionalModule } from '@nestjs-transactional/core';
+import { OutboxModule, OutboxProcessingModule } from '@nestjs-transactional/outbox';
+
+@Module({
+  imports: [
+    // isGlobal: true is REQUIRED so outbox providers can see
+    // TransactionManager across module boundaries.
+    TransactionalModule.forRoot({
+      isGlobal: true,
+      adapters: [/* your adapter registrations */],
+    }),
+    OutboxModule.forRoot({
+      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 {}
+
+@Module({
+  imports: [
+    TransactionalModule.forRoot({ isGlobal: true /* ... */ }),
+    OutboxModule.forRoot({ republishOnStartup: true /* ... */ }),
+    OrderModule,
+    InventoryModule,
+  ],
+})
+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:
+
+```
+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';
+
+@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.
+  }
+}
+```
+
+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
+
+```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));
+  }
+}
+```
+
+### 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}
+```
+
+- **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,
+  ) {}
+}
+```
+
+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:
+
+```typescript
+import { EVENT_EXTERNALIZER, type EventExternalizer } from '@nestjs-transactional/outbox';
+
+@Module({
+  providers: [
+    {
+      provide: EVENT_EXTERNALIZER,
+      useClass: MyCustomExternalizer, // implements EventExternalizer
+    },
+  ],
+})
+export class MyAppModule {}
+```
+
+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';
+
+@Injectable()
+export class MyDiagnostics {
+  constructor(private readonly externalization: ExternalizationRegistry) {}
+
+  isExternalized(typeName: string): boolean {
+    return this.externalization.has(typeName);
+  }
+}
+```
+
+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 utilities
+
+Exported via the `/testing` subpath for assertions about which events
+the code under test published. Mirrors Spring Modulith's
+`PublishedEvents` / `AssertablePublishedEvents`.
+
+```typescript
+import {
+  PublishedEvents,
+  AssertablePublishedEvents,
+} 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);
+  });
+});
+```
+
+`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).
+
+## License
+
+MIT

package/dist/api/completed-event-publications.d.ts

@@ -0,0 +1,31 @@
+import { type EventPublicationRepository } from '../repository/event-publication-repository';
+import type { EventPublication } from '../types/event-publication';
+/**
+ * Operator-facing query + purge API for publications that have
+ * reached the terminal `COMPLETED` state. Equivalent to Spring
+ * Modulith's `CompletedEventPublications`.
+ *
+ * Relevant when the completion mode is `UPDATE` (the default) — the
+ * row is kept for audit and needs to be purged eventually.
+ */
+export declare class CompletedEventPublications {
+    private readonly repository;
+    constructor(repository: EventPublicationRepository);
+    /**
+     * Return completed publications, optionally filtered by
+     * `completionDate` and capped by `limit`.
+     */
+    findAll(options?: {
+        readonly olderThan?: Date;
+        readonly limit?: number;
+    }): Promise<EventPublication[]>;
+    /** How many publications are currently in `COMPLETED`. */
+    count(): Promise<number>;
+    /**
+     * Delete completed publications. When `olderThan` is provided, only
+     * publications whose `completionDate` is strictly before it are
+     * removed. Returns the number of rows deleted.
+     */
+    purge(olderThan?: Date): Promise<number>;
+}
+//# sourceMappingURL=completed-event-publications.d.ts.map

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

@@ -0,0 +1,58 @@
+"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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompletedEventPublications = void 0;
+const common_1 = require("@nestjs/common");
+const event_publication_repository_1 = require("../repository/event-publication-repository");
+/**
+ * Operator-facing query + purge API for publications that have
+ * reached the terminal `COMPLETED` state. Equivalent to Spring
+ * Modulith's `CompletedEventPublications`.
+ *
+ * Relevant when the completion mode is `UPDATE` (the default) — the
+ * row is kept for audit and needs to be purged eventually.
+ */
+let CompletedEventPublications = class CompletedEventPublications {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /**
+     * Return completed publications, optionally filtered by
+     * `completionDate` and capped by `limit`.
+     */
+    async findAll(options) {
+        return this.repository.findCompleted(options);
+    }
+    /** How many publications are currently in `COMPLETED`. */
+    async count() {
+        const completed = await this.repository.findCompleted();
+        return completed.length;
+    }
+    /**
+     * Delete completed publications. When `olderThan` is provided, only
+     * publications whose `completionDate` is strictly before it are
+     * removed. Returns the number of rows deleted.
+     */
+    async purge(olderThan) {
+        return this.repository.deleteCompleted(olderThan);
+    }
+};
+exports.CompletedEventPublications = CompletedEventPublications;
+exports.CompletedEventPublications = CompletedEventPublications = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(event_publication_repository_1.EVENT_PUBLICATION_REPOSITORY)),
+    __metadata("design:paramtypes", [Object])
+], CompletedEventPublications);
+//# sourceMappingURL=completed-event-publications.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"completed-event-publications.js","sourceRoot":"","sources":["../../src/api/completed-event-publications.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAEpD,6FAGoD;AAGpD;;;;;;;GAOG;AAEI,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IAGlB;IAFnB,YAEmB,UAAsC;QAAtC,eAAU,GAAV,UAAU,CAA4B;IACtD,CAAC;IAEJ;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,OAGb;QACC,OAAO,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,KAAK;QACT,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;QACxD,OAAO,SAAS,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAgB;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF,CAAA;AA/BY,gEAA0B;qCAA1B,0BAA0B;IADtC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,2DAA4B,CAAC,CAAA;;GAF5B,0BAA0B,CA+BtC"}

package/dist/api/failed-event-publications.d.ts

@@ -0,0 +1,36 @@
+import { type EventPublicationRepository } from '../repository/event-publication-repository';
+import type { EventPublication } from '../types/event-publication';
+import { ResubmissionOptions } from '../types/resubmission-options';
+/**
+ * Operator-facing query + resubmit API for publications currently in
+ * the `FAILED` state. Equivalent to Spring Modulith's
+ * `FailedEventPublications`.
+ */
+export declare class FailedEventPublications {
+    private readonly repository;
+    constructor(repository: EventPublicationRepository);
+    /**
+     * Return every failed publication matching the optional filters
+     * (minimum age in ms since `publicationDate`, cap on
+     * `completionAttempts`).
+     */
+    findAll(options?: {
+        readonly minAge?: number;
+        readonly maxAttempts?: number;
+    }): Promise<EventPublication[]>;
+    /** How many publications are currently in `FAILED`. */
+    count(): Promise<number>;
+    /**
+     * Transition selected failed publications to `RESUBMITTED` so the
+     * processor will pick them up again. Returns the number of rows
+     * transitioned.
+     *
+     * Selection order:
+     * 1. Pull failed publications matching the `minAge` /
+     *    `maxCompletionAttempts` filters.
+     * 2. Apply the user-supplied `filter` predicate, if any.
+     * 3. Keep at most `batchSize` publications.
+     */
+    resubmit(options?: ResubmissionOptions): Promise<number>;
+}
+//# sourceMappingURL=failed-event-publications.d.ts.map

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

@@ -0,0 +1,75 @@
+"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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FailedEventPublications = void 0;
+const common_1 = require("@nestjs/common");
+const event_publication_repository_1 = require("../repository/event-publication-repository");
+const publication_status_1 = require("../types/publication-status");
+const resubmission_options_1 = require("../types/resubmission-options");
+/**
+ * Operator-facing query + resubmit API for publications currently in
+ * the `FAILED` state. Equivalent to Spring Modulith's
+ * `FailedEventPublications`.
+ */
+let FailedEventPublications = class FailedEventPublications {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /**
+     * Return every failed publication matching the optional filters
+     * (minimum age in ms since `publicationDate`, cap on
+     * `completionAttempts`).
+     */
+    async findAll(options) {
+        return this.repository.findFailed(options);
+    }
+    /** How many publications are currently in `FAILED`. */
+    async count() {
+        const failed = await this.repository.findFailed();
+        return failed.length;
+    }
+    /**
+     * Transition selected failed publications to `RESUBMITTED` so the
+     * processor will pick them up again. Returns the number of rows
+     * transitioned.
+     *
+     * Selection order:
+     * 1. Pull failed publications matching the `minAge` /
+     *    `maxCompletionAttempts` filters.
+     * 2. Apply the user-supplied `filter` predicate, if any.
+     * 3. Keep at most `batchSize` publications.
+     */
+    async resubmit(options = resubmission_options_1.ResubmissionOptions.defaults()) {
+        const failed = await this.repository.findFailed({
+            minAge: options.minAge,
+            maxAttempts: options.maxCompletionAttempts ?? undefined,
+        });
+        const filtered = options.filter !== null ? failed.filter(options.filter) : failed;
+        const toProcess = filtered.slice(0, options.batchSize);
+        for (const pub of toProcess) {
+            await this.repository.updateStatus(pub.id, publication_status_1.PublicationStatus.RESUBMITTED, {
+                lastResubmissionDate: new Date(),
+            });
+        }
+        return toProcess.length;
+    }
+};
+exports.FailedEventPublications = FailedEventPublications;
+exports.FailedEventPublications = FailedEventPublications = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(event_publication_repository_1.EVENT_PUBLICATION_REPOSITORY)),
+    __metadata("design:paramtypes", [Object])
+], FailedEventPublications);
+//# sourceMappingURL=failed-event-publications.js.map

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

@@ -0,0 +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"}

package/dist/api/incomplete-event-publications.d.ts

@@ -0,0 +1,28 @@
+import { type EventPublicationRepository } from '../repository/event-publication-repository';
+import type { EventPublication } from '../types/event-publication';
+import { ResubmissionOptions } from '../types/resubmission-options';
+/**
+ * Operator-facing query + resubmit API for every publication that has
+ * not yet reached the terminal `COMPLETED` state. Equivalent to Spring
+ * Modulith's `IncompleteEventPublications`.
+ *
+ * Typical use case: startup / restart recovery — query the backlog,
+ * bulk-resubmit retriable rows, let the processor drain.
+ */
+export declare class IncompleteEventPublications {
+    private readonly repository;
+    constructor(repository: EventPublicationRepository);
+    /** Return every publication whose status is not `COMPLETED`. */
+    findAll(): Promise<EventPublication[]>;
+    /** How many publications are currently not `COMPLETED`. */
+    count(): Promise<number>;
+    /**
+     * Scan every non-completed publication and transition retriable
+     * ones (`FAILED`, `PUBLISHED`) to `RESUBMITTED`. Publications
+     * currently `PROCESSING` or `RESUBMITTED` are left untouched —
+     * `PROCESSING` is owned by a worker and `RESUBMITTED` is already in
+     * the retry queue. Returns the number of rows transitioned.
+     */
+    resubmitIncompletePublications(options?: ResubmissionOptions): Promise<number>;
+}
+//# sourceMappingURL=incomplete-event-publications.d.ts.map