@zdavison/matador 2.0.1

package/src/schema/types.ts

@@ -0,0 +1,217 @@
+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;
+}

package/src/topology/builder.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, it } from 'bun:test';
+import { TopologyBuilder, TopologyValidationError } from './builder.js';
+
+describe('TopologyBuilder', () => {
+  describe('withNamespace', () => {
+    it('should set the namespace', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('myapp')
+        .addQueue('events')
+        .build();
+
+      expect(topology.namespace).toBe('myapp');
+    });
+
+    it('should reject empty namespace', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('')
+        .addQueue('events');
+
+      expect(() => builder.build()).toThrow(TopologyValidationError);
+    });
+
+    it('should reject namespace starting with number', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('123app')
+        .addQueue('events');
+
+      expect(() => builder.build()).toThrow(TopologyValidationError);
+    });
+
+    it('should allow hyphens and underscores in namespace', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('my-app_v2')
+        .addQueue('events')
+        .build();
+
+      expect(topology.namespace).toBe('my-app_v2');
+    });
+  });
+
+  describe('addQueue', () => {
+    it('should add a queue with defaults', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .build();
+
+      expect(topology.queues).toHaveLength(1);
+      expect(topology.queues[0]?.name).toBe('events');
+    });
+
+    it('should add queue with options', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events', {
+          concurrency: 5,
+          consumerTimeout: 30000,
+          priorities: true,
+        })
+        .build();
+
+      expect(topology.queues[0]?.concurrency).toBe(5);
+      expect(topology.queues[0]?.consumerTimeout).toBe(30000);
+      expect(topology.queues[0]?.priorities).toBe(true);
+    });
+
+    it('should add multiple queues', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .addQueue('notifications')
+        .addQueue('analytics')
+        .build();
+
+      expect(topology.queues).toHaveLength(3);
+    });
+
+    it('should reject duplicate queue names', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .addQueue('events');
+
+      expect(() => builder.build()).toThrow('Duplicate queue name');
+    });
+
+    it('should reject empty queue name', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('');
+
+      expect(() => builder.build()).toThrow('Queue name cannot be empty');
+    });
+
+    it('should reject queue names starting with number', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('123queue');
+
+      expect(() => builder.build()).toThrow('must start with a letter');
+    });
+
+    it('should reject invalid concurrency', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events', { concurrency: 0 });
+
+      expect(() => builder.build()).toThrow('concurrency must be at least 1');
+    });
+
+    it('should reject negative consumer timeout', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events', { consumerTimeout: -1 });
+
+      expect(() => builder.build()).toThrow(
+        'consumer timeout must be non-negative',
+      );
+    });
+  });
+
+  describe('withDeadLetter', () => {
+    it('should configure dead letter settings', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .withDeadLetter({
+          unhandled: { enabled: false },
+          undeliverable: { enabled: true },
+        })
+        .build();
+
+      expect(topology.deadLetter.unhandled.enabled).toBe(false);
+      expect(topology.deadLetter.undeliverable.enabled).toBe(true);
+    });
+
+    it('should merge with defaults', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .withDeadLetter({ unhandled: { enabled: false } })
+        .build();
+
+      // undeliverable should keep default
+      expect(topology.deadLetter.unhandled.enabled).toBe(false);
+      expect(topology.deadLetter.undeliverable.enabled).toBe(true);
+    });
+  });
+
+  describe('withRetry', () => {
+    it('should configure retry settings', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .withRetry({
+          enabled: true,
+          defaultDelayMs: 5000,
+          maxDelayMs: 600000,
+        })
+        .build();
+
+      expect(topology.retry.enabled).toBe(true);
+      expect(topology.retry.defaultDelayMs).toBe(5000);
+      expect(topology.retry.maxDelayMs).toBe(600000);
+    });
+
+    it('should reject negative default delay', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .withRetry({ defaultDelayMs: -1 });
+
+      expect(() => builder.build()).toThrow('delay must be non-negative');
+    });
+
+    it('should reject max delay less than default', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .withRetry({
+          defaultDelayMs: 10000,
+          maxDelayMs: 5000,
+        });
+
+      expect(() => builder.build()).toThrow(
+        'Max retry delay must be greater than or equal to default',
+      );
+    });
+  });
+
+  describe('withoutRetry', () => {
+    it('should disable retry', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .withoutRetry()
+        .build();
+
+      expect(topology.retry.enabled).toBe(false);
+    });
+  });
+
+  describe('withoutDeadLetter', () => {
+    it('should disable dead letter queues', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .withoutDeadLetter()
+        .build();
+
+      expect(topology.deadLetter.unhandled.enabled).toBe(false);
+      expect(topology.deadLetter.undeliverable.enabled).toBe(false);
+    });
+  });
+
+  describe('validate', () => {
+    it('should return issues without throwing', () => {
+      const builder = TopologyBuilder.create();
+      const issues = builder.validate();
+
+      expect(issues.length).toBeGreaterThan(0);
+      expect(issues).toContain('Namespace is required');
+      expect(issues).toContain('At least one queue is required');
+    });
+
+    it('should return empty array for valid topology', () => {
+      const builder = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events');
+
+      const issues = builder.validate();
+      expect(issues).toHaveLength(0);
+    });
+  });
+
+  describe('build', () => {
+    it('should throw TopologyValidationError with issues', () => {
+      const builder = TopologyBuilder.create();
+
+      try {
+        builder.build();
+        expect(true).toBe(false); // Should not reach here
+      } catch (error) {
+        expect(error).toBeInstanceOf(TopologyValidationError);
+        expect((error as TopologyValidationError).issues).toContain(
+          'Namespace is required',
+        );
+      }
+    });
+
+    it('should return immutable topology', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('events')
+        .build();
+
+      // Verify structure
+      expect(topology.namespace).toBe('test');
+      expect(topology.queues).toHaveLength(1);
+      expect(topology.deadLetter.unhandled.enabled).toBe(true);
+      expect(topology.retry.enabled).toBe(true);
+    });
+  });
+
+  describe('exact queue option', () => {
+    it('should mark queue as exact (external)', () => {
+      const topology = TopologyBuilder.create()
+        .withNamespace('test')
+        .addQueue('external-queue', { exact: true })
+        .build();
+
+      expect(topology.queues[0]?.exact).toBe(true);
+    });
+  });
+});

