@nestjs/cqrs 10.2.8 → 11.0.0-next.1

package/dist/unhandled-exception-bus.d.ts

@@ -1,15 +1,16 @@
 import { Type } from '@nestjs/common';
 import 'reflect-metadata';
 import { Observable } from 'rxjs';
-import { ICommand, IEvent, IUnhandledExceptionPublisher, UnhandledExceptionInfo } from './interfaces';
+import { CqrsModuleOptions, ICommand, IEvent, IUnhandledExceptionPublisher, UnhandledExceptionInfo } from './interfaces';
 import { ObservableBus } from './utils/observable-bus';
 /**
  * A bus that publishes unhandled exceptions.
  * @template Cause The type of the cause of the exception.
  */
 export declare class UnhandledExceptionBus<Cause = IEvent | ICommand> extends ObservableBus<UnhandledExceptionInfo<Cause>> {
+    private readonly options?;
     private _publisher;
-    constructor();
+    constructor(options?: CqrsModuleOptions | undefined);
     /**
      * Filter values depending on their instance type (comparison is made
      * using native `instanceof`).
@@ -17,7 +18,7 @@ export declare class UnhandledExceptionBus<Cause = IEvent | ICommand> extends Ob
      * @param types List of types to filter by.
      * @return A stream only emitting the filtered exceptions.
      */
-    static ofType<TInput, TOutput>(...types: Type<TOutput>[]): (source: Observable<UnhandledExceptionInfo<TInput>>) => Observable<UnhandledExceptionInfo<TOutput>>;
+    static ofType<TInput extends IEvent | ICommand, TOutput extends IEvent | ICommand>(...types: Type<TOutput>[]): (source: Observable<UnhandledExceptionInfo<TInput>>) => Observable<UnhandledExceptionInfo<TOutput>>;
     /**
      * Gets the publisher of the bus.
      */

package/dist/unhandled-exception-bus.js

@@ -8,11 +8,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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.UnhandledExceptionBus = void 0;
 const common_1 = require("@nestjs/common");
 require("reflect-metadata");
 const rxjs_1 = require("rxjs");
+const constants_1 = require("./constants");
 const default_unhandled_exception_pubsub_1 = require("./helpers/default-unhandled-exception-pubsub");
 const observable_bus_1 = require("./utils/observable-bus");
 /**
@@ -20,9 +24,16 @@ const observable_bus_1 = require("./utils/observable-bus");
  * @template Cause The type of the cause of the exception.
  */
 let UnhandledExceptionBus = class UnhandledExceptionBus extends observable_bus_1.ObservableBus {
-    constructor() {
+    constructor(options) {
         super();
-        this.useDefaultPublisher();
+        this.options = options;
+        if (this.options?.unhandledExceptionPublisher) {
+            this._publisher = this.options
+                .unhandledExceptionPublisher;
+        }
+        else {
+            this.useDefaultPublisher();
+        }
     }
     /**
      * Filter values depending on their instance type (comparison is made
@@ -58,8 +69,10 @@ let UnhandledExceptionBus = class UnhandledExceptionBus extends observable_bus_1
         this._publisher = new default_unhandled_exception_pubsub_1.DefaultUnhandledExceptionPubSub(this.subject$);
     }
 };
-UnhandledExceptionBus = __decorate([
+exports.UnhandledExceptionBus = UnhandledExceptionBus;
+exports.UnhandledExceptionBus = UnhandledExceptionBus = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [])
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(constants_1.CQRS_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
 ], UnhandledExceptionBus);
-exports.UnhandledExceptionBus = UnhandledExceptionBus;

package/dist/utils/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[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];

package/jest.config.js

@@ -1,4 +1,9 @@
 module.exports = {
   preset: 'ts-jest',
   testEnvironment: 'node',
+  rootDir: '.',
+  testMatch: ['<rootDir>/src/**/*.spec.ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest'
+  },
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@nestjs/cqrs",
-  "version": "10.2.8",
+  "version": "11.0.0-next.1",
   "description": "A lightweight CQRS module for Nest framework (node.js)",
   "license": "MIT",
   "url": "https://github.com/nestjs/cqrs#readme",
   "scripts": {
     "test": "jest",
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
     "format": "prettier --write \"**/*.ts\"",
     "lint": "eslint \"src/**/*.ts\" --fix",
     "prepublish:next": "npm run build",
@@ -15,32 +15,32 @@
     "publish:npm": "npm publish --access public",
     "prerelease": "npm run build",
     "release": "release-it",
-    "prepare": "husky install"
-  },
-  "dependencies": {
-    "uuid": "11.0.2"
+    "prepare": "husky install",
+    "test:e2e": "jest --config ./test/jest-e2e.json --runInBand"
   },
+  "dependencies": {},
   "devDependencies": {
-    "@commitlint/cli": "19.5.0",
-    "@commitlint/config-angular": "19.5.0",
-    "@nestjs/common": "10.4.6",
-    "@nestjs/core": "10.4.6",
-    "@types/node": "22.8.2",
+    "@commitlint/cli": "19.6.0",
+    "@commitlint/config-angular": "19.6.0",
+    "@nestjs/common": "10.4.11",
+    "@nestjs/core": "10.4.11",
+    "@nestjs/testing": "10.4.12",
     "@types/jest": "29.5.14",
-    "@typescript-eslint/eslint-plugin": "8.12.1",
-    "@typescript-eslint/parser": "8.12.1",
-    "eslint": "9.13.0",
+    "@types/node": "22.10.1",
+    "@typescript-eslint/eslint-plugin": "8.16.0",
+    "@typescript-eslint/parser": "8.16.0",
+    "eslint": "9.15.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-import": "2.31.0",
-    "husky": "9.1.6",
+    "husky": "9.1.7",
     "jest": "29.7.0",
     "lint-staged": "15.2.10",
-    "prettier": "3.3.3",
+    "prettier": "3.4.1",
     "reflect-metadata": "0.2.2",
     "release-it": "17.10.0",
     "rxjs": "7.8.1",
     "ts-jest": "29.2.5",
-    "typescript": "5.6.3"
+    "typescript": "5.7.2"
   },
   "peerDependencies": {
     "@nestjs/common": "^9.0.0 || ^10.0.0",
@@ -54,5 +54,17 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/nestjs/cqrs"
+  },
+  "changelog": {
+    "labels": {
+      "feature": "Features",
+      "bug": "Bug fixes",
+      "enhancement": "Enhancements",
+      "docs": "Docs",
+      "dependencies": "Dependencies",
+      "type: code style": "Code style tweaks",
+      "status: blocked": "Breaking changes",
+      "breaking change": "Breaking changes"
+    }
   }
 }

package/renovate.json

@@ -1,10 +1,11 @@
 {
   "semanticCommits": true,
-  "packageRules": [{
-    "depTypeList": ["devDependencies"],
-    "automerge": true
-  }],
-  "extends": [
-    "config:base"
-  ]
+  "packageRules": [
+    {
+      "depTypeList": ["devDependencies"],
+      "automerge": true
+    }
+  ],
+  "labels": ["dependencies"],
+  "extends": ["config:base"]
 }

package/test/e2e/basic-flows.spec.ts

@@ -0,0 +1,98 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { setTimeout } from 'timers/promises';
+import { CommandBus, QueryBus } from '../../src';
+import { AppModule } from '../src/app.module';
+import { DropAncientItemHandler } from '../src/heroes/commands/handlers/drop-ancient-item.handler';
+import { KillDragonHandler } from '../src/heroes/commands/handlers/kill-dragon.handler';
+import { DropAncientItemCommand } from '../src/heroes/commands/impl/drop-ancient-item.command';
+import { KillDragonCommand } from '../src/heroes/commands/impl/kill-dragon.command';
+import { HeroFoundItemHandler } from '../src/heroes/events/handlers/hero-found-item.handler';
+import { HeroKilledDragonHandler } from '../src/heroes/events/handlers/hero-killed-dragon.handler';
+import { HeroFoundItemEvent } from '../src/heroes/events/impl/hero-found-item.event';
+import { HeroKilledDragonEvent } from '../src/heroes/events/impl/hero-killed-dragon.event';
+import { GetHeroesQuery } from '../src/heroes/queries/impl';
+import { HERO_ID } from '../src/heroes/repository/fixtures/user';
+import { ANCIENT_ITEM_ID } from '../src/heroes/sagas/heroes.sagas';
+import { waitImmediate } from '../utils/wait-immediate';
+
+describe('Basic flows', () => {
+  let moduleRef: TestingModule;
+
+  beforeAll(async () => {
+    moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    await moduleRef.init();
+  });
+
+  describe('when "KillDragonCommand" command is dispatched', () => {
+    let killDragonExecuteSpy: jest.SpyInstance;
+    let heroKilledDragonHandleSpy: jest.SpyInstance;
+    let command: KillDragonCommand;
+
+    beforeAll(async () => {
+      const killDragonHandler = moduleRef.get(KillDragonHandler);
+      const heroKilledDragonHandler = moduleRef.get(HeroKilledDragonHandler);
+
+      killDragonExecuteSpy = jest.spyOn(killDragonHandler, 'execute');
+      heroKilledDragonHandleSpy = jest.spyOn(heroKilledDragonHandler, 'handle');
+
+      const commandBus = moduleRef.get(CommandBus);
+      const heroId = HERO_ID;
+      const dragonId = 'dragonId';
+
+      command = new KillDragonCommand(heroId, dragonId);
+      await commandBus.execute(command);
+      await waitImmediate();
+    });
+
+    it('should execute command handler', () => {
+      expect(killDragonExecuteSpy).toHaveBeenCalledWith(command);
+    });
+
+    it('should handle "HeroKillDragonEvent" event', () => {
+      const event = new HeroKilledDragonEvent(command.heroId, command.dragonId);
+      expect(heroKilledDragonHandleSpy).toHaveBeenCalledWith(event);
+    });
+
+    describe('when saga triggered', () => {
+      let dropAncientExecuteSpy: jest.SpyInstance;
+      let heroFoundItemSpy: jest.SpyInstance;
+
+      beforeAll(async () => {
+        const dropAncientItemHandler = moduleRef.get(DropAncientItemHandler);
+        const heroFoundItemHandler = moduleRef.get(HeroFoundItemHandler);
+        dropAncientExecuteSpy = jest.spyOn(dropAncientItemHandler, 'execute');
+        heroFoundItemSpy = jest.spyOn(heroFoundItemHandler, 'handle');
+
+        // Wait 1 second for saga to be triggered
+        await setTimeout(1000);
+      });
+
+      it('should dispatch "DropAncientItemCommand" and execute its command handler', () => {
+        expect(dropAncientExecuteSpy).toHaveBeenCalledWith(
+          new DropAncientItemCommand(HERO_ID, ANCIENT_ITEM_ID),
+        );
+      });
+
+      it('should handle "HeroFoundItemEvent" event', () => {
+        expect(heroFoundItemSpy).toHaveBeenCalledWith(
+          new HeroFoundItemEvent(HERO_ID, ANCIENT_ITEM_ID),
+        );
+      });
+    });
+  });
+
+  describe('when "GetHeroesQuery" query is executed', () => {
+    it('should return all heroes', async () => {
+      const queryBus = moduleRef.get(QueryBus);
+      const heroes = await queryBus.execute(new GetHeroesQuery());
+      expect(heroes).toEqual([expect.objectContaining({ id: HERO_ID })]);
+    });
+  });
+
+  afterAll(async () => {
+    await moduleRef.close();
+  });
+});

package/test/e2e/generics.spec.ts

@@ -0,0 +1,198 @@
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+import { Test, TestingModule } from '@nestjs/testing';
+import {
+  Command,
+  CommandBus,
+  ICommandHandler,
+  Query,
+  QueryBus,
+} from '../../src';
+import { AppModule } from '../src/app.module';
+
+describe('Generics', () => {
+  let moduleRef: TestingModule;
+  let commandBus: CommandBus;
+  let queryBus: QueryBus;
+
+  beforeAll(async () => {
+    moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    await moduleRef.init();
+
+    commandBus = moduleRef.get(CommandBus);
+    queryBus = moduleRef.get(QueryBus);
+  });
+
+  describe('Commands', () => {
+    describe('when "Command" utility class is used', () => {
+      it('should infer return type', async () => {
+        const command = new Command<string>();
+
+        try {
+          await commandBus.execute(command).then((value) => {
+            value as string;
+
+            // @ts-expect-error
+            value as number;
+          });
+        } catch (err) {
+          // Do nothing
+        } finally {
+          expect(true).toBeTruthy();
+        }
+      });
+    });
+
+    describe('when any other class is used', () => {
+      it('should fallback to any return type', async () => {
+        class MyCommand {}
+
+        const command = new MyCommand();
+
+        try {
+          await commandBus.execute(command).then((value) => {
+            value as string;
+            value as number;
+          });
+        } catch (err) {
+          // Do nothing
+        } finally {
+          expect(true).toBeTruthy();
+        }
+      });
+
+      it('should use the 2nd generic parameter as return type', async () => {
+        class MyCommand {}
+
+        const command = new MyCommand();
+
+        try {
+          await commandBus.execute<MyCommand, string>(command).then((value) => {
+            value as string;
+
+            // @ts-expect-error
+            value as number;
+          });
+        } catch (err) {
+          // Do nothing
+        } finally {
+          expect(true).toBeTruthy();
+        }
+      });
+    });
+  });
+
+  describe('Queries', () => {
+    describe('when "Query" utility class is used', () => {
+      it('should infer return type', async () => {
+        const query = new Query<string>();
+
+        try {
+          await queryBus.execute(query).then((value) => {
+            value as string;
+
+            // @ts-expect-error
+            value as number;
+          });
+        } catch (err) {
+          // Do nothing
+        } finally {
+          expect(true).toBeTruthy();
+        }
+      });
+    });
+
+    describe('when any other class is used', () => {
+      it('should fallback to any return type', async () => {
+        class MyQuery {}
+
+        const query = new MyQuery();
+
+        try {
+          await queryBus.execute(query).then((value) => {
+            value as string;
+            value as number;
+          });
+        } catch (err) {
+          // Do nothing
+        } finally {
+          expect(true).toBeTruthy();
+        }
+      });
+
+      it('should use the 2nd generic parameter as return type', async () => {
+        class MyQuery {}
+
+        const query = new MyQuery();
+
+        try {
+          await queryBus.execute<MyQuery, string>(query).then((value) => {
+            value as string;
+
+            // @ts-expect-error
+            value as number;
+          });
+        } catch (err) {
+          // Do nothing
+        } finally {
+          expect(true).toBeTruthy();
+        }
+      });
+    });
+  });
+
+  describe('Command handlers', () => {
+    it('should infer return type', async () => {
+      class Test extends Command<{
+        value: string;
+      }> {}
+
+      class ValidHandler implements ICommandHandler<Test> {
+        execute(command: Test): Promise<{ value: string }> {
+          throw new Error('Method not implemented.');
+        }
+      }
+
+      class InvalidHandler implements ICommandHandler<Test> {
+        // @ts-expect-error
+        execute(command: Test): Promise<{ value: number }> {
+          throw new Error('Method not implemented.');
+        }
+      }
+
+      try {
+        commandBus.bind(
+          new InstanceWrapper({
+            metatype: ValidHandler,
+            instance: new ValidHandler(),
+          }),
+          'Test',
+        );
+        commandBus.bind(
+          new InstanceWrapper({
+            metatype: InvalidHandler,
+            instance: new InvalidHandler() as any,
+          }),
+          'Test2',
+        );
+
+        await commandBus.execute(new Test()).then((value) => {
+          value.value as string;
+
+          // @ts-expect-error
+          value as number;
+        });
+      } catch (err) {
+        // Do nothing
+      } finally {
+        expect(true).toBeTruthy();
+      }
+    });
+  });
+
+  afterAll(async () => {
+    await moduleRef.close();
+  });
+});

package/test/e2e/request-scope.spec.ts

@@ -0,0 +1,141 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { setTimeout } from 'timers/promises';
+import { AsyncContext, CommandBus, QueryBus } from '../../src';
+import { AppModule } from '../src/app.module';
+import { HERO_ID } from '../src/heroes/repository/fixtures/user';
+import { ANCIENT_ITEM_ID } from '../src/heroes/sagas/heroes.sagas';
+import { ScopedDropAncientItemHandler } from '../src/scoped/commands/handlers/scoped-drop-ancient-item.handler';
+import { ScopedKillDragonHandler } from '../src/scoped/commands/handlers/scoped-kill-dragon.handler';
+import { ScopedDropAncientItemCommand } from '../src/scoped/commands/impl/scoped-drop-ancient-item.command';
+import { ScopedKillDragonCommand } from '../src/scoped/commands/impl/scoped-kill-dragon.command';
+import { ScopedHeroFoundItemHandler } from '../src/scoped/events/handlers/scoped-hero-found-item.handler';
+import { ScopedHeroKilledDragonHandler } from '../src/scoped/events/handlers/scoped-hero-killed-dragon.handler';
+import { ScopedHeroFoundItemEvent } from '../src/scoped/events/impl/hero-found-item.event';
+import { ScopedHeroKilledDragonEvent } from '../src/scoped/events/impl/hero-killed-dragon.event';
+import { ScopedGetHeroesQuery } from '../src/scoped/queries/impl';
+import { waitImmediate } from '../utils/wait-immediate';
+
+describe('Request scope', () => {
+  let moduleRef: TestingModule;
+
+  beforeAll(async () => {
+    moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    await moduleRef.init();
+  });
+
+  describe('when "ScopedKillDragonCommand" command is dispatched', () => {
+    const asyncContext = new AsyncContext();
+
+    let killDragonExecuteSpy: jest.SpyInstance;
+    let heroKilledDragonHandleSpy: jest.SpyInstance;
+    let command: ScopedKillDragonCommand;
+
+    beforeAll(async () => {
+      moduleRef.registerRequestByContextId(asyncContext, asyncContext.id);
+
+      const killDragonHandler = await moduleRef.resolve(
+        ScopedKillDragonHandler,
+        asyncContext.id,
+      );
+      const heroKilledDragonHandler = await moduleRef.resolve(
+        ScopedHeroKilledDragonHandler,
+        asyncContext.id,
+      );
+
+      killDragonExecuteSpy = jest.spyOn(killDragonHandler, 'execute');
+      heroKilledDragonHandleSpy = jest.spyOn(heroKilledDragonHandler, 'handle');
+
+      const commandBus = moduleRef.get(CommandBus);
+      const heroId = HERO_ID;
+      const dragonId = 'dragonId';
+
+      command = new ScopedKillDragonCommand(heroId, dragonId);
+      await commandBus.execute(command, asyncContext);
+      await waitImmediate();
+    });
+
+    it('should execute command handler', () => {
+      expect(killDragonExecuteSpy).toHaveBeenCalledWith(command);
+    });
+
+    it('should handle "ScopedHeroKilledDragonEvent" event', () => {
+      const event = new ScopedHeroKilledDragonEvent(
+        command.heroId,
+        command.dragonId,
+      );
+      expect(heroKilledDragonHandleSpy).toHaveBeenCalledWith(event);
+    });
+
+    describe('when saga triggered', () => {
+      let dropAncientExecuteSpy: jest.SpyInstance;
+      let heroFoundItemSpy: jest.SpyInstance;
+
+      beforeAll(async () => {
+        const dropAncientItemHandler = await moduleRef.resolve(
+          ScopedDropAncientItemHandler,
+          asyncContext.id,
+        );
+        const heroFoundItemHandler = await moduleRef.resolve(
+          ScopedHeroFoundItemHandler,
+          asyncContext.id,
+        );
+        dropAncientExecuteSpy = jest.spyOn(dropAncientItemHandler, 'execute');
+        heroFoundItemSpy = jest.spyOn(heroFoundItemHandler, 'handle');
+
+        // Wait 1 second for saga to be triggered
+        await setTimeout(1000);
+      });
+
+      it('should dispatch "ScopedDropAncientItemCommand" and execute its command handler', () => {
+        expect(dropAncientExecuteSpy).toHaveBeenCalledWith(
+          new ScopedDropAncientItemCommand(HERO_ID, ANCIENT_ITEM_ID),
+        );
+      });
+
+      it('should handle "ScopedHeroFoundItemEvent" event', () => {
+        expect(heroFoundItemSpy).toHaveBeenCalledWith(
+          new ScopedHeroFoundItemEvent(HERO_ID, ANCIENT_ITEM_ID),
+        );
+      });
+    });
+  });
+
+  describe('when "ScopedKillDragonCommand" command is dispatched and no async context is provided', () => {
+    const heroId = HERO_ID;
+    const dragonId = 'dragonId';
+    const command = new ScopedKillDragonCommand(heroId, dragonId);
+
+    it('should generate a unique async context', async () => {
+      const commandBus = moduleRef.get(CommandBus);
+      const result = await commandBus.execute(command);
+      expect(result).toEqual({ heroId, dragonId });
+    });
+  });
+
+  describe('when "ScopedGetHeroesQuery" query is executed', () => {
+    it('should return all heroes', async () => {
+      const asyncContext = new AsyncContext();
+      const queryBus = moduleRef.get(QueryBus);
+      const heroes = await queryBus.execute(
+        new ScopedGetHeroesQuery(),
+        asyncContext,
+      );
+      expect(heroes).toEqual([expect.objectContaining({ id: HERO_ID })]);
+    });
+  });
+
+  describe('when "ScopedGetHeroesQuery" query is executed and no async context is provided', () => {
+    it('should return all heroes', async () => {
+      const queryBus = moduleRef.get(QueryBus);
+      const heroes = await queryBus.execute(new ScopedGetHeroesQuery());
+      expect(heroes).toEqual([expect.objectContaining({ id: HERO_ID })]);
+    });
+  });
+
+  afterAll(async () => {
+    await moduleRef.close();
+  });
+});