@nestjs-transactional/cqrs 1.0.0-alpha.0

package/dist/event-publisher/hybrid-event-publisher.js

@@ -0,0 +1,86 @@
+"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.HybridEventPublisher = exports.OUTBOX_PUBLICATION_SCHEDULER = void 0;
+const common_1 = require("@nestjs/common");
+const event_dispatcher_1 = require("../event-dispatcher/event-dispatcher");
+/**
+ * DI token for the optional outbox scheduler injected into
+ * {@link HybridEventPublisher}. When unbound, the hybrid publisher
+ * delegates only to the in-memory dispatcher.
+ */
+exports.OUTBOX_PUBLICATION_SCHEDULER = Symbol('OUTBOX_PUBLICATION_SCHEDULER');
+/**
+ * `IEventPublisher` implementation that routes aggregate-emitted
+ * events through BOTH the in-memory transactional dispatcher
+ * (`@TransactionalEventsHandler`) AND — when wired — the outbox
+ * (`@OutboxEventsHandler`, introduced in a later phase). Both paths
+ * run inside the surrounding transaction:
+ *
+ * - In-memory: the dispatcher attaches hooks to the current
+ *   transaction so listeners fire at the configured phase
+ *   (`AFTER_COMMIT` by default). No database rows are written.
+ * - Outbox: {@link OutboxPublicationScheduler.scheduleForPublication}
+ *   buffers the event and flushes the buffer via one `beforeCommit`
+ *   hook per transaction. Publication rows commit atomically with
+ *   the business write; rollback skips the flush.
+ *
+ * When no outbox scheduler is bound, behaves identically to
+ * {@link TransactionalEventPublisher}. Callers get outbox semantics
+ * automatically as soon as the scheduler is wired — no code change
+ * at the call site.
+ *
+ * Important: the outbox path is best-effort from the perspective of
+ * `AggregateRoot.commit()`. `commit()` is synchronous, so we cannot
+ * await the DB write here. Errors raised while the `beforeCommit`
+ * hook flushes the buffer DO bubble up — they cause the transaction
+ * to roll back, which is the intended behavior.
+ *
+ * **Multi-dataSource (Phase 14.7).** The outbox scheduler is the
+ * smart-facade `OutboxEventPublisher` (DD-024). When wired,
+ * AggregateRoot events are routed to the per-dataSource publisher
+ * that owns the event class — the same routing semantics as
+ * `OutboxEventPublisher.publish()`. Multi-DS apps with multiple
+ * outbox stacks (one `OutboxModule.forRoot()` per dataSource per
+ * ADR-019) bind `OUTBOX_PUBLICATION_SCHEDULER` to the smart facade
+ * via `useExisting: OutboxEventPublisher`; the facade's internal
+ * Map fans out to the correct per-DS publisher.
+ */
+let HybridEventPublisher = class HybridEventPublisher {
+    dispatcher;
+    outbox;
+    constructor(dispatcher, outbox) {
+        this.dispatcher = dispatcher;
+        this.outbox = outbox;
+    }
+    publish(event) {
+        this.dispatcher.scheduleDispatch(event);
+        if (this.outbox !== undefined) {
+            this.outbox.scheduleForPublication(event);
+        }
+    }
+    publishAll(events) {
+        for (const event of events) {
+            this.publish(event);
+        }
+    }
+};
+exports.HybridEventPublisher = HybridEventPublisher;
+exports.HybridEventPublisher = HybridEventPublisher = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(exports.OUTBOX_PUBLICATION_SCHEDULER)),
+    __metadata("design:paramtypes", [event_dispatcher_1.TransactionalEventDispatcher, Object])
+], HybridEventPublisher);
+//# sourceMappingURL=hybrid-event-publisher.js.map

package/dist/event-publisher/hybrid-event-publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-event-publisher.js","sourceRoot":"","sources":["../../src/event-publisher/hybrid-event-publisher.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAA8D;AAG9D,2EAAoF;AA2BpF;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,MAAM,CAAC,8BAA8B,CAAC,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEI,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IAEZ;IAGA;IAJnB,YACmB,UAAwC,EAGxC,MAAmC;QAHnC,eAAU,GAAV,UAAU,CAA8B;QAGxC,WAAM,GAAN,MAAM,CAA6B;IACnD,CAAC;IAEJ,OAAO,CAAmB,KAAQ;QAChC,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,UAAU,CAAmB,MAAW;QACtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;CACF,CAAA;AApBY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,mBAAU,GAAE;IAIR,WAAA,IAAA,iBAAQ,GAAE,CAAA;IACV,WAAA,IAAA,eAAM,EAAC,oCAA4B,CAAC,CAAA;qCAFR,+CAA4B;GAFhD,oBAAoB,CAoBhC"}

