@nestjs-transactional/outbox-typeorm 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,347 @@
+# @nestjs-transactional/outbox-typeorm
+
+[![npm version](https://img.shields.io/npm/v/%40nestjs-transactional%2Foutbox-typeorm/alpha?style=flat-square&label=npm)](https://www.npmjs.com/package/@nestjs-transactional/outbox-typeorm)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/igorgolovanov/nestjs-transactional/blob/main/LICENSE)
+
+TypeORM persistence backend for
+[`@nestjs-transactional/outbox`](../outbox). Ships the
+`event_publication` table schema, a TypeORM-backed implementation of
+the `EventPublicationRepository` SPI, and (in a later iteration) the
+NestJS module wiring.
+
+## Status
+
+Alpha. Public API may change between 0.x releases. Current shape:
+
+- `EventPublicationEntity` / `EventPublicationArchiveEntity` schema
+  with all four indexes for worker / operator / cleanup paths.
+- `TypeOrmEventPublicationRepository` integrates through the
+  transparent transactional repository patches in
+  [`@nestjs-transactional/typeorm`](../typeorm) — every read and
+  write commits atomically with the business transaction.
+- `OutboxTypeOrmModule.forRoot({ dataSource?, isDefault? })` and
+  `forRootAsync({...})` — DataSource is resolved from DI via
+  `@nestjs/typeorm`'s `getDataSourceToken(name)`, mirroring
+  `TypeOrmTransactionalModule`.
+- `SchemaInitializer` for development-time auto-init plus the
+  shipped TypeORM migration `CreateEventPublication1700000000000`.
+
+Design notes: [`docs/roadmap/README.md`](../../docs/roadmap/README.md),
+[ADR-006](../../docs/adr/006-outbox-pattern.md),
+[ADR-019](../../docs/adr/019-outbox-multi-forroot-pattern.md).
+
+## What ships today
+
+### Entities
+
+- `EventPublicationEntity` (`event_publication`): the hot queue. Four
+  indexes cover the worker, operator, and cleanup paths:
+  - `(status, publicationDate)` — `findReadyForProcessing`,
+    `findStale`.
+  - `(status, listenerId)` — per-listener retries.
+  - `(eventType)` — operator queries and event externalization.
+  - `(completionDate)` — `findCompleted(olderThan)` and
+    `deleteCompleted(olderThan)`.
+  `status` is `varchar(32)` rather than a Postgres `enum`, to keep new
+  lifecycle states from forcing a type migration.
+
+- `EventPublicationArchiveEntity` (`event_publication_archive`): the
+  cold audit trail used by the `ARCHIVE` completion mode. Same fields
+  as `EventPublicationEntity` except `completionDate` is non-nullable
+  — rows only arrive here after having completed.
+
+### Repository
+
+`TypeOrmEventPublicationRepository` implements
+`EventPublicationRepository` from `outbox`. Highlights:
+
+- Every read and write goes through the ambient
+  `EntityManager` resolved by
+  `@nestjs-transactional/typeorm`'s `getCurrentEntityManager`, so
+  publication rows commit atomically with the business data when the
+  caller is inside a `@Transactional()` scope.
+- `tryClaim` issues a single conditional `UPDATE`
+  (`WHERE id = :id AND status IN (PUBLISHED, RESUBMITTED)`) and
+  returns whether the row was actually transitioned — atomic under
+  concurrent workers.
+- `findReadyForProcessing` uses
+  `SELECT ... FOR UPDATE SKIP LOCKED` so multiple workers can poll
+  without fighting for the same rows.
+- `archiveCompleted` copies the row into
+  `event_publication_archive` and then deletes it from the hot queue
+  — atomicity comes from the ambient transaction the processor wraps
+  the listener invocation in.
+
+## Installation (once published)
+
+```bash
+pnpm add @nestjs-transactional/core \
+         @nestjs-transactional/typeorm \
+         @nestjs-transactional/outbox \
+         @nestjs-transactional/outbox-typeorm
+```
+
+Peer dependencies: `@nestjs/common`, `@nestjs/core`, `@nestjs/typeorm`,
+`reflect-metadata`, `rxjs`, `typeorm`.
+
+## Usage
+
+Full wiring for an application that publishes, processes, and
+recovers events against a TypeORM-backed registry:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { TransactionalModule } from '@nestjs-transactional/core';
+import { TypeOrmTransactionalModule } from '@nestjs-transactional/typeorm';
+import {
+  OutboxModule,
+  OutboxProcessingModule,
+} from '@nestjs-transactional/outbox';
+import {
+  EventPublicationEntity,
+  EventPublicationArchiveEntity,
+  OutboxTypeOrmModule,
+  typeOrmEventPublicationRepositoryProvider,
+} from '@nestjs-transactional/outbox-typeorm';
+
+import { OrderPlacedEvent } from './events';
+
+const dataSource = new DataSource({
+  type: 'postgres',
+  // ...
+  entities: [
+    EventPublicationEntity,
+    EventPublicationArchiveEntity,
+    // ...your domain entities
+  ],
+});
+
+@Module({
+  imports: [
+    // 1. Core transaction infrastructure — must be global so
+    //    downstream modules can see TransactionManager.
+    TransactionalModule.forRoot({ isGlobal: true }),
+
+    // 2. TypeORM adapter registration. `forRoot` resolves the
+    //    actual DataSource via @nestjs/typeorm's
+    //    `getDataSourceToken(name)` — so `TypeOrmModule.forRoot(...)`
+    //    must be imported above this. Activates transparent
+    //    transactional Repository dispatch.
+    TypeOrmTransactionalModule.forRoot({ isDefault: true }),
+
+    // 3. Outbox-typeorm registration. `forRoot` resolves the
+    //    DataSource from DI (same pattern as
+    //    TypeOrmTransactionalModule). Registers the
+    //    `TypeOrmEventPublicationRepository` under a private per-DS
+    //    token; the cross-module bridge
+    //    `typeOrmEventPublicationRepositoryProvider()` (passed to
+    //    `OutboxModule.forRoot` below) aliases the official outbox
+    //    token to that private one. The `SchemaInitializer` is
+    //    instantiated per-DS — production should disable it and
+    //    apply the shipped TypeORM migration instead.
+    OutboxTypeOrmModule.forRoot({
+      schemaInitialization: { enabled: process.env.NODE_ENV !== 'production' },
+    }),
+
+    // 4. Outbox-core wiring. Forward the TypeORM repository via the
+    //    aliasing Provider so outbox does NOT install its
+    //    InMemory default.
+    OutboxModule.forRoot({
+      repository: typeOrmEventPublicationRepositoryProvider(),
+      republishOnStartup: true,
+      processor: { pollingInterval: 1000, batchSize: 100 },
+      staleness: { processing: 60_000, monitorInterval: 30_000 },
+    }),
+
+    // 5. Register the event classes the outbox should know about.
+    //    Each feature module would normally call forFeature() for the
+    //    events it owns; this single-module example collapses them.
+    OutboxModule.forFeature([OrderPlacedEvent]),
+
+    // 6. Only in worker processes — starts the processor and
+    //    staleness monitor on bootstrap. API-only apps that just
+    //    publish events should NOT import this.
+    OutboxProcessingModule,
+  ],
+})
+export class AppModule {}
+```
+
+### Why the `repository` forwarding provider
+
+`OutboxModule.forRoot` defaults to
+`InMemoryEventPublicationRepository` for the
+`EVENT_PUBLICATION_REPOSITORY` token when `repository` is omitted.
+Passing `typeOrmEventPublicationRepositoryProvider` replaces that
+default with a `useExisting` alias pointing at the TypeORM
+implementation registered by `OutboxTypeOrmModule.forFeature`. Leaving
+the option out would install two providers for the same token —
+the InMemory one would win and your publications would never reach
+the database.
+
+### 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(orderId: string): Promise<void> {
+    // ...persist business data in the same transaction...
+    await this.outbox.publish(new OrderPlacedEvent(orderId));
+  }
+}
+```
+
+The publication row commits atomically with the business data. If
+the transaction rolls back, the publication row is rolled back too
+— there is no "event published without the business change landing"
+failure mode.
+
+### 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 in a fresh REQUIRES_NEW transaction after the publishing
+    // transaction has committed, retried on exception, resumable
+    // across process restarts.
+  }
+}
+```
+
+## Schema management
+
+Two supported paths, matching Spring Modulith's split between
+reviewed schema changes and the
+`spring.modulith.events.jdbc.schema-initialization.enabled`
+developer shortcut.
+
+### Production: run the TypeORM migration (preferred)
+
+The package ships a ready-to-use migration,
+`CreateEventPublication1700000000000`, that creates both
+`event_publication` and `event_publication_archive` with every
+index. Register it with your DataSource and run it through the
+TypeORM CLI as part of your deploy:
+
+```typescript
+// data-source.ts
+import { DataSource } from 'typeorm';
+import { CreateEventPublication1700000000000 } from '@nestjs-transactional/outbox-typeorm';
+
+export const dataSource = new DataSource({
+  type: 'postgres',
+  // ...
+  migrations: [CreateEventPublication1700000000000, /* ...your own */],
+});
+```
+
+```bash
+pnpm typeorm migration:run -d ./dist/data-source.js
+```
+
+The timestamp `1700000000000` is a placeholder chosen to sort
+before most application-owned migrations. Feel free to copy the
+migration file into your own `migrations/` directory and rename it
+to match your team's timestamp convention — the migration body is
+just a call to `applyEventPublicationSchema(queryRunner)` from this
+package, so keeping a thin wrapper in your own tree is encouraged.
+
+### Development: auto-init at bootstrap
+
+Useful for local development and integration suites that spin a
+fresh database up per run. `SchemaInitializer` is a
+NestJS-lifecycle-aware provider that creates both tables on
+application bootstrap when its `enabled` option is set:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { getDataSourceToken } from '@nestjs/typeorm';
+import {
+  SchemaInitializer,
+  SCHEMA_INITIALIZATION_OPTIONS,
+} from '@nestjs-transactional/outbox-typeorm';
+
+@Module({
+  providers: [
+    {
+      provide: SCHEMA_INITIALIZATION_OPTIONS,
+      useValue: { enabled: process.env.NODE_ENV !== 'production' },
+    },
+    {
+      provide: SchemaInitializer,
+      useFactory: (ds: DataSource, opts) => new SchemaInitializer(ds, opts),
+      inject: [getDataSourceToken(), SCHEMA_INITIALIZATION_OPTIONS],
+    },
+  ],
+})
+export class OutboxSchemaModule {}
+```
+
+The initializer is a no-op when `enabled: false`. When enabled and
+the hot table already exists, it logs a debug line and bails out
+before running any DDL — safe to leave on across restarts. **Do
+not enable in production** — schema changes should always go
+through a reviewed migration.
+
+## Using with `@nestjs-transactional/cqrs`
+
+When the application uses `@nestjs/cqrs` aggregates, bind
+`OutboxEventPublisher` under the cqrs package's
+`OUTBOX_PUBLICATION_SCHEDULER` token AND bind
+`OutboxListenerRegistry` under `OUTBOX_LISTENER_REGISTRAR`.
+`HybridEventPublisher` (wired by `CqrsTransactionalModule.forRoot()`)
+then routes every `aggregate.commit()` through both the in-memory
+phase-aware dispatcher AND the outbox, and
+`IntegrationEventsHandlerScanner` routes
+`@IntegrationEventsHandler` classes through the outbox worker.
+See [`../cqrs/README.md#outbox-integration`](../cqrs/README.md#outbox-integration)
+for the full wiring recipe and the trade-offs between
+`@TransactionalEventsHandler`, `@OutboxEventsHandler`, and
+`@IntegrationEventsHandler`.
+
+## Testing
+
+Integration tests live under `test/integration/` and rely on
+[`testcontainers-node`](https://node.testcontainers.org/) to spin up
+a real Postgres 16 container for every run. Requires Docker to be
+running locally:
+
+```bash
+pnpm --filter @nestjs-transactional/outbox-typeorm test:integration
+```
+
+Unit-test-only runs (`pnpm test`) skip the integration suite per the
+shared Jest base config.
+
+## Worked examples
+
+- [`basic-typeorm-outbox`](../../examples/basic-typeorm-outbox) — single-DS outbox with Postgres, atomicity proven by 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), [`audit-logging`](../../examples/audit-logging) — outbox-driven business saga and asymmetric audit-DS sink.
+- [`e-commerce-orders`](../../examples/e-commerce-orders) — three-DataSource flagship using `OutboxTypeOrmModule.forRoot` per DS.
+
+Full catalogue: [examples/README.md](../../examples/README.md).
+
+## License
+
+MIT

package/dist/entity/event-publication-archive.entity.d.ts

@@ -0,0 +1,24 @@
+import { PublicationStatus } from '@nestjs-transactional/outbox';
+/**
+ * Archive table for event publications that have been completed and
+ * moved out of the hot queue — used by the `ARCHIVE` completion mode.
+ * Rows never change after insertion; this table is intended for audit,
+ * debugging, and compliance review rather than worker-time queries.
+ *
+ * Schema mirrors {@link EventPublicationEntity} except that
+ * `completionDate` is non-nullable — a publication is only archived
+ * after it has completed, so the field is always populated.
+ */
+export declare class EventPublicationArchiveEntity {
+    id: string;
+    listenerId: string;
+    eventType: string;
+    serializedEvent: string;
+    publicationDate: Date;
+    status: PublicationStatus;
+    completionDate: Date;
+    lastResubmissionDate: Date | null;
+    completionAttempts: number;
+    failureReason: string | null;
+}
+//# sourceMappingURL=event-publication-archive.entity.d.ts.map

package/dist/entity/event-publication-archive.entity.js

@@ -0,0 +1,84 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventPublicationArchiveEntity = void 0;
+const outbox_1 = require("@nestjs-transactional/outbox");
+const typeorm_1 = require("typeorm");
+/**
+ * Archive table for event publications that have been completed and
+ * moved out of the hot queue — used by the `ARCHIVE` completion mode.
+ * Rows never change after insertion; this table is intended for audit,
+ * debugging, and compliance review rather than worker-time queries.
+ *
+ * Schema mirrors {@link EventPublicationEntity} except that
+ * `completionDate` is non-nullable — a publication is only archived
+ * after it has completed, so the field is always populated.
+ */
+let EventPublicationArchiveEntity = class EventPublicationArchiveEntity {
+    id;
+    listenerId;
+    eventType;
+    serializedEvent;
+    publicationDate;
+    status;
+    completionDate;
+    lastResubmissionDate;
+    completionAttempts;
+    failureReason;
+};
+exports.EventPublicationArchiveEntity = EventPublicationArchiveEntity;
+__decorate([
+    (0, typeorm_1.PrimaryColumn)('uuid'),
+    __metadata("design:type", String)
+], EventPublicationArchiveEntity.prototype, "id", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'listener_id', length: 512 }),
+    __metadata("design:type", String)
+], EventPublicationArchiveEntity.prototype, "listenerId", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'event_type', length: 256 }),
+    __metadata("design:type", String)
+], EventPublicationArchiveEntity.prototype, "eventType", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'serialized_event', type: 'text' }),
+    __metadata("design:type", String)
+], EventPublicationArchiveEntity.prototype, "serializedEvent", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'publication_date', type: 'timestamptz' }),
+    __metadata("design:type", Date)
+], EventPublicationArchiveEntity.prototype, "publicationDate", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'varchar', length: 32 }),
+    __metadata("design:type", String)
+], EventPublicationArchiveEntity.prototype, "status", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'completion_date', type: 'timestamptz' }),
+    __metadata("design:type", Date)
+], EventPublicationArchiveEntity.prototype, "completionDate", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'last_resubmission_date', type: 'timestamptz', nullable: true }),
+    __metadata("design:type", Object)
+], EventPublicationArchiveEntity.prototype, "lastResubmissionDate", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'completion_attempts', type: 'int' }),
+    __metadata("design:type", Number)
+], EventPublicationArchiveEntity.prototype, "completionAttempts", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'failure_reason', type: 'text', nullable: true }),
+    __metadata("design:type", Object)
+], EventPublicationArchiveEntity.prototype, "failureReason", void 0);
+exports.EventPublicationArchiveEntity = EventPublicationArchiveEntity = __decorate([
+    (0, typeorm_1.Entity)('event_publication_archive'),
+    (0, typeorm_1.Index)(['completionDate']),
+    (0, typeorm_1.Index)(['listenerId']),
+    (0, typeorm_1.Index)(['eventType'])
+], EventPublicationArchiveEntity);
+//# sourceMappingURL=event-publication-archive.entity.js.map