package/src/topology/builder.ts

@@ -0,0 +1,199 @@
+import type { HasDescription } from '../errors/index.js';
+import type {
+  DeadLetterConfig,
+  QueueDefinition,
+  RetryConfig,
+  Topology,
+} from './types.js';
+
+/**
+ * Options for adding a queue.
+ * Excludes 'name' as that is provided as the first argument to addQueue.
+ */
+export type QueueOptions = Omit<QueueDefinition, 'name'>;
+
+/**
+ * Error thrown when topology validation fails.
+ */
+export class TopologyValidationError extends Error implements HasDescription {
+  readonly description =
+    'The topology configuration is invalid. Check the issues array for ' +
+    'specific validation failures such as missing namespace, invalid queue ' +
+    'names, or conflicting settings. This error occurs during Matador ' +
+    'initialization and must be fixed in the configuration.';
+
+  constructor(
+    message: string,
+    public readonly issues: readonly string[],
+  ) {
+    super(message);
+    this.name = 'TopologyValidationError';
+  }
+}
+
+/**
+ * Fluent builder for creating Topology configurations.
+ */
+export class TopologyBuilder {
+  /**
+   * Creates a new TopologyBuilder instance.
+   */
+  static create(): TopologyBuilder {
+    return new TopologyBuilder();
+  }
+
+  private namespace = '';
+  private queues: QueueDefinition[] = [];
+  private deadLetter: DeadLetterConfig = {
+    unhandled: { enabled: true },
+    undeliverable: { enabled: true },
+  };
+  private retry: RetryConfig = {
+    enabled: true,
+    defaultDelayMs: 1000,
+    maxDelayMs: 300000, // 5 minutes
+  };
+
+  /**
+   * Sets the namespace prefix for all queues.
+   */
+  withNamespace(namespace: string): this {
+    this.namespace = namespace;
+    return this;
+  }
+
+  /**
+   * Adds a queue to the topology.
+   */
+  addQueue(name: string, options: QueueOptions = {}): this {
+    this.queues.push({ name, ...options });
+    return this;
+  }
+
+  /**
+   * Alias for addQueue().
+   */
+  queue(name: string, options: QueueOptions = {}): this {
+    return this.addQueue(name, options);
+  }
+
+  /**
+   * Configures dead-letter queue settings.
+   */
+  withDeadLetter(config: Partial<DeadLetterConfig>): this {
+    this.deadLetter = {
+      unhandled: config.unhandled ?? this.deadLetter.unhandled,
+      undeliverable: config.undeliverable ?? this.deadLetter.undeliverable,
+    };
+    return this;
+  }
+
+  /**
+   * Configures retry settings.
+   */
+  withRetry(config: Partial<RetryConfig>): this {
+    this.retry = {
+      enabled: config.enabled ?? this.retry.enabled,
+      defaultDelayMs: config.defaultDelayMs ?? this.retry.defaultDelayMs,
+      maxDelayMs: config.maxDelayMs ?? this.retry.maxDelayMs,
+    };
+    return this;
+  }
+
+  /**
+   * Disables retry functionality.
+   */
+  withoutRetry(): this {
+    this.retry = { ...this.retry, enabled: false };
+    return this;
+  }
+
+  /**
+   * Disables dead-letter queues.
+   */
+  withoutDeadLetter(): this {
+    this.deadLetter = {
+      unhandled: { enabled: false },
+      undeliverable: { enabled: false },
+    };
+    return this;
+  }
+
+  /**
+   * Validates the topology configuration.
+   */
+  validate(): readonly string[] {
+    const issues: string[] = [];
+
+    if (!this.namespace || this.namespace.trim() === '') {
+      issues.push('Namespace is required');
+    } else if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(this.namespace)) {
+      issues.push(
+        'Namespace must start with a letter and contain only alphanumeric characters, underscores, and hyphens',
+      );
+    }
+
+    if (this.queues.length === 0) {
+      issues.push('At least one queue is required');
+    }
+
+    const queueNames = new Set<string>();
+    for (const queue of this.queues) {
+      if (!queue.name || queue.name.trim() === '') {
+        issues.push('Queue name cannot be empty');
+      } else if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(queue.name)) {
+        issues.push(
+          `Queue name "${queue.name}" must start with a letter and contain only alphanumeric characters, underscores, and hyphens`,
+        );
+      } else if (queueNames.has(queue.name)) {
+        issues.push(`Duplicate queue name: "${queue.name}"`);
+      } else {
+        queueNames.add(queue.name);
+      }
+
+      if (queue.concurrency !== undefined && queue.concurrency < 1) {
+        issues.push(`Queue "${queue.name}" concurrency must be at least 1`);
+      }
+
+      if (queue.consumerTimeout !== undefined && queue.consumerTimeout < 0) {
+        issues.push(
+          `Queue "${queue.name}" consumer timeout must be non-negative`,
+        );
+      }
+    }
+
+    if (this.retry.enabled) {
+      if (this.retry.defaultDelayMs < 0) {
+        issues.push('Default retry delay must be non-negative');
+      }
+      if (this.retry.maxDelayMs < this.retry.defaultDelayMs) {
+        issues.push(
+          'Max retry delay must be greater than or equal to default delay',
+        );
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * Builds the topology configuration.
+   * @throws TopologyValidationError if validation fails
+   */
+  build(): Topology {
+    const issues = this.validate();
+    if (issues.length > 0) {
+      throw new TopologyValidationError(
+        `Invalid topology: ${issues.join('; ')}`,
+        issues,
+      );
+    }
+
+    return {
+      namespace: this.namespace,
+      queues: [...this.queues],
+      deadLetter: this.deadLetter,
+      retry: this.retry,
+    };
+  }
+}

package/src/topology/index.ts

@@ -0,0 +1,15 @@
+export type {
+  DeadLetterConfig,
+  DeadLetterQueueConfig,
+  QueueDefinition,
+  RetryConfig,
+  Topology,
+} from './types.js';
+export {
+  getDeadLetterQueueName,
+  getQualifiedQueueName,
+  getRetryQueueName,
+} from './types.js';
+
+export type { QueueOptions } from './builder.js';
+export { TopologyBuilder, TopologyValidationError } from './builder.js';