package/dist/event-publisher/transactional-event-publisher-adapter.d.ts

@@ -0,0 +1,32 @@
+import { AggregateRoot, EventBus, EventPublisher, type IEventPublisher } from '@nestjs/cqrs';
+type AggregateConstructor<T extends AggregateRoot> = new (...args: never[]) => T;
+/**
+ * Drop-in replacement for `@nestjs/cqrs`'s `EventPublisher`. Wired
+ * automatically by `CqrsTransactionalModule` via
+ * `{ provide: EventPublisher, useFactory: ... }`.
+ *
+ * Override strategy:
+ * - `mergeObjectContext` / `mergeClassContext` replace `publish` and
+ *   `publishAll` on the aggregate with calls into the injected
+ *   {@link IEventPublisher} strategy —
+ *   {@link HybridEventPublisher} (default, bridges to both the
+ *   in-memory dispatcher and the outbox) or
+ *   {@link TransactionalEventPublisher} (in-memory only, legacy).
+ * - The parent `EventPublisher.eventBus` is still injected (required
+ *   by the base class constructor) but is not used by our override —
+ *   events flow exclusively through the configured strategy.
+ *
+ * Note: consumers calling `eventBus.publish(...)` directly (outside of an
+ * aggregate) still go through the original `@nestjs/cqrs` `EventBus` and
+ * bypass phase-aware dispatching. Only aggregate-emitted events routed
+ * via `mergeObjectContext` / `mergeClassContext` get transactional
+ * semantics.
+ */
+export declare class TransactionalEventPublisherAdapter extends EventPublisher {
+    private readonly strategy;
+    constructor(strategy: IEventPublisher, eventBus: EventBus);
+    mergeClassContext<T extends AggregateConstructor<AggregateRoot>>(metatype: T): T;
+    mergeObjectContext<T extends AggregateRoot>(object: T): T;
+}
+export {};
+//# sourceMappingURL=transactional-event-publisher-adapter.d.ts.map

package/dist/event-publisher/transactional-event-publisher-adapter.js

@@ -0,0 +1,72 @@
+"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.TransactionalEventPublisherAdapter = void 0;
+const common_1 = require("@nestjs/common");
+const cqrs_1 = require("@nestjs/cqrs");
+/**
+ * Drop-in replacement for `@nestjs/cqrs`'s `EventPublisher`. Wired
+ * automatically by `CqrsTransactionalModule` via
+ * `{ provide: EventPublisher, useFactory: ... }`.
+ *
+ * Override strategy:
+ * - `mergeObjectContext` / `mergeClassContext` replace `publish` and
+ *   `publishAll` on the aggregate with calls into the injected
+ *   {@link IEventPublisher} strategy —
+ *   {@link HybridEventPublisher} (default, bridges to both the
+ *   in-memory dispatcher and the outbox) or
+ *   {@link TransactionalEventPublisher} (in-memory only, legacy).
+ * - The parent `EventPublisher.eventBus` is still injected (required
+ *   by the base class constructor) but is not used by our override —
+ *   events flow exclusively through the configured strategy.
+ *
+ * Note: consumers calling `eventBus.publish(...)` directly (outside of an
+ * aggregate) still go through the original `@nestjs/cqrs` `EventBus` and
+ * bypass phase-aware dispatching. Only aggregate-emitted events routed
+ * via `mergeObjectContext` / `mergeClassContext` get transactional
+ * semantics.
+ */
+let TransactionalEventPublisherAdapter = class TransactionalEventPublisherAdapter extends cqrs_1.EventPublisher {
+    strategy;
+    constructor(strategy, eventBus) {
+        super(eventBus);
+        this.strategy = strategy;
+    }
+    mergeClassContext(metatype) {
+        const strategy = this.strategy;
+        class TransactionalMerged extends metatype {
+            publish(event) {
+                strategy.publish(event);
+            }
+            publishAll(events) {
+                strategy.publishAll?.(events);
+            }
+        }
+        return TransactionalMerged;
+    }
+    mergeObjectContext(object) {
+        const strategy = this.strategy;
+        const host = object;
+        host.publish = (event) => {
+            strategy.publish(event);
+        };
+        host.publishAll = (events) => {
+            strategy.publishAll?.(events);
+        };
+        return object;
+    }
+};
+exports.TransactionalEventPublisherAdapter = TransactionalEventPublisherAdapter;
+exports.TransactionalEventPublisherAdapter = TransactionalEventPublisherAdapter = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, cqrs_1.EventBus])
+], TransactionalEventPublisherAdapter);
+//# sourceMappingURL=transactional-event-publisher-adapter.js.map