package/dist/entity/event-publication-archive.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-publication-archive.entity.js","sourceRoot":"","sources":["../../src/entity/event-publication-archive.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,yDAAiE;AACjE,qCAA+D;AAE/D;;;;;;;;;GASG;AAKI,IAAM,6BAA6B,GAAnC,MAAM,6BAA6B;IAExC,EAAE,CAAU;IAGZ,UAAU,CAAU;IAGpB,SAAS,CAAU;IAGnB,eAAe,CAAU;IAGzB,eAAe,CAAQ;IAGvB,MAAM,CAAqB;IAG3B,cAAc,CAAQ;IAGtB,oBAAoB,CAAe;IAGnC,kBAAkB,CAAU;IAG5B,aAAa,CAAiB;CAC/B,CAAA;AA9BY,sEAA6B;AAExC;IADC,IAAA,uBAAa,EAAC,MAAM,CAAC;;yDACV;AAGZ;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;iEACzB;AAGpB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;gEACzB;AAGnB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;sEAC1B;AAGzB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;8BACxC,IAAI;sEAAC;AAGvB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;;6DACb;AAG3B;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;8BACxC,IAAI;qEAAC;AAGtB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;2EAC7C;AAGnC;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;;yEACzB;AAG5B;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;oEACnC;wCA7BnB,6BAA6B;IAJzC,IAAA,gBAAM,EAAC,2BAA2B,CAAC;IACnC,IAAA,eAAK,EAAC,CAAC,gBAAgB,CAAC,CAAC;IACzB,IAAA,eAAK,EAAC,CAAC,YAAY,CAAC,CAAC;IACrB,IAAA,eAAK,EAAC,CAAC,WAAW,CAAC,CAAC;GACR,6BAA6B,CA8BzC"}

