@zdavison/matador 2.0.8 → 2.0.10

package/src/core/shutdown.ts

@@ -1,165 +0,0 @@
-import { type Logger, consoleLogger } from '../hooks/index.js';
-
-/**
- * Shutdown state.
- */
-export type ShutdownState =
-  | 'running'
-  | 'stopping-receive'
-  | 'waiting-handlers'
-  | 'stopping-enqueue'
-  | 'disconnecting'
-  | 'stopped';
-
-/**
- * Configuration for shutdown manager.
- */
-export interface ShutdownConfig {
-  /** Timeout for graceful shutdown in milliseconds */
-  readonly gracefulShutdownTimeout: number;
-
-  /** Polling interval when waiting for handlers to idle */
-  readonly idlePollingInterval: number;
-
-  /** Logger for shutdown events (defaults to console) */
-  readonly logger: Logger;
-}
-
-/**
- * Default shutdown configuration.
- */
-export const defaultShutdownConfig: ShutdownConfig = {
-  gracefulShutdownTimeout: 30000,
-  idlePollingInterval: 1000,
-  logger: consoleLogger,
-};
-
-/**
- * Handler state tracking.
- */
-export interface HandlersState {
-  readonly eventsBeingProcessed: number;
-  readonly eventsBeingEnqueued: number;
-  readonly isIdle: boolean;
-}
-
-/**
- * Manages graceful shutdown of Matador.
- *
- * Shutdown sequence:
- * 1. Stop receiving new messages
- * 2. Wait for in-flight processing to complete
- * 3. Stop accepting new enqueue requests
- * 4. Disconnect transport
- */
-export class ShutdownManager {
-  private _state: ShutdownState = 'running';
-  private readonly config: ShutdownConfig;
-  private eventsBeingProcessed = 0;
-  private acceptingEnqueue = true;
-
-  constructor(
-    private readonly getEnqueueCount: () => number,
-    private readonly stopReceiving: () => Promise<void>,
-    private readonly disconnectTransport: () => Promise<void>,
-    config: Partial<ShutdownConfig> = {},
-  ) {
-    this.config = { ...defaultShutdownConfig, ...config };
-  }
-
-  /**
-   * Current shutdown state.
-   */
-  get state(): ShutdownState {
-    return this._state;
-  }
-
-  /**
-   * Whether enqueue is currently allowed.
-   */
-  get isEnqueueAllowed(): boolean {
-    return this.acceptingEnqueue;
-  }
-
-  /**
-   * Gets current handler state.
-   */
-  getHandlersState(): HandlersState {
-    const eventsBeingEnqueued = this.getEnqueueCount();
-    return {
-      eventsBeingProcessed: this.eventsBeingProcessed,
-      eventsBeingEnqueued,
-      isIdle: this.eventsBeingProcessed === 0 && eventsBeingEnqueued === 0,
-    };
-  }
-
-  /**
-   * Increment processing counter.
-   */
-  incrementProcessing(): void {
-    this.eventsBeingProcessed++;
-  }
-
-  /**
-   * Decrement processing counter.
-   */
-  decrementProcessing(): void {
-    this.eventsBeingProcessed--;
-  }
-
-  /**
-   * Performs graceful shutdown.
-   */
-  async shutdown(): Promise<void> {
-    if (this._state !== 'running') {
-      return;
-    }
-
-    // 1. Stop receiving new messages
-    this._state = 'stopping-receive';
-    await this.stopReceiving();
-
-    // 2. Wait for handlers to idle
-    this._state = 'waiting-handlers';
-    await this.waitForIdle();
-
-    // 3. Stop accepting new enqueue requests
-    this._state = 'stopping-enqueue';
-    this.acceptingEnqueue = false;
-
-    // 4. Disconnect transport
-    this._state = 'disconnecting';
-    await this.disconnectTransport();
-
-    this._state = 'stopped';
-  }
-
-  /**
-   * Forcefully stops without waiting.
-   */
-  async forceStop(): Promise<void> {
-    this.acceptingEnqueue = false;
-    await this.stopReceiving();
-    await this.disconnectTransport();
-    this._state = 'stopped';
-  }
-
-  private async waitForIdle(): Promise<void> {
-    const deadline = Date.now() + this.config.gracefulShutdownTimeout;
-
-    while (!this.getHandlersState().isIdle) {
-      if (Date.now() > deadline) {
-        this.config.logger.warn(
-          `[Matador] 🟡 Shutdown timeout reached with ${this.eventsBeingProcessed} events still processing`,
-        );
-        break;
-      }
-
-      await this.sleep(this.config.idlePollingInterval);
-    }
-  }
-
-  private sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-}