package/dist/event-publisher/transactional-event-publisher-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional-event-publisher-adapter.js","sourceRoot":"","sources":["../../src/event-publisher/transactional-event-publisher-adapter.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,uCAMsB;AAOtB;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEI,IAAM,kCAAkC,GAAxC,MAAM,kCAAmC,SAAQ,qBAAc;IAEjD;IADnB,YACmB,QAAyB,EAC1C,QAAkB;QAElB,KAAK,CAAC,QAAQ,CAAC,CAAC;QAHC,aAAQ,GAAR,QAAQ,CAAiB;IAI5C,CAAC;IAED,iBAAiB,CAAgD,QAAW;QAC1E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAE/B,MAAM,mBAAoB,SAAS,QAAgD;YACjF,OAAO,CAAwB,KAAa;gBAC1C,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;YACD,UAAU,CAAwB,MAAgB;gBAChD,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;SACF;QAED,OAAO,mBAAmC,CAAC;IAC7C,CAAC;IAED,kBAAkB,CAA0B,MAAS;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,MAAM,IAAI,GAAG,MAGZ,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,CAAC,KAAa,EAAQ,EAAE;YACrC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,CAAC,MAAgB,EAAQ,EAAE;YAC3C,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAA;AArCY,gFAAkC;6CAAlC,kCAAkC;IAD9C,IAAA,mBAAU,GAAE;6CAIC,eAAQ;GAHT,kCAAkC,CAqC9C"}

package/dist/event-publisher/transactional-event-publisher.d.ts

@@ -0,0 +1,33 @@
+import type { IEvent, IEventPublisher } from '@nestjs/cqrs';
+import { TransactionalEventDispatcher } from '../event-dispatcher/event-dispatcher';
+/**
+ * `IEventPublisher` implementation that routes aggregate-emitted events
+ * to {@link TransactionalEventDispatcher} instead of pushing them straight
+ * into the `@nestjs/cqrs` `EventBus`.
+ *
+ * The dispatcher then attaches each event as a hook on the active
+ * transaction — so `AFTER_COMMIT` listeners only fire once the
+ * transaction commits, `AFTER_ROLLBACK` fires on rollback, etc.
+ *
+ * The class itself is the "strategy" half of the pair; it does not
+ * override `@nestjs/cqrs`'s `EventPublisher` by itself. The override is
+ * done by {@link TransactionalEventPublisherAdapter}, which injects this
+ * publisher into the aggregate-root merge path.
+ */
+export declare class TransactionalEventPublisher implements IEventPublisher {
+    private readonly dispatcher;
+    constructor(dispatcher: TransactionalEventDispatcher);
+    /**
+     * Route a single aggregate event through the dispatcher. Intentionally
+     * synchronous: `IEventPublisher.publish` may return anything, and the
+     * dispatcher's own scheduling is sync (hooks attach synchronously;
+     * invocation is deferred to commit/rollback time).
+     */
+    publish<T extends IEvent>(event: T): void;
+    /**
+     * Route a list of aggregate events through the dispatcher, preserving
+     * their order (listeners fire in the order the aggregate emitted them).
+     */
+    publishAll<T extends IEvent>(events: T[]): void;
+}
+//# sourceMappingURL=transactional-event-publisher.d.ts.map

