@zdavison/matador-nest 2.0.1

package/src/index.ts

@@ -0,0 +1,28 @@
+// Decorators
+export { OnMatadorEvent, MatadorSubscriber } from './decorators/index.js';
+
+// Module
+export { MatadorModule } from './module/index.js';
+
+// Services
+export { MatadorService } from './services/index.js';
+
+// Discovery
+export { SubscriberDiscoveryService } from './discovery/index.js';
+
+// Types
+export type {
+  OnMatadorEventOptions,
+  MatadorEventHandlerMetadata,
+  MatadorModuleOptions,
+  MatadorModuleAsyncOptions,
+  MatadorOptionsFactory,
+  NestMatadorOptions,
+} from './types.js';
+
+// Constants (for advanced use cases)
+export {
+  MATADOR_EVENT_HANDLER,
+  MATADOR_EVENT_HANDLERS,
+  MATADOR_OPTIONS,
+} from './constants.js';

package/src/module/index.ts

@@ -0,0 +1 @@
+export { MatadorModule } from './matador.module.js';

package/src/module/matador.module.ts

@@ -0,0 +1,162 @@
+import {
+  type DynamicModule,
+  Global,
+  type InjectionToken,
+  Module,
+  type Provider,
+} from '@nestjs/common';
+import { DiscoveryModule, DiscoveryService } from '@nestjs/core';
+import { MATADOR_OPTIONS } from '../constants.js';
+import { SubscriberDiscoveryService } from '../discovery/subscriber-discovery.service.js';
+import { MatadorService } from '../services/matador.service.js';
+import type {
+  MatadorModuleAsyncOptions,
+  MatadorModuleOptions,
+  MatadorOptionsFactory,
+} from '../types.js';
+
+/**
+ * NestJS module for integrating Matador event processing.
+ *
+ * Use `MatadorModule.forRoot()` for synchronous configuration or
+ * `MatadorModule.forRootAsync()` for async configuration with dependency injection.
+ *
+ * @example Synchronous configuration
+ * ```typescript
+ * @Module({
+ *   imports: [
+ *     MatadorModule.forRoot({
+ *       transport: new RabbitMQTransport({ url: 'amqp://localhost' }),
+ *       topology: TopologyBuilder.create()
+ *         .withNamespace('myapp')
+ *         .addQueue('events', { concurrency: 10 })
+ *         .build(),
+ *       consumeFrom: ['events'],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example Async configuration with ConfigService
+ * ```typescript
+ * @Module({
+ *   imports: [
+ *     ConfigModule.forRoot(),
+ *     MatadorModule.forRootAsync({
+ *       imports: [ConfigModule],
+ *       inject: [ConfigService],
+ *       useFactory: (config: ConfigService) => ({
+ *         transport: new RabbitMQTransport({
+ *           url: config.get('RABBITMQ_URL'),
+ *         }),
+ *         topology: TopologyBuilder.create()
+ *           .withNamespace(config.get('APP_NAME'))
+ *           .addQueue('events')
+ *           .build(),
+ *         consumeFrom: ['events'],
+ *       }),
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+@Global()
+@Module({})
+export class MatadorModule {
+  /**
+   * Configures the MatadorModule with static options.
+   *
+   * @param options - Module configuration options
+   * @returns Dynamic module configuration
+   */
+  static forRoot(options: MatadorModuleOptions): DynamicModule {
+    return {
+      module: MatadorModule,
+      imports: [DiscoveryModule],
+      providers: [
+        {
+          provide: MATADOR_OPTIONS,
+          useValue: options,
+        },
+        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: MatadorModuleAsyncOptions): DynamicModule {
+    const asyncProviders = this.createAsyncProviders(options);
+
+    return {
+      module: MatadorModule,
+      imports: [DiscoveryModule, ...(options.imports ?? [])],
+      providers: [
+        ...asyncProviders,
+        DiscoveryService,
+        SubscriberDiscoveryService,
+        MatadorService,
+      ],
+      exports: [MatadorService],
+    };
+  }
+
+  /**
+   * Creates async providers for the module options.
+   */
+  private static createAsyncProviders(
+    options: MatadorModuleAsyncOptions,
+  ): Provider[] {
+    if (options.useFactory) {
+      return [
+        {
+          provide: MATADOR_OPTIONS,
+          useFactory: options.useFactory,
+          inject: (options.inject ?? []) as InjectionToken[],
+        },
+      ];
+    }
+
+    if (options.useClass) {
+      return [
+        {
+          provide: options.useClass,
+          useClass: options.useClass,
+        },
+        {
+          provide: MATADOR_OPTIONS,
+          useFactory: async (
+            factory: MatadorOptionsFactory,
+          ): Promise<MatadorModuleOptions> => factory.createMatadorOptions(),
+          inject: [options.useClass],
+        },
+      ];
+    }
+
+    if (options.useExisting) {
+      return [
+        {
+          provide: MATADOR_OPTIONS,
+          useFactory: async (
+            factory: MatadorOptionsFactory,
+          ): Promise<MatadorModuleOptions> => factory.createMatadorOptions(),
+          inject: [options.useExisting],
+        },
+      ];
+    }
+
+    throw new Error(
+      'MatadorModule.forRootAsync() requires useFactory, useClass, or useExisting',
+    );
+  }
+}

package/src/services/index.ts

@@ -0,0 +1 @@
+export { MatadorService } from './matador.service.js';

package/src/services/matador.service.ts

@@ -0,0 +1,283 @@
+import {
+  type BeforeApplicationShutdown,
+  Inject,
+  Injectable,
+  Logger,
+  type OnApplicationBootstrap,
+  type OnApplicationShutdown,
+  type OnModuleDestroy,
+  type OnModuleInit,
+} from '@nestjs/common';
+import {
+  type Event,
+  type EventClass,
+  type EventOptions,
+  Matador,
+  SchemaRegistry,
+  type SendResult,
+  isSchemaEntryTuple,
+} from '@zdavison/matador';
+import { MATADOR_OPTIONS } from '../constants.js';
+import { SubscriberDiscoveryService } from '../discovery/subscriber-discovery.service.js';
+import type { MatadorModuleOptions } from '../types.js';
+
+/**
+ * Injectable service that wraps Matador and integrates with NestJS lifecycle.
+ *
+ * This service handles:
+ * - Building the Matador instance with discovered subscribers
+ * - Starting Matador at the configured lifecycle hook
+ * - Graceful shutdown with drain timeout
+ * - Preventing event sending during shutdown
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class OrderService {
+ *   constructor(private readonly matador: MatadorService) {}
+ *
+ *   async createOrder(data: CreateOrderDto) {
+ *     // ... create order logic ...
+ *     await this.matador.send(OrderCreatedEvent, { orderId: order.id });
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class MatadorService
+  implements
+    OnModuleInit,
+    OnApplicationBootstrap,
+    OnModuleDestroy,
+    BeforeApplicationShutdown,
+    OnApplicationShutdown
+{
+  private readonly logger = new Logger(MatadorService.name);
+  private matador!: Matador;
+  private isShuttingDown = false;
+  private isStarted = false;
+
+  constructor(
+    @Inject(MATADOR_OPTIONS) private readonly options: MatadorModuleOptions,
+    private readonly discoveryService: SubscriberDiscoveryService,
+  ) {}
+
+  /**
+   * Called when MatadorModule is initialized.
+   * Builds Matador instance and starts if startOn === 'onModuleInit'.
+   */
+  async onModuleInit(): Promise<void> {
+    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(): Promise<void> {
+    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(): Promise<void> {
+    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(): Promise<void> {
+    const shutdownOn = this.options.shutdownOn ?? 'beforeApplicationShutdown';
+    if (shutdownOn === 'beforeApplicationShutdown') {
+      await this.doShutdown();
+    }
+  }
+
+  /**
+   * Called after beforeApplicationShutdown completes.
+   * Shuts down Matador if shutdownOn === 'onApplicationShutdown'.
+   */
+  async onApplicationShutdown(): Promise<void> {
+    if (this.options.shutdownOn === 'onApplicationShutdown') {
+      await this.doShutdown();
+    }
+  }
+
+  /**
+   * Sends an event to all registered subscribers.
+   *
+   * @throws Error if called during shutdown
+   *
+   * @example
+   * ```typescript
+   * // Pass the event class and data directly
+   * await matadorService.send(UserCreatedEvent, { userId: '123' });
+   *
+   * // Or pass an event instance
+   * const event = new UserCreatedEvent({ userId: '123' });
+   * await matadorService.send(event);
+   * ```
+   */
+  async send<T>(
+    eventClass: EventClass<T>,
+    data: T,
+    options?: EventOptions,
+  ): Promise<SendResult>;
+  async send<T>(event: Event<T>, options?: EventOptions): Promise<SendResult>;
+  async send<T>(
+    eventOrClass: EventClass<T> | Event<T>,
+    dataOrOptions?: T | EventOptions,
+    options?: EventOptions,
+  ): Promise<SendResult> {
+    if (this.isShuttingDown) {
+      throw new Error('Cannot send events during shutdown');
+    }
+
+    // Determine if first arg is an event instance or event class
+    const isEventClass =
+      typeof eventOrClass === 'function' && 'key' in eventOrClass;
+
+    if (isEventClass) {
+      return this.matador.send(
+        eventOrClass as EventClass<T>,
+        dataOrOptions as T,
+        options,
+      );
+    }
+    return this.matador.send(
+      eventOrClass as Event<T>,
+      dataOrOptions as EventOptions | undefined,
+    );
+  }
+
+  /**
+   * Gets the underlying Matador instance for advanced operations.
+   */
+  getMatador(): Matador {
+    return this.matador;
+  }
+
+  /**
+   * Starts consuming (if autoStart was false).
+   */
+  async start(): Promise<void> {
+    return this.doStart();
+  }
+
+  /**
+   * Checks if connected to transport.
+   */
+  isConnected(): boolean {
+    return this.matador?.isConnected() ?? false;
+  }
+
+  /**
+   * Checks if shutdown is in progress.
+   */
+  isShutdownInProgress(): boolean {
+    return this.isShuttingDown;
+  }
+
+  /**
+   * Waits for all pending messages to be processed.
+   */
+  async waitForIdle(timeoutMs?: number): Promise<boolean> {
+    return this.matador.waitForIdle(timeoutMs);
+  }
+
+  /**
+   * Initializes the Matador instance with discovered schema.
+   */
+  private initializeMatador(): void {
+    const mergedSchema = this.discoveryService.getMergedSchema(this.options);
+
+    // Validate schema at startup
+    const registry = new SchemaRegistry();
+    for (const entry of Object.values(mergedSchema)) {
+      if (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(
+      {
+        transport: this.options.transport,
+        topology: this.options.topology,
+        schema: mergedSchema,
+        consumeFrom: this.options.consumeFrom
+          ? [...this.options.consumeFrom]
+          : undefined,
+        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');
+  }
+
+  private shouldAutoStart(): boolean {
+    return this.options.autoStart !== false;
+  }
+
+  private async doStart(): Promise<void> {
+    if (this.isStarted) {
+      return;
+    }
+
+    await this.matador.start();
+    this.isStarted = true;
+    this.logger.log('Matador started');
+  }
+
+  private async doShutdown(): Promise<void> {
+    if (!this.isStarted || this.isShuttingDown) {
+      return;
+    }
+
+    this.isShuttingDown = true;
+    this.logger.log('Graceful shutdown initiated, draining in-flight messages');
+
+    // Wait for in-flight messages to complete (with configurable timeout)
+    const timeoutMs =
+      this.options.shutdownConfig?.gracefulShutdownTimeout ?? 30000;
+    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');
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1 @@
+export { MatadorTestingModule } from './matador-testing.module.js';

package/src/testing/matador-testing.module.ts

@@ -0,0 +1,71 @@
+import { type DynamicModule, Module } from '@nestjs/common';
+import { LocalTransport, TopologyBuilder } from '@zdavison/matador';
+import { MatadorModule } from '../module/matador.module.js';
+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'],
+ * })
+ * ```
+ */
+@Module({})
+export 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 {
+    const defaultOptions: MatadorModuleOptions = {
+      transport: new LocalTransport(),
+      topology: TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .build(),
+      consumeFrom: ['events'],
+      autoStart: true,
+    };
+
+    return MatadorModule.forRoot({
+      ...defaultOptions,
+      ...overrides,
+    });
+  }
+}

package/src/testing.ts

@@ -0,0 +1,2 @@
+// Testing utilities
+export { MatadorTestingModule } from './testing/index.js';

package/src/types.ts

@@ -0,0 +1,119 @@
+import type { ModuleMetadata, Type } from '@nestjs/common';
+import type {
+  AnySubscriber,
+  BaseSubscriberOptions,
+  EventClass,
+  Idempotency,
+  MatadorConfig,
+  MatadorHooks,
+} from '@zdavison/matador';
+
+/**
+ * Options for the @OnMatadorEvent decorator.
+ * Derived from BaseSubscriberOptions with additional NestJS-specific fields.
+ */
+export interface OnMatadorEventOptions extends BaseSubscriberOptions {
+  /** Optional: override auto-generated name (default: ClassName.methodName) */
+  readonly name?: string | undefined;
+
+  /** Idempotency declaration for retry handling */
+  readonly idempotent?: Idempotency | undefined;
+}
+
+/**
+ * Metadata stored on methods decorated with @OnMatadorEvent.
+ */
+export interface MatadorEventHandlerMetadata {
+  readonly eventClass: EventClass<unknown>;
+  readonly options: OnMatadorEventOptions;
+  readonly methodName: string;
+}
+
+/**
+ * NestJS-specific options that extend MatadorConfig.
+ */
+export interface NestMatadorOptions {
+  /** Optional lifecycle hooks */
+  readonly hooks?: MatadorHooks | undefined;
+
+  /**
+   * Additional events to register (for events without decorated subscribers).
+   * Maps event class to subscriber stubs or external subscribers.
+   */
+  readonly additionalEvents?:
+    | Map<EventClass<unknown>, AnySubscriber[]>
+    | undefined;
+
+  /**
+   * Whether to auto-start consuming.
+   * Default: true
+   */
+  readonly autoStart?: boolean | undefined;
+
+  /**
+   * Which NestJS lifecycle hook to start Matador on.
+   * - 'onModuleInit': Start when MatadorModule initializes (earliest)
+   * - 'onApplicationBootstrap': Start after all modules init (default, recommended)
+   *
+   * Use 'onModuleInit' if other modules depend on Matador being connected
+   * during their own onModuleInit/onApplicationBootstrap hooks.
+   *
+   * Default: 'onApplicationBootstrap'
+   */
+  readonly startOn?: 'onModuleInit' | 'onApplicationBootstrap' | undefined;
+
+  /**
+   * Which NestJS lifecycle hook to shutdown Matador on.
+   * - 'onModuleDestroy': Shutdown when MatadorModule is destroyed (earliest)
+   * - 'beforeApplicationShutdown': Shutdown before app closes (default, recommended)
+   * - 'onApplicationShutdown': Shutdown when app closes (latest)
+   *
+   * Use 'beforeApplicationShutdown' to ensure Matador finishes processing
+   * before other modules start their shutdown.
+   *
+   * Default: 'beforeApplicationShutdown'
+   */
+  readonly shutdownOn?:
+    | 'onModuleDestroy'
+    | 'beforeApplicationShutdown'
+    | 'onApplicationShutdown'
+    | undefined;
+
+  /**
+   * Global subscriber options applied to all discovered subscribers.
+   */
+  readonly globalSubscriberDefaults?:
+    | Pick<BaseSubscriberOptions, 'importance'> & {
+        readonly idempotent?: Idempotency | undefined;
+      }
+    | undefined;
+}
+
+/**
+ * Configuration options for MatadorModule.
+ * Derived from MatadorConfig (minus schema which is auto-generated) plus NestJS-specific options.
+ */
+export interface MatadorModuleOptions
+  extends Omit<MatadorConfig, 'schema'>,
+    NestMatadorOptions {}
+
+/**
+ * Factory interface for creating MatadorModuleOptions.
+ */
+export interface MatadorOptionsFactory {
+  createMatadorOptions(): Promise<MatadorModuleOptions> | MatadorModuleOptions;
+}
+
+/**
+ * Async configuration options for MatadorModule.forRootAsync().
+ */
+export interface MatadorModuleAsyncOptions
+  extends Pick<ModuleMetadata, 'imports'> {
+  readonly inject?: readonly unknown[] | undefined;
+  readonly useFactory?: (
+    // biome-ignore lint/suspicious/noExplicitAny: Factory can receive any injected dependencies
+    ...args: any[]
+  ) => Promise<MatadorModuleOptions> | MatadorModuleOptions;
+  readonly useClass?: Type<MatadorOptionsFactory> | undefined;
+  readonly useExisting?: Type<MatadorOptionsFactory> | undefined;
+}