@zdavison/matador 2.0.1

package/src/transport/transport.ts

@@ -0,0 +1,200 @@
+import type { Topology } from '../topology/types.js';
+import type { Envelope } from '../types/index.js';
+import type { TransportCapabilities } from './capabilities.js';
+
+/**
+ * Transport-specific send options.
+ * Each transport can define its own options under its transport name key.
+ */
+export interface TransportSendOptions {
+  /** RabbitMQ-specific send options */
+  readonly rabbitmq?: RabbitMQSendOptions | undefined;
+}
+
+/**
+ * RabbitMQ-specific options for sending messages.
+ */
+export interface RabbitMQSendOptions {
+  /** Message expiration in milliseconds */
+  readonly expiration?: number | undefined;
+
+  /** Message persistence mode */
+  readonly persistent?: boolean | undefined;
+
+  /** Routing key override */
+  readonly routingKey?: string | undefined;
+}
+
+/**
+ * Options for sending a message.
+ */
+export interface SendOptions {
+  /** Delay delivery by this many milliseconds */
+  readonly delay?: number | undefined;
+
+  /** Priority level (0-255, higher = more important) */
+  readonly priority?: number | undefined;
+
+  /** Transport-specific options */
+  readonly transport?: TransportSendOptions | undefined;
+}
+
+/**
+ * Transport-specific subscribe options.
+ * Each transport can define its own options under its transport name key.
+ */
+export interface TransportSubscribeOptions {
+  /** RabbitMQ-specific subscribe options */
+  readonly rabbitmq?: RabbitMQSubscribeOptions | undefined;
+}
+
+/**
+ * RabbitMQ-specific options for subscribing.
+ */
+export interface RabbitMQSubscribeOptions {
+  /** Consumer tag */
+  readonly consumerTag?: string | undefined;
+
+  /** Prefetch count (overrides concurrency option) */
+  readonly prefetch?: number | undefined;
+
+  /** Exclusive consumer */
+  readonly exclusive?: boolean | undefined;
+}
+
+/**
+ * Options for subscribing to a queue.
+ */
+export interface SubscribeOptions {
+  /** Concurrency hint (number of concurrent handlers) */
+  readonly concurrency?: number | undefined;
+
+  /** Override default delivery semantics */
+  readonly deliveryMode?: 'at-least-once' | 'at-most-once' | undefined;
+
+  /** Transport-specific options */
+  readonly transport?: TransportSubscribeOptions | undefined;
+}
+
+/**
+ * Receipt for a received message, used for acknowledgment.
+ */
+export interface MessageReceipt {
+  /** Opaque handle for the transport to identify the message */
+  readonly handle: unknown;
+
+  /** True if this is a redelivery (transport-reported if capable) */
+  readonly redelivered: boolean;
+
+  /** 1-based attempt number (transport-reported if capable, else from envelope) */
+  readonly attemptNumber: number;
+
+  /**
+   * Native delivery count from the transport.
+   * Tracks how many times this specific message was delivered without acknowledgment.
+   * Used for poison message detection to prevent crash loops.
+   * For transports that don't track this, defaults to attemptNumber.
+   */
+  readonly deliveryCount: number;
+
+  /** Original queue/topic the message came from */
+  readonly sourceQueue: string;
+
+  /**
+   * The name of the transport that received this message (e.g., 'local', 'rabbitmq').
+   * For MultiTransport, this is the actual underlying transport, not the wrapper name.
+   */
+  readonly sourceTransport: string;
+}
+
+/**
+ * Handler function for processing received messages.
+ */
+export type MessageHandler = (
+  envelope: Envelope,
+  receipt: MessageReceipt,
+) => Promise<void>;
+
+/**
+ * Subscription handle for managing active subscriptions.
+ */
+export interface Subscription {
+  /** Cancels the subscription */
+  unsubscribe(): Promise<void>;
+
+  /** Whether the subscription is currently active */
+  readonly isActive: boolean;
+}
+
+/**
+ * Transport interface - the minimal abstraction for message delivery.
+ * Transports handle only I/O; all business logic lives in Matador core.
+ */
+export interface Transport {
+  /** Transport identifier */
+  readonly name: string;
+
+  /** Capabilities supported by this transport */
+  readonly capabilities: TransportCapabilities;
+
+  /**
+   * Establishes connection to the message broker.
+   * Should handle initial connection with retries.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Gracefully disconnects from the message broker.
+   * Should close all consumers before connection.
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Returns whether the transport is currently connected.
+   */
+  isConnected(): boolean;
+
+  /**
+   * Translates and applies the generic topology to the transport.
+   * Creates necessary queues, exchanges, topics, etc.
+   */
+  applyTopology(topology: Topology): Promise<void>;
+
+  /**
+   * Sends a message to the specified queue.
+   * @returns The name of the transport that was used (useful for MultiTransport)
+   */
+  send(
+    queue: string,
+    envelope: Envelope,
+    options?: SendOptions,
+  ): Promise<Transport['name']>;
+
+  /**
+   * Subscribes to messages on the specified queue.
+   * The handler receives decoded envelopes and receipts.
+   */
+  subscribe(
+    queue: string,
+    handler: MessageHandler,
+    options?: SubscribeOptions,
+  ): Promise<Subscription>;
+
+  /**
+   * Acknowledges/completes a message.
+   * Called after processing is done (success, retry scheduled, or dead-lettered).
+   */
+  complete(receipt: MessageReceipt): Promise<void>;
+
+  /**
+   * Sends a message to the dead-letter queue.
+   * For transports with native DL routing, may use native mechanism.
+   * For others, sends to DLQ then completes original.
+   */
+  sendToDeadLetter?(
+    receipt: MessageReceipt,
+    dlqName: string,
+    envelope: Envelope,
+    reason: string,
+  ): Promise<void>;
+}