package/dist/event-publisher/transactional-event-publisher.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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalEventPublisher = void 0;
+const common_1 = require("@nestjs/common");
+const event_dispatcher_1 = require("../event-dispatcher/event-dispatcher");
+/**
+ * `IEventPublisher` implementation that routes aggregate-emitted events
+ * to {@link TransactionalEventDispatcher} instead of pushing them straight
+ * into the `@nestjs/cqrs` `EventBus`.
+ *
+ * The dispatcher then attaches each event as a hook on the active
+ * transaction — so `AFTER_COMMIT` listeners only fire once the
+ * transaction commits, `AFTER_ROLLBACK` fires on rollback, etc.
+ *
+ * The class itself is the "strategy" half of the pair; it does not
+ * override `@nestjs/cqrs`'s `EventPublisher` by itself. The override is
+ * done by {@link TransactionalEventPublisherAdapter}, which injects this
+ * publisher into the aggregate-root merge path.
+ */
+let TransactionalEventPublisher = class TransactionalEventPublisher {
+    dispatcher;
+    constructor(dispatcher) {
+        this.dispatcher = dispatcher;
+    }
+    /**
+     * Route a single aggregate event through the dispatcher. Intentionally
+     * synchronous: `IEventPublisher.publish` may return anything, and the
+     * dispatcher's own scheduling is sync (hooks attach synchronously;
+     * invocation is deferred to commit/rollback time).
+     */
+    publish(event) {
+        this.dispatcher.scheduleDispatch(event);
+    }
+    /**
+     * Route a list of aggregate events through the dispatcher, preserving
+     * their order (listeners fire in the order the aggregate emitted them).
+     */
+    publishAll(events) {
+        for (const event of events) {
+            this.publish(event);
+        }
+    }
+};
+exports.TransactionalEventPublisher = TransactionalEventPublisher;
+exports.TransactionalEventPublisher = TransactionalEventPublisher = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [event_dispatcher_1.TransactionalEventDispatcher])
+], TransactionalEventPublisher);
+//# sourceMappingURL=transactional-event-publisher.js.map

package/dist/event-publisher/transactional-event-publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional-event-publisher.js","sourceRoot":"","sources":["../../src/event-publisher/transactional-event-publisher.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAG5C,2EAAoF;AAEpF;;;;;;;;;;;;;GAaG;AAEI,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;IACT;IAA7B,YAA6B,UAAwC;QAAxC,eAAU,GAAV,UAAU,CAA8B;IAAG,CAAC;IAEzE;;;;;OAKG;IACH,OAAO,CAAmB,KAAQ;QAChC,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,UAAU,CAAmB,MAAW;QACtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;CACF,CAAA;AAtBY,kEAA2B;sCAA3B,2BAA2B;IADvC,IAAA,mBAAU,GAAE;qCAE8B,+CAA4B;GAD1D,2BAA2B,CAsBvC"}

package/dist/handlers/bootstrap.d.ts

@@ -0,0 +1,18 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { CqrsHandlerWrapper } from './handler-wrapper';
+/**
+ * Fires `CqrsHandlerWrapper.wrapAll` at application bootstrap, after all
+ * `onModuleInit` hooks (including `@nestjs/cqrs`'s explorer) have
+ * completed. `@nestjs/cqrs`'s bus bindings resolve `instance.execute` at
+ * call time, so a late wrap still takes effect for every subsequent
+ * dispatch.
+ *
+ * Registered by `CqrsTransactionalModule` (added in a later iteration).
+ * Not intended for direct consumer instantiation.
+ */
+export declare class CqrsTransactionalBootstrap implements OnApplicationBootstrap {
+    private readonly wrapper;
+    constructor(wrapper: CqrsHandlerWrapper);
+    onApplicationBootstrap(): void;
+}
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/handlers/bootstrap.js

@@ -0,0 +1,39 @@
+"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.CqrsTransactionalBootstrap = void 0;
+const common_1 = require("@nestjs/common");
+const handler_wrapper_1 = require("./handler-wrapper");
+/**
+ * Fires `CqrsHandlerWrapper.wrapAll` at application bootstrap, after all
+ * `onModuleInit` hooks (including `@nestjs/cqrs`'s explorer) have
+ * completed. `@nestjs/cqrs`'s bus bindings resolve `instance.execute` at
+ * call time, so a late wrap still takes effect for every subsequent
+ * dispatch.
+ *
+ * Registered by `CqrsTransactionalModule` (added in a later iteration).
+ * Not intended for direct consumer instantiation.
+ */
+let CqrsTransactionalBootstrap = class CqrsTransactionalBootstrap {
+    wrapper;
+    constructor(wrapper) {
+        this.wrapper = wrapper;
+    }
+    onApplicationBootstrap() {
+        this.wrapper.wrapAll();
+    }
+};
+exports.CqrsTransactionalBootstrap = CqrsTransactionalBootstrap;
+exports.CqrsTransactionalBootstrap = CqrsTransactionalBootstrap = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [handler_wrapper_1.CqrsHandlerWrapper])
+], CqrsTransactionalBootstrap);
+//# sourceMappingURL=bootstrap.js.map