package/dist/entity/event-publication.entity.d.ts

@@ -0,0 +1,33 @@
+import { PublicationStatus } from '@nestjs-transactional/outbox';
+/**
+ * Hot-queue TypeORM entity backing the Event Publication Registry.
+ *
+ * Schema follows the contract of `EventPublication` from
+ * `@nestjs-transactional/outbox`. Rows move through the lifecycle
+ * `PUBLISHED → PROCESSING → COMPLETED` (or `FAILED → RESUBMITTED → ...`
+ * on retry).
+ *
+ * Indexes:
+ * - `(status, publicationDate)` — primary index for `findReadyForProcessing`
+ *   (worker poll) and `findStale` (staleness monitor).
+ * - `(status, listenerId)` — looking up retries scoped to a single listener.
+ * - `(eventType)` — operator queries and event externalization filters.
+ * - `(completionDate)` — `findCompleted(olderThan)` and
+ *   `deleteCompleted(olderThan)` cleanup.
+ *
+ * `status` is stored as `varchar(32)` rather than a Postgres `enum` type
+ * to avoid schema churn whenever a new lifecycle state is introduced.
+ */
+export declare class EventPublicationEntity {
+    id: string;
+    listenerId: string;
+    eventType: string;
+    serializedEvent: string;
+    publicationDate: Date;
+    status: PublicationStatus;
+    completionDate: Date | null;
+    lastResubmissionDate: Date | null;
+    completionAttempts: number;
+    failureReason: string | null;
+}
+//# sourceMappingURL=event-publication.entity.d.ts.map

