@zdavison/matador 2.0.9 → 2.0.10

package/src/topology/types.ts

@@ -1,183 +0,0 @@
-/**
- * Transport-agnostic topology definition.
- * Matador owns the topology; transports translate and apply it.
- */
-export interface Topology {
-  /** Namespace prefix for all queues */
-  readonly namespace: string;
-
-  /** Work queues for processing events */
-  readonly queues: readonly QueueDefinition[];
-
-  /** Dead-letter queue configuration */
-  readonly deadLetter: DeadLetterConfig;
-
-  /** Retry queue configuration */
-  readonly retry: RetryConfig;
-}
-
-/**
- * Individual queue definition.
- */
-export interface QueueDefinition {
-  /** Queue name (will be prefixed with namespace unless exact: true) */
-  readonly name: string;
-
-  /** Concurrency for this queue */
-  readonly concurrency?: number | undefined;
-
-  /** Consumer timeout in milliseconds */
-  readonly consumerTimeout?: number | undefined;
-
-  /** Enable priority support if transport allows */
-  readonly priorities?: boolean | undefined;
-
-  /**
-   * When true, the queue name is used exactly as provided without any
-   * modification. The namespace prefix will NOT be added, and no other
-   * transformations will be applied. Use this for referencing external
-   * queues that are not managed by Matador.
-   */
-  readonly exact?: boolean | undefined;
-
-  /** Transport-specific queue options */
-  readonly transport?: TransportQueueOptions | undefined;
-}
-
-/**
- * Transport-specific queue options.
- * Each transport can define its own options under its transport name key.
- */
-export interface TransportQueueOptions {
-  /** RabbitMQ-specific queue options */
-  readonly rabbitmq?: RabbitMQQueueDefinition | undefined;
-}
-
-/**
- * RabbitMQ-specific queue definition options.
- */
-export interface RabbitMQQueueDefinition {
-  /**
-   * Exact RabbitMQ queue assertion options.
-   * When provided, these options completely replace all auto-computed defaults
-   * (durable, x-queue-type, x-dead-letter-exchange, etc.).
-   */
-  readonly options?: RabbitMQQueueOptions | undefined;
-}
-
-/**
- * RabbitMQ queue assertion options.
- * Maps to amqplib's Options.AssertQueue.
- */
-export interface RabbitMQQueueOptions {
-  /** Queue survives broker restart */
-  readonly durable?: boolean | undefined;
-
-  /** Queue is deleted when last consumer unsubscribes */
-  readonly autoDelete?: boolean | undefined;
-
-  /** Queue can only be used by the declaring connection */
-  readonly exclusive?: boolean | undefined;
-
-  /** Exchange to which dead-lettered messages are sent */
-  readonly deadLetterExchange?: string | undefined;
-
-  /** Routing key for dead-lettered messages */
-  readonly deadLetterRoutingKey?: string | undefined;
-
-  /** Message TTL in milliseconds */
-  readonly messageTtl?: number | undefined;
-
-  /** Queue expires after this many milliseconds of non-use */
-  readonly expires?: number | undefined;
-
-  /** Maximum number of messages in the queue */
-  readonly maxLength?: number | undefined;
-
-  /** Maximum priority level (0-255) */
-  readonly maxPriority?: number | undefined;
-
-  /** Additional x-* arguments for RabbitMQ */
-  readonly arguments?: Record<string, unknown> | undefined;
-}
-
-/**
- * Dead-letter queue configuration.
- */
-export interface DeadLetterConfig {
-  /** Unhandled events (schema mismatch) queue */
-  readonly unhandled: DeadLetterQueueConfig;
-
-  /** Undeliverable events (permanent failures) queue */
-  readonly undeliverable: DeadLetterQueueConfig;
-}
-
-/**
- * Configuration for a specific dead-letter queue.
- */
-export interface DeadLetterQueueConfig {
-  /** Whether this DLQ is enabled */
-  readonly enabled: boolean;
-
-  /** Maximum number of messages in the DLQ */
-  readonly maxLength?: number | undefined;
-}
-
-/**
- * Retry queue configuration.
- */
-export interface RetryConfig {
-  /** Enable retry queue with delay */
-  readonly enabled: boolean;
-
-  /** Default retry delay in milliseconds */
-  readonly defaultDelayMs: number;
-
-  /** Maximum retry delay in milliseconds */
-  readonly maxDelayMs: number;
-}
-
-/**
- * Gets the fully qualified queue name with namespace prefix.
- */
-export function getQualifiedQueueName(
-  namespace: string,
-  queueName: string,
-): string {
-  return `${namespace}.${queueName}`;
-}
-
-/**
- * Gets the dead-letter queue name for a given queue.
- */
-export function getDeadLetterQueueName(
-  namespace: string,
-  queueName: string,
-  dlqType: 'unhandled' | 'undeliverable',
-): string {
-  return `${namespace}.${queueName}.${dlqType}`;
-}
-
-/**
- * Gets the retry queue name for a given queue.
- */
-export function getRetryQueueName(
-  namespace: string,
-  queueName: string,
-): string {
-  return `${namespace}.${queueName}.retry`;
-}
-
-/**
- * Resolves the actual queue name for a given queue definition.
- * When exact: true, returns name as-is. Otherwise, returns namespace.name.
- */
-export function resolveQueueName(
-  namespace: string,
-  queueDef: QueueDefinition,
-): string {
-  if (queueDef.exact) {
-    return queueDef.name;
-  }
-  return `${namespace}.${queueDef.name}`;
-}