package/src/types/common.ts

@@ -0,0 +1,53 @@
+/**
+ * Delivery semantics for message processing.
+ * - 'at-least-once': Acknowledge after processing (may redeliver on failure)
+ * - 'at-most-once': Acknowledge before processing (no redelivery, may lose messages)
+ */
+export type DeliveryMode = 'at-least-once' | 'at-most-once';
+
+/**
+ * Importance level for subscribers, used for monitoring and alerting prioritization.
+ */
+export type Importance =
+  | 'can-ignore'
+  | 'should-investigate'
+  | 'must-investigate';
+
+/**
+ * Idempotency declaration for subscribers.
+ * - 'yes': Safe to retry on failure (subscriber handles duplicates)
+ * - 'no': Not safe to retry, may cause duplicate side effects
+ * - 'unknown': Idempotency not determined (default)
+ * - 'resumable': Uses checkpoint-based idempotency via io() calls
+ */
+export type Idempotency = 'yes' | 'no' | 'unknown' | 'resumable';
+
+/**
+ * Result of a validation operation.
+ */
+export interface ValidationResult {
+  readonly valid: boolean;
+  readonly errors: readonly ValidationError[];
+}
+
+/**
+ * Individual validation error.
+ */
+export interface ValidationError {
+  readonly path: string;
+  readonly message: string;
+}
+
+/**
+ * Creates a successful validation result.
+ */
+export function validResult(): ValidationResult {
+  return { valid: true, errors: [] };
+}
+
+/**
+ * Creates a failed validation result.
+ */
+export function invalidResult(errors: ValidationError[]): ValidationResult {
+  return { valid: false, errors };
+}

package/src/types/envelope.ts

