@zdavison/matador 2.0.1

package/src/hooks/safe-hooks.ts

@@ -0,0 +1,223 @@
+import type {
+  CheckpointClearedContext,
+  CheckpointHitContext,
+  CheckpointLoadedContext,
+  CheckpointMissContext,
+} from '../checkpoint/index.js';
+import type { ConnectionState } from '../transport/index.js';
+import type { Envelope, SubscriberDefinition } from '../types/index.js';
+import {
+  type DecodeErrorContext,
+  type EnqueueErrorContext,
+  type EnqueueSuccessContext,
+  type EnqueueWarningContext,
+  type Logger,
+  type MatadorHooks,
+  type WorkerErrorContext,
+  type WorkerExecuteFn,
+  type WorkerSuccessContext,
+  consoleLogger,
+} from './types.js';
+
+/**
+ * Wraps hooks with error handling to prevent hook errors from breaking processing.
+ * All hooks become safe to call and will catch any errors internally.
+ */
+export class SafeHooks {
+  private readonly hooks: MatadorHooks;
+
+  /** The logger instance used by Matador. */
+  readonly logger: Logger;
+
+  constructor(hooks: MatadorHooks = {}) {
+    this.hooks = hooks;
+    this.logger = hooks.logger ?? consoleLogger;
+  }
+
+  async onEnqueueSuccess(context: EnqueueSuccessContext): Promise<void> {
+    await this.safeCall('onEnqueueSuccess', () =>
+      this.hooks.onEnqueueSuccess?.(context),
+    );
+  }
+
+  async onEnqueueWarning(context: EnqueueWarningContext): Promise<void> {
+    await this.safeCall('onEnqueueWarning', () =>
+      this.hooks.onEnqueueWarning?.(context),
+    );
+  }
+
+  async onEnqueueError(context: EnqueueErrorContext): Promise<void> {
+    await this.safeCall('onEnqueueError', () =>
+      this.hooks.onEnqueueError?.(context),
+    );
+  }
+
+  async onWorkerWrap(
+    envelope: Envelope,
+    subscriber: SubscriberDefinition,
+    execute: WorkerExecuteFn,
+  ): Promise<void> {
+    if (this.hooks.onWorkerWrap) {
+      try {
+        await this.hooks.onWorkerWrap(envelope, subscriber, execute);
+      } catch (error) {
+        this.logger.warn(
+          '[Matador] 🟡 Hook onWorkerWrap threw an error',
+          error,
+        );
+        // Still try to execute if wrap failed
+        await execute();
+      }
+    } else {
+      await execute();
+    }
+  }
+
+  async onWorkerBeforeProcess(
+    envelope: Envelope,
+    subscriber: SubscriberDefinition,
+  ): Promise<void> {
+    await this.safeCall('onWorkerBeforeProcess', () =>
+      this.hooks.onWorkerBeforeProcess?.(envelope, subscriber),
+    );
+  }
+
+  async onWorkerSuccess(context: WorkerSuccessContext): Promise<void> {
+    await this.safeCall('onWorkerSuccess', () =>
+      this.hooks.onWorkerSuccess?.(context),
+    );
+  }
+
+  async onWorkerError(context: WorkerErrorContext): Promise<void> {
+    await this.safeCall('onWorkerError', () =>
+      this.hooks.onWorkerError?.(context),
+    );
+  }
+
+  async onDecodeError(context: DecodeErrorContext): Promise<void> {
+    await this.safeCall('onDecodeError', () =>
+      this.hooks.onDecodeError?.(context),
+    );
+  }
+
+  async onConnectionStateChange(state: ConnectionState): Promise<void> {
+    await this.safeCall('onConnectionStateChange', () =>
+      this.hooks.onConnectionStateChange?.(state),
+    );
+  }
+
+  async loadUniversalMetadata(): Promise<Record<string, unknown>> {
+    if (!this.hooks.loadUniversalMetadata) {
+      return {};
+    }
+
+    try {
+      const result = await this.hooks.loadUniversalMetadata();
+      return result ?? {};
+    } catch (error) {
+      this.logger.warn(
+        '[Matador] 🟡 Hook loadUniversalMetadata threw an error',
+        error,
+      );
+      return {};
+    }
+  }
+
+  async getQueueConcurrency(queueName: string): Promise<number | undefined> {
+    if (!this.hooks.getQueueConcurrency) {
+      return undefined;
+    }
+
+    try {
+      return await this.hooks.getQueueConcurrency(queueName);
+    } catch (error) {
+      this.logger.warn(
+        '[Matador] 🟡 Hook getQueueConcurrency threw an error',
+        error,
+      );
+      return undefined;
+    }
+  }
+
+  async getRetryDelay(
+    envelope: Envelope,
+    attemptNumber: number,
+  ): Promise<number | undefined> {
+    if (!this.hooks.getRetryDelay) {
+      return undefined;
+    }
+
+    try {
+      return await this.hooks.getRetryDelay(envelope, attemptNumber);
+    } catch (error) {
+      this.logger.warn('[Matador] 🟡 Hook getRetryDelay threw an error', error);
+      return undefined;
+    }
+  }
+
+  async getAttempts(envelope: Envelope): Promise<number | undefined> {
+    if (!this.hooks.getAttempts) {
+      return undefined;
+    }
+
+    try {
+      return await this.hooks.getAttempts(envelope);
+    } catch (error) {
+      this.logger.warn('[Matador] 🟡 Hook getAttempts threw an error', error);
+      return undefined;
+    }
+  }
+
+  async getMaxDeliveries(envelope: Envelope): Promise<number | undefined> {
+    if (!this.hooks.getMaxDeliveries) {
+      return undefined;
+    }
+
+    try {
+      return await this.hooks.getMaxDeliveries(envelope);
+    } catch (error) {
+      this.logger.warn(
+        '[Matador] 🟡 Hook getMaxDeliveries threw an error',
+        error,
+      );
+      return undefined;
+    }
+  }
+
+  // === Checkpoint Hooks ===
+
+  async onCheckpointLoaded(context: CheckpointLoadedContext): Promise<void> {
+    await this.safeCall('onCheckpointLoaded', () =>
+      this.hooks.onCheckpointLoaded?.(context),
+    );
+  }
+
+  async onCheckpointHit(context: CheckpointHitContext): Promise<void> {
+    await this.safeCall('onCheckpointHit', () =>
+      this.hooks.onCheckpointHit?.(context),
+    );
+  }
+
+  async onCheckpointMiss(context: CheckpointMissContext): Promise<void> {
+    await this.safeCall('onCheckpointMiss', () =>
+      this.hooks.onCheckpointMiss?.(context),
+    );
+  }
+
+  async onCheckpointCleared(context: CheckpointClearedContext): Promise<void> {
+    await this.safeCall('onCheckpointCleared', () =>
+      this.hooks.onCheckpointCleared?.(context),
+    );
+  }
+
+  private async safeCall(
+    hookName: string,
+    fn: () => void | Promise<void> | undefined,
+  ): Promise<void> {
+    try {
+      await fn();
+    } catch (error) {
+      this.logger.warn(`[Matador] 🟡 Hook ${hookName} threw an error`, error);
+    }
+  }
+}