package/src/transport/capabilities.ts

@@ -1,88 +0,0 @@
-import type { DeliveryMode } from '../types/index.js';
-
-/**
- * Describes the native capabilities of a transport.
- * Matador adapts its behavior based on these capabilities.
- */
-export interface TransportCapabilities {
-  /**
-   * Delivery semantics the transport supports.
-   * - 'at-least-once': Ack after processing (may redeliver on failure)
-   * - 'at-most-once': Ack before processing (no redelivery, may lose messages)
-   */
-  readonly deliveryModes: readonly DeliveryMode[];
-
-  /**
-   * Transport can delay message delivery natively.
-   * - true: Use transport's native delay (BullMQ, RabbitMQ with plugin)
-   * - false: Matador handles via retry queue with TTL or external scheduler
-   */
-  readonly delayedMessages: boolean;
-
-  /**
-   * Transport can route failed messages to dead-letter queue natively.
-   * - 'native': Transport handles DL routing (RabbitMQ DLX)
-   * - 'manual': Matador must send() to DLQ then complete() original
-   * - 'none': No DL support, Matador logs and discards
-   */
-  readonly deadLetterRouting: 'native' | 'manual' | 'none';
-
-  /**
-   * Transport tracks delivery/attempt count natively.
-   * - true: Receipt includes accurate attemptNumber from transport
-   * - false: Matador tracks attempts in envelope.docket.attempts field
-   */
-  readonly attemptTracking: boolean;
-
-  /**
-   * How transport handles concurrency.
-   * - 'prefetch': Channel-based prefetch (RabbitMQ)
-   * - 'worker': Worker concurrency setting (BullMQ)
-   * - 'partition': Partition-based parallelism (Kafka)
-   * - 'none': No concurrency control (Memory)
-   */
-  readonly concurrencyModel: 'prefetch' | 'worker' | 'partition' | 'none';
-
-  /**
-   * Message ordering guarantees.
-   * - 'none': No ordering guarantee (most transports with multiple consumers)
-   * - 'queue': Ordered within queue (single consumer scenarios)
-   * - 'partition': Ordered within partition/key (Kafka)
-   */
-  readonly ordering: 'none' | 'queue' | 'partition';
-
-  /**
-   * Transport supports message priority.
-   * - true: Higher priority messages processed first
-   * - false: FIFO only
-   */
-  readonly priorities: boolean;
-}
-
-/**
- * Checks if the transport supports a specific delivery mode.
- */
-export function supportsDeliveryMode(
-  capabilities: TransportCapabilities,
-  mode: DeliveryMode,
-): boolean {
-  return capabilities.deliveryModes.includes(mode);
-}
-
-/**
- * Checks if the transport supports native delayed messages.
- */
-export function supportsDelayedMessages(
-  capabilities: TransportCapabilities,
-): boolean {
-  return capabilities.delayedMessages;
-}
-
-/**
- * Checks if the transport has native dead-letter routing.
- */
-export function hasNativeDeadLetter(
-  capabilities: TransportCapabilities,
-): boolean {
-  return capabilities.deadLetterRouting === 'native';
-}

