@zdavison/matador 2.0.1

package/src/schema/registry.ts

@@ -0,0 +1,226 @@
+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,
+      description: subscriber.description,
+      idempotent: subscriber.idempotent ?? 'unknown',
+      importance: subscriber.importance ?? 'should-investigate',
+    };
+
+    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;
+  }
+}

package/src/schema/types.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  MatadorEvent,
+  createSubscriber,
+  createSubscriberStub,
+} from '../types/index.js';
+import { bind, installPlugins, isSchemaEntryTuple } from './types.js';
+import type { MatadorSchema } from './types.js';
+
+class UserCreatedEvent extends MatadorEvent {
+  static readonly key = 'user.created';
+  static readonly description = 'User created event';
+
+  constructor(public data: { userId: string }) {
+    super();
+  }
+}
+
+class OrderPlacedEvent extends MatadorEvent {
+  static readonly key = 'order.placed';
+  static readonly description = 'Order placed event';
+
+  constructor(public data: { orderId: string }) {
+    super();
+  }
+}
+
+class ChatMessageSentEvent extends MatadorEvent {
+  static readonly key = 'chat.message.sent';
+  static readonly description = 'Chat message sent event';
+
+  constructor(public data: { messageId: string }) {
+    super();
+  }
+}
+
+describe('bind', () => {
+  it('should create a schema entry tuple', () => {
+    const subscriber = createSubscriber<UserCreatedEvent>({
+      name: 'test-sub',
+      description: 'Test subscriber',
+      callback: async () => {},
+    });
+    const entry = bind(UserCreatedEvent, [subscriber]);
+
+    expect(isSchemaEntryTuple(entry)).toBe(true);
+    expect(entry[0]).toBe(UserCreatedEvent);
+    expect(entry[1]).toHaveLength(1);
+    expect(entry[1][0]).toBe(subscriber);
+  });
+});
+
+describe('isSchemaEntryTuple', () => {
+  it('should return true for tuple format', () => {
+    const entry = [UserCreatedEvent, []] as const;
+    expect(isSchemaEntryTuple(entry)).toBe(true);
+  });
+
+  it('should return false for object format', () => {
+    const entry = { eventClass: UserCreatedEvent, subscribers: [] };
+    expect(isSchemaEntryTuple(entry)).toBe(false);
+  });
+});
+
+describe('installPlugins', () => {
+  it('should add plugin subscriber to all events', () => {
+    const sub1 = createSubscriber<UserCreatedEvent>({
+      name: 'user-handler',
+      description: 'Handles user events',
+      callback: async () => {},
+    });
+    const sub2 = createSubscriber<OrderPlacedEvent>({
+      name: 'order-handler',
+      description: 'Handles order events',
+      callback: async () => {},
+    });
+    const globalSub = createSubscriber<MatadorEvent>({
+      name: 'analytics',
+      description: 'Analytics subscriber',
+      callback: async () => {},
+    });
+
+    const baseSchema: MatadorSchema = {
+      [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+      [OrderPlacedEvent.key]: [OrderPlacedEvent, [sub2]],
+    };
+
+    const schema = installPlugins(baseSchema, [{ subscriber: globalSub }]);
+
+    // Check user.created has both subscribers
+    const userEntry = schema[UserCreatedEvent.key];
+    expect(isSchemaEntryTuple(userEntry!)).toBe(true);
+    const [, userSubs] = userEntry as [unknown, readonly unknown[]];
+    expect(userSubs).toHaveLength(2);
+    expect(userSubs[0]).toBe(sub1);
+    expect(userSubs[1]).toBe(globalSub);
+
+    // Check order.placed has both subscribers
+    const orderEntry = schema[OrderPlacedEvent.key];
+    const [, orderSubs] = orderEntry as [unknown, readonly unknown[]];
+    expect(orderSubs).toHaveLength(2);
+    expect(orderSubs[0]).toBe(sub2);
+    expect(orderSubs[1]).toBe(globalSub);
+  });
+
+  it('should respect exclusions', () => {
+    const sub1 = createSubscriber<UserCreatedEvent>({
+      name: 'user-handler',
+      description: 'Handles user events',
+      callback: async () => {},
+    });
+    const sub2 = createSubscriber<OrderPlacedEvent>({
+      name: 'order-handler',
+      description: 'Handles order events',
+      callback: async () => {},
+    });
+    const sub3 = createSubscriber<ChatMessageSentEvent>({
+      name: 'chat-handler',
+      description: 'Handles chat events',
+      callback: async () => {},
+    });
+    const globalSub = createSubscriber<MatadorEvent>({
+      name: 'analytics',
+      description: 'Analytics subscriber',
+      callback: async () => {},
+    });
+
+    const baseSchema: MatadorSchema = {
+      [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+      [OrderPlacedEvent.key]: [OrderPlacedEvent, [sub2]],
+      [ChatMessageSentEvent.key]: [ChatMessageSentEvent, [sub3]],
+    };
+
+    const schema = installPlugins(baseSchema, [
+      {
+        subscriber: globalSub,
+        exclusions: [ChatMessageSentEvent.key],
+      },
+    ]);
+
+    // user.created should have analytics
+    const userEntry = schema[UserCreatedEvent.key];
+    const [, userSubs] = userEntry as [unknown, readonly unknown[]];
+    expect(userSubs).toHaveLength(2);
+
+    // order.placed should have analytics
+    const orderEntry = schema[OrderPlacedEvent.key];
+    const [, orderSubs] = orderEntry as [unknown, readonly unknown[]];
+    expect(orderSubs).toHaveLength(2);
+
+    // chat.message.sent should NOT have analytics (excluded)
+    const chatEntry = schema[ChatMessageSentEvent.key];
+    const [, chatSubs] = chatEntry as [unknown, readonly unknown[]];
+    expect(chatSubs).toHaveLength(1);
+    expect(chatSubs[0]).toBe(sub3);
+  });
+
+  it('should handle multiple plugins', () => {
+    const sub1 = createSubscriber<UserCreatedEvent>({
+      name: 'user-handler',
+      description: 'Handles user events',
+      callback: async () => {},
+    });
+    const analyticsSub = createSubscriber<MatadorEvent>({
+      name: 'analytics',
+      description: 'Analytics subscriber',
+      callback: async () => {},
+    });
+    const loggingSub = createSubscriber<MatadorEvent>({
+      name: 'logging',
+      description: 'Logging subscriber',
+      callback: async () => {},
+    });
+
+    const baseSchema: MatadorSchema = {
+      [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+    };
+
+    const schema = installPlugins(baseSchema, [
+      { subscriber: analyticsSub },
+      { subscriber: loggingSub },
+    ]);
+
+    const entry = schema[UserCreatedEvent.key];
+    const [, subs] = entry as [unknown, readonly unknown[]];
+    expect(subs).toHaveLength(3);
+    expect(subs[0]).toBe(sub1);
+    expect(subs[1]).toBe(analyticsSub);
+    expect(subs[2]).toBe(loggingSub);
+  });
+
+  it('should handle object format schema entries', () => {
+    const sub1 = createSubscriber<UserCreatedEvent>({
+      name: 'user-handler',
+      description: 'Handles user events',
+      callback: async () => {},
+    });
+    const globalSub = createSubscriber<MatadorEvent>({
+      name: 'analytics',
+      description: 'Analytics subscriber',
+      callback: async () => {},
+    });
+
+    const baseSchema: MatadorSchema = {
+      [UserCreatedEvent.key]: {
+        eventClass: UserCreatedEvent,
+        subscribers: [sub1],
+      },
+    };
+
+    const schema = installPlugins(baseSchema, [{ subscriber: globalSub }]);
+
+    const entry = schema[UserCreatedEvent.key];
+    expect(isSchemaEntryTuple(entry!)).toBe(true);
+    const [eventClass, subs] = entry as [unknown, readonly unknown[]];
+    expect(eventClass).toBe(UserCreatedEvent);
+    expect(subs).toHaveLength(2);
+  });
+
+  it('should work with subscriber stubs', () => {
+    const sub1 = createSubscriber<UserCreatedEvent>({
+      name: 'user-handler',
+      description: 'Handles user events',
+      callback: async () => {},
+    });
+    const stubSub = createSubscriberStub({
+      name: 'remote-analytics',
+      description: 'Remote analytics stub',
+      targetQueue: 'analytics-worker',
+    });
+
+    const baseSchema: MatadorSchema = {
+      [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+    };
+
+    const schema = installPlugins(baseSchema, [{ subscriber: stubSub }]);
+
+    const entry = schema[UserCreatedEvent.key];
+    const [, subs] = entry as [unknown, readonly unknown[]];
+    expect(subs).toHaveLength(2);
+    expect(subs[1]).toBe(stubSub);
+  });
+
+  it('should return empty schema for empty input', () => {
+    const schema = installPlugins({}, [
+      {
+        subscriber: createSubscriber<MatadorEvent>({
+          name: 'analytics',
+          description: 'Analytics subscriber',
+          callback: async () => {},
+        }),
+      },
+    ]);
+
+    expect(Object.keys(schema)).toHaveLength(0);
+  });
+
+  it('should not modify original schema', () => {
+    const sub1 = createSubscriber<UserCreatedEvent>({
+      name: 'user-handler',
+      description: 'Handles user events',
+      callback: async () => {},
+    });
+    const globalSub = createSubscriber<MatadorEvent>({
+      name: 'analytics',
+      description: 'Analytics subscriber',
+      callback: async () => {},
+    });
+
+    const baseSchema: MatadorSchema = {
+      [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+    };
+
+    installPlugins(baseSchema, [{ subscriber: globalSub }]);
+
+    // Original schema should be unchanged
+    const entry = baseSchema[UserCreatedEvent.key];
+    const [, subs] = entry as [unknown, readonly unknown[]];
+    expect(subs).toHaveLength(1);
+  });
+});