package/dist/handlers/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/handlers/bootstrap.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAyE;AAEzE,uDAAuD;AAEvD;;;;;;;;;GASG;AAEI,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IACR;IAA7B,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAE5D,sBAAsB;QACpB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;CACF,CAAA;AANY,gEAA0B;qCAA1B,0BAA0B;IADtC,IAAA,mBAAU,GAAE;qCAE2B,oCAAkB;GAD7C,0BAA0B,CAMtC"}

package/dist/handlers/handler-wrapper.d.ts

@@ -0,0 +1,77 @@
+import 'reflect-metadata';
+import { DiscoveryService } from '@nestjs/core';
+import { TransactionManager, type TransactionalMetadata } from '@nestjs-transactional/core';
+/**
+ * DI injection token for {@link HandlerWrapperOptions}. The wrapper reads
+ * options via this token so `CqrsTransactionalModule` can provide them
+ * synchronously or asynchronously.
+ */
+export declare const CQRS_HANDLER_WRAPPER_OPTIONS: unique symbol;
+/**
+ * Options that control which CQRS handler kinds are wrapped and how the
+ * transaction is configured when the handler has no explicit
+ * `@Transactional()` metadata.
+ */
+export interface HandlerWrapperOptions {
+    /** Wrap `@CommandHandler`-decorated classes. Default: `true`. */
+    readonly wrapCommandHandlers?: boolean;
+    /** Wrap `@QueryHandler`-decorated classes. Default: `true`. */
+    readonly wrapQueryHandlers?: boolean;
+    /** Wrap `@EventsHandler`-decorated classes. Default: `true`. */
+    readonly wrapEventHandlers?: boolean;
+    /**
+     * Fallback metadata applied to query handlers that carry no
+     * `@Transactional` annotation. Typically `{ readOnly: true }`. When
+     * omitted, undecorated query handlers are left unwrapped (no
+     * transaction).
+     */
+    readonly defaultQueryOptions?: Partial<TransactionalMetadata>;
+    /**
+     * Fallback metadata applied to command handlers that carry no
+     * `@Transactional` annotation. When omitted, undecorated command
+     * handlers are left unwrapped.
+     */
+    readonly defaultCommandOptions?: Partial<TransactionalMetadata>;
+}
+/**
+ * Wraps the `execute` (or `handle`) method of every `@CommandHandler` /
+ * `@QueryHandler` / `@EventsHandler` instance with a transaction, using
+ * the handler's own `@Transactional` metadata where present or the
+ * kind-specific defaults from {@link HandlerWrapperOptions} otherwise.
+ *
+ * The replacement is an own-property assignment on each handler instance,
+ * shadowing the prototype method. `@nestjs/cqrs`'s buses resolve
+ * `instance.execute` / `instance.handle` at call time (late binding), so
+ * the wrap takes effect for every subsequent bus dispatch.
+ *
+ * Double-wrap prevention: each wrapped method is tagged with the shared
+ * `WRAPPED_MARKER` symbol. Other mechanisms in the coordinated wrapping
+ * triad (see ADR-005) honour the same marker.
+ *
+ * Limitation: only works with static-dependency-tree (singleton) handlers.
+ * Request-scoped handlers are resolved per-request by `@nestjs/cqrs`'s
+ * `ModuleRef.resolve`, which produces a fresh instance our wrap has not
+ * mutated.
+ */
+export declare class CqrsHandlerWrapper {
+    private readonly discovery;
+    private readonly manager;
+    private readonly options;
+    private readonly logger;
+    constructor(discovery: DiscoveryService, manager: TransactionManager, options: HandlerWrapperOptions);
+    /**
+     * Scan every provider and wrap handler methods. Safe to call multiple
+     * times — the `WRAPPED_MARKER` check guarantees idempotency.
+     */
+    wrapAll(): void;
+    private classifyHandler;
+    private wrapHandler;
+    /**
+     * Priority order: method-level `@Transactional` > class-level
+     * `@Transactional` > kind-specific defaults. Returns `undefined` when
+     * nothing applies — the handler is then left unwrapped.
+     */
+    private resolveMetadata;
+    private pickDefaults;
+}
+//# sourceMappingURL=handler-wrapper.d.ts.map

