@zdavison/matador 2.0.8 → 2.0.10

package/src/schema/registry.test.ts

@@ -1,339 +0,0 @@
-import { beforeEach, describe, expect, it } from 'bun:test';
-import { MatadorEvent, createSubscriber } from '../types/index.js';
-import { SchemaError, SchemaRegistry } from './registry.js';
-
-class TestEvent extends MatadorEvent {
-  static readonly key = 'test.event';
-  static readonly description = 'A test event';
-
-  constructor(public data: { id: string }) {
-    super();
-  }
-}
-
-class AliasedEvent extends MatadorEvent {
-  static readonly key = 'user.created.v2';
-  static readonly description = 'User created event with aliases';
-  static readonly aliases = ['user.created', 'user.created.v1'];
-
-  constructor(public data: { name: string }) {
-    super();
-  }
-}
-
-describe('SchemaRegistry', () => {
-  let registry: SchemaRegistry;
-
-  beforeEach(() => {
-    registry = new SchemaRegistry();
-  });
-
-  describe('register', () => {
-    it('should register an event with subscribers', () => {
-      const subscriber = createSubscriber({
-        name: 'test-subscriber',
-        description: 'Test subscriber',
-        callback: async () => {},
-      });
-
-      registry.register(TestEvent, [subscriber]);
-
-      expect(registry.hasEvent('test.event')).toBe(true);
-      expect(registry.getSubscribers('test.event')).toHaveLength(1);
-    });
-
-    it('should throw when registering duplicate event without override', () => {
-      const subscriber = createSubscriber({
-        name: 'test-subscriber',
-        description: 'Test subscriber',
-        callback: async () => {},
-      });
-
-      registry.register(TestEvent, [subscriber]);
-
-      expect(() => registry.register(TestEvent, [subscriber])).toThrow(
-        SchemaError,
-      );
-    });
-
-    it('should allow override when option is set', () => {
-      const subscriber1 = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      const subscriber2 = createSubscriber({
-        name: 'sub-2',
-        description: 'Subscriber 2',
-        callback: async () => {},
-      });
-
-      registry.register(TestEvent, [subscriber1]);
-      registry.register(TestEvent, [subscriber2], { override: true });
-
-      const subscribers = registry.getSubscribers('test.event');
-      expect(subscribers).toHaveLength(1);
-      expect(subscribers[0]?.name).toBe('sub-2');
-    });
-
-    it('should register aliases', () => {
-      const subscriber = createSubscriber({
-        name: 'test-subscriber',
-        description: 'Test subscriber',
-        callback: async () => {},
-      });
-
-      registry.register(AliasedEvent, [subscriber]);
-
-      expect(registry.hasEvent('user.created.v2')).toBe(true);
-      expect(registry.hasEvent('user.created')).toBe(true);
-      expect(registry.hasEvent('user.created.v1')).toBe(true);
-    });
-
-    it('should throw on duplicate aliases without override', () => {
-      class EventWithSameAlias extends MatadorEvent {
-        static readonly key = 'another.event';
-        static readonly description = 'Another event';
-        static readonly aliases = ['user.created']; // conflicts with AliasedEvent
-
-        constructor(public data: { x: number }) {
-          super();
-        }
-      }
-
-      const sub1 = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      const sub2 = createSubscriber({
-        name: 'sub-2',
-        description: 'Subscriber 2',
-        callback: async () => {},
-      });
-
-      registry.register(AliasedEvent, [sub1]);
-
-      expect(() => registry.register(EventWithSameAlias, [sub2])).toThrow(
-        'Alias "user.created" is already registered',
-      );
-    });
-  });
-
-  describe('getEventClass', () => {
-    it('should return event class by key', () => {
-      const subscriber = createSubscriber({
-        name: 'test-subscriber',
-        description: 'Test subscriber',
-        callback: async () => {},
-      });
-      registry.register(TestEvent, [subscriber]);
-
-      const eventClass = registry.getEventClass('test.event');
-      expect(eventClass).toBeDefined();
-      expect(eventClass?.key).toBe('test.event');
-    });
-
-    it('should return event class by alias', () => {
-      const subscriber = createSubscriber({
-        name: 'test-subscriber',
-        description: 'Test subscriber',
-        callback: async () => {},
-      });
-      registry.register(AliasedEvent, [subscriber]);
-
-      const eventClass = registry.getEventClass('user.created');
-      expect(eventClass).toBeDefined();
-      expect(eventClass?.key).toBe('user.created.v2');
-    });
-
-    it('should return undefined for unknown key', () => {
-      expect(registry.getEventClass('unknown.event')).toBeUndefined();
-    });
-  });
-
-  describe('getSubscribers', () => {
-    it('should return all subscribers for an event', () => {
-      const sub1 = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      const sub2 = createSubscriber({
-        name: 'sub-2',
-        description: 'Subscriber 2',
-        callback: async () => {},
-      });
-
-      registry.register(TestEvent, [sub1, sub2]);
-
-      const subscribers = registry.getSubscribers('test.event');
-      expect(subscribers).toHaveLength(2);
-      expect(subscribers[0]?.name).toBe('sub-1');
-      expect(subscribers[1]?.name).toBe('sub-2');
-    });
-
-    it('should return empty array for unknown event', () => {
-      expect(registry.getSubscribers('unknown.event')).toEqual([]);
-    });
-  });
-
-  describe('getSubscriber', () => {
-    it('should return specific subscriber by name', () => {
-      const sub1 = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      const sub2 = createSubscriber({
-        name: 'sub-2',
-        description: 'Subscriber 2',
-        callback: async () => {},
-      });
-
-      registry.register(TestEvent, [sub1, sub2]);
-
-      const subscriber = registry.getSubscriber('test.event', 'sub-2');
-      expect(subscriber?.name).toBe('sub-2');
-    });
-
-    it('should return undefined for unknown subscriber', () => {
-      const sub = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      registry.register(TestEvent, [sub]);
-
-      expect(registry.getSubscriber('test.event', 'unknown')).toBeUndefined();
-    });
-  });
-
-  describe('getSubscriberDefinition', () => {
-    it('should return subscriber definition for pipeline', () => {
-      const sub = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-        idempotent: 'yes',
-        importance: 'must-investigate',
-        targetQueue: 'custom-queue',
-      });
-
-      registry.register(TestEvent, [sub]);
-
-      const definition = registry.getSubscriberDefinition(
-        'test.event',
-        'sub-1',
-      );
-      expect(definition).toEqual({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        idempotent: 'yes',
-        importance: 'must-investigate',
-        targetQueue: 'custom-queue',
-      });
-    });
-
-    it('should return undefined for unknown subscriber', () => {
-      expect(
-        registry.getSubscriberDefinition('unknown', 'unknown'),
-      ).toBeUndefined();
-    });
-  });
-
-  describe('getExecutableSubscriber', () => {
-    it('should return subscriber with callback', () => {
-      const callback = async () => {};
-      const sub = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback,
-      });
-
-      registry.register(TestEvent, [sub]);
-
-      const executable = registry.getExecutableSubscriber(
-        'test.event',
-        'sub-1',
-      );
-      expect(executable).toBeDefined();
-      expect(executable?.callback).toBe(callback);
-    });
-  });
-
-  describe('getEventKeys', () => {
-    it('should return all registered event keys', () => {
-      const sub1 = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      const sub2 = createSubscriber({
-        name: 'sub-2',
-        description: 'Subscriber 2',
-        callback: async () => {},
-      });
-
-      registry.register(TestEvent, [sub1]);
-      registry.register(AliasedEvent, [sub2]);
-
-      const keys = registry.getEventKeys();
-      expect(keys).toContain('test.event');
-      expect(keys).toContain('user.created.v2');
-      expect(keys).not.toContain('user.created'); // aliases not included
-    });
-  });
-
-  describe('validate', () => {
-    it('should pass validation for valid schema', () => {
-      const sub = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      registry.register(TestEvent, [sub]);
-
-      const result = registry.validate();
-      expect(result.valid).toBe(true);
-      expect(result.issues).toHaveLength(0);
-    });
-
-    it('should detect duplicate subscriber names', () => {
-      const sub1 = createSubscriber({
-        name: 'duplicate-name',
-        description: 'Duplicate subscriber',
-        callback: async () => {},
-      });
-      const sub2 = createSubscriber({
-        name: 'duplicate-name',
-        description: 'Duplicate subscriber',
-        callback: async () => {},
-      });
-
-      registry.register(TestEvent, [sub1, sub2]);
-
-      const result = registry.validate();
-      expect(result.valid).toBe(false);
-      expect(result.issues).toHaveLength(1);
-      expect(result.issues[0]?.severity).toBe('error');
-      expect(result.issues[0]?.message).toContain('Duplicate subscriber name');
-    });
-  });
-
-  describe('clear', () => {
-    it('should remove all entries', () => {
-      const sub = createSubscriber({
-        name: 'sub-1',
-        description: 'Subscriber 1',
-        callback: async () => {},
-      });
-      registry.register(TestEvent, [sub]);
-
-      registry.clear();
-
-      expect(registry.hasEvent('test.event')).toBe(false);
-      expect(registry.getEventKeys()).toHaveLength(0);
-    });
-  });
-});