package/src/transport/connection-manager.ts

@@ -1,218 +0,0 @@
-/**
- * Connection state machine states.
- */
-export type ConnectionState =
-  | { readonly status: 'disconnected' }
-  | { readonly status: 'connecting'; readonly attempt: number }
-  | { readonly status: 'connected' }
-  | {
-      readonly status: 'reconnecting';
-      readonly attempt: number;
-      readonly lastError: Error;
-    }
-  | { readonly status: 'failed'; readonly error: Error };
-
-/**
- * Configuration for the connection manager.
- */
-export interface ConnectionManagerConfig {
-  /** Maximum reconnection attempts before giving up (0 = infinite) */
-  readonly maxReconnectAttempts: number;
-
-  /** Initial delay between reconnection attempts (ms) */
-  readonly initialReconnectDelay: number;
-
-  /** Maximum delay between reconnection attempts (ms) */
-  readonly maxReconnectDelay: number;
-
-  /** Backoff multiplier for reconnection delay */
-  readonly backoffMultiplier: number;
-
-  /** Heartbeat interval for connection health (ms), optional */
-  readonly heartbeatInterval?: number;
-}
-
-/**
- * Default configuration values.
- */
-export const defaultConnectionConfig: ConnectionManagerConfig = {
-  maxReconnectAttempts: 0, // Infinite
-  initialReconnectDelay: 1000,
-  maxReconnectDelay: 30000,
-  backoffMultiplier: 2,
-};
-
-/**
- * Callback for state change notifications.
- */
-export type StateChangeCallback = (state: ConnectionState) => void;
-
-/**
- * Function that performs the actual connection.
- */
-export type ConnectFn = () => Promise<void>;
-
-/**
- * Function that performs disconnection.
- */
-export type DisconnectFn = () => Promise<void>;
-
-/**
- * Manages connection lifecycle with automatic reconnection.
- */
-export class ConnectionManager {
-  private _state: ConnectionState = { status: 'disconnected' };
-  private readonly listeners: Set<StateChangeCallback> = new Set();
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-  private readonly config: ConnectionManagerConfig;
-
-  constructor(
-    private readonly connectFn: ConnectFn,
-    private readonly disconnectFn: DisconnectFn,
-    config: Partial<ConnectionManagerConfig> = {},
-  ) {
-    this.config = { ...defaultConnectionConfig, ...config };
-  }
-
-  /**
-   * Current connection state.
-   */
-  get state(): ConnectionState {
-    return this._state;
-  }
-
-  /**
-   * Whether currently connected.
-   */
-  isConnected(): boolean {
-    return this._state.status === 'connected';
-  }
-
-  /**
-   * Register a callback for connection state changes.
-   */
-  onStateChange(callback: StateChangeCallback): () => void {
-    this.listeners.add(callback);
-    return () => this.listeners.delete(callback);
-  }
-
-  /**
-   * Attempt to establish connection.
-   */
-  async connect(): Promise<void> {
-    if (this._state.status === 'connected') {
-      return;
-    }
-
-    this.setState({ status: 'connecting', attempt: 1 });
-
-    try {
-      await this.connectFn();
-      this.setState({ status: 'connected' });
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      await this.handleConnectionFailure(err, 1);
-    }
-  }
-
-  /**
-   * Gracefully disconnect.
-   */
-  async disconnect(): Promise<void> {
-    this.clearReconnectTimer();
-
-    if (this._state.status === 'disconnected') {
-      return;
-    }
-
-    try {
-      await this.disconnectFn();
-    } finally {
-      this.setState({ status: 'disconnected' });
-    }
-  }
-
-  /**
-   * Called by transport when connection is lost unexpectedly.
-   */
-  async handleConnectionLost(error: Error): Promise<void> {
-    if (this._state.status === 'disconnected') {
-      return;
-    }
-
-    this.setState({ status: 'reconnecting', attempt: 1, lastError: error });
-    await this.attemptReconnect(1);
-  }
-
-  /**
-   * Calculate delay for a given attempt using exponential backoff.
-   */
-  calculateDelay(attempt: number): number {
-    const delay =
-      this.config.initialReconnectDelay *
-      Math.pow(this.config.backoffMultiplier, attempt - 1);
-    return Math.min(delay, this.config.maxReconnectDelay);
-  }
-
-  private setState(state: ConnectionState): void {
-    this._state = state;
-    for (const listener of this.listeners) {
-      try {
-        listener(state);
-      } catch {
-        // Ignore listener errors
-      }
-    }
-  }
-
-  private async handleConnectionFailure(
-    error: Error,
-    attempt: number,
-  ): Promise<void> {
-    if (this.shouldGiveUp(attempt)) {
-      this.setState({ status: 'failed', error });
-      throw error;
-    }
-
-    this.setState({
-      status: 'reconnecting',
-      attempt: attempt + 1,
-      lastError: error,
-    });
-    await this.attemptReconnect(attempt + 1);
-  }
-
-  private shouldGiveUp(attempt: number): boolean {
-    return (
-      this.config.maxReconnectAttempts > 0 &&
-      attempt >= this.config.maxReconnectAttempts
-    );
-  }
-
-  private async attemptReconnect(attempt: number): Promise<void> {
-    const delay = this.calculateDelay(attempt);
-
-    await new Promise<void>((resolve) => {
-      this.reconnectTimer = setTimeout(resolve, delay);
-    });
-
-    if (this._state.status === 'disconnected') {
-      return;
-    }
-
-    try {
-      await this.connectFn();
-      this.setState({ status: 'connected' });
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      await this.handleConnectionFailure(err, attempt);
-    }
-  }
-
-  private clearReconnectTimer(): void {
-    if (this.reconnectTimer !== null) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-  }
-}

