@zdavison/matador-nest 2.0.1

package/test/decorators.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'bun:test';
+import 'reflect-metadata';
+import { type Envelope, MatadorEvent } from '@zdavison/matador';
+import { MATADOR_EVENT_HANDLERS } from '../src/constants.js';
+import { OnMatadorEvent } from '../src/decorators/on-matador-event.decorator.js';
+
+// Test event
+class TestEvent extends MatadorEvent<{ userId: string }> {
+  static readonly key = 'test.event';
+  static readonly description = 'Test event';
+
+  constructor(public readonly data: { userId: string }) {
+    super();
+  }
+}
+
+describe('@OnMatadorEvent decorator', () => {
+  it('stores metadata on the class', () => {
+    class TestService {
+      @OnMatadorEvent(TestEvent, {
+        description: 'Test handler',
+      })
+      async handleTestEvent(_envelope: Envelope<TestEvent['data']>) {
+        // handler
+      }
+    }
+
+    const handlers = Reflect.getMetadata(MATADOR_EVENT_HANDLERS, TestService);
+
+    expect(handlers).toBeDefined();
+    expect(handlers).toHaveLength(1);
+    expect(handlers[0].eventClass).toBe(TestEvent);
+    expect(handlers[0].options.description).toBe('Test handler');
+    expect(handlers[0].methodName).toBe('handleTestEvent');
+  });
+
+  it('stores multiple handlers on the same class', () => {
+    class AnotherEvent extends MatadorEvent<{ data: string }> {
+      static readonly key = 'another.event';
+      constructor(public readonly data: { data: string }) {
+        super();
+      }
+    }
+
+    class MultiHandlerService {
+      @OnMatadorEvent(TestEvent, {
+        description: 'Handler 1',
+      })
+      async handler1(_envelope: Envelope<TestEvent['data']>) {
+        // handler
+      }
+
+      @OnMatadorEvent(AnotherEvent, {
+        description: 'Handler 2',
+      })
+      async handler2(_envelope: Envelope<AnotherEvent['data']>) {
+        // handler
+      }
+    }
+
+    const handlers = Reflect.getMetadata(
+      MATADOR_EVENT_HANDLERS,
+      MultiHandlerService,
+    );
+
+    expect(handlers).toBeDefined();
+    expect(handlers).toHaveLength(2);
+    expect(handlers[0].eventClass).toBe(TestEvent);
+    expect(handlers[1].eventClass).toBe(AnotherEvent);
+  });
+
+  it('supports custom subscriber name', () => {
+    class ServiceWithCustomName {
+      @OnMatadorEvent(TestEvent, {
+        name: 'custom-name',
+        description: 'Custom named handler',
+      })
+      async handleEvent(_envelope: Envelope<TestEvent['data']>) {
+        // handler
+      }
+    }
+
+    const handlers = Reflect.getMetadata(
+      MATADOR_EVENT_HANDLERS,
+      ServiceWithCustomName,
+    );
+
+    expect(handlers[0].options.name).toBe('custom-name');
+  });
+
+  it('supports all subscriber options', () => {
+    class ServiceWithAllOptions {
+      @OnMatadorEvent(TestEvent, {
+        description: 'Full options handler',
+        idempotent: 'yes',
+        importance: 'must-investigate',
+        targetQueue: 'priority-queue',
+      })
+      async handleEvent(_envelope: Envelope<TestEvent['data']>) {
+        // handler
+      }
+    }
+
+    const handlers = Reflect.getMetadata(
+      MATADOR_EVENT_HANDLERS,
+      ServiceWithAllOptions,
+    );
+
+    expect(handlers[0].options.idempotent).toBe('yes');
+    expect(handlers[0].options.importance).toBe('must-investigate');
+    expect(handlers[0].options.targetQueue).toBe('priority-queue');
+  });
+
+  it('supports resumable subscribers', () => {
+    class ResumableService {
+      @OnMatadorEvent(TestEvent, {
+        description: 'Resumable handler',
+        idempotent: 'resumable',
+      })
+      async handleEvent(_envelope: Envelope<TestEvent['data']>) {
+        // handler
+      }
+    }
+
+    const handlers = Reflect.getMetadata(
+      MATADOR_EVENT_HANDLERS,
+      ResumableService,
+    );
+
+    expect(handlers[0].options.idempotent).toBe('resumable');
+  });
+});

