@zdavison/matador 2.0.8 → 2.0.10

package/src/transport/transport.ts

@@ -1,200 +0,0 @@
-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

@@ -1,53 +0,0 @@
-/**
- * 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/dispatcher.ts

@@ -1,18 +0,0 @@
-import type { SendResult } from '../core/fanout.js';
-import type { Event, EventClass, EventOptions } from './event.js';
-
-/**
- * Interface for dispatching events.
- * Implemented by Matador to allow subscribers to send events.
- */
-export interface Dispatcher {
-  /**
-   * Sends an event to all registered subscribers.
-   */
-  send<T>(
-    eventClass: EventClass<T>,
-    data: T,
-    options?: EventOptions,
-  ): Promise<SendResult>;
-  send<T>(event: Event<T>, options?: EventOptions): Promise<SendResult>;
-}

package/src/types/envelope.ts

@@ -1,244 +0,0 @@
-import type { Importance } from './common.js';
-import type { Event, EventStatic } from './event.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 }),
-    },
-  };
-}
-
-/**
- * Options for creating a dummy envelope.
- * All fields are optional and will use sensible defaults if not provided.
- */
-export interface CreateDummyEnvelopeOptions {
-  readonly id?: string | undefined;
-  readonly eventKey?: string | undefined;
-  readonly eventDescription?: string | undefined;
-  readonly targetSubscriber?: string | undefined;
-  readonly importance?: Importance | undefined;
-  readonly correlationId?: string | undefined;
-  readonly metadata?: Record<string, unknown> | undefined;
-  readonly delayMs?: number | undefined;
-}
-
-/**
- * Type helper to extract the data type from an Event, or return T as-is.
- */
-type ExtractData<T> = T extends Event<infer D> ? D : T;
-
-/**
- * Checks if a value is a Matador Event (has data property and constructor with key).
- */
-function isEvent<T>(value: unknown): value is Event<T> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'data' in value &&
-    typeof (value.constructor as EventStatic).key === 'string'
-  );
-}
-
-/**
- * Helper to create a test envelope for a given event instance or raw data.
- * Useful for unit testing subscriber callbacks directly.
- *
- * When passing an Event instance, the eventKey and eventDescription will be
- * automatically extracted from the event class (unless overridden in options).
- *
- * @example With raw data
- * ```typescript
- * const envelope = createDummyEnvelope({ userId: '123', email: 'test@example.com' });
- * ```
- *
- * @example With an Event instance
- * ```typescript
- * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
- * const envelope = createDummyEnvelope(event);
- * // eventKey is automatically set to UserCreatedEvent.key
- * await mySubscriber.callback(envelope, event.data);
- * ```
- *
- * @example With options
- * ```typescript
- * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
- * const envelope = createDummyEnvelope(event, {
- *   metadata: { traceId: 'abc-123' },
- *   correlationId: 'request-456',
- * });
- * ```
- */
-export function createDummyEnvelope<T>(
-  dataOrEvent: T,
-  options?: CreateDummyEnvelopeOptions,
-): Envelope<ExtractData<T>> {
-  let data: ExtractData<T>;
-  let eventKey = options?.eventKey ?? 'dummy.event.key';
-  let eventDescription = options?.eventDescription;
-
-  if (isEvent(dataOrEvent)) {
-    data = dataOrEvent.data as ExtractData<T>;
-    const eventStatic = dataOrEvent.constructor as EventStatic;
-    eventKey = options?.eventKey ?? eventStatic.key;
-    eventDescription = options?.eventDescription ?? eventStatic.description;
-  } else {
-    data = dataOrEvent as ExtractData<T>;
-  }
-
-  return createEnvelope({
-    data,
-    eventKey,
-    eventDescription,
-    targetSubscriber: options?.targetSubscriber ?? 'dummy-subscriber',
-    importance: options?.importance ?? 'can-ignore',
-    id: options?.id,
-    correlationId: options?.correlationId,
-    metadata: options?.metadata,
-    delayMs: options?.delayMs,
-  });
-}

package/src/types/event.test.ts

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