@@ -0,0 +1,152 @@
+import type { Importance } from './common.js';
+
+/**
+ * Message envelope containing the event data and routing/observability metadata.
+ * This is the transport-agnostic message format used throughout Matador.
+ */
+export interface Envelope<T = unknown> {
+  /** Unique message ID (UUID v4) */
+  readonly id: string;
+
+  /** The event data */
+  readonly data: T;
+
+  /** Routing, processing state, and observability metadata */
+  readonly docket: Docket;
+}
+
+/**
+ * Metadata associated with an envelope for routing, processing state, and observability.
+ */
+export interface Docket {
+  // === Routing ===
+
+  /** Event key for routing */
+  readonly eventKey: string;
+
+  /** Human-readable description of the event (for observability/logging) */
+  readonly eventDescription?: string | undefined;
+
+  /** Target subscriber name for 1:1 routing */
+  readonly targetSubscriber: string;
+
+  /** Original queue before any dead-letter routing */
+  originalQueue?: string | undefined;
+
+  /** Scheduled processing time for delayed messages (ISO 8601 string) */
+  scheduledFor?: string | undefined;
+
+  // === Processing State ===
+
+  /**
+   * Attempt counter managed by Matador (1-based).
+   * Incremented on each retry. Used when transport doesn't track attempts.
+   */
+  attempts: number;
+
+  /** When the envelope was first created (ISO 8601 string) */
+  readonly createdAt: string;
+
+  /** Error message from first failure (for debugging) */
+  firstError?: string | undefined;
+
+  /** Error message from most recent failure */
+  lastError?: string | undefined;
+
+  // === Observability ===
+
+  /** Importance level for monitoring */
+  readonly importance: Importance;
+
+  /** Correlation ID for request tracing */
+  readonly correlationId?: string | undefined;
+
+  /**
+   * Custom metadata provided by the application.
+   * This is the merged result of universal metadata (from loadUniversalMetadata hook)
+   * and event-specific metadata (from dispatch options). Event-specific metadata
+   * overrides universal metadata when keys conflict.
+   */
+  readonly metadata?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Fields from Docket that can be specified when creating an envelope.
+ */
+type DocketCreateFields = Pick<
+  Docket,
+  | 'eventKey'
+  | 'eventDescription'
+  | 'targetSubscriber'
+  | 'importance'
+  | 'correlationId'
+>;
+
+/**
+ * Options for creating an envelope.
+ */
+export interface CreateEnvelopeOptions<T> extends DocketCreateFields {
+  /** Optional custom ID (defaults to UUID v4) */
+  readonly id?: string | undefined;
+
+  /** The event data */
+  readonly data: T;
+
+  /**
+   * Event-specific metadata to include in the docket.
+   * Will be merged with universal metadata, with these values taking precedence.
+   */
+  readonly metadata?: Record<string, unknown> | undefined;
+
+  /**
+   * Universal metadata loaded from the loadUniversalMetadata hook.
+   * This is provided by the fanout engine, not by the caller.
+   * @internal
+   */
+  readonly universalMetadata?: Record<string, unknown> | undefined;
+
+  /** Delay processing by this many milliseconds */
+  readonly delayMs?: number | undefined;
+}
+
+/**
+ * Creates a new envelope with the provided options.
+ */
+export function createEnvelope<T>(
+  options: CreateEnvelopeOptions<T>,
+): Envelope<T> {
+  const now = new Date().toISOString();
+
+  // Merge universal metadata with event-specific metadata
+  // Event-specific metadata takes precedence
+  const mergedMetadata =
+    options.universalMetadata || options.metadata
+      ? { ...options.universalMetadata, ...options.metadata }
+      : undefined;
+
+  return {
+    id: options.id ?? crypto.randomUUID(),
+    data: options.data,
+    docket: {
+      // Routing
+      eventKey: options.eventKey,
+      ...(options.eventDescription !== undefined && {
+        eventDescription: options.eventDescription,
+      }),
+      targetSubscriber: options.targetSubscriber,
+      ...(options.delayMs !== undefined &&
+        options.delayMs > 0 && {
+          scheduledFor: new Date(Date.now() + options.delayMs).toISOString(),
+        }),
+      // Processing state
+      attempts: 1,
+      createdAt: now,
+      // Observability
+      importance: options.importance,
+      ...(options.correlationId !== undefined && {
+        correlationId: options.correlationId,
+      }),
+      ...(mergedMetadata !== undefined && { metadata: mergedMetadata }),
+    },
+  };
+}

package/src/types/event.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'bun:test';
+import { createEnvelope } from './envelope.js';
+import { MatadorEvent } from './event.js';
+
+class UserCreatedEvent extends MatadorEvent {
+  static readonly key = 'user.created';
+  static readonly description = 'Fired when a new user is created';
+
+  constructor(public data: { userId: string; email: string }) {
+    super();
+  }
+}
+
+class OrderPlacedEvent extends MatadorEvent {
+  static readonly key = 'order.placed';
+  static readonly description = 'Fired when an order is placed';
+  static readonly aliases = ['order.created'];
+
+  constructor(public data: { orderId: string; amount: number }) {
+    super();
+  }
+}
+
+class MinimalEvent extends MatadorEvent {
+  static readonly key = 'minimal.event';
+
+  constructor(public data: { id: string }) {
+    super();
+  }
+}
+
+describe('Event', () => {
+  describe('static fields', () => {
+    it('should have static key field on class', () => {
+      expect(UserCreatedEvent.key).toBe('user.created');
+      expect(OrderPlacedEvent.key).toBe('order.placed');
+      expect(MinimalEvent.key).toBe('minimal.event');
+    });
+
+    it('should have static description field on class when defined', () => {
+      expect(UserCreatedEvent.description).toBe(
+        'Fired when a new user is created',
+      );
+      expect(OrderPlacedEvent.description).toBe(
+        'Fired when an order is placed',
+      );
+      expect(MinimalEvent.description).toBeUndefined();
+    });
+
+    it('should have static aliases field on class when defined', () => {
+      expect(UserCreatedEvent.aliases).toBeUndefined();
+      expect(OrderPlacedEvent.aliases).toEqual(['order.created']);
+      expect(MinimalEvent.aliases).toBeUndefined();
+    });
+  });
+
+  describe('instance data', () => {
+    it('should have instance data field', () => {
+      const event = new UserCreatedEvent({
+        userId: 'usr_001',
+        email: 'test@example.com',
+      });
+
+      expect(event.data).toEqual({
+        userId: 'usr_001',
+        email: 'test@example.com',
+      });
+    });
+  });
+});
+
+describe('Envelope with eventDescription', () => {
+  it('should include eventDescription in docket when provided', () => {
+    const event = new UserCreatedEvent({
+      userId: 'usr_123',
+      email: 'test@example.com',
+    });
+
+    const envelope = createEnvelope({
+      eventKey: UserCreatedEvent.key,
+      eventDescription: UserCreatedEvent.description,
+      targetSubscriber: 'test-subscriber',
+      data: event.data,
+      importance: 'should-investigate',
+    });
+
+    expect(envelope.docket.eventKey).toBe('user.created');
+    expect(envelope.docket.eventDescription).toBe(
+      'Fired when a new user is created',
+    );
+  });
+
+  it('should not include eventDescription in docket when undefined', () => {
+    const event = new MinimalEvent({ id: 'min_123' });
+
+    const envelope = createEnvelope({
+      eventKey: MinimalEvent.key,
+      eventDescription: MinimalEvent.description,
+      targetSubscriber: 'test-subscriber',
+      data: event.data,
+      importance: 'should-investigate',
+    });
+
+    expect(envelope.docket.eventKey).toBe('minimal.event');
+    expect(envelope.docket.eventDescription).toBeUndefined();
+  });
+
+  it('should serialize envelope with eventDescription for logging', () => {
+    const event = new OrderPlacedEvent({
+      orderId: 'ord_456',
+      amount: 99.99,
+    });
+
+    const envelope = createEnvelope({
+      eventKey: OrderPlacedEvent.key,
+      eventDescription: OrderPlacedEvent.description,
+      targetSubscriber: 'order-processor',
+      data: event.data,
+      importance: 'must-investigate',
+    });
+
+    const serialized = JSON.stringify(envelope);
+    const parsed = JSON.parse(serialized);
+
+    expect(parsed.docket.eventKey).toBe('order.placed');
+    expect(parsed.docket.eventDescription).toBe(
+      'Fired when an order is placed',
+    );
+    expect(parsed.data.orderId).toBe('ord_456');
+  });
+
+  it('should include eventDescription in hook logging context', () => {
+    const event = new UserCreatedEvent({
+      userId: 'usr_error',
+      email: 'error@example.com',
+    });
+
+    const envelope = createEnvelope({
+      eventKey: UserCreatedEvent.key,
+      eventDescription: UserCreatedEvent.description,
+      targetSubscriber: 'user-handler',
+      data: event.data,
+      importance: 'should-investigate',
+    });
+
+    // Simulating what would be logged in onEnqueueError hook
+    const errorLog = {
+      message: 'Failed to enqueue event',
+      eventKey: envelope.docket.eventKey,
+      eventDescription: envelope.docket.eventDescription,
+      data: envelope.data,
+    };
+
+    expect(errorLog.eventKey).toBe('user.created');
+    expect(errorLog.eventDescription).toBe('Fired when a new user is created');
+  });
+});

package/src/types/event.ts

@@ -0,0 +1,118 @@
+/**
+ * Unique event routing key type alias.
+ */
+export type EventKey = string;
+
+/**
+ * JSON-serializable primitive types.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+
+/**
+ * JSON-serializable value (recursive type for objects and arrays).
+ */
+export type JsonValue =
+  | JsonPrimitive
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * JSON-serializable record type for metadata.
+ */
+export type JsonRecord = Record<string, JsonValue>;
+
+/**
+ * Static properties required on Event classes for schema registration.
+ */
+export interface EventStatic<T = unknown> {
+  /** Unique routing key for the event */
+  readonly key: string;
+
+  /** Human-readable description of the event */
+  readonly description?: string;
+
+  /** Alternative names/keys for backwards compatibility */
+  readonly aliases?: readonly string[];
+
+  /** Create an instance from data (for deserialization) */
+  new (data: T): Event<T>;
+}
+
+/**
+ * Base interface for all events.
+ * Events represent something that happened in the system.
+ */
+export interface Event<T = unknown> {
+  /** The event data/payload */
+  readonly data: T;
+
+  /** Event-specific metadata (merged with EventOptions metadata on dispatch) */
+  readonly metadata?: JsonRecord | undefined;
+}
+
+/**
+ * Options for dispatching an event.
+ */
+export interface EventOptions {
+  /** Delay processing by this many milliseconds */
+  readonly delayMs?: number | undefined;
+
+  /** Correlation ID for request tracing */
+  readonly correlationId?: string | undefined;
+
+  /**
+   * Event-specific metadata to include in the docket.
+   * This metadata will be merged with:
+   * 1. Event instance metadata (if defined on the event)
+   * 2. Universal metadata from the loadUniversalMetadata hook
+   * With EventOptions metadata taking precedence over event metadata,
+   * and both taking precedence over universal metadata.
+   */
+  readonly metadata?: JsonRecord | undefined;
+}
+
+/**
+ * Abstract base class for creating Matador events.
+ * Extend this class to define custom events.
+ *
+ * @example
+ * ```typescript
+ * class UserCreatedEvent extends MatadorEvent {
+ *   static readonly key = 'user.created'
+ *   static readonly description = 'Fired when a new user is created'
+ *
+ *   constructor(
+ *     public data: { userId: string; email: string },
+ *     public metadata?: JsonRecord,
+ *   ) {
+ *     super()
+ *   }
+ * }
+ * ```
+ */
+export abstract class MatadorEvent<T = unknown> implements Event<T> {
+  static readonly key: string;
+  static readonly description?: string;
+  static readonly aliases?: readonly string[];
+
+  /** The event data/payload - must be defined by subclass */
+  abstract readonly data: T;
+
+  /** Event-specific metadata */
+  readonly metadata?: JsonRecord | undefined;
+}
+
+/**
+ * Type helper to extract the data type from an event class.
+ */
+export type EventData<E extends Event<unknown>> = E extends Event<infer T>
+  ? T
+  : never;
+
+/**
+ * Type helper to get the event class type.
+ */
+export type EventClass<T = unknown> = EventStatic<T> &
+  (new (
+    data: T,
+  ) => Event<T>);