package/src/hooks/types.ts

@@ -0,0 +1,248 @@
+import type {
+  CheckpointClearedContext,
+  CheckpointHitContext,
+  CheckpointLoadedContext,
+  CheckpointMissContext,
+} from '../checkpoint/index.js';
+import type { RetryDecision } from '../retry/index.js';
+import type { ConnectionState, Transport } from '../transport/index.js';
+import type { Envelope, SubscriberDefinition } from '../types/index.js';
+
+/**
+ * Logger interface for Matador internal logging.
+ */
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Default logger that uses console.
+ */
+export const consoleLogger: Logger = {
+  debug: (message, ...args) => console.debug(message, ...args),
+  info: (message, ...args) => console.info(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args),
+};
+
+/**
+ * Context for enqueue success hook.
+ */
+export interface EnqueueSuccessContext {
+  readonly envelope: Envelope;
+  readonly queue: string;
+  /** The transport that was used (e.g., 'local', 'rabbitmq') */
+  readonly transport: string;
+}
+
+/**
+ * Context for enqueue warning hook (fallback used).
+ */
+export interface EnqueueWarningContext {
+  readonly envelope: Envelope;
+  readonly originalQueue: string;
+  readonly fallbackQueue: string;
+  readonly error: Error;
+}
+
+/**
+ * Context for transport fallback hook.
+ */
+export interface TransportFallbackContext {
+  /** The envelope that was being sent */
+  readonly envelope: Envelope;
+  /** The queue the message was being sent to */
+  readonly queue: string;
+  /** The transport that failed */
+  readonly failedTransport: Transport['name'];
+  /** The transport that will be tried next */
+  readonly nextTransport: Transport['name'];
+  /** The error from the failed transport */
+  readonly error: Error;
+}
+
+/**
+ * Context for enqueue error hook.
+ */
+export interface EnqueueErrorContext {
+  readonly envelope: Envelope;
+  readonly error: Error;
+  /** The transport that failed (e.g., 'local', 'rabbitmq') */
+  readonly transport: string;
+}
+
+/**
+ * Context for decode error hook.
+ */
+export interface DecodeErrorContext {
+  readonly error: Error;
+  readonly rawMessage: Uint8Array;
+  readonly sourceQueue: string;
+  /** The transport that received the message (e.g., 'local', 'rabbitmq') */
+  readonly transport: string;
+}
+
+/**
+ * Context for worker success hook.
+ */
+export interface WorkerSuccessContext {
+  readonly envelope: Envelope;
+  readonly subscriber: SubscriberDefinition;
+  readonly result: unknown;
+  readonly durationMs: number;
+  /** The transport that received the message (e.g., 'local', 'rabbitmq') */
+  readonly transport: string;
+}
+
+/**
+ * Context for worker error hook.
+ */
+export interface WorkerErrorContext {
+  readonly envelope: Envelope;
+  readonly subscriber: SubscriberDefinition;
+  readonly error: Error;
+  readonly durationMs: number;
+  readonly decision: RetryDecision;
+  /** The transport that received the message (e.g., 'local', 'rabbitmq') */
+  readonly transport: string;
+}
+
+/**
+ * Execution function passed to onWorkerWrap for APM wrapping.
+ */
+export type WorkerExecuteFn = () => Promise<void>;
+
+/**
+ * All available hooks for Matador.
+ */
+export interface MatadorHooks {
+  /**
+   * Logger for internal Matador logging.
+   * Defaults to console logger if not provided.
+   */
+  logger?: Logger;
+
+  /**
+   * Called when an event is successfully enqueued.
+   */
+  onEnqueueSuccess?(context: EnqueueSuccessContext): void | Promise<void>;
+
+  /**
+   * Called when enqueue falls back to a secondary queue.
+   */
+  onEnqueueWarning?(context: EnqueueWarningContext): void | Promise<void>;
+
+  /**
+   * Called when transport fallback occurs during send.
+   * Only fires when using MultiTransport with fallbackEnabled=true.
+   */
+  onTransportFallback?(context: TransportFallbackContext): void | Promise<void>;
+
+  /**
+   * Called when enqueue fails completely.
+   */
+  onEnqueueError?(context: EnqueueErrorContext): void | Promise<void>;
+
+  /**
+   * Wraps entire worker processing (for APM context).
+   * Must call execute() to run the actual processing.
+   */
+  onWorkerWrap?(
+    envelope: Envelope,
+    subscriber: SubscriberDefinition,
+    execute: WorkerExecuteFn,
+  ): Promise<void>;
+
+  /**
+   * Called before processing begins.
+   */
+  onWorkerBeforeProcess?(
+    envelope: Envelope,
+    subscriber: SubscriberDefinition,
+  ): void | Promise<void>;
+
+  /**
+   * Called after successful processing.
+   */
+  onWorkerSuccess?(context: WorkerSuccessContext): void | Promise<void>;
+
+  /**
+   * Called after processing error.
+   */
+  onWorkerError?(context: WorkerErrorContext): void | Promise<void>;
+
+  /**
+   * Called when message decoding fails.
+   */
+  onDecodeError?(context: DecodeErrorContext): void | Promise<void>;
+
+  /**
+   * Called when transport connection state changes.
+   */
+  onConnectionStateChange?(state: ConnectionState): void | Promise<void>;
+
+  /**
+   * Loads universal metadata to add to all envelopes.
+   */
+  loadUniversalMetadata?():
+    | Record<string, unknown>
+    | Promise<Record<string, unknown>>;
+
+  /**
+   * Dynamic queue concurrency lookup.
+   */
+  getQueueConcurrency?(
+    queueName: string,
+  ): number | undefined | Promise<number | undefined>;
+
+  /**
+   * Dynamic retry delay lookup.
+   */
+  getRetryDelay?(
+    envelope: Envelope,
+    attemptNumber: number,
+  ): number | undefined | Promise<number | undefined>;
+
+  /**
+   * Dynamic max attempts lookup.
+   */
+  getAttempts?(
+    envelope: Envelope,
+  ): number | undefined | Promise<number | undefined>;
+
+  /**
+   * Dynamic max deliveries (poison threshold) lookup.
+   */
+  getMaxDeliveries?(
+    envelope: Envelope,
+  ): number | undefined | Promise<number | undefined>;
+
+  // === Checkpoint Hooks (Resumable Subscribers) ===
+
+  /**
+   * Called when a checkpoint is loaded for a retry.
+   * Only fires for resumable subscribers on retry attempts.
+   */
+  onCheckpointLoaded?(context: CheckpointLoadedContext): void | Promise<void>;
+
+  /**
+   * Called when an io() operation uses a cached value (checkpoint hit).
+   * Useful for observability and metrics.
+   */
+  onCheckpointHit?(context: CheckpointHitContext): void | Promise<void>;
+
+  /**
+   * Called when an io() operation executes (cache miss).
+   * Useful for observability and metrics.
+   */
+  onCheckpointMiss?(context: CheckpointMissContext): void | Promise<void>;
+
+  /**
+   * Called when a checkpoint is cleared.
+   * Fires on successful completion or when moving to dead-letter queue.
+   */
+  onCheckpointCleared?(context: CheckpointClearedContext): void | Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,231 @@
+// Core
+export type {
+  FanoutConfig,
+  HandlersState,
+  MatadorConfig,
+  SendError,
+  SendResult,
+  ShutdownConfig,
+  ShutdownState,
+} from './core/index.js';
+export {
+  defaultShutdownConfig,
+  FanoutEngine,
+  Matador,
+  ShutdownManager,
+} from './core/index.js';
+
+// Types
+export type {
+  AnySubscriber,
+  BaseSubscriberOptions,
+  CreateEnvelopeOptions,
+  DeliveryMode,
+  Docket,
+  Envelope,
+  EnvelopeOf,
+  Event,
+  EventClass,
+  EventData,
+  EventKey,
+  EventOptions,
+  EventStatic,
+  Idempotency,
+  Importance,
+  JsonRecord,
+  Subscriber,
+  SubscriberCallback,
+  SubscriberDefinition,
+  SubscriberOptions,
+  SubscriberStub,
+  ValidationError,
+  ValidationResult,
+} from './types/index.js';
+export {
+  MatadorEvent,
+  createEnvelope,
+  createSubscriber,
+  createSubscriberStub,
+  invalidResult,
+  isSubscriber,
+  isSubscriberStub,
+  validResult,
+} from './types/index.js';
+
+// Transport
+export type {
+  ConnectFn,
+  ConnectionManagerConfig,
+  ConnectionState,
+  DisconnectFn,
+  MessageHandler,
+  MessageReceipt,
+  RabbitMQSendOptions,
+  RabbitMQSubscribeOptions,
+  RabbitMQTransportConfig,
+  SendOptions,
+  StateChangeCallback,
+  SubscribeOptions,
+  Subscription,
+  Transport,
+  TransportCapabilities,
+  TransportSendOptions,
+  TransportSubscribeOptions,
+} from './transport/index.js';
+export {
+  ConnectionManager,
+  defaultConnectionConfig,
+  hasNativeDeadLetter,
+  LocalTransport,
+  RabbitMQTransport,
+  MultiTransport,
+  type MultiTransportConfig,
+  type MultiTransportHooks,
+  supportsDeliveryMode,
+  supportsDelayedMessages,
+} from './transport/index.js';
+
+// Topology
+export type {
+  DeadLetterConfig,
+  DeadLetterQueueConfig,
+  QueueDefinition,
+  QueueOptions,
+  RetryConfig,
+  Topology,
+} from './topology/index.js';
+export {
+  getDeadLetterQueueName,
+  getQualifiedQueueName,
+  getRetryQueueName,
+  TopologyBuilder,
+  TopologyValidationError,
+} from './topology/index.js';
+
+// Codec
+export type {
+  Codec,
+  EncodedMessage,
+  HeaderAwareCodec,
+} from './codec/index.js';
+export { CodecDecodeError, JsonCodec, RabbitMQCodec } from './codec/index.js';
+
+// Schema
+export type {
+  MatadorSchema,
+  RegisterOptions,
+  SchemaEntry,
+  SchemaEntryTuple,
+  SchemaIssue,
+  SchemaPlugin,
+  SchemaValidationResult,
+} from './schema/index.js';
+export {
+  bind,
+  installPlugins,
+  isSchemaEntryTuple,
+  SchemaError,
+  SchemaRegistry,
+} from './schema/index.js';
+
+// Retry
+export type {
+  RetryContext,
+  RetryDecision,
+  RetryPolicy,
+  StandardRetryPolicyConfig,
+} from './retry/index.js';
+export {
+  defaultRetryConfig,
+  StandardRetryPolicy,
+} from './retry/index.js';
+
+// Hooks
+export type {
+  DecodeErrorContext,
+  EnqueueErrorContext,
+  EnqueueSuccessContext,
+  EnqueueWarningContext,
+  Logger,
+  MatadorHooks,
+  WorkerErrorContext,
+  WorkerExecuteFn,
+  WorkerSuccessContext,
+} from './hooks/index.js';
+export { consoleLogger, SafeHooks } from './hooks/index.js';
+
+// Pipeline
+export type { PipelineConfig, ProcessResult } from './pipeline/index.js';
+export { ProcessingPipeline } from './pipeline/index.js';
+
+// Errors
+export type { HasDescription } from './errors/index.js';
+export {
+  // Retry control errors
+  DontRetry,
+  DoRetry,
+  EventAssertionError,
+  RetryControlError,
+  isAssertionError,
+  isDontRetry,
+  isDoRetry,
+  // Matador errors with descriptions
+  MatadorError,
+  isMatadorError,
+  // Lifecycle errors
+  NotStartedError,
+  isNotStartedError,
+  ShutdownInProgressError,
+  // Transport errors
+  TransportNotConnectedError,
+  isTransportNotConnectedError,
+  TransportClosedError,
+  TransportSendError,
+  AllTransportsFailedError,
+  DelayedMessagesNotSupportedError,
+  // Schema & configuration errors
+  EventNotRegisteredError,
+  isEventNotRegisteredError,
+  SubscriberNotRegisteredError,
+  isSubscriberNotRegisteredError,
+  NoSubscribersExistError,
+  InvalidSchemaError,
+  SubscriberIsStubError,
+  LocalTransportCannotProcessStubError,
+  // Queue errors
+  QueueNotFoundError,
+  // Event validation errors
+  InvalidEventError,
+  // Message processing errors
+  MessageMaybePoisonedError,
+  isMessageMaybePoisonedError,
+  IdempotentMessageCannotRetryError,
+  isIdempotentMessageCannotRetryError,
+  // Timeout errors
+  TimeoutError,
+  // Utility
+  hasDescription,
+} from './errors/index.js';
+
+// Checkpoint (Resumable Subscribers)
+export type {
+  Checkpoint,
+  CheckpointClearedContext,
+  CheckpointHitContext,
+  CheckpointLoadedContext,
+  CheckpointMissContext,
+  CheckpointStore,
+  JsonSerializable,
+  ResumableContextConfig,
+  ResumableContextHooks,
+  SubscriberContext,
+} from './checkpoint/index.js';
+export {
+  CheckpointStoreError,
+  DuplicateIoKeyError,
+  MemoryCheckpointStore,
+  NoOpCheckpointStore,
+  ResumableContext,
+  isCheckpointStoreError,
+  isDuplicateIoKeyError,
+} from './checkpoint/index.js';

package/src/pipeline/index.ts

@@ -0,0 +1,2 @@
+export type { PipelineConfig, ProcessResult } from './pipeline.js';
+export { ProcessingPipeline } from './pipeline.js';