@nestjs/cqrs 12.0.0 → 12.1.0

package/.circleci/config.yml

@@ -17,7 +17,7 @@ jobs:
   build:
     working_directory: ~/nest
     docker:
-      - image: cimg/node:24.19.0
+      - image: cimg/node:24.21.0
     steps:
       - checkout
       - restore_cache:
@@ -35,7 +35,7 @@ jobs:
   e2e_test:
     working_directory: ~/nest
     docker:
-      - image: cimg/node:24.19.0
+      - image: cimg/node:24.21.0
     steps:
       - checkout
       - *restore-cache
@@ -46,7 +46,7 @@ jobs:
   test:
     working_directory: ~/nest
     docker:
-      - image: cimg/node:24.19.0
+      - image: cimg/node:24.21.0
     steps:
       - checkout
       - *restore-cache

package/dist/event-bus.js

@@ -122,7 +122,7 @@ let EventBus = EventBus_1 = class EventBus extends ObservableBus {
             }
             const unhandledError = this.mapToUnhandledErrorInfo(event, error);
             this.unhandledExceptionBus.publish(unhandledError);
-            this._logger.error(`"${handler.constructor.name}" has thrown an unhandled exception.`, error);
+            this._logger.error(`"${handler.instance?.constructor.name ?? handler.name}" has thrown an unhandled exception.`, error);
             return of();
         }))));
         this.eventOperators.push(eventOperator);

package/dist/event-publisher.d.ts

