@zdavison/matador-nest 2.0.1

package/dist/testing/matador-testing.module.d.ts

@@ -0,0 +1,53 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { MatadorModuleOptions } from '../types.js';
+/**
+ * Testing module for Matador with sensible defaults for unit/integration tests.
+ *
+ * Uses LocalTransport by default, which processes messages synchronously
+ * in-memory without requiring external infrastructure.
+ *
+ * @example Basic usage
+ * ```typescript
+ * describe('NotificationService', () => {
+ *   let module: TestingModule;
+ *   let matadorService: MatadorService;
+ *
+ *   beforeEach(async () => {
+ *     module = await Test.createTestingModule({
+ *       imports: [MatadorTestingModule.forTest()],
+ *       providers: [NotificationService],
+ *     }).compile();
+ *
+ *     matadorService = module.get(MatadorService);
+ *     await module.init();
+ *   });
+ *
+ *   it('processes events', async () => {
+ *     await matadorService.send(UserCreatedEvent, { userId: '123' });
+ *     await matadorService.waitForIdle();
+ *     // Assert expected behavior
+ *   });
+ * });
+ * ```
+ *
+ * @example With custom overrides
+ * ```typescript
+ * MatadorTestingModule.forTest({
+ *   topology: TopologyBuilder.create()
+ *     .withNamespace('custom-test')
+ *     .addQueue('my-queue')
+ *     .build(),
+ *   consumeFrom: ['my-queue'],
+ * })
+ * ```
+ */
+export declare class MatadorTestingModule {
+    /**
+     * Creates a testing module with LocalTransport and default configuration.
+     *
+     * @param overrides - Optional overrides for the default configuration
+     * @returns Dynamic module configuration
+     */
+    static forTest(overrides?: Partial<MatadorModuleOptions>): DynamicModule;
+}
+//# sourceMappingURL=matador-testing.module.d.ts.map

package/dist/testing/matador-testing.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matador-testing.module.d.ts","sourceRoot":"","sources":["../../src/testing/matador-testing.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAG5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,oBAAoB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,aAAa;CAgBzE"}

package/dist/testing/matador-testing.module.js

@@ -0,0 +1,77 @@
+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;
+};
+import { Module } from '@nestjs/common';
+import { LocalTransport, TopologyBuilder } from '@zdavison/matador';
+import { MatadorModule } from '../module/matador.module.js';
+/**
+ * Testing module for Matador with sensible defaults for unit/integration tests.
+ *
+ * Uses LocalTransport by default, which processes messages synchronously
+ * in-memory without requiring external infrastructure.
+ *
+ * @example Basic usage
+ * ```typescript
+ * describe('NotificationService', () => {
+ *   let module: TestingModule;
+ *   let matadorService: MatadorService;
+ *
+ *   beforeEach(async () => {
+ *     module = await Test.createTestingModule({
+ *       imports: [MatadorTestingModule.forTest()],
+ *       providers: [NotificationService],
+ *     }).compile();
+ *
+ *     matadorService = module.get(MatadorService);
+ *     await module.init();
+ *   });
+ *
+ *   it('processes events', async () => {
+ *     await matadorService.send(UserCreatedEvent, { userId: '123' });
+ *     await matadorService.waitForIdle();
+ *     // Assert expected behavior
+ *   });
+ * });
+ * ```
+ *
+ * @example With custom overrides
+ * ```typescript
+ * MatadorTestingModule.forTest({
+ *   topology: TopologyBuilder.create()
+ *     .withNamespace('custom-test')
+ *     .addQueue('my-queue')
+ *     .build(),
+ *   consumeFrom: ['my-queue'],
+ * })
+ * ```
+ */
+let MatadorTestingModule = class MatadorTestingModule {
+    /**
+     * Creates a testing module with LocalTransport and default configuration.
+     *
+     * @param overrides - Optional overrides for the default configuration
+     * @returns Dynamic module configuration
+     */
+    static forTest(overrides) {
+        const defaultOptions = {
+            transport: new LocalTransport(),
+            topology: TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build(),
+            consumeFrom: ['events'],
+            autoStart: true,
+        };
+        return MatadorModule.forRoot({
+            ...defaultOptions,
+            ...overrides,
+        });
+    }
+};
+MatadorTestingModule = __decorate([
+    Module({})
+], MatadorTestingModule);
+export { MatadorTestingModule };

package/dist/testing.cjs