package/test/discovery.test.ts

@@ -0,0 +1,278 @@
+import { beforeEach, describe, expect, it } from 'bun:test';
+import 'reflect-metadata';
+import type { DiscoveryService } from '@nestjs/core';
+import {
+  type AnySubscriber,
+  type Envelope,
+  type EventClass,
+  MatadorEvent,
+} from '@zdavison/matador';
+import { OnMatadorEvent } from '../src/decorators/on-matador-event.decorator.js';
+import { SubscriberDiscoveryService } from '../src/discovery/subscriber-discovery.service.js';
+
+// Test events
+class UserCreatedEvent extends MatadorEvent<{ userId: string }> {
+  static readonly key = 'user.created';
+  static readonly description = 'User created event';
+
+  constructor(public readonly data: { userId: string }) {
+    super();
+  }
+}
+
+class OrderPlacedEvent extends MatadorEvent<{ orderId: string }> {
+  static readonly key = 'order.placed';
+  static readonly description = 'Order placed event';
+
+  constructor(public readonly data: { orderId: string }) {
+    super();
+  }
+}
+
+describe('SubscriberDiscoveryService', () => {
+  let discoveryService: SubscriberDiscoveryService;
+  let mockNestDiscovery: { getProviders: () => Array<{ instance: unknown }> };
+
+  beforeEach(() => {
+    mockNestDiscovery = {
+      getProviders: () => [],
+    };
+  });
+
+  it('discovers decorated methods and builds schema', () => {
+    // Create a service with decorated handlers
+    class TestService {
+      @OnMatadorEvent(UserCreatedEvent, {
+        description: 'Handles user creation',
+      })
+      async onUserCreated(_envelope: Envelope<UserCreatedEvent['data']>) {
+        // handler
+      }
+    }
+
+    const instance = new TestService();
+
+    mockNestDiscovery.getProviders = () =>
+      [
+        {
+          instance,
+        },
+      ] ;
+
+    discoveryService = new SubscriberDiscoveryService(
+      mockNestDiscovery as unknown as DiscoveryService,
+    );
+
+    // Trigger discovery (simulates onModuleInit)
+    discoveryService.onModuleInit();
+
+    const schema = discoveryService.getSchema();
+
+    expect(schema[UserCreatedEvent.key]).toBeDefined();
+    const [eventClass, subscribers] = schema[UserCreatedEvent.key] as [
+      unknown,
+      unknown[],
+    ];
+    expect(eventClass).toBe(UserCreatedEvent);
+    expect(subscribers).toHaveLength(1);
+    expect(subscribers[0]).toHaveProperty('name', 'TestService.onUserCreated');
+    expect(subscribers[0]).toHaveProperty(
+      'description',
+      'Handles user creation',
+    );
+  });
+
+  it('uses custom name when provided', () => {
+    class TestService {
+      @OnMatadorEvent(UserCreatedEvent, {
+        name: 'custom-handler-name',
+        description: 'Handles user creation',
+      })
+      async onUserCreated(_envelope: Envelope<UserCreatedEvent['data']>) {
+        // handler
+      }
+    }
+
+    const instance = new TestService();
+
+    mockNestDiscovery.getProviders = () =>
+      [
+        {
+          instance,
+        },
+      ] ;
+
+    discoveryService = new SubscriberDiscoveryService(
+      mockNestDiscovery as unknown as DiscoveryService,
+    );
+
+    discoveryService.onModuleInit();
+
+    const schema = discoveryService.getSchema();
+    const [, subscribers] = schema[UserCreatedEvent.key] as [
+      unknown,
+      unknown[],
+    ];
+    expect(subscribers[0]).toHaveProperty('name', 'custom-handler-name');
+  });
+
+  it('discovers multiple handlers for the same event', () => {
+    class ServiceA {
+      @OnMatadorEvent(UserCreatedEvent, {
+        description: 'Handler A',
+      })
+      async handle(_envelope: Envelope<UserCreatedEvent['data']>) {
+        // handler
+      }
+    }
+
+    class ServiceB {
+      @OnMatadorEvent(UserCreatedEvent, {
+        description: 'Handler B',
+      })
+      async handle(_envelope: Envelope<UserCreatedEvent['data']>) {
+        // handler
+      }
+    }
+
+    const instanceA = new ServiceA();
+    const instanceB = new ServiceB();
+
+    mockNestDiscovery.getProviders = () =>
+      [{ instance: instanceA }, { instance: instanceB }] ;
+
+    discoveryService = new SubscriberDiscoveryService(
+      mockNestDiscovery as unknown as DiscoveryService,
+    );
+
+    discoveryService.onModuleInit();
+
+    const schema = discoveryService.getSchema();
+    const [, subscribers] = schema[UserCreatedEvent.key] as [
+      unknown,
+      unknown[],
+    ];
+    expect(subscribers).toHaveLength(2);
+  });
+
+  it('discovers handlers for different events', () => {
+    class TestService {
+      @OnMatadorEvent(UserCreatedEvent, {
+        description: 'User handler',
+      })
+      async onUserCreated(_envelope: Envelope<UserCreatedEvent['data']>) {
+        // handler
+      }
+
+      @OnMatadorEvent(OrderPlacedEvent, {
+        description: 'Order handler',
+      })
+      async onOrderPlaced(_envelope: Envelope<OrderPlacedEvent['data']>) {
+        // handler
+      }
+    }
+
+    const instance = new TestService();
+
+    mockNestDiscovery.getProviders = () =>
+      [
+        {
+          instance,
+        },
+      ] ;
+
+    discoveryService = new SubscriberDiscoveryService(
+      mockNestDiscovery as unknown as DiscoveryService,
+    );
+
+    discoveryService.onModuleInit();
+
+    const schema = discoveryService.getSchema();
+
+    expect(schema[UserCreatedEvent.key]).toBeDefined();
+    expect(schema[OrderPlacedEvent.key]).toBeDefined();
+  });
+
+  it('skips providers without decorated methods', () => {
+    class PlainService {
+      someMethod() {
+        return 'plain';
+      }
+    }
+
+    const instance = new PlainService();
+
+    mockNestDiscovery.getProviders = () =>
+      [
+        {
+          instance,
+        },
+      ] ;
+
+    discoveryService = new SubscriberDiscoveryService(
+      mockNestDiscovery as unknown as DiscoveryService,
+    );
+
+    discoveryService.onModuleInit();
+
+    const schema = discoveryService.getSchema();
+    expect(Object.keys(schema)).toHaveLength(0);
+  });
+
+  it('merges additional events from options', () => {
+    class TestService {
+      @OnMatadorEvent(UserCreatedEvent, {
+        description: 'Discovered handler',
+      })
+      async handle(_envelope: Envelope<UserCreatedEvent['data']>) {
+        // handler
+      }
+    }
+
+    const instance = new TestService();
+
+    mockNestDiscovery.getProviders = () =>
+      [
+        {
+          instance,
+        },
+      ] ;
+
+    discoveryService = new SubscriberDiscoveryService(
+      mockNestDiscovery as unknown as DiscoveryService,
+    );
+
+    discoveryService.onModuleInit();
+
+    // Additional event with subscriber
+    const additionalSubscriber = {
+      name: 'additional-subscriber',
+      description: 'Additional handler',
+      callback: async () => {},
+      importance: 'should-investigate' as const,
+      idempotent: 'unknown' as const,
+    };
+
+    const additionalEvents = new Map<EventClass<unknown>, AnySubscriber[]>();
+    additionalEvents.set(
+      OrderPlacedEvent as EventClass<unknown>,
+      [additionalSubscriber],
+    );
+
+    const mergedSchema = discoveryService.getMergedSchema({
+      transport: {} as never,
+      topology: {} as never,
+      additionalEvents,
+    });
+
+    expect(mergedSchema[UserCreatedEvent.key]).toBeDefined();
+    expect(mergedSchema[OrderPlacedEvent.key]).toBeDefined();
+
+    const [, orderSubscribers] = mergedSchema[OrderPlacedEvent.key] as [
+      unknown,
+      unknown[],
+    ];
+    expect(orderSubscribers).toHaveLength(1);
+    expect(orderSubscribers[0]).toHaveProperty('name', 'additional-subscriber');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": false,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"],
+  "references": [{ "path": "../matador" }]
+}