@nestjs-transactional/outbox 1.0.0-alpha.0

package/dist/types/completion-mode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Behavior when a publication is successfully completed.
+ *
+ * - `UPDATE`: set `completion_date` on the record (default). Keeps the
+ *   row for inspection of completed publications; requires manual
+ *   purging eventually.
+ * - `DELETE`: delete the record. No audit of completed publications.
+ * - `ARCHIVE`: move the record to an archive table, keeping it for
+ *   inspection without weighing down the hot queue.
+ */
+export declare enum CompletionMode {
+    UPDATE = "UPDATE",
+    DELETE = "DELETE",
+    ARCHIVE = "ARCHIVE"
+}
+//# sourceMappingURL=completion-mode.d.ts.map

package/dist/types/completion-mode.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompletionMode = void 0;
+/**
+ * Behavior when a publication is successfully completed.
+ *
+ * - `UPDATE`: set `completion_date` on the record (default). Keeps the
+ *   row for inspection of completed publications; requires manual
+ *   purging eventually.
+ * - `DELETE`: delete the record. No audit of completed publications.
+ * - `ARCHIVE`: move the record to an archive table, keeping it for
+ *   inspection without weighing down the hot queue.
+ */
+var CompletionMode;
+(function (CompletionMode) {
+    CompletionMode["UPDATE"] = "UPDATE";
+    CompletionMode["DELETE"] = "DELETE";
+    CompletionMode["ARCHIVE"] = "ARCHIVE";
+})(CompletionMode || (exports.CompletionMode = CompletionMode = {}));
+//# sourceMappingURL=completion-mode.js.map

package/dist/types/completion-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-mode.js","sourceRoot":"","sources":["../../src/types/completion-mode.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,mCAAiB,CAAA;IACjB,qCAAmB,CAAA;AACrB,CAAC,EAJW,cAAc,8BAAd,cAAc,QAIzB"}

package/dist/types/errors.d.ts