@@ -13,6 +13,7 @@ export declare class EventPublisher<EventBase extends IEvent = IEvent> {
     /**
      * Merge the event publisher into the provided class.
      * This is required to make `publish` and `publishAll` available on the `AggregateRoot` class.
+     * The aggregate is the dispatcher context, unless `commit()`, `publish()` or `publishAll()` is given one.
      * @param metatype The class to merge into.
      * @param asyncContext The async context (if scoped).
      */
@@ -20,6 +21,7 @@ export declare class EventPublisher<EventBase extends IEvent = IEvent> {
     /**
      * Merge the event publisher into the provided object.
      * This is required to make `publish` and `publishAll` available on the `IAggregateRoot` class instance.
+     * The aggregate is the dispatcher context, unless `commit()`, `publish()` or `publishAll()` is given one.
      * @param object The object to merge into.
      * @param asyncContext The async context (if scoped).
      */

package/dist/event-publisher.js

@@ -19,33 +19,35 @@ let EventPublisher = class EventPublisher {
     /**
      * Merge the event publisher into the provided class.
      * This is required to make `publish` and `publishAll` available on the `AggregateRoot` class.
+     * The aggregate is the dispatcher context, unless `commit()`, `publish()` or `publishAll()` is given one.
      * @param metatype The class to merge into.
      * @param asyncContext The async context (if scoped).
      */
     mergeClassContext(metatype, asyncContext) {
         const eventBus = this.eventBus;
         return class extends metatype {
-            publish(event) {
-                eventBus.publish(event, this, asyncContext);
+            publish(event, dispatcherContext) {
+                return eventBus.publish(event, dispatcherContext === undefined ? this : dispatcherContext, asyncContext);
             }
-            publishAll(events) {
-                eventBus.publishAll(events, this, asyncContext);
+            publishAll(events, dispatcherContext) {
+                return eventBus.publishAll(events, dispatcherContext === undefined ? this : dispatcherContext, asyncContext);
             }
         };
     }
     /**
      * Merge the event publisher into the provided object.
      * This is required to make `publish` and `publishAll` available on the `IAggregateRoot` class instance.
+     * The aggregate is the dispatcher context, unless `commit()`, `publish()` or `publishAll()` is given one.
      * @param object The object to merge into.
      * @param asyncContext The async context (if scoped).
      */
     mergeObjectContext(object, asyncContext) {
         const eventBus = this.eventBus;
-        object.publish = (event) => {
-            eventBus.publish(event, object, asyncContext);
+        object.publish = (event, dispatcherContext) => {
+            return eventBus.publish(event, dispatcherContext === undefined ? object : dispatcherContext, asyncContext);
         };
-        object.publishAll = (events) => {
-            eventBus.publishAll(events, object, asyncContext);
+        object.publishAll = (events, dispatcherContext) => {
+            return eventBus.publishAll(events, dispatcherContext === undefined ? object : dispatcherContext, asyncContext);
         };
         return object;
     }

package/dist/interfaces/aggregate-root.interface.d.ts

@@ -10,17 +10,27 @@ export interface IAggregateRoot<EventBase extends IEvent = IEvent> {
     /**
      * Publishes a single event.
      * @param event The event to publish.
+     * @param dispatcherContext Dispatcher context passed to the event publisher, such as
+     * `{ transaction }`. Defaults to the aggregate (merged with `EventPublisher`) or none (`@Publishable()`).
+     * @returns What the event bus returns (the event publisher's result).
      */
-    publish<T extends EventBase = EventBase>(event: T): void;
+    publish<T extends EventBase = EventBase>(event: T, dispatcherContext?: unknown): any;
     /**
      * Publishes multiple events.
      * @param events The events to publish.
+     * @param dispatcherContext Dispatcher context passed to the event publisher, such as
+     * `{ transaction }`. Defaults to the aggregate (merged with `EventPublisher`) or none (`@Publishable()`).
+     * @returns What the event bus returns (the event publisher's result).
      */
-    publishAll<T extends EventBase = EventBase>(events: T[]): void;
+    publishAll<T extends EventBase = EventBase>(events: T[], dispatcherContext?: unknown): any;
     /**
      * Commits all uncommitted events.
+     * The events are cleared once they are handed to the event bus, before an asynchronous publisher settles.
+     * @param dispatcherContext Dispatcher context passed to the event publisher, such as
+     * `{ transaction }`. Defaults to the aggregate (merged with `EventPublisher`) or none (`@Publishable()`).
+     * @returns What `publishAll()` returns: await it to wait for (and catch the errors of) an asynchronous publisher.
      */
-    commit(): void;
+    commit(dispatcherContext?: unknown): any;
     /**
      * Uncommits all events.
      */

package/dist/mixins/with-aggregate-root.mixin.js

@@ -22,11 +22,19 @@ export function WithAggregateRoot(Base) {
         get autoCommit() {
             return this[IS_AUTO_COMMIT_ENABLED];
         }
-        publish(event) { }
-        publishAll(events) { }
-        commit() {
-            this.publishAll(this[INTERNAL_EVENTS]);
-            this[INTERNAL_EVENTS].length = 0;
+        publish(event, dispatcherContext) { }
+        publishAll(events, dispatcherContext) { }
+        commit(dispatcherContext) {
+            const events = this[INTERNAL_EVENTS];
+            // With a dispatcher context, the caller awaits the publisher, which may read
+            // the events after it returns: hand it a copy, as the events are cleared below.
+            const result = dispatcherContext === undefined
+                ? this.publishAll(events)
+                : this.publishAll([...events], dispatcherContext);
+            // Cleared once the publisher has been called, not once it settles (as before):
+            // a caller that doesn't await must not publish the same events twice.
+            events.length = 0;
+            return result;
         }
         uncommit() {
             this[INTERNAL_EVENTS].length = 0;

package/dist/storages/aggregate-root.storage.js

@@ -4,11 +4,15 @@ export class AggregateRootStorage {
     }
     static mergeContext(eventBus) {
         for (const item of this.storage) {
-            item.prototype.publish = function (event) {
-                eventBus.publish(event);
+            item.prototype.publish = function (event, dispatcherContext) {
+                return dispatcherContext === undefined
+                    ? eventBus.publish(event)
+                    : eventBus.publish(event, dispatcherContext);
             };
-            item.prototype.publishAll = function (events) {
-                eventBus.publishAll(events);
+            item.prototype.publishAll = function (events, dispatcherContext) {
+                return dispatcherContext === undefined
+                    ? eventBus.publishAll(events)
+                    : eventBus.publishAll(events, dispatcherContext);
             };
         }
         this.storage = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/cqrs",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "A lightweight CQRS module for Nest framework (node.js)",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,21 +34,21 @@
     "test:e2e": "vitest run --config vitest.config.e2e.ts"
   },
   "devDependencies": {
-    "@commitlint/cli": "21.2.2",
-    "@commitlint/config-angular": "21.2.2",
-    "@nestjs/common": "12.0.1",
-    "@nestjs/core": "12.0.1",
-    "@nestjs/testing": "12.0.1",
-    "@types/node": "24.13.3",
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-angular": "21.2.3",
+    "@nestjs/common": "12.1.1",
+    "@nestjs/core": "12.1.1",
+    "@nestjs/testing": "12.1.1",
+    "@types/node": "24.19.0",
     "husky": "9.1.7",
-    "lint-staged": "17.3.0",
-    "oxlint": "1.80.0",
-    "prettier": "3.9.6",
+    "lint-staged": "17.6.0",
+    "oxlint": "1.86.0",
+    "prettier": "3.9.9",
     "reflect-metadata": "0.2.2",
-    "release-it": "21.0.2",
+    "release-it": "21.1.0",
     "rxjs": "7.8.2",
     "typescript": "7.0.2",
-    "vite": "8.2.2",
+    "vite": "8.3.1",
     "vitest": "4.1.11"
   },
   "peerDependencies": {

package/test/e2e/aggregate-commit-context.spec.ts

@@ -0,0 +1,243 @@
+import { Inject, Injectable, Module, Scope } from '@nestjs/common';
+import { REQUEST } from '@nestjs/core';
+import { Test, TestingModule } from '@nestjs/testing';
+import { setImmediate } from 'timers/promises';
+import {
+  AggregateRoot,
+  AsyncContext,
+  CommandBus,
+  CommandHandler,
+  CqrsModule,
+  EventBus,
+  EventPublisher,
+  EventsHandler,
+  ICommandHandler,
+  IEvent,
+  IEventHandler,
+  IEventPublisher,
+  Publishable,
+} from '../../src/index.js';
+import { waitImmediate } from '../utils/wait-immediate.js';
+
+interface Transaction {
+  id: string;
+  fail?: Error;
+}
+
+class OrderPlacedEvent implements IEvent {
+  constructor(public readonly orderId: string) {}
+}
+
+class Order extends AggregateRoot {
+  constructor(public readonly id: string) {
+    super();
+  }
+
+  place() {
+    this.apply(new OrderPlacedEvent(this.id));
+  }
+}
+
+@Publishable()
+class PublishableOrder extends Order {}
+
+class PlaceOrderCommand {
+  constructor(
+    public readonly orderId: string,
+    public readonly transaction?: Transaction,
+    public readonly publishable = false,
+  ) {}
+}
+
+class ScopedPlaceOrderCommand {
+  constructor(
+    public readonly orderId: string,
+    public readonly transaction: Transaction,
+  ) {}
+}
+
+/**
+ * Stands in for a publisher that writes events through the dispatcher context's transaction
+ * (an outbox, or durable workflows) before it hands them to the in-memory handlers.
+ */
+@Injectable()
+class TransactionalEventPublisher implements IEventPublisher {
+  readonly written: Array<{
+    orderIds: string[];
+    context: unknown;
+    asyncContext?: AsyncContext;
+  }> = [];
+  private readonly inner: IEventPublisher;
+
+  constructor(eventBus: EventBus) {
+    this.inner = eventBus.publisher;
+    eventBus.publisher = this;
+  }
+
+  publish(event: IEvent, context?: unknown, asyncContext?: AsyncContext) {
+    return this.publishAll([event], context, asyncContext);
+  }
+
+  async publishAll(
+    events: IEvent[],
+    context?: unknown,
+    asyncContext?: AsyncContext,
+  ) {
+    await setImmediate();
+    const transaction = (context as { transaction?: Transaction } | undefined)
+      ?.transaction;
+    if (transaction?.fail) {
+      throw transaction.fail;
+    }
+    this.written.push({
+      orderIds: events.map((event) => (event as OrderPlacedEvent).orderId),
+      context,
+      asyncContext,
+    });
+    events.forEach((event) => this.inner.publish(event, context, asyncContext));
+    return `written in ${transaction?.id ?? 'no transaction'}`;
+  }
+}
+
+@CommandHandler(PlaceOrderCommand)
+class PlaceOrderHandler implements ICommandHandler<PlaceOrderCommand> {
+  constructor(private readonly publisher: EventPublisher) {}
+
+  async execute({ orderId, transaction, publishable }: PlaceOrderCommand) {
+    const order = publishable
+      ? new PublishableOrder(orderId)
+      : this.publisher.mergeObjectContext(new Order(orderId));
+    order.place();
+    return transaction ? order.commit({ transaction }) : order.commit();
+  }
+}
+
+@CommandHandler(ScopedPlaceOrderCommand, { scope: Scope.REQUEST })
+class ScopedPlaceOrderHandler implements ICommandHandler<ScopedPlaceOrderCommand> {
+  constructor(
+    private readonly publisher: EventPublisher,
+    @Inject(REQUEST) private readonly context: AsyncContext,
+  ) {}
+
+  async execute({ orderId, transaction }: ScopedPlaceOrderCommand) {
+    const MergedOrder = this.publisher.mergeClassContext(Order, this.context);
+    const order = new MergedOrder(orderId);
+    order.place();
+    return order.commit({ transaction });
+  }
+}
+
+@EventsHandler(OrderPlacedEvent)
+class OrderPlacedHandler implements IEventHandler<OrderPlacedEvent> {
+  static readonly handled: string[] = [];
+
+  handle(event: OrderPlacedEvent) {
+    OrderPlacedHandler.handled.push(event.orderId);
+  }
+}
+
+@Module({
+  imports: [CqrsModule.forRoot()],
+  providers: [
+    TransactionalEventPublisher,
+    PlaceOrderHandler,
+    ScopedPlaceOrderHandler,
+    OrderPlacedHandler,
+  ],
+})
+class OrdersModule {}
+
+describe('Aggregate commit with a dispatcher context', () => {
+  let moduleRef: TestingModule;
+  let commandBus: CommandBus;
+  let publisher: TransactionalEventPublisher;
+
+  beforeAll(async () => {
+    moduleRef = await Test.createTestingModule({
+      imports: [OrdersModule],
+    }).compile();
+    await moduleRef.init();
+
+    commandBus = moduleRef.get(CommandBus);
+    publisher = moduleRef.get(TransactionalEventPublisher);
+  });
+
+  beforeEach(() => {
+    publisher.written.length = 0;
+    OrderPlacedHandler.handled.length = 0;
+  });
+
+  afterAll(async () => {
+    await moduleRef.close();
+  });
+
+  it('awaits the publisher, which receives the transaction and the events', async () => {
+    const transaction = { id: 'tx-1' };
+
+    const result = await commandBus.execute(
+      new PlaceOrderCommand('order-1', transaction),
+    );
+
+    expect(result).toBe('written in tx-1');
+    expect(publisher.written).toEqual([
+      {
+        orderIds: ['order-1'],
+        context: { transaction },
+        asyncContext: undefined,
+      },
+    ]);
+    await waitImmediate();
+    expect(OrderPlacedHandler.handled).toEqual(['order-1']);
+  });
+
+  it("rejects with the publisher's error", async () => {
+    const fail = new Error('serialization failure');
+
+    await expect(
+      commandBus.execute(
+        new PlaceOrderCommand('order-2', { id: 'tx-2', fail }),
+      ),
+    ).rejects.toBe(fail);
+
+    await waitImmediate();
+    expect(publisher.written).toEqual([]);
+    expect(OrderPlacedHandler.handled).toEqual([]);
+  });
+
+  it('passes the transaction from a @Publishable() aggregate', async () => {
+    const transaction = { id: 'tx-3' };
+
+    await commandBus.execute(
+      new PlaceOrderCommand('order-3', transaction, true),
+    );
+
+    expect(publisher.written).toEqual([
+      {
+        orderIds: ['order-3'],
+        context: { transaction },
+        asyncContext: undefined,
+      },
+    ]);
+  });
+
+  it('keeps the async context of a request-scoped handler', async () => {
+    const asyncContext = new AsyncContext();
+    const transaction = { id: 'tx-4' };
+
+    await commandBus.execute(
+      new ScopedPlaceOrderCommand('order-4', transaction),
+      asyncContext,
+    );
+
+    expect(publisher.written).toEqual([
+      { orderIds: ['order-4'], context: { transaction }, asyncContext },
+    ]);
+  });
+
+  it('keeps passing the aggregate as the dispatcher context without one', async () => {
+    await commandBus.execute(new PlaceOrderCommand('order-5'));
+
+    expect(publisher.written).toHaveLength(1);
+    expect(publisher.written[0].context).toBeInstanceOf(Order);
+  });
+});

package/test/e2e/unhandled-exceptions.spec.ts

@@ -1,3 +1,4 @@
+import { Logger } from '@nestjs/common';
 import { Test, TestingModule } from '@nestjs/testing';
 import { take } from 'rxjs';
 import { CommandBus, UnhandledExceptionBus } from '../../src/index.js';
@@ -57,6 +58,24 @@ describe('Unhandled exceptions', () => {
 
       await exceptionPromise;
     });
+
+    it('should log the event handler class name', async () => {
+      const loggerSpy = vi.spyOn(Logger.prototype, 'error');
+      const command = new UnhandledExceptionCommand('event');
+      const commandBus = moduleRef.get(CommandBus);
+
+      const exceptionPromise = new Promise<void>((resolve) => {
+        unhandledExceptionBus.pipe(take(1)).subscribe(() => resolve());
+      });
+      await commandBus.execute(command);
+      await exceptionPromise;
+
+      expect(loggerSpy).toHaveBeenCalledWith(
+        '"UnhandledExceptionEventHandler" has thrown an unhandled exception.',
+        new Error(`Unhandled exception in ${command.failAt}`),
+      );
+      loggerSpy.mockRestore();
+    });
   });
 
   describe('when exception is thrown from saga', () => {