package/dist/entity/event-publication.entity.js

@@ -0,0 +1,98 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventPublicationEntity = void 0;
+const outbox_1 = require("@nestjs-transactional/outbox");
+const typeorm_1 = require("typeorm");
+/**
+ * Hot-queue TypeORM entity backing the Event Publication Registry.
+ *
+ * Schema follows the contract of `EventPublication` from
+ * `@nestjs-transactional/outbox`. Rows move through the lifecycle
+ * `PUBLISHED → PROCESSING → COMPLETED` (or `FAILED → RESUBMITTED → ...`
+ * on retry).
+ *
+ * Indexes:
+ * - `(status, publicationDate)` — primary index for `findReadyForProcessing`
+ *   (worker poll) and `findStale` (staleness monitor).
+ * - `(status, listenerId)` — looking up retries scoped to a single listener.
+ * - `(eventType)` — operator queries and event externalization filters.
+ * - `(completionDate)` — `findCompleted(olderThan)` and
+ *   `deleteCompleted(olderThan)` cleanup.
+ *
+ * `status` is stored as `varchar(32)` rather than a Postgres `enum` type
+ * to avoid schema churn whenever a new lifecycle state is introduced.
+ */
+let EventPublicationEntity = class EventPublicationEntity {
+    id;
+    listenerId;
+    eventType;
+    serializedEvent;
+    publicationDate;
+    status;
+    completionDate;
+    lastResubmissionDate;
+    completionAttempts;
+    failureReason;
+};
+exports.EventPublicationEntity = EventPublicationEntity;
+__decorate([
+    (0, typeorm_1.PrimaryColumn)('uuid'),
+    __metadata("design:type", String)
+], EventPublicationEntity.prototype, "id", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'listener_id', length: 512 }),
+    __metadata("design:type", String)
+], EventPublicationEntity.prototype, "listenerId", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'event_type', length: 256 }),
+    __metadata("design:type", String)
+], EventPublicationEntity.prototype, "eventType", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'serialized_event', type: 'text' }),
+    __metadata("design:type", String)
+], EventPublicationEntity.prototype, "serializedEvent", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'publication_date', type: 'timestamptz' }),
+    __metadata("design:type", Date)
+], EventPublicationEntity.prototype, "publicationDate", void 0);
+__decorate([
+    (0, typeorm_1.Column)({
+        type: 'varchar',
+        length: 32,
+        default: outbox_1.PublicationStatus.PUBLISHED,
+    }),
+    __metadata("design:type", String)
+], EventPublicationEntity.prototype, "status", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'completion_date', type: 'timestamptz', nullable: true }),
+    __metadata("design:type", Object)
+], EventPublicationEntity.prototype, "completionDate", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'last_resubmission_date', type: 'timestamptz', nullable: true }),
+    __metadata("design:type", Object)
+], EventPublicationEntity.prototype, "lastResubmissionDate", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'completion_attempts', type: 'int', default: 0 }),
+    __metadata("design:type", Number)
+], EventPublicationEntity.prototype, "completionAttempts", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ name: 'failure_reason', type: 'text', nullable: true }),
+    __metadata("design:type", Object)
+], EventPublicationEntity.prototype, "failureReason", void 0);
+exports.EventPublicationEntity = EventPublicationEntity = __decorate([
+    (0, typeorm_1.Entity)('event_publication'),
+    (0, typeorm_1.Index)(['status', 'publicationDate']),
+    (0, typeorm_1.Index)(['status', 'listenerId']),
+    (0, typeorm_1.Index)(['eventType']),
+    (0, typeorm_1.Index)(['completionDate'])
+], EventPublicationEntity);
+//# sourceMappingURL=event-publication.entity.js.map