@@ -0,0 +1,50 @@
+import { TransactionError } from '@nestjs-transactional/core';
+import type { PublicationStatus } from './publication-status';
+/**
+ * Base class for errors raised by `@nestjs-transactional/outbox`.
+ * Subclass for any specific failure mode so that callers can match on
+ * `code` without relying on string parsing.
+ */
+export declare class OutboxError extends TransactionError {
+    readonly code: string;
+}
+/**
+ * Raised when a lookup by publication ID finds no matching record.
+ */
+export declare class PublicationNotFoundError extends OutboxError {
+    readonly code = "PUBLICATION_NOT_FOUND";
+    constructor(id: string);
+}
+/**
+ * Raised when the registry is asked to move a publication to a state
+ * that is not reachable from its current one — e.g. `COMPLETED` →
+ * `PROCESSING`.
+ */
+export declare class InvalidPublicationTransitionError extends OutboxError {
+    readonly code = "INVALID_PUBLICATION_TRANSITION";
+    constructor(from: PublicationStatus, to: PublicationStatus);
+}
+/**
+ * Raised when the serializer cannot encode an event payload — typically
+ * because the payload contains non-plain values (functions, cycles, ...).
+ */
+export declare class SerializationError extends OutboxError {
+    readonly code = "SERIALIZATION_ERROR";
+}
+/**
+ * Raised when the serializer cannot decode a stored event payload —
+ * typically because the schema has drifted or the type is unregistered.
+ */
+export declare class DeserializationError extends OutboxError {
+    readonly code = "DESERIALIZATION_ERROR";
+}
+/**
+ * Raised when two listeners are registered with the same id. Listener
+ * ids must be globally unique because they are stored on each
+ * `EventPublication` row and drive retry / resume resolution.
+ */
+export declare class DuplicateListenerIdError extends OutboxError {
+    readonly code = "DUPLICATE_LISTENER_ID";
+    constructor(id: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuplicateListenerIdError = exports.DeserializationError = exports.SerializationError = exports.InvalidPublicationTransitionError = exports.PublicationNotFoundError = exports.OutboxError = void 0;
+const core_1 = require("@nestjs-transactional/core");
+/**
+ * Base class for errors raised by `@nestjs-transactional/outbox`.
+ * Subclass for any specific failure mode so that callers can match on
+ * `code` without relying on string parsing.
+ */
+class OutboxError extends core_1.TransactionError {
+    code = 'OUTBOX_ERROR';
+}
+exports.OutboxError = OutboxError;
+/**
+ * Raised when a lookup by publication ID finds no matching record.
+ */
+class PublicationNotFoundError extends OutboxError {
+    code = 'PUBLICATION_NOT_FOUND';
+    constructor(id) {
+        super(`Publication not found: ${id}`);
+    }
+}
+exports.PublicationNotFoundError = PublicationNotFoundError;
+/**
+ * Raised when the registry is asked to move a publication to a state
+ * that is not reachable from its current one — e.g. `COMPLETED` →
+ * `PROCESSING`.
+ */
+class InvalidPublicationTransitionError extends OutboxError {
+    code = 'INVALID_PUBLICATION_TRANSITION';
+    constructor(from, to) {
+        super(`Invalid publication state transition: ${from} → ${to}`);
+    }
+}
+exports.InvalidPublicationTransitionError = InvalidPublicationTransitionError;
+/**
+ * Raised when the serializer cannot encode an event payload — typically
+ * because the payload contains non-plain values (functions, cycles, ...).
+ */
+class SerializationError extends OutboxError {
+    code = 'SERIALIZATION_ERROR';
+}
+exports.SerializationError = SerializationError;
+/**
+ * Raised when the serializer cannot decode a stored event payload —
+ * typically because the schema has drifted or the type is unregistered.
+ */
+class DeserializationError extends OutboxError {
+    code = 'DESERIALIZATION_ERROR';
+}
+exports.DeserializationError = DeserializationError;
+/**
+ * Raised when two listeners are registered with the same id. Listener
+ * ids must be globally unique because they are stored on each
+ * `EventPublication` row and drive retry / resume resolution.
+ */
+class DuplicateListenerIdError extends OutboxError {
+    code = 'DUPLICATE_LISTENER_ID';
+    constructor(id) {
+        super(`Listener with id '${id}' is already registered`);
+    }
+}
+exports.DuplicateListenerIdError = DuplicateListenerIdError;
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":";;;AAAA,qDAA8D;AAI9D;;;;GAIG;AACH,MAAa,WAAY,SAAQ,uBAAgB;IACtC,IAAI,GAAW,cAAc,CAAC;CACxC;AAFD,kCAEC;AAED;;GAEG;AACH,MAAa,wBAAyB,SAAQ,WAAW;IAC9C,IAAI,GAAG,uBAAuB,CAAC;IAExC,YAAY,EAAU;QACpB,KAAK,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC;CACF;AAND,4DAMC;AAED;;;;GAIG;AACH,MAAa,iCAAkC,SAAQ,WAAW;IACvD,IAAI,GAAG,gCAAgC,CAAC;IAEjD,YAAY,IAAuB,EAAE,EAAqB;QACxD,KAAK,CAAC,yCAAyC,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;IACjE,CAAC;CACF;AAND,8EAMC;AAED;;;GAGG;AACH,MAAa,kBAAmB,SAAQ,WAAW;IACxC,IAAI,GAAG,qBAAqB,CAAC;CACvC;AAFD,gDAEC;AAED;;;GAGG;AACH,MAAa,oBAAqB,SAAQ,WAAW;IAC1C,IAAI,GAAG,uBAAuB,CAAC;CACzC;AAFD,oDAEC;AAED;;;;GAIG;AACH,MAAa,wBAAyB,SAAQ,WAAW;IAC9C,IAAI,GAAG,uBAAuB,CAAC;IAExC,YAAY,EAAU;QACpB,KAAK,CAAC,qBAAqB,EAAE,yBAAyB,CAAC,CAAC;IAC1D,CAAC;CACF;AAND,4DAMC"}

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

@@ -0,0 +1,47 @@
+import type { PublicationStatus } from './publication-status';
+/**
+ * Persistent record of an event that was published and needs to be
+ * delivered to a listener.
+ *
+ * Inspired by Spring Modulith's `EventPublication`.
+ */
+export interface EventPublication {
+    /** Opaque identifier (UUID). */
+    readonly id: string;
+    /**
+     * Qualified listener name, e.g. `"InventoryManagement.on(OrderCompletedEvent)"`.
+     * Used as a stable identity for retry / resume — see ADR-009 (planned).
+     */
+    readonly listenerId: string;
+    /** The event's class name (discriminator for deserialization). */
+    readonly eventType: string;
+    /** JSON-serialized event payload. */
+    readonly serializedEvent: string;
+    /** Wall-clock time at which the publication was created. */
+    readonly publicationDate: Date;
+    /** Current lifecycle state. */
+    readonly status: PublicationStatus;
+    /** When the publication reached {@link PublicationStatus.COMPLETED}. */
+    readonly completionDate: Date | null;
+    /** When the publication was last moved to {@link PublicationStatus.RESUBMITTED}. */
+    readonly lastResubmissionDate: Date | null;
+    /** Starts at 0, incremented each time a listener picks up the publication. */
+    readonly completionAttempts: number;
+    /** Error message from the most recent failure, if any. */
+    readonly failureReason: string | null;
+}
+/**
+ * Input accepted by the registry for creating a new publication.
+ *
+ * The registry fills in `id`, `status` (`PUBLISHED`), `completionDate`
+ * (`null`), `lastResubmissionDate` (`null`), `completionAttempts` (`0`),
+ * and `failureReason` (`null`). If `publicationDate` is omitted, the
+ * registry defaults it to "now".
+ */
+export interface NewEventPublication {
+    readonly listenerId: string;
+    readonly eventType: string;
+    readonly serializedEvent: string;
+    readonly publicationDate?: Date;
+}
+//# sourceMappingURL=event-publication.d.ts.map

package/dist/types/event-publication.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=event-publication.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-publication.js","sourceRoot":"","sources":["../../src/types/event-publication.ts"],"names":[],"mappings":""}

package/dist/types/publication-status.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Lifecycle state of an {@link EventPublication}.
+ *
+ * Inspired by Spring Modulith's Event Publication Registry.
+ *
+ * State transitions (normal flow):
+ *
+ *   PUBLISHED → PROCESSING → COMPLETED
+ *
+ * State transitions (failure flow):
+ *
+ *   PUBLISHED → PROCESSING → FAILED → RESUBMITTED → PROCESSING → COMPLETED
+ */
+export declare enum PublicationStatus {
+    /** Created, waiting to be picked up by a listener. */
+    PUBLISHED = "PUBLISHED",
+    /** A listener has picked it up and is currently executing. */
+    PROCESSING = "PROCESSING",
+    /** Listener finished successfully. */
+    COMPLETED = "COMPLETED",
+    /** Listener threw an exception. */
+    FAILED = "FAILED",
+    /** Previously FAILED, now queued for retry. */
+    RESUBMITTED = "RESUBMITTED"
+}
+//# sourceMappingURL=publication-status.d.ts.map

package/dist/types/publication-status.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicationStatus = void 0;
+/**
+ * Lifecycle state of an {@link EventPublication}.
+ *
+ * Inspired by Spring Modulith's Event Publication Registry.
+ *
+ * State transitions (normal flow):
+ *
+ *   PUBLISHED → PROCESSING → COMPLETED
+ *
+ * State transitions (failure flow):
+ *
+ *   PUBLISHED → PROCESSING → FAILED → RESUBMITTED → PROCESSING → COMPLETED
+ */
+var PublicationStatus;
+(function (PublicationStatus) {
+    /** Created, waiting to be picked up by a listener. */
+    PublicationStatus["PUBLISHED"] = "PUBLISHED";
+    /** A listener has picked it up and is currently executing. */
+    PublicationStatus["PROCESSING"] = "PROCESSING";
+    /** Listener finished successfully. */
+    PublicationStatus["COMPLETED"] = "COMPLETED";
+    /** Listener threw an exception. */
+    PublicationStatus["FAILED"] = "FAILED";
+    /** Previously FAILED, now queued for retry. */
+    PublicationStatus["RESUBMITTED"] = "RESUBMITTED";
+})(PublicationStatus || (exports.PublicationStatus = PublicationStatus = {}));
+//# sourceMappingURL=publication-status.js.map

package/dist/types/publication-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publication-status.js","sourceRoot":"","sources":["../../src/types/publication-status.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,IAAY,iBAWX;AAXD,WAAY,iBAAiB;IAC3B,sDAAsD;IACtD,4CAAuB,CAAA;IACvB,8DAA8D;IAC9D,8CAAyB,CAAA;IACzB,sCAAsC;IACtC,4CAAuB,CAAA;IACvB,mCAAmC;IACnC,sCAAiB,CAAA;IACjB,+CAA+C;IAC/C,gDAA2B,CAAA;AAC7B,CAAC,EAXW,iBAAiB,iCAAjB,iBAAiB,QAW5B"}

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

@@ -0,0 +1,37 @@
+import type { EventPublication } from './event-publication';
+/**
+ * Predicate that decides whether a given publication should be included
+ * in a resubmission batch.
+ */
+export type ResubmissionFilter = (publication: EventPublication) => boolean;
+/**
+ * Builder-style configuration for a resubmission pass.
+ *
+ * @example
+ * ```ts
+ * ResubmissionOptions.defaults()
+ *   .withBatchSize(50)
+ *   .withMaxInFlight(5)
+ *   .withMinAge(10_000)
+ *   .withMaxAttempts(3);
+ * ```
+ */
+export declare class ResubmissionOptions {
+    private _batchSize;
+    private _maxInFlight;
+    private _minAge;
+    private _maxCompletionAttempts;
+    private _filter;
+    static defaults(): ResubmissionOptions;
+    withBatchSize(size: number): this;
+    withMaxInFlight(n: number): this;
+    withMinAge(ms: number): this;
+    withMaxAttempts(n: number): this;
+    withFilter(filter: ResubmissionFilter): this;
+    get batchSize(): number;
+    get maxInFlight(): number;
+    get minAge(): number;
+    get maxCompletionAttempts(): number | null;
+    get filter(): ResubmissionFilter | null;
+}
+//# sourceMappingURL=resubmission-options.d.ts.map

package/dist/types/resubmission-options.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResubmissionOptions = void 0;
+/**
+ * Builder-style configuration for a resubmission pass.
+ *
+ * @example
+ * ```ts
+ * ResubmissionOptions.defaults()
+ *   .withBatchSize(50)
+ *   .withMaxInFlight(5)
+ *   .withMinAge(10_000)
+ *   .withMaxAttempts(3);
+ * ```
+ */
+class ResubmissionOptions {
+    _batchSize = 100;
+    _maxInFlight = 10;
+    _minAge = 0;
+    _maxCompletionAttempts = null;
+    _filter = null;
+    static defaults() {
+        return new ResubmissionOptions();
+    }
+    withBatchSize(size) {
+        this._batchSize = size;
+        return this;
+    }
+    withMaxInFlight(n) {
+        this._maxInFlight = n;
+        return this;
+    }
+    withMinAge(ms) {
+        this._minAge = ms;
+        return this;
+    }
+    withMaxAttempts(n) {
+        this._maxCompletionAttempts = n;
+        return this;
+    }
+    withFilter(filter) {
+        this._filter = filter;
+        return this;
+    }
+    get batchSize() {
+        return this._batchSize;
+    }
+    get maxInFlight() {
+        return this._maxInFlight;
+    }
+    get minAge() {
+        return this._minAge;
+    }
+    get maxCompletionAttempts() {
+        return this._maxCompletionAttempts;
+    }
+    get filter() {
+        return this._filter;
+    }
+}
+exports.ResubmissionOptions = ResubmissionOptions;
+//# sourceMappingURL=resubmission-options.js.map

package/dist/types/resubmission-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resubmission-options.js","sourceRoot":"","sources":["../../src/types/resubmission-options.ts"],"names":[],"mappings":";;;AAQA;;;;;;;;;;;GAWG;AACH,MAAa,mBAAmB;IACtB,UAAU,GAAG,GAAG,CAAC;IACjB,YAAY,GAAG,EAAE,CAAC;IAClB,OAAO,GAAG,CAAC,CAAC;IACZ,sBAAsB,GAAkB,IAAI,CAAC;IAC7C,OAAO,GAA8B,IAAI,CAAC;IAElD,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,mBAAmB,EAAE,CAAC;IACnC,CAAC;IAED,aAAa,CAAC,IAAY;QACxB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,eAAe,CAAC,CAAS;QACvB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,eAAe,CAAC,CAAS;QACvB,IAAI,CAAC,sBAAsB,GAAG,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,MAA0B;QACnC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,IAAI,qBAAqB;QACvB,OAAO,IAAI,CAAC,sBAAsB,CAAC;IACrC,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF;AAvDD,kDAuDC"}

package/dist/types/staleness-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Configuration for detecting stale publications that should be marked
+ * as {@link PublicationStatus.FAILED}.
+ *
+ * Any value of `0` disables that specific staleness check.
+ */
+export interface StalenessConfig {
+    /** Max duration (ms) in `PUBLISHED` state before marking as `FAILED`. */
+    readonly published: number;
+    /** Max duration (ms) in `PROCESSING` state before marking as `FAILED`. */
+    readonly processing: number;
+    /** Max duration (ms) in `RESUBMITTED` state before marking as `FAILED`. */
+    readonly resubmitted: number;
+    /** How often (ms) the staleness monitor runs. Defaults to 60000 (1 minute). */
+    readonly monitorInterval: number;
+}
+export declare const DEFAULT_STALENESS_CONFIG: StalenessConfig;
+//# sourceMappingURL=staleness-config.d.ts.map

package/dist/types/staleness-config.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STALENESS_CONFIG = void 0;
+exports.DEFAULT_STALENESS_CONFIG = {
+    published: 0,
+    processing: 0,
+    resubmitted: 0,
+    monitorInterval: 60_000,
+};
+//# sourceMappingURL=staleness-config.js.map

package/dist/types/staleness-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness-config.js","sourceRoot":"","sources":["../../src/types/staleness-config.ts"],"names":[],"mappings":";;;AAiBa,QAAA,wBAAwB,GAAoB;IACvD,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,CAAC;IACd,eAAe,EAAE,MAAM;CACxB,CAAC"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@nestjs-transactional/outbox",
+  "version": "1.0.0-alpha.0",
+  "description": "Persistent Event Publication Registry for @nestjs-transactional — Spring Modulith equivalent (ORM-agnostic core)",
+  "license": "MIT",
+  "author": "Igor Golovanov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/igorgolovanov/nestjs-transactional.git",
+    "directory": "packages/outbox"
+  },
+  "bugs": {
+    "url": "https://github.com/igorgolovanov/nestjs-transactional/issues"
+  },
+  "homepage": "https://github.com/igorgolovanov/nestjs-transactional/tree/main/packages/outbox#readme",
+  "keywords": [
+    "nestjs",
+    "outbox",
+    "event-publication-registry",
+    "spring-modulith",
+    "transactional-outbox",
+    "transaction"
+  ],
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.js.map",
+    "!dist/**/*.spec.*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.0.0",
+    "@nestjs-transactional/core": "^1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.5.4",
+    "@nestjs-transactional/core": "1.0.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rimraf dist *.tsbuildinfo coverage",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\""
+  }
+}