package/dist/handlers/handler-wrapper.js

@@ -0,0 +1,183 @@
+"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); }
+};
+var CqrsHandlerWrapper_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CqrsHandlerWrapper = exports.CQRS_HANDLER_WRAPPER_OPTIONS = void 0;
+require("reflect-metadata");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const core_2 = require("@nestjs-transactional/core");
+/**
+ * Metadata keys written by `@nestjs/cqrs`'s `@CommandHandler` /
+ * `@QueryHandler` / `@EventsHandler` decorators onto the handler class
+ * constructor. The package does NOT re-export these from its public
+ * barrel — we mirror them here because we read them at wrap time to
+ * identify CQRS handlers.
+ *
+ * Values must match the strings in
+ * `node_modules/@nestjs/cqrs/dist/decorators/constants.js`. Coupling to
+ * `@nestjs/cqrs` internals is explicitly accepted per DD-002
+ * (`docs/dd/002-no-fork-nestjs-cqrs.md`) — we prefer wrapping
+ * to forking.
+ */
+const COMMAND_HANDLER_METADATA = '__commandHandler__';
+const QUERY_HANDLER_METADATA = '__queryHandler__';
+const EVENTS_HANDLER_METADATA = '__eventsHandler__';
+/**
+ * Process-global identity for the "already wrapped" marker, matching
+ * `WRAPPED_MARKER` in the core package. `Symbol.for` resolves to the same
+ * symbol across any copy of the package tree, so a method wrapped by
+ * `TransactionalMethodsBootstrap` (core) will still be recognized by us
+ * and vice versa. Core does not re-export this symbol from its public
+ * barrel; its JSDoc documents re-derivation via `Symbol.for` as supported.
+ */
+const WRAPPED_MARKER = Symbol.for('@nestjs-transactional/wrapped');
+/**
+ * DI injection token for {@link HandlerWrapperOptions}. The wrapper reads
+ * options via this token so `CqrsTransactionalModule` can provide them
+ * synchronously or asynchronously.
+ */
+exports.CQRS_HANDLER_WRAPPER_OPTIONS = Symbol('CQRS_HANDLER_WRAPPER_OPTIONS');
+/**
+ * Wraps the `execute` (or `handle`) method of every `@CommandHandler` /
+ * `@QueryHandler` / `@EventsHandler` instance with a transaction, using
+ * the handler's own `@Transactional` metadata where present or the
+ * kind-specific defaults from {@link HandlerWrapperOptions} otherwise.
+ *
+ * The replacement is an own-property assignment on each handler instance,
+ * shadowing the prototype method. `@nestjs/cqrs`'s buses resolve
+ * `instance.execute` / `instance.handle` at call time (late binding), so
+ * the wrap takes effect for every subsequent bus dispatch.
+ *
+ * Double-wrap prevention: each wrapped method is tagged with the shared
+ * `WRAPPED_MARKER` symbol. Other mechanisms in the coordinated wrapping
+ * triad (see ADR-005) honour the same marker.
+ *
+ * Limitation: only works with static-dependency-tree (singleton) handlers.
+ * Request-scoped handlers are resolved per-request by `@nestjs/cqrs`'s
+ * `ModuleRef.resolve`, which produces a fresh instance our wrap has not
+ * mutated.
+ */
+let CqrsHandlerWrapper = CqrsHandlerWrapper_1 = class CqrsHandlerWrapper {
+    discovery;
+    manager;
+    options;
+    logger = new common_1.Logger(CqrsHandlerWrapper_1.name);
+    constructor(discovery, manager, options) {
+        this.discovery = discovery;
+        this.manager = manager;
+        this.options = options;
+    }
+    /**
+     * Scan every provider and wrap handler methods. Safe to call multiple
+     * times — the `WRAPPED_MARKER` check guarantees idempotency.
+     */
+    wrapAll() {
+        const providers = this.discovery.getProviders();
+        let wrappedCount = 0;
+        for (const wrapper of providers) {
+            if (wrapper.instance === null || wrapper.instance === undefined) {
+                continue;
+            }
+            if (typeof wrapper.metatype !== 'function') {
+                // Value / factory providers have no class constructor — nothing to
+                // classify as a CQRS handler.
+                continue;
+            }
+            const instance = wrapper.instance;
+            const metatype = wrapper.metatype;
+            const kind = this.classifyHandler(metatype);
+            if (kind === null) {
+                continue;
+            }
+            const methodName = kind === 'event' ? 'handle' : 'execute';
+            if (this.wrapHandler(instance, metatype, methodName, kind)) {
+                wrappedCount++;
+            }
+        }
+        this.logger.log(`Wrapped ${wrappedCount} CQRS handler${wrappedCount === 1 ? '' : 's'} with @Transactional`);
+    }
+    classifyHandler(metatype) {
+        if (this.options.wrapCommandHandlers !== false &&
+            Reflect.hasMetadata(COMMAND_HANDLER_METADATA, metatype)) {
+            return 'command';
+        }
+        if (this.options.wrapQueryHandlers !== false &&
+            Reflect.hasMetadata(QUERY_HANDLER_METADATA, metatype)) {
+            return 'query';
+        }
+        if (this.options.wrapEventHandlers !== false &&
+            Reflect.hasMetadata(EVENTS_HANDLER_METADATA, metatype)) {
+            return 'event';
+        }
+        return null;
+    }
+    wrapHandler(instance, metatype, methodName, kind) {
+        const host = instance;
+        const currentMethod = host[methodName];
+        if (typeof currentMethod !== 'function') {
+            return false;
+        }
+        if (Reflect.getMetadata(WRAPPED_MARKER, currentMethod) === true) {
+            return false;
+        }
+        const resolved = this.resolveMetadata(currentMethod, metatype, kind);
+        if (resolved === undefined) {
+            return false;
+        }
+        const boundOriginal = currentMethod.bind(instance);
+        const manager = this.manager;
+        const wrapped = (...args) => manager.run(resolved, () => Promise.resolve(boundOriginal(...args)));
+        Reflect.defineMetadata(WRAPPED_MARKER, true, wrapped);
+        Reflect.defineMetadata(core_2.TRANSACTIONAL_METADATA, resolved, wrapped);
+        host[methodName] = wrapped;
+        this.logger.debug(`Wrapped ${kind} handler ${instance.constructor.name}.${methodName} ` +
+            `(propagation=${resolved.propagation ?? core_2.PropagationMode.REQUIRED})`);
+        return true;
+    }
+    /**
+     * Priority order: method-level `@Transactional` > class-level
+     * `@Transactional` > kind-specific defaults. Returns `undefined` when
+     * nothing applies — the handler is then left unwrapped.
+     */
+    resolveMetadata(method, metatype, kind) {
+        const explicit = (0, core_2.getTransactionalMetadata)(method) ?? (0, core_2.getTransactionalMetadata)(metatype);
+        if (explicit !== undefined) {
+            return explicit;
+        }
+        const defaults = this.pickDefaults(kind);
+        if (defaults === undefined) {
+            return undefined;
+        }
+        return { propagation: core_2.PropagationMode.REQUIRED, ...defaults };
+    }
+    pickDefaults(kind) {
+        switch (kind) {
+            case 'query':
+                return this.options.defaultQueryOptions;
+            case 'command':
+                return this.options.defaultCommandOptions;
+            case 'event':
+                return undefined;
+        }
+    }
+};
+exports.CqrsHandlerWrapper = CqrsHandlerWrapper;
+exports.CqrsHandlerWrapper = CqrsHandlerWrapper = CqrsHandlerWrapper_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(2, (0, common_1.Inject)(exports.CQRS_HANDLER_WRAPPER_OPTIONS)),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_2.TransactionManager, Object])
+], CqrsHandlerWrapper);
+//# sourceMappingURL=handler-wrapper.js.map

