@zdavison/matador 2.0.1

package/dist/schema/registry.test.js

@@ -0,0 +1,278 @@
+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 {
+    data;
+    static key = 'test.event';
+    static description = 'A test event';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+class AliasedEvent extends MatadorEvent {
+    data;
+    static key = 'user.created.v2';
+    static description = 'User created event with aliases';
+    static aliases = ['user.created', 'user.created.v1'];
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+describe('SchemaRegistry', () => {
+    let registry;
+    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 {
+                data;
+                static key = 'another.event';
+                static description = 'Another event';
+                static aliases = ['user.created']; // conflicts with AliasedEvent
+                constructor(data) {
+                    super();
+                    this.data = data;
+                }
+            }
+            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/dist/schema/types.d.ts

@@ -0,0 +1,158 @@
+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 declare function bind<T extends MatadorEvent>(eventClass: EventClass<T['data']>, subscribers: readonly (Subscriber<T> | SubscriberStub)[]): SchemaEntryTuple<T>;
+/**
+ * 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.
+ */
+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 declare function isSchemaEntryTuple(entry: RuntimeSchemaEntry | RuntimeSchemaEntryTuple): entry is RuntimeSchemaEntryTuple;
+/**
+ * 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 declare function installPlugins(schema: MatadorSchema, plugins: readonly SchemaPlugin[]): MatadorSchema;
+//# sourceMappingURL=types.d.ts.map

package/dist/schema/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IAChE,sBAAsB;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAE3C,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,EAAE,CAAC;CACnE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,SAAS;IAC7E,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjC,WAAW,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,EAAE;CACzD,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,YAAY,EACzC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EACjC,WAAW,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,EAAE,GACvD,gBAAgB,CAAC,CAAC,CAAC,CAErB;AAED;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,KAAK,IAAI,EAAE,GAAG,GAAG,YAAY,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS;IAC7C,UAAU,EAAE,aAAa;IACzB,WAAW,EAAE,SAAS,aAAa,EAAE;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,uBAAuB,CAAC;CAC3E,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,GAAG,uBAAuB,GAClD,KAAK,IAAI,uBAAuB,CAElC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IAEnC,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,aAAa,CA0Bf"}

package/dist/schema/types.js

@@ -0,0 +1,74 @@
+/**
+ * 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(eventClass, subscribers) {
+    return [eventClass, subscribers];
+}
+/**
+ * Type guard to check if a schema entry is in tuple format.
+ */
+export function isSchemaEntryTuple(entry) {
+    return Array.isArray(entry);
+}
+/**
+ * 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, plugins) {
+    const result = {};
+    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 = [];
+        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;
+}

package/dist/schema/types.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.test.d.ts.map

package/dist/schema/types.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test.d.ts","sourceRoot":"","sources":["../../src/schema/types.test.ts"],"names":[],"mappings":""}