@zdavison/matador 2.0.8 → 2.0.10

package/src/schema/types.test.ts

@@ -1,280 +0,0 @@
-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',
-      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);
-  });
-});

package/src/schema/types.ts

@@ -1,217 +0,0 @@
-import type {
-  AnySubscriber,
-  EventClass,
-  MatadorEvent,
-  Subscriber,
-  SubscriberStub,
-} from '../types/index.js';
-
-/**
- * Type-safe schema entry for a single event type (object format).
- * The type parameter enforces that subscribers match the event type.
- */
-export interface SchemaEntry<T extends MatadorEvent = MatadorEvent> {
-  /** The event class */
-  readonly eventClass: EventClass<T['data']>;
-
-  /** Subscribers for this event */
-  readonly subscribers: readonly (Subscriber<T> | SubscriberStub)[];
-}
-
-/**
- * Type-safe schema entry as a tuple: [EventClass, Subscribers[]]
- * The type parameter enforces that subscribers match the event type.
- *
- * @example
- * ```typescript
- * const entry: SchemaEntryTuple<UserCreatedEvent> = [
- *   UserCreatedEvent,
- *   [createSubscriber<UserCreatedEvent>('handler', async (env) => {})]
- * ];
- * ```
- */
-export type SchemaEntryTuple<T extends MatadorEvent = MatadorEvent> = readonly [
-  eventClass: EventClass<T['data']>,
-  subscribers: readonly (Subscriber<T> | SubscriberStub)[],
-];
-
-/**
- * Creates a type-safe schema entry tuple.
- * Ensures that subscribers are compatible with the event class at compile time.
- *
- * @example
- * ```typescript
- * const schema = {
- *   [UserCreatedEvent.key]: bind(UserCreatedEvent, [
- *     createSubscriber<UserCreatedEvent>('send-email', async (env) => {
- *       console.log(env.data.email); // Type-safe access
- *     }),
- *   ]),
- * } satisfies MatadorSchema;
- * ```
- */
-export function bind<T extends MatadorEvent>(
-  eventClass: EventClass<T['data']>,
-  subscribers: readonly (Subscriber<T> | SubscriberStub)[],
-): SchemaEntryTuple<T> {
-  return [eventClass, subscribers] as const;
-}
-
-/**
- * Minimal type for event class in schema storage.
- * Only requires the static `key` property for routing.
- * Constructor constraint is omitted to allow heterogeneous event types.
- */
-// biome-ignore lint/suspicious/noExplicitAny: Constructor accepts any data type for variance compatibility
-export type AnyEventClass = {
-  readonly key: string;
-  new (data: any): MatadorEvent;
-};
-
-/**
- * Runtime schema entry stored in MatadorSchema (object format).
- * Uses AnySubscriber and AnyEventClass to allow heterogeneous event types.
- * Type safety is enforced at definition time via `schemaEntry()` helper.
- */
-export interface RuntimeSchemaEntry {
-  readonly eventClass: AnyEventClass;
-  readonly subscribers: readonly AnySubscriber[];
-}
-
-/**
- * Runtime schema tuple stored in MatadorSchema.
- * Uses AnySubscriber and AnyEventClass to allow heterogeneous event types.
- * Type safety is enforced at definition time via `schemaEntry()` helper.
- */
-export type RuntimeSchemaEntryTuple = readonly [
-  eventClass: AnyEventClass,
-  subscribers: readonly AnySubscriber[],
-];
-
-/**
- * Matador schema mapping event keys to their definitions.
- * Supports both object format (SchemaEntry) and tuple format (SchemaEntryTuple).
- *
- * For type-safe schema definitions, use the `bind` helper function
- * which ensures subscribers are compatible with their event class.
- *
- * @example
- * ```typescript
- * // Type-safe with bind helper:
- * const schema = {
- *   [UserCreatedEvent.key]: bind(UserCreatedEvent, [emailSubscriber]),
- * } satisfies MatadorSchema;
- *
- * // Or inline (less type-safe):
- * const schema: MatadorSchema = {
- *   [UserCreatedEvent.key]: [UserCreatedEvent, [emailSubscriber]],
- * };
- * ```
- */
-export type MatadorSchema = {
-  readonly [eventKey: string]: RuntimeSchemaEntry | RuntimeSchemaEntryTuple;
-};
-
-/**
- * Type guard to check if a schema entry is in tuple format.
- */
-export function isSchemaEntryTuple(
-  entry: RuntimeSchemaEntry | RuntimeSchemaEntryTuple,
-): entry is RuntimeSchemaEntryTuple {
-  return Array.isArray(entry);
-}
-
-/**
- * Options for schema registration.
- */
-export interface RegisterOptions {
-  /** Override existing registration if present */
-  readonly override?: boolean;
-}
-
-/**
- * Result of schema validation.
- */
-export interface SchemaValidationResult {
-  readonly valid: boolean;
-  readonly issues: readonly SchemaIssue[];
-}
-
-/**
- * Individual schema issue.
- */
-export interface SchemaIssue {
-  readonly severity: 'error' | 'warning';
-  readonly eventKey: string;
-  readonly message: string;
-}
-
-/**
- * Plugin definition for adding subscribers to multiple events.
- */
-export interface SchemaPlugin {
-  /** The subscriber to add to events */
-  readonly subscriber: AnySubscriber;
-
-  /** Event keys to exclude from this plugin */
-  readonly exclusions?: readonly string[];
-}
-
-/**
- * Installs plugins (global subscribers) into a schema.
- * Each plugin subscriber is added to all events except those in its exclusions list.
- *
- * @param schema - The base schema to extend
- * @param plugins - Array of plugins to install
- * @returns A new schema with plugin subscribers added
- *
- * @example
- * ```typescript
- * const baseSchema: MatadorSchema = {
- *   [UserCreatedEvent.key]: [UserCreatedEvent, [sendWelcomeEmail]],
- *   [OrderPlacedEvent.key]: [OrderPlacedEvent, [processOrder]],
- *   [ChatMessageSent.key]: [ChatMessageSent, [notifyRecipient]],
- * };
- *
- * const schema = installPlugins(baseSchema, [
- *   {
- *     subscriber: logToBigQuery,
- *     exclusions: [ChatMessageSent.key], // Don't log chat messages
- *   },
- *   {
- *     subscriber: trackAnalytics,
- *     // No exclusions - added to all events
- *   },
- * ]);
- * ```
- */
-export function installPlugins(
-  schema: MatadorSchema,
-  plugins: readonly SchemaPlugin[],
-): MatadorSchema {
-  const result: Record<string, RuntimeSchemaEntry | RuntimeSchemaEntryTuple> =
-    {};
-
-  for (const [eventKey, entry] of Object.entries(schema)) {
-    // Get existing event class and subscribers
-    const [eventClass, existingSubscribers] = isSchemaEntryTuple(entry)
-      ? [entry[0], entry[1]]
-      : [entry.eventClass, entry.subscribers];
-
-    // Collect subscribers to add from plugins
-    const pluginSubscribers: AnySubscriber[] = [];
-    for (const plugin of plugins) {
-      if (!plugin.exclusions?.includes(eventKey)) {
-        pluginSubscribers.push(plugin.subscriber);
-      }
-    }
-
-    // Create new entry with combined subscribers
-    result[eventKey] = [
-      eventClass,
-      [...existingSubscribers, ...pluginSubscribers],
-    ];
-  }
-
-  return result;
-}