package/dist/handlers/handler-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-wrapper.js","sourceRoot":"","sources":["../../src/handlers/handler-wrapper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4BAA0B;AAE1B,2CAA4D;AAC5D,uCAAgD;AAChD,qDAMoC;AAEpC;;;;;;;;;;;;GAYG;AACH,MAAM,wBAAwB,GAAG,oBAAoB,CAAC;AACtD,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAClD,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,cAAc,GAAW,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAE3E;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,MAAM,CAAC,8BAA8B,CAAC,CAAC;AAqCnF;;;;;;;;;;;;;;;;;;;GAmBG;AAEI,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAIV;IACA;IAEA;IANF,MAAM,GAAG,IAAI,eAAM,CAAC,oBAAkB,CAAC,IAAI,CAAC,CAAC;IAE9D,YACmB,SAA2B,EAC3B,OAA2B,EAE3B,OAA8B;QAH9B,cAAS,GAAT,SAAS,CAAkB;QAC3B,YAAO,GAAP,OAAO,CAAoB;QAE3B,YAAO,GAAP,OAAO,CAAuB;IAC9C,CAAC;IAEJ;;;OAGG;IACH,OAAO;QACL,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;QAChD,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;YAChC,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAChE,SAAS;YACX,CAAC;YACD,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBAC3C,mEAAmE;gBACnE,8BAA8B;gBAC9B,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAkB,CAAC;YAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAkB,CAAC;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,SAAS;YACX,CAAC;YAED,MAAM,UAAU,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3D,IAAI,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC3D,YAAY,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CACb,WAAW,YAAY,gBAAgB,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAC3F,CAAC;IACJ,CAAC;IAEO,eAAe,CAAC,QAAgB;QACtC,IACE,IAAI,CAAC,OAAO,CAAC,mBAAmB,KAAK,KAAK;YAC1C,OAAO,CAAC,WAAW,CAAC,wBAAwB,EAAE,QAAQ,CAAC,EACvD,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IACE,IAAI,CAAC,OAAO,CAAC,iBAAiB,KAAK,KAAK;YACxC,OAAO,CAAC,WAAW,CAAC,sBAAsB,EAAE,QAAQ,CAAC,EACrD,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IACE,IAAI,CAAC,OAAO,CAAC,iBAAiB,KAAK,KAAK;YACxC,OAAO,CAAC,WAAW,CAAC,uBAAuB,EAAE,QAAQ,CAAC,EACtD,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,WAAW,CACjB,QAAgB,EAChB,QAAgB,EAChB,UAAkB,EAClB,IAAiB;QAEjB,MAAM,IAAI,GAAG,QAAmC,CAAC;QACjD,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,OAAO,aAAa,KAAK,UAAU,EAAE,CAAC;YACxC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,OAAO,CAAC,WAAW,CAAC,cAAc,EAAE,aAAa,CAAC,KAAK,IAAI,EAAE,CAAC;YAChE,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,aAAa,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QACrE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,aAAa,GAAI,aAA+B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAE7B,MAAM,OAAO,GAAG,CAAC,GAAG,IAAe,EAAoB,EAAE,CACvD,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEvE,OAAO,CAAC,cAAc,CAAC,cAAc,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,CAAC,cAAc,CAAC,6BAAsB,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAElE,IAAI,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,WAAW,IAAI,YAAY,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,UAAU,GAAG;YACnE,gBAAgB,QAAQ,CAAC,WAAW,IAAI,sBAAe,CAAC,QAAQ,GAAG,CACtE,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACK,eAAe,CACrB,MAAc,EACd,QAAgB,EAChB,IAAiB;QAEjB,MAAM,QAAQ,GAAG,IAAA,+BAAwB,EAAC,MAAM,CAAC,IAAI,IAAA,+BAAwB,EAAC,QAAQ,CAAC,CAAC;QACxF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,EAAE,WAAW,EAAE,sBAAe,CAAC,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAAC;IAChE,CAAC;IAEO,YAAY,CAAC,IAAiB;QACpC,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,OAAO;gBACV,OAAO,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC;YAC1C,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC;YAC5C,KAAK,OAAO;gBACV,OAAO,SAAS,CAAC;QACrB,CAAC;IACH,CAAC;CACF,CAAA;AA3IY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,mBAAU,GAAE;IAOR,WAAA,IAAA,eAAM,EAAC,oCAA4B,CAAC,CAAA;qCAFT,uBAAgB;QAClB,yBAAkB;GALnC,kBAAkB,CA2I9B"}