package/src/schema/registry.ts

@@ -1,229 +0,0 @@
-import type { HasDescription } from '../errors/index.js';
-import type {
-  AnySubscriber,
-  EventClass,
-  MatadorEvent,
-  Subscriber,
-  SubscriberDefinition,
-} from '../types/index.js';
-import { isSubscriber } from '../types/index.js';
-import type {
-  RegisterOptions,
-  SchemaEntry,
-  SchemaIssue,
-  SchemaValidationResult,
-} from './types.js';
-
-/**
- * Error thrown when schema operations fail.
- */
-export class SchemaError extends Error implements HasDescription {
-  readonly description =
-    'A schema operation failed, such as registering a duplicate event or ' +
-    'conflicting alias. This is a configuration error that should be fixed ' +
-    'during development. Review the event and subscriber registrations to ' +
-    'resolve the conflict.';
-
-  constructor(message: string) {
-    super(message);
-    this.name = 'SchemaError';
-  }
-}
-
-/**
- * Registry for managing event-subscriber relationships.
- */
-export class SchemaRegistry {
-  private readonly entries = new Map<string, SchemaEntry>();
-  private readonly aliases = new Map<string, string>();
-
-  /**
-   * Registers an event class with its subscribers.
-   */
-  register<T>(
-    eventClass: EventClass<T>,
-    subscribers: readonly AnySubscriber[],
-    options: RegisterOptions = {},
-  ): void {
-    const key = eventClass.key;
-
-    if (this.entries.has(key) && !options.override) {
-      throw new SchemaError(`Event "${key}" is already registered`);
-    }
-
-    this.entries.set(key, {
-      eventClass,
-      subscribers,
-    } as SchemaEntry);
-
-    // Register aliases
-    if (eventClass.aliases) {
-      for (const alias of eventClass.aliases) {
-        if (
-          this.aliases.has(alias) &&
-          this.aliases.get(alias) !== key &&
-          !options.override
-        ) {
-          throw new SchemaError(
-            `Alias "${alias}" is already registered for event "${this.aliases.get(alias)}"`,
-          );
-        }
-        this.aliases.set(alias, key);
-      }
-    }
-  }
-
-  /**
-   * Gets the event class for a given key.
-   */
-  getEventClass(key: string): EventClass | undefined {
-    const entry = this.entries.get(key);
-    if (entry) return entry.eventClass;
-
-    // Check aliases
-    const aliasKey = this.aliases.get(key);
-    if (aliasKey) {
-      return this.entries.get(aliasKey)?.eventClass;
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Gets all subscribers for an event key.
-   */
-  getSubscribers(eventKey: string): readonly AnySubscriber[] {
-    const entry = this.getEntry(eventKey);
-    return entry?.subscribers ?? [];
-  }
-
-  /**
-   * Gets a specific subscriber by event key and subscriber name.
-   */
-  getSubscriber(
-    eventKey: string,
-    subscriberName: string,
-  ): AnySubscriber | undefined {
-    const subscribers = this.getSubscribers(eventKey);
-    return subscribers.find((s) => s.name === subscriberName);
-  }
-
-  /**
-   * Gets a subscriber definition for the pipeline.
-   */
-  getSubscriberDefinition(
-    eventKey: string,
-    subscriberName: string,
-  ): SubscriberDefinition | undefined {
-    const subscriber = this.getSubscriber(eventKey, subscriberName);
-    if (!subscriber) return undefined;
-
-    const def: SubscriberDefinition = {
-      name: subscriber.name,
-      idempotent: subscriber.idempotent ?? 'unknown',
-      importance: subscriber.importance ?? 'should-investigate',
-      ...('description' in subscriber &&
-        subscriber.description !== undefined && {
-          description: subscriber.description,
-        }),
-    };
-
-    if (subscriber.targetQueue !== undefined) {
-      (def as { targetQueue?: string }).targetQueue = subscriber.targetQueue;
-    }
-
-    return def;
-  }
-
-  /**
-   * Gets a subscriber with callback for execution.
-   */
-  getExecutableSubscriber(
-    eventKey: string,
-    subscriberName: string,
-  ): Subscriber<MatadorEvent<unknown>> | undefined {
-    const subscriber = this.getSubscriber(eventKey, subscriberName);
-    if (!subscriber || !isSubscriber(subscriber)) return undefined;
-    return subscriber;
-  }
-
-  /**
-   * Gets the event class by alias.
-   */
-  getEventByAlias(alias: string): EventClass | undefined {
-    const key = this.aliases.get(alias);
-    if (!key) return undefined;
-    return this.entries.get(key)?.eventClass;
-  }
-
-  /**
-   * Checks if an event key is registered.
-   */
-  hasEvent(key: string): boolean {
-    return this.entries.has(key) || this.aliases.has(key);
-  }
-
-  /**
-   * Gets all registered event keys.
-   */
-  getEventKeys(): readonly string[] {
-    return [...this.entries.keys()];
-  }
-
-  /**
-   * Validates the schema for issues.
-   */
-  validate(): SchemaValidationResult {
-    const issues: SchemaIssue[] = [];
-
-    for (const [key, entry] of this.entries) {
-      // Check for duplicate subscriber names
-      const names = new Set<string>();
-      for (const subscriber of entry.subscribers) {
-        if (names.has(subscriber.name)) {
-          issues.push({
-            severity: 'error',
-            eventKey: key,
-            message: `Duplicate subscriber name: "${subscriber.name}"`,
-          });
-        }
-        names.add(subscriber.name);
-      }
-
-      // Check for subscribers without callbacks (stubs in consuming instance)
-      const stubs = entry.subscribers.filter((s) => !isSubscriber(s));
-      if (stubs.length === entry.subscribers.length && stubs.length > 0) {
-        issues.push({
-          severity: 'warning',
-          eventKey: key,
-          message: 'All subscribers are stubs, no local handlers',
-        });
-      }
-    }
-
-    return {
-      valid: issues.filter((i) => i.severity === 'error').length === 0,
-      issues,
-    };
-  }
-
-  /**
-   * Clears all registered entries.
-   */
-  clear(): void {
-    this.entries.clear();
-    this.aliases.clear();
-  }
-
-  private getEntry(eventKey: string): SchemaEntry | undefined {
-    const entry = this.entries.get(eventKey);
-    if (entry) return entry;
-
-    const aliasKey = this.aliases.get(eventKey);
-    if (aliasKey) {
-      return this.entries.get(aliasKey);
-    }
-
-    return undefined;
-  }
-}