package/src/transport/index.ts

@@ -1,42 +0,0 @@
-export type { TransportCapabilities } from './capabilities.js';
-export {
-  hasNativeDeadLetter,
-  supportsDeliveryMode,
-  supportsDelayedMessages,
-} from './capabilities.js';
-
-export type {
-  MessageHandler,
-  MessageReceipt,
-  RabbitMQSendOptions,
-  RabbitMQSubscribeOptions,
-  SendOptions,
-  SubscribeOptions,
-  Subscription,
-  Transport,
-  TransportSendOptions,
-  TransportSubscribeOptions,
-} from './transport.js';
-
-export type {
-  ConnectFn,
-  ConnectionManagerConfig,
-  ConnectionState,
-  DisconnectFn,
-  StateChangeCallback,
-} from './connection-manager.js';
-export {
-  ConnectionManager,
-  defaultConnectionConfig,
-} from './connection-manager.js';
-
-export { LocalTransport } from './local/local-transport.js';
-
-export type {
-  MultiTransportConfig,
-  MultiTransportHooks,
-} from './multi/multi-transport.js';
-export { MultiTransport } from './multi/multi-transport.js';
-
-export type { RabbitMQTransportConfig } from './rabbitmq/rabbitmq-transport.js';
-export { RabbitMQTransport } from './rabbitmq/rabbitmq-transport.js';