@zdavison/matador 2.0.8 → 2.0.10

package/src/errors/retry-errors.ts

@@ -1,188 +0,0 @@
-import assert from 'node:assert';
-import type { Envelope } from '../types/envelope.js';
-
-/**
- * Base class for retry control errors.
- * These errors control the retry behavior of message processing.
- */
-export abstract class RetryControlError extends Error {
-  /**
-   * Error class name for monitoring tools.
-   */
-  declare readonly name: string;
-
-  /**
-   * Human-readable description of the error and recommended actions.
-   */
-  abstract readonly description: string;
-
-  constructor(message: string) {
-    super(message);
-    this.name = this.constructor.name;
-    // Ensure name is preserved when serialized
-    Object.defineProperty(this, 'name', {
-      value: this.constructor.name,
-      enumerable: true,
-      configurable: false,
-      writable: false,
-    });
-  }
-
-  /**
-   * Returns a serializable representation for logging/monitoring.
-   */
-  toJSON(): Record<string, unknown> {
-    return {
-      name: this.name,
-      message: this.message,
-      description: this.description,
-      stack: this.stack,
-    };
-  }
-}
-
-/**
- * Forces retry regardless of subscriber idempotency setting.
- * Use when you know the operation is safe to retry.
- *
- * ACTION: Check subscriber code to understand why retry was forced.
- * This overrides default retry behavior based on idempotency settings.
- */
-export class DoRetry extends RetryControlError {
-  readonly description =
-    'A subscriber explicitly requested retry by throwing DoRetry. ' +
-    'ACTION: Check the subscriber code to understand why retry was forced. ' +
-    'This overrides the default retry behavior based on idempotency settings.';
-
-  constructor(message = 'Forced retry requested') {
-    super(message);
-  }
-}
-
-/**
- * Prevents retry regardless of subscriber idempotency setting.
- * Use for permanent failures that should not be retried.
- *
- * ACTION: Check subscriber code to understand why retry was disabled.
- * Typically used for permanent failures like invalid data or business rule violations.
- */
-export class DontRetry extends RetryControlError {
-  readonly description =
-    'A subscriber explicitly prevented retry by throwing DontRetry. ' +
-    'ACTION: Check the subscriber code to understand why retry was disabled. ' +
-    'Typically used for permanent failures like invalid data or business rule violations. ' +
-    'The message will be sent to the dead-letter queue for manual review.';
-
-  constructor(message = 'Retry explicitly disabled') {
-    super(message);
-  }
-}
-
-/**
- * Thrown by `assertEvent` in the event of a failed assertion.
- *
- * This error indicates that an event was in an unexpected state when it reached the subscriber.
- * Throwing this error will indicate to Matador NOT to retry the event - it will be sent
- * directly to the undeliverable dead-letter queue.
- *
- * Use `assertEvent` in your subscribers to assert properties about an event payload.
- * This is useful in scenarios where you would expect an event payload to contain a field
- * based on the types, but something unexpected caused it to not be present.
- *
- * @see assertEvent
- */
-export class EventAssertionError extends Error {
-  declare readonly name: string;
-
-  readonly description =
-    'Thrown to indicate that an event was in an unexpected state when it reached the subscriber. ' +
-    'Throwing this error will indicate to Matador NOT to retry the event. ' +
-    'Matador does not throw this error directly - it is thrown by assertEvent, which you can ' +
-    'use in your subscribers to assert properties about an event. ' +
-    'This can be useful in scenarios where you would expect an event payload to contain a field ' +
-    'based on the types, but something unexpected caused it to not be present. ' +
-    'Using this instead of the NodeJS assert allows Matador to not retry the event subscriber.';
-
-  /** The envelope that failed the assertion */
-  readonly envelope: Envelope<unknown>;
-
-  constructor(envelope: Envelope<unknown>, message: string) {
-    super(message);
-    this.name = 'EventAssertionError';
-    this.envelope = envelope;
-    Object.defineProperty(this, 'name', {
-      value: 'EventAssertionError',
-      enumerable: true,
-      configurable: false,
-      writable: false,
-    });
-  }
-
-  toJSON(): Record<string, unknown> {
-    return {
-      name: this.name,
-      message: this.message,
-      description: this.description,
-      envelope: this.envelope,
-      stack: this.stack,
-    };
-  }
-}
-
-/**
- * Checks if an error forces a retry.
- */
-export function isDoRetry(error: unknown): error is DoRetry {
-  return error instanceof DoRetry;
-}
-
-/**
- * Checks if an error prevents retry.
- */
-export function isDontRetry(error: unknown): error is DontRetry {
-  return error instanceof DontRetry;
-}
-
-/**
- * Checks if an error is an assertion error (never retry).
- */
-export function isAssertionError(error: unknown): error is EventAssertionError {
-  return error instanceof EventAssertionError;
-}
-
-/**
- * Same as Node.js `assert`, but throws an `EventAssertionError` if the assertion fails.
- *
- * `EventAssertionError`s thrown within a subscriber do not cause the subscriber to be retried.
- * The event will be delivered to the undeliverable dead-letter queue instead.
- *
- * @see https://nodejs.org/api/assert.html#assertvalue-message
- * @param envelope - The envelope this assertion relates to.
- * @param value - The value to assert. If falsy, the assertion fails.
- * @param message - The message to include in the error if the assertion fails.
- * @throws {EventAssertionError} If the assertion fails.
- *
- * @example
- * ```typescript
- * const subscriber = createSubscriber<MyEvent>({
- *   name: 'my-subscriber',
- *   description: 'Processes MyEvent',
- *   callback: async (envelope) => {
- *     // Assert that userId exists - if not, event goes to DLQ without retry
- *     assertEvent(envelope, envelope.data.userId, 'userId is required');
- *     // ... rest of processing
- *   },
- * });
- * ```
- */
-export function assertEvent(
-  envelope: Envelope<unknown>,
-  value: unknown,
-  message: string,
-): asserts value {
-  try {
-    assert(value, message);
-  } catch {
-    throw new EventAssertionError(envelope, message);
-  }
-}

package/src/hooks/index.ts

@@ -1,14 +0,0 @@
-export type {
-  DecodeErrorContext,
-  EnqueueErrorContext,
-  EnqueueSuccessContext,
-  Logger,
-  MatadorHooks,
-  TransportFallbackContext,
-  WorkerErrorContext,
-  WorkerExecuteFn,
-  WorkerSuccessContext,
-} from './types.js';
-
-export { consoleLogger } from './types.js';
-export { SafeHooks } from './safe-hooks.js';

package/src/hooks/safe-hooks.ts

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

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