package/dist/entity/event-publication.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-publication.entity.js","sourceRoot":"","sources":["../../src/entity/event-publication.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,yDAAiE;AACjE,qCAA+D;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AAMI,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IAEjC,EAAE,CAAU;IAGZ,UAAU,CAAU;IAGpB,SAAS,CAAU;IAGnB,eAAe,CAAU;IAGzB,eAAe,CAAQ;IAOvB,MAAM,CAAqB;IAG3B,cAAc,CAAe;IAG7B,oBAAoB,CAAe;IAGnC,kBAAkB,CAAU;IAG5B,aAAa,CAAiB;CAC/B,CAAA;AAlCY,wDAAsB;AAEjC;IADC,IAAA,uBAAa,EAAC,MAAM,CAAC;;kDACV;AAGZ;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;0DACzB;AAGpB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;yDACzB;AAGnB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;+DAC1B;AAGzB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;8BACxC,IAAI;+DAAC;AAOvB;IALC,IAAA,gBAAM,EAAC;QACN,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,0BAAiB,CAAC,SAAS;KACrC,CAAC;;sDACyB;AAG3B;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;8DAC5C;AAG7B;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;oEAC7C;AAGnC;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;;kEACrC;AAG5B;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;6DACnC;iCAjCnB,sBAAsB;IALlC,IAAA,gBAAM,EAAC,mBAAmB,CAAC;IAC3B,IAAA,eAAK,EAAC,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IACpC,IAAA,eAAK,EAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAC/B,IAAA,eAAK,EAAC,CAAC,WAAW,CAAC,CAAC;IACpB,IAAA,eAAK,EAAC,CAAC,gBAAgB,CAAC,CAAC;GACb,sBAAsB,CAkClC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './entity/event-publication.entity';
+export * from './entity/event-publication-archive.entity';
+export * from './repository/typeorm-event-publication.repository';
+export * from './schema/event-publication-schema';
+export * from './schema/schema-initialization-options';
+export * from './schema/schema-initializer';
+export * from './migrations/1700000000000-create-event-publication';
+export * from './module/outbox-typeorm.module';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./entity/event-publication.entity"), exports);
+__exportStar(require("./entity/event-publication-archive.entity"), exports);
+__exportStar(require("./repository/typeorm-event-publication.repository"), exports);
+__exportStar(require("./schema/event-publication-schema"), exports);
+__exportStar(require("./schema/schema-initialization-options"), exports);
+__exportStar(require("./schema/schema-initializer"), exports);
+__exportStar(require("./migrations/1700000000000-create-event-publication"), exports);
+__exportStar(require("./module/outbox-typeorm.module"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oEAAkD;AAClD,4EAA0D;AAC1D,oFAAkE;AAClE,oEAAkD;AAClD,yEAAuD;AACvD,8DAA4C;AAC5C,sFAAoE;AACpE,iEAA+C"}