package/src/errors/checkpoint-errors.ts

@@ -1,62 +0,0 @@
-import { MatadorError } from './matador-errors.js';
-
-/**
- * Thrown when a duplicate io() key is used within a single subscriber execution.
- * Each io() call must have a unique key to prevent cache collisions.
- */
-export class DuplicateIoKeyError extends MatadorError {
-  readonly description =
-    'The same io() key was used multiple times in a single subscriber execution. ' +
-    'Each io() call must have a unique key to ensure correct checkpoint behavior. ' +
-    'ACTION: Ensure all io() keys are unique within the subscriber. ' +
-    'For dynamic operations (e.g., loops), include a unique identifier in the key ' +
-    '(e.g., `process-item-${item.id}`).';
-
-  constructor(
-    public readonly key: string,
-    public readonly subscriberName: string,
-  ) {
-    super(
-      `Duplicate io key "${key}" in subscriber "${subscriberName}". ` +
-        `Each io() call must have a unique key.`,
-    );
-  }
-}
-
-/**
- * Thrown when checkpoint store operations fail.
- */
-export class CheckpointStoreError extends MatadorError {
-  readonly description =
-    'A checkpoint store operation failed. This may cause issues with resumable subscribers. ' +
-    'ACTION: Check the underlying storage system (Redis, etc.) for connectivity issues. ' +
-    'The subscriber may re-execute operations that were already completed.';
-
-  constructor(
-    public readonly operation: 'get' | 'set' | 'delete',
-    public readonly envelopeId: string,
-    public readonly cause: Error,
-  ) {
-    super(
-      `Checkpoint store ${operation} failed for envelope "${envelopeId}": ${cause.message}`,
-    );
-  }
-}
-
-/**
- * Type guard for DuplicateIoKeyError.
- */
-export function isDuplicateIoKeyError(
-  error: unknown,
-): error is DuplicateIoKeyError {
-  return error instanceof DuplicateIoKeyError;
-}
-
-/**
- * Type guard for CheckpointStoreError.
- */
-export function isCheckpointStoreError(
-  error: unknown,
-): error is CheckpointStoreError {
-  return error instanceof CheckpointStoreError;
-}

package/src/errors/has-description.ts

@@ -1,25 +0,0 @@
-/**
- * Interface for errors that provide a human-readable description.
- * The description explains what the error means and what actions
- * users should take when encountering it in logs/observability.
- */
-export interface HasDescription {
-  /**
-   * Human-readable description of the error type.
-   * Intended for logging and observability to help users understand
-   * the error and determine appropriate remediation steps.
-   */
-  readonly description: string;
-}
-
-/**
- * Type guard to check if an error implements HasDescription.
- */
-export function hasDescription(error: unknown): error is HasDescription {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'description' in error &&
-    typeof (error as HasDescription).description === 'string'
-  );
-}

package/src/errors/index.ts

@@ -1,58 +0,0 @@
-export type { HasDescription } from './has-description.js';
-export { hasDescription } from './has-description.js';
-
-export {
-  assertEvent,
-  DontRetry,
-  DoRetry,
-  EventAssertionError,
-  isAssertionError,
-  isDontRetry,
-  isDoRetry,
-  RetryControlError,
-} from './retry-errors.js';
-
-export {
-  // Base class
-  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,
-} from './matador-errors.js';
-
-export {
-  // Checkpoint errors
-  CheckpointStoreError,
-  DuplicateIoKeyError,
-  isCheckpointStoreError,
-  isDuplicateIoKeyError,
-} from './checkpoint-errors.js';