@@ -0,0 +1,498 @@
+'use strict';
+
+var common = require('@nestjs/common');
+var matador = require('@zdavison/matador');
+var core = require('@nestjs/core');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/constants.ts
+var MATADOR_EVENT_HANDLERS = /* @__PURE__ */ Symbol("MATADOR_EVENT_HANDLERS");
+var MATADOR_OPTIONS = /* @__PURE__ */ Symbol("MATADOR_OPTIONS");
+function _ts_decorate(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;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var SubscriberDiscoveryService = class {
+  static {
+    __name(this, "SubscriberDiscoveryService");
+  }
+  discoveryService;
+  schema = {};
+  discovered = false;
+  constructor(discoveryService) {
+    this.discoveryService = discoveryService;
+  }
+  onModuleInit() {
+    this.discoverSubscribers();
+  }
+  /**
+  * Discovers all @OnMatadorEvent decorated methods and builds the schema.
+  */
+  discoverSubscribers() {
+    if (this.discovered) {
+      return;
+    }
+    const providers = this.discoveryService.getProviders();
+    for (const wrapper of providers) {
+      const { instance } = wrapper;
+      if (!instance || typeof instance !== "object") {
+        continue;
+      }
+      const handlers = Reflect.getMetadata(MATADOR_EVENT_HANDLERS, instance.constructor);
+      if (!handlers || handlers.length === 0) {
+        continue;
+      }
+      for (const handler of handlers) {
+        this.registerHandler(instance, handler);
+      }
+    }
+    this.discovered = true;
+  }
+  /**
+  * Registers a single handler method as a subscriber.
+  */
+  registerHandler(instance, metadata) {
+    const { eventClass, options, methodName } = metadata;
+    const className = instance.constructor.name;
+    const subscriberName = options.name ?? `${className}.${methodName}`;
+    const isResumable = options.idempotent === "resumable";
+    const boundMethod = instance[methodName].bind(instance);
+    const subscriber = isResumable ? matador.createSubscriber({
+      name: subscriberName,
+      description: options.description,
+      idempotent: "resumable",
+      importance: options.importance,
+      targetQueue: options.targetQueue,
+      enabled: options.enabled,
+      callback: /* @__PURE__ */ __name(async (envelope, context) => {
+        await boundMethod(envelope, context);
+      }, "callback")
+    }) : matador.createSubscriber({
+      name: subscriberName,
+      description: options.description,
+      idempotent: options.idempotent,
+      importance: options.importance,
+      targetQueue: options.targetQueue,
+      enabled: options.enabled,
+      callback: /* @__PURE__ */ __name(async (envelope) => {
+        await boundMethod(envelope);
+      }, "callback")
+    });
+    this.addToSchema(eventClass, subscriber);
+  }
+  /**
+  * Adds a subscriber to the schema for an event.
+  */
+  addToSchema(eventClass, subscriber) {
+    const eventKey = eventClass.key;
+    const existing = this.schema[eventKey];
+    if (existing) {
+      const [existingEventClass, existingSubscribers] = existing;
+      this.schema[eventKey] = [
+        existingEventClass,
+        [
+          ...existingSubscribers,
+          subscriber
+        ]
+      ];
+    } else {
+      this.schema[eventKey] = [
+        eventClass,
+        [
+          subscriber
+        ]
+      ];
+    }
+  }
+  /**
+  * Gets the discovered schema.
+  * Must be called after onModuleInit has run.
+  */
+  getSchema() {
+    return this.schema;
+  }
+  /**
+  * Gets the schema merged with additional events from options.
+  */
+  getMergedSchema(options) {
+    const mergedSchema = {
+      ...this.schema
+    };
+    if (options.additionalEvents) {
+      for (const [eventClass, subscribers] of options.additionalEvents) {
+        const existing = mergedSchema[eventClass.key];
+        if (existing) {
+          const [existingEventClass, existingSubscribers] = existing;
+          mergedSchema[eventClass.key] = [
+            existingEventClass,
+            [
+              ...existingSubscribers,
+              ...subscribers
+            ]
+          ];
+        } else {
+          mergedSchema[eventClass.key] = [
+            eventClass,
+            subscribers
+          ];
+        }
+      }
+    }
+    return mergedSchema;
+  }
+};
+SubscriberDiscoveryService = _ts_decorate([
+  common.Injectable(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof core.DiscoveryService === "undefined" ? Object : core.DiscoveryService
+  ])
+], SubscriberDiscoveryService);
+function _ts_decorate2(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;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+var MatadorService = class _MatadorService {
+  static {
+    __name(this, "MatadorService");
+  }
+  options;
+  discoveryService;
+  logger = new common.Logger(_MatadorService.name);
+  matador;
+  isShuttingDown = false;
+  isStarted = false;
+  constructor(options, discoveryService) {
+    this.options = options;
+    this.discoveryService = discoveryService;
+  }
+  /**
+  * Called when MatadorModule is initialized.
+  * Builds Matador instance and starts if startOn === 'onModuleInit'.
+  */
+  async onModuleInit() {
+    this.initializeMatador();
+    if (this.shouldAutoStart() && this.options.startOn === "onModuleInit") {
+      await this.doStart();
+    }
+  }
+  /**
+  * Called after all modules are initialized and the app is ready to start.
+  * Starts Matador if startOn === 'onApplicationBootstrap' (default).
+  */
+  async onApplicationBootstrap() {
+    const startOn = this.options.startOn ?? "onApplicationBootstrap";
+    if (this.shouldAutoStart() && startOn === "onApplicationBootstrap") {
+      await this.doStart();
+    }
+  }
+  /**
+  * Called when MatadorModule is destroyed.
+  * Shuts down Matador if shutdownOn === 'onModuleDestroy'.
+  */
+  async onModuleDestroy() {
+    if (this.options.shutdownOn === "onModuleDestroy") {
+      await this.doShutdown();
+    }
+  }
+  /**
+  * Called when the application receives a shutdown signal (SIGTERM, etc).
+  * Shuts down Matador if shutdownOn === 'beforeApplicationShutdown' (default).
+  */
+  async beforeApplicationShutdown() {
+    const shutdownOn = this.options.shutdownOn ?? "beforeApplicationShutdown";
+    if (shutdownOn === "beforeApplicationShutdown") {
+      await this.doShutdown();
+    }
+  }
+  /**
+  * Called after beforeApplicationShutdown completes.
+  * Shuts down Matador if shutdownOn === 'onApplicationShutdown'.
+  */
+  async onApplicationShutdown() {
+    if (this.options.shutdownOn === "onApplicationShutdown") {
+      await this.doShutdown();
+    }
+  }
+  async send(eventOrClass, dataOrOptions, options) {
+    if (this.isShuttingDown) {
+      throw new Error("Cannot send events during shutdown");
+    }
+    const isEventClass = typeof eventOrClass === "function" && "key" in eventOrClass;
+    if (isEventClass) {
+      return this.matador.send(eventOrClass, dataOrOptions, options);
+    }
+    return this.matador.send(eventOrClass, dataOrOptions);
+  }
+  /**
+  * Gets the underlying Matador instance for advanced operations.
+  */
+  getMatador() {
+    return this.matador;
+  }
+  /**
+  * Starts consuming (if autoStart was false).
+  */
+  async start() {
+    return this.doStart();
+  }
+  /**
+  * Checks if connected to transport.
+  */
+  isConnected() {
+    return this.matador?.isConnected() ?? false;
+  }
+  /**
+  * Checks if shutdown is in progress.
+  */
+  isShutdownInProgress() {
+    return this.isShuttingDown;
+  }
+  /**
+  * Waits for all pending messages to be processed.
+  */
+  async waitForIdle(timeoutMs) {
+    return this.matador.waitForIdle(timeoutMs);
+  }
+  /**
+  * Initializes the Matador instance with discovered schema.
+  */
+  initializeMatador() {
+    const mergedSchema = this.discoveryService.getMergedSchema(this.options);
+    const registry = new matador.SchemaRegistry();
+    for (const entry of Object.values(mergedSchema)) {
+      if (matador.isSchemaEntryTuple(entry)) {
+        const [eventClass, subscribers] = entry;
+        registry.register(eventClass, subscribers);
+      } else {
+        registry.register(entry.eventClass, entry.subscribers);
+      }
+    }
+    const validation = registry.validate();
+    if (!validation.valid) {
+      const errors = validation.issues.filter((i) => i.severity === "error");
+      if (errors.length > 0) {
+        throw new Error(`Invalid Matador schema: ${errors.map((i) => i.message).join(", ")}`);
+      }
+    }
+    this.matador = new matador.Matador({
+      transport: this.options.transport,
+      topology: this.options.topology,
+      schema: mergedSchema,
+      consumeFrom: this.options.consumeFrom ? [
+        ...this.options.consumeFrom
+      ] : void 0,
+      codec: this.options.codec,
+      retryPolicy: this.options.retryPolicy,
+      checkpointStore: this.options.checkpointStore,
+      shutdownConfig: this.options.shutdownConfig
+    }, this.options.hooks);
+    this.logger.log("Matador instance initialized");
+  }
+  shouldAutoStart() {
+    return this.options.autoStart !== false;
+  }
+  async doStart() {
+    if (this.isStarted) {
+      return;
+    }
+    await this.matador.start();
+    this.isStarted = true;
+    this.logger.log("Matador started");
+  }
+  async doShutdown() {
+    if (!this.isStarted || this.isShuttingDown) {
+      return;
+    }
+    this.isShuttingDown = true;
+    this.logger.log("Graceful shutdown initiated, draining in-flight messages");
+    const timeoutMs = this.options.shutdownConfig?.gracefulShutdownTimeout ?? 3e4;
+    const drained = await this.matador.waitForIdle(timeoutMs);
+    if (!drained) {
+      this.logger.warn(`Shutdown timeout reached after ${timeoutMs}ms, some messages may not have completed`);
+    }
+    await this.matador.shutdown();
+    this.logger.log("Matador shutdown complete");
+  }
+};
+MatadorService = _ts_decorate2([
+  common.Injectable(),
+  _ts_param(0, common.Inject(MATADOR_OPTIONS)),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof MatadorModuleOptions === "undefined" ? Object : MatadorModuleOptions,
+    typeof SubscriberDiscoveryService === "undefined" ? Object : SubscriberDiscoveryService
+  ])
+], MatadorService);
+
+// src/module/matador.module.ts
+function _ts_decorate3(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;
+}
+__name(_ts_decorate3, "_ts_decorate");
+var MatadorModule = class _MatadorModule {
+  static {
+    __name(this, "MatadorModule");
+  }
+  /**
+  * Configures the MatadorModule with static options.
+  *
+  * @param options - Module configuration options
+  * @returns Dynamic module configuration
+  */
+  static forRoot(options) {
+    return {
+      module: _MatadorModule,
+      imports: [
+        core.DiscoveryModule
+      ],
+      providers: [
+        {
+          provide: MATADOR_OPTIONS,
+          useValue: options
+        },
+        core.DiscoveryService,
+        SubscriberDiscoveryService,
+        MatadorService
+      ],
+      exports: [
+        MatadorService
+      ]
+    };
+  }
+  /**
+  * Configures the MatadorModule with async options.
+  * Use this when you need to inject dependencies like ConfigService.
+  *
+  * @param options - Async module configuration options
+  * @returns Dynamic module configuration
+  */
+  static forRootAsync(options) {
+    const asyncProviders = this.createAsyncProviders(options);
+    return {
+      module: _MatadorModule,
+      imports: [
+        core.DiscoveryModule,
+        ...options.imports ?? []
+      ],
+      providers: [
+        ...asyncProviders,
+        core.DiscoveryService,
+        SubscriberDiscoveryService,
+        MatadorService
+      ],
+      exports: [
+        MatadorService
+      ]
+    };
+  }
+  /**
+  * Creates async providers for the module options.
+  */
+  static createAsyncProviders(options) {
+    if (options.useFactory) {
+      return [
+        {
+          provide: MATADOR_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject ?? []
+        }
+      ];
+    }
+    if (options.useClass) {
+      return [
+        {
+          provide: options.useClass,
+          useClass: options.useClass
+        },
+        {
+          provide: MATADOR_OPTIONS,
+          useFactory: /* @__PURE__ */ __name(async (factory) => factory.createMatadorOptions(), "useFactory"),
+          inject: [
+            options.useClass
+          ]
+        }
+      ];
+    }
+    if (options.useExisting) {
+      return [
+        {
+          provide: MATADOR_OPTIONS,
+          useFactory: /* @__PURE__ */ __name(async (factory) => factory.createMatadorOptions(), "useFactory"),
+          inject: [
+            options.useExisting
+          ]
+        }
+      ];
+    }
+    throw new Error("MatadorModule.forRootAsync() requires useFactory, useClass, or useExisting");
+  }
+};
+MatadorModule = _ts_decorate3([
+  common.Global(),
+  common.Module({})
+], MatadorModule);
+
+// src/testing/matador-testing.module.ts
+function _ts_decorate4(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;
+}
+__name(_ts_decorate4, "_ts_decorate");
+exports.MatadorTestingModule = class MatadorTestingModule {
+  static {
+    __name(this, "MatadorTestingModule");
+  }
+  /**
+  * Creates a testing module with LocalTransport and default configuration.
+  *
+  * @param overrides - Optional overrides for the default configuration
+  * @returns Dynamic module configuration
+  */
+  static forTest(overrides) {
+    const defaultOptions = {
+      transport: new matador.LocalTransport(),
+      topology: matador.TopologyBuilder.create().withNamespace("test").addQueue("events").build(),
+      consumeFrom: [
+        "events"
+      ],
+      autoStart: true
+    };
+    return MatadorModule.forRoot({
+      ...defaultOptions,
+      ...overrides
+    });
+  }
+};
+exports.MatadorTestingModule = _ts_decorate4([
+  common.Module({})
+], exports.MatadorTestingModule);
+//# sourceMappingURL=testing.cjs.map
+//# sourceMappingURL=testing.cjs.map