@zdavison/matador 2.0.1

package/src/retry/standard-policy.ts

@@ -0,0 +1,156 @@
+import {
+  IdempotentMessageCannotRetryError,
+  MessageMaybePoisonedError,
+  isAssertionError,
+  isDoRetry,
+  isDontRetry,
+} from '../errors/index.js';
+import type { RetryContext, RetryDecision, RetryPolicy } from './policy.js';
+
+/**
+ * Configuration for the standard retry policy.
+ */
+export interface StandardRetryPolicyConfig {
+  /** Maximum number of attempts before dead-lettering */
+  readonly maxAttempts: number;
+
+  /** Base delay between retries in milliseconds */
+  readonly baseDelay: number;
+
+  /** Maximum delay between retries in milliseconds */
+  readonly maxDelay: number;
+
+  /** Multiplier for exponential backoff */
+  readonly backoffMultiplier: number;
+
+  /**
+   * Maximum native delivery count before considering message poisoned.
+   * This prevents crash loops from messages that crash the worker.
+   * Poison messages are sent directly to the dead-letter queue.
+   * Default: 5
+   */
+  readonly maxDeliveries: number;
+}
+
+/**
+ * Default configuration values.
+ */
+export const defaultRetryConfig: StandardRetryPolicyConfig = {
+  maxAttempts: 3,
+  baseDelay: 1000,
+  maxDelay: 300000, // 5 minutes
+  backoffMultiplier: 2,
+  maxDeliveries: 5,
+};
+
+/**
+ * Standard retry policy implementing Matador v1 behavior.
+ *
+ * Decision logic (in priority order):
+ * 1. Poison message → dead-letter (prevent crash loops)
+ * 2. EventAssertionError → dead-letter (never retry)
+ * 3. DontRetry → dead-letter (explicit no-retry)
+ * 4. DoRetry → retry if under max attempts
+ * 5. Max attempts exceeded → dead-letter
+ * 6. Non-idempotent subscriber on redelivery → dead-letter
+ * 7. Default → retry with exponential backoff
+ */
+export class StandardRetryPolicy implements RetryPolicy {
+  private readonly config: StandardRetryPolicyConfig;
+
+  constructor(config: Partial<StandardRetryPolicyConfig> = {}) {
+    this.config = { ...defaultRetryConfig, ...config };
+  }
+
+  shouldRetry(context: RetryContext): RetryDecision {
+    const { envelope, error, subscriber, receipt } = context;
+    const errorMessage = error.message;
+
+    // 1. Poison message detection - prevent crash loops
+    if (receipt.deliveryCount >= this.config.maxDeliveries) {
+      const poisonError = new MessageMaybePoisonedError(
+        envelope.id,
+        receipt.deliveryCount,
+        this.config.maxDeliveries,
+      );
+      return {
+        action: 'dead-letter',
+        queue: 'undeliverable',
+        reason: poisonError.message,
+      };
+    }
+
+    // 2. Assertion errors never retry
+    if (isAssertionError(error)) {
+      return {
+        action: 'dead-letter',
+        queue: 'undeliverable',
+        reason: `assertion error: ${errorMessage}`,
+      };
+    }
+
+    // 3. Explicit no-retry
+    if (isDontRetry(error)) {
+      return {
+        action: 'dead-letter',
+        queue: 'undeliverable',
+        reason: errorMessage,
+      };
+    }
+
+    // 4. Explicit retry request
+    if (isDoRetry(error)) {
+      if (receipt.attemptNumber >= this.config.maxAttempts) {
+        return {
+          action: 'dead-letter',
+          queue: 'undeliverable',
+          reason: `max attempts exceeded (${this.config.maxAttempts}) with forced retry`,
+        };
+      }
+      return {
+        action: 'retry',
+        delay: this.getDelay(context),
+      };
+    }
+
+    // 5. Max attempts exceeded
+    if (receipt.attemptNumber >= this.config.maxAttempts) {
+      return {
+        action: 'dead-letter',
+        queue: 'undeliverable',
+        reason: `max attempts exceeded (${this.config.maxAttempts})`,
+      };
+    }
+
+    // 6. Non-idempotent subscriber on redelivery
+    // 'no' and 'unknown' are treated the same (safer default)
+    if (
+      receipt.redelivered &&
+      (subscriber.idempotent === 'no' || subscriber.idempotent === 'unknown')
+    ) {
+      const idempotentError = new IdempotentMessageCannotRetryError(
+        envelope.id,
+        subscriber.name,
+      );
+      return {
+        action: 'dead-letter',
+        queue: 'undeliverable',
+        reason: idempotentError.message,
+      };
+    }
+
+    // 7. Default: retry with backoff
+    return {
+      action: 'retry',
+      delay: this.getDelay(context),
+    };
+  }
+
+  getDelay(context: RetryContext): number {
+    const attempt = context.receipt.attemptNumber;
+    const delay =
+      this.config.baseDelay *
+      Math.pow(this.config.backoffMultiplier, attempt - 1);
+    return Math.min(delay, this.config.maxDelay);
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,16 @@
+export type {
+  AnyEventClass,
+  MatadorSchema,
+  RegisterOptions,
+  RuntimeSchemaEntry,
+  RuntimeSchemaEntryTuple,
+  SchemaEntry,
+  SchemaEntryTuple,
+  SchemaIssue,
+  SchemaPlugin,
+  SchemaValidationResult,
+} from './types.js';
+
+export { bind, installPlugins, isSchemaEntryTuple } from './types.js';
+
+export { SchemaError, SchemaRegistry } from './registry.js';

package/src/schema/registry.test.ts

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