@signaltree/events 7.6.1 → 8.0.0

package/dist/core/error-classification.cjs

@@ -1,282 +0,0 @@
-'use strict';
-
-/**
- * Error Classification - Determine retry behavior for errors
- *
- * Provides:
- * - Retryable vs non-retryable error classification
- * - Error categories (transient, permanent, poison)
- * - Retry configuration per error type
- * - Custom error classifiers
- */
-/**
- * Default retry configurations by classification
- */
-const DEFAULT_RETRY_CONFIGS = {
-  transient: {
-    maxAttempts: 5,
-    initialDelayMs: 1000,
-    maxDelayMs: 60000,
-    backoffMultiplier: 2,
-    jitter: 0.1
-  },
-  permanent: {
-    maxAttempts: 0,
-    initialDelayMs: 0,
-    maxDelayMs: 0,
-    backoffMultiplier: 1,
-    jitter: 0
-  },
-  poison: {
-    maxAttempts: 0,
-    initialDelayMs: 0,
-    maxDelayMs: 0,
-    backoffMultiplier: 1,
-    jitter: 0
-  },
-  unknown: {
-    maxAttempts: 3,
-    initialDelayMs: 2000,
-    maxDelayMs: 30000,
-    backoffMultiplier: 2,
-    jitter: 0.2
-  }
-};
-/**
- * Known transient error patterns
- */
-const TRANSIENT_ERROR_PATTERNS = [
-// Network errors
-/ECONNREFUSED/i, /ECONNRESET/i, /ETIMEDOUT/i, /ENETUNREACH/i, /EHOSTUNREACH/i, /ENOTFOUND/i, /socket hang up/i, /network error/i, /connection.*timeout/i, /request.*timeout/i,
-// Database transient
-/deadlock/i, /lock wait timeout/i, /too many connections/i, /connection pool exhausted/i, /temporarily unavailable/i,
-// HTTP transient
-/502 bad gateway/i, /503 service unavailable/i, /504 gateway timeout/i, /429 too many requests/i,
-// Redis/Queue transient
-/BUSY/i, /LOADING/i, /CLUSTERDOWN/i, /READONLY/i,
-// Generic transient
-/temporary failure/i, /try again/i, /retry/i, /throttl/i, /rate limit/i, /circuit breaker/i];
-/**
- * Known permanent error patterns
- */
-const PERMANENT_ERROR_PATTERNS = [
-// Auth errors
-/unauthorized/i, /forbidden/i, /access denied/i, /permission denied/i, /invalid token/i, /token expired/i,
-// Business logic
-/not found/i, /already exists/i, /duplicate/i, /conflict/i, /invalid state/i, /precondition failed/i,
-// HTTP permanent
-/400 bad request/i, /401 unauthorized/i, /403 forbidden/i, /404 not found/i, /409 conflict/i, /422 unprocessable/i];
-/**
- * Known poison error patterns (send to DLQ immediately)
- */
-const POISON_ERROR_PATTERNS = [
-// Schema/Serialization
-/invalid json/i, /json parse error/i, /unexpected token/i, /schema validation/i, /invalid event schema/i, /deserialization/i, /malformed/i,
-// Data corruption
-/data corruption/i, /checksum mismatch/i, /integrity error/i];
-/**
- * Error codes that indicate transient failures
- */
-const TRANSIENT_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENETUNREACH', 'EHOSTUNREACH', 'ENOTFOUND', 'EPIPE', 'EAI_AGAIN']);
-/**
- * HTTP status codes that indicate transient failures
- */
-const TRANSIENT_HTTP_STATUS = new Set([408, 429, 500, 502, 503, 504]);
-/**
- * HTTP status codes that indicate permanent failures
- */
-const PERMANENT_HTTP_STATUS = new Set([400, 401, 403, 404, 405, 409, 410, 422]);
-/**
- * Create an error classifier
- *
- * @example
- * ```typescript
- * const classifier = createErrorClassifier({
- *   customClassifiers: [
- *     (error) => {
- *       if (error instanceof MyCustomTransientError) return 'transient';
- *       return null; // Let default classification handle it
- *     }
- *   ],
- *   retryConfigs: {
- *     transient: { maxAttempts: 10 }, // Override max attempts
- *   },
- * });
- *
- * const result = classifier.classify(error);
- * if (result.sendToDlq) {
- *   await dlqService.send(event, error, result.reason);
- * }
- * ```
- */
-function createErrorClassifier(config = {}) {
-  const customClassifiers = config.customClassifiers ?? [];
-  const defaultClassification = config.defaultClassification ?? 'unknown';
-  // Merge retry configs
-  const retryConfigs = {
-    transient: {
-      ...DEFAULT_RETRY_CONFIGS.transient,
-      ...config.retryConfigs?.transient
-    },
-    permanent: {
-      ...DEFAULT_RETRY_CONFIGS.permanent,
-      ...config.retryConfigs?.permanent
-    },
-    poison: {
-      ...DEFAULT_RETRY_CONFIGS.poison,
-      ...config.retryConfigs?.poison
-    },
-    unknown: {
-      ...DEFAULT_RETRY_CONFIGS.unknown,
-      ...config.retryConfigs?.unknown
-    }
-  };
-  function extractErrorInfo(error) {
-    if (error instanceof Error) {
-      const errWithCode = error;
-      return {
-        message: error.message,
-        name: error.name,
-        code: errWithCode.code,
-        status: errWithCode.status ?? errWithCode.statusCode ?? errWithCode.response?.status
-      };
-    }
-    if (typeof error === 'object' && error !== null) {
-      const obj = error;
-      return {
-        message: String(obj['message'] ?? obj['error'] ?? ''),
-        code: obj['code'],
-        status: obj['status'] ?? obj['statusCode']
-      };
-    }
-    return {
-      message: String(error)
-    };
-  }
-  function classifyByPatterns(message) {
-    // Check poison patterns first (most specific)
-    for (const pattern of POISON_ERROR_PATTERNS) {
-      if (pattern.test(message)) {
-        return 'poison';
-      }
-    }
-    // Check permanent patterns
-    for (const pattern of PERMANENT_ERROR_PATTERNS) {
-      if (pattern.test(message)) {
-        return 'permanent';
-      }
-    }
-    // Check transient patterns
-    for (const pattern of TRANSIENT_ERROR_PATTERNS) {
-      if (pattern.test(message)) {
-        return 'transient';
-      }
-    }
-    return null;
-  }
-  function classify(error) {
-    // 1. Try custom classifiers first
-    for (const classifier of customClassifiers) {
-      const result = classifier(error);
-      if (result !== null) {
-        return {
-          classification: result,
-          retryConfig: retryConfigs[result],
-          sendToDlq: result === 'poison' || result === 'permanent',
-          reason: `Custom classifier: ${result}`
-        };
-      }
-    }
-    const {
-      message,
-      code,
-      status,
-      name
-    } = extractErrorInfo(error);
-    // 2. Check error code
-    if (code && TRANSIENT_ERROR_CODES.has(code)) {
-      return {
-        classification: 'transient',
-        retryConfig: retryConfigs.transient,
-        sendToDlq: false,
-        reason: `Error code: ${code}`
-      };
-    }
-    // 3. Check HTTP status
-    if (status !== undefined) {
-      if (TRANSIENT_HTTP_STATUS.has(status)) {
-        return {
-          classification: 'transient',
-          retryConfig: retryConfigs.transient,
-          sendToDlq: false,
-          reason: `HTTP status: ${status}`
-        };
-      }
-      if (PERMANENT_HTTP_STATUS.has(status)) {
-        return {
-          classification: 'permanent',
-          retryConfig: retryConfigs.permanent,
-          sendToDlq: true,
-          reason: `HTTP status: ${status}`
-        };
-      }
-    }
-    // 4. Check error patterns
-    const patternResult = classifyByPatterns(message) ?? classifyByPatterns(name ?? '');
-    if (patternResult) {
-      return {
-        classification: patternResult,
-        retryConfig: retryConfigs[patternResult],
-        sendToDlq: patternResult === 'poison' || patternResult === 'permanent',
-        reason: `Pattern match: ${message.slice(0, 50)}`
-      };
-    }
-    // 5. Use default classification
-    return {
-      classification: defaultClassification,
-      retryConfig: retryConfigs[defaultClassification],
-      sendToDlq: defaultClassification === 'poison' || defaultClassification === 'permanent',
-      reason: 'No matching pattern, using default'
-    };
-  }
-  function isRetryable(error) {
-    const result = classify(error);
-    return result.classification === 'transient' || result.classification === 'unknown';
-  }
-  function calculateDelay(attempt, retryConfig) {
-    // Exponential backoff: initialDelay * multiplier^attempt
-    const baseDelay = retryConfig.initialDelayMs * Math.pow(retryConfig.backoffMultiplier, attempt);
-    // Cap at maxDelay
-    const cappedDelay = Math.min(baseDelay, retryConfig.maxDelayMs);
-    // Add jitter to prevent thundering herd
-    const jitter = cappedDelay * retryConfig.jitter * Math.random();
-    return Math.round(cappedDelay + jitter);
-  }
-  return {
-    classify,
-    isRetryable,
-    calculateDelay
-  };
-}
-/**
- * Pre-configured error classifier instance
- */
-const defaultErrorClassifier = createErrorClassifier();
-/**
- * Quick helper to check if error is retryable
- */
-function isRetryableError(error) {
-  return defaultErrorClassifier.isRetryable(error);
-}
-/**
- * Quick helper to classify error
- */
-function classifyError(error) {
-  return defaultErrorClassifier.classify(error);
-}
-
-exports.DEFAULT_RETRY_CONFIGS = DEFAULT_RETRY_CONFIGS;
-exports.classifyError = classifyError;
-exports.createErrorClassifier = createErrorClassifier;
-exports.defaultErrorClassifier = defaultErrorClassifier;
-exports.isRetryableError = isRetryableError;

package/dist/core/factory.cjs

@@ -1,148 +0,0 @@
-'use strict';
-
-var types = require('./types.cjs');
-
-/**
- * Generate a UUID v7 (time-sortable)
- *
- * UUID v7 format: timestamp (48 bits) + version (4 bits) + random (12 bits) + variant (2 bits) + random (62 bits)
- */
-function generateEventId() {
-  // Get timestamp in milliseconds
-  const timestamp = Date.now();
-  // Convert to hex (12 characters for 48 bits)
-  const timestampHex = timestamp.toString(16).padStart(12, '0');
-  // Generate random bytes
-  const randomBytes = new Uint8Array(10);
-  crypto.getRandomValues(randomBytes);
-  // Convert to hex
-  const randomHex = Array.from(randomBytes).map(b => b.toString(16).padStart(2, '0')).join('');
-  // Construct UUID v7
-  // Format: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx
-  // Where x is timestamp/random and 7 is version, y is variant (8, 9, a, or b)
-  const uuid = [timestampHex.slice(0, 8),
-  // time_low
-  timestampHex.slice(8, 12),
-  // time_mid
-  '7' + randomHex.slice(0, 3),
-  // version (7) + random
-  (parseInt(randomHex.slice(3, 5), 16) & 0x3f | 0x80).toString(16).padStart(2, '0') + randomHex.slice(5, 7),
-  // variant + random
-  randomHex.slice(7, 19) // random
-  ].join('-');
-  return uuid;
-}
-/**
- * Generate a correlation ID (also UUID v7 for traceability)
- */
-function generateCorrelationId() {
-  return generateEventId();
-}
-/**
- * Create a single event
- */
-function createEvent(type, data, options) {
-  const id = options.id ?? generateEventId();
-  const correlationId = options.correlationId ?? generateCorrelationId();
-  const timestamp = options.timestamp ?? new Date().toISOString();
-  const actor = options.actor ?? {
-    id: 'system',
-    type: 'system'
-  };
-  const metadata = {
-    source: options.source,
-    environment: options.environment,
-    ...options.metadata
-  };
-  return {
-    id,
-    type,
-    version: options.version ?? types.DEFAULT_EVENT_VERSION,
-    timestamp,
-    correlationId,
-    causationId: options.causationId,
-    actor,
-    metadata,
-    data,
-    priority: options.priority,
-    aggregate: options.aggregate
-  };
-}
-/**
- * Create an event factory with default configuration
- *
- * @example
- * ```typescript
- * const factory = createEventFactory({
- *   source: 'trade-service',
- *   environment: process.env.NODE_ENV || 'development',
- * });
- *
- * const event = factory.create('TradeProposalCreated', {
- *   tradeId: '123',
- *   initiatorId: 'user-1',
- *   recipientId: 'user-2',
- * }, {
- *   actor: { id: 'user-1', type: 'user' },
- *   priority: 'high',
- * });
- * ```
- */
-function createEventFactory(config) {
-  // Thread-local-like storage for correlation ID
-  let currentCorrelationId;
-  const systemActor = config.systemActor ?? {
-    id: 'system',
-    type: 'system',
-    name: config.source
-  };
-  const generateId = config.generateId ?? generateEventId;
-  const generateCorrelation = config.generateCorrelationId ?? generateCorrelationId;
-  return {
-    create(type, data, options = {}) {
-      const id = options.id ?? generateId();
-      const correlationId = options.correlationId ?? currentCorrelationId ?? generateCorrelation();
-      const timestamp = options.timestamp ?? new Date().toISOString();
-      const actor = options.actor ?? systemActor;
-      const metadata = {
-        source: config.source,
-        environment: config.environment,
-        ...options.metadata
-      };
-      return {
-        id,
-        type,
-        version: options.version ?? types.DEFAULT_EVENT_VERSION,
-        timestamp,
-        correlationId,
-        causationId: options.causationId,
-        actor,
-        metadata,
-        data,
-        priority: options.priority,
-        aggregate: options.aggregate
-      };
-    },
-    createFromCause(type, data, cause, options = {}) {
-      return this.create(type, data, {
-        ...options,
-        correlationId: cause.correlationId,
-        causationId: cause.id
-      });
-    },
-    getCorrelationId() {
-      return currentCorrelationId;
-    },
-    setCorrelationId(id) {
-      currentCorrelationId = id;
-    },
-    clearCorrelationId() {
-      currentCorrelationId = undefined;
-    }
-  };
-}
-
-exports.createEvent = createEvent;
-exports.createEventFactory = createEventFactory;
-exports.generateCorrelationId = generateCorrelationId;
-exports.generateEventId = generateEventId;

package/dist/core/idempotency.cjs

@@ -1,252 +0,0 @@
-'use strict';
-
-/**
- * In-memory idempotency store
- *
- * Best for:
- * - Development and testing
- * - Single-instance deployments
- * - Short-lived processes
- *
- * NOT recommended for:
- * - Production multi-instance deployments
- * - Long-running processes with many events
- */
-class InMemoryIdempotencyStore {
-  records = new Map();
-  cleanupTimer;
-  defaultTtlMs;
-  defaultLockTtlMs;
-  maxRecords;
-  constructor(config = {}) {
-    this.defaultTtlMs = config.defaultTtlMs ?? 24 * 60 * 60 * 1000; // 24 hours
-    this.defaultLockTtlMs = config.defaultLockTtlMs ?? 30 * 1000; // 30 seconds
-    this.maxRecords = config.maxRecords ?? 100000;
-    if (config.cleanupIntervalMs !== 0) {
-      const interval = config.cleanupIntervalMs ?? 60 * 1000;
-      this.cleanupTimer = setInterval(() => this.cleanup(), interval);
-    }
-  }
-  makeKey(eventId, consumer) {
-    return `${consumer}:${eventId}`;
-  }
-  async check(event, consumer, options = {}) {
-    const key = this.makeKey(event.id, consumer);
-    const record = this.records.get(key);
-    const now = Date.now();
-    // Check for existing record
-    if (record && record.expiresAt > now) {
-      // If processing and lock expired, treat as stale and allow reprocessing
-      if (record.status === 'processing') {
-        const lockExpired = record.startedAt.getTime() + this.defaultLockTtlMs < now;
-        if (lockExpired) {
-          // Lock expired, allow new processing attempt
-          if (options.acquireLock) {
-            const updated = {
-              ...record,
-              startedAt: new Date(),
-              attempts: record.attempts + 1
-            };
-            this.records.set(key, updated);
-            return {
-              isDuplicate: false,
-              lockAcquired: true
-            };
-          }
-          return {
-            isDuplicate: false
-          };
-        }
-        // Still processing within lock period - treat as duplicate
-        return {
-          isDuplicate: true,
-          processedAt: record.startedAt
-        };
-      }
-      // Completed or failed record exists
-      return {
-        isDuplicate: true,
-        processedAt: record.completedAt ?? record.startedAt,
-        result: record.result
-      };
-    }
-    // No existing record or expired
-    if (options.acquireLock !== false) {
-      const ttlMs = options.lockTtlMs ?? this.defaultTtlMs;
-      const newRecord = {
-        eventId: event.id,
-        eventType: event.type,
-        startedAt: new Date(),
-        status: 'processing',
-        consumer,
-        attempts: 1,
-        expiresAt: now + ttlMs
-      };
-      this.records.set(key, newRecord);
-      this.enforceMaxRecords();
-      return {
-        isDuplicate: false,
-        lockAcquired: true
-      };
-    }
-    return {
-      isDuplicate: false
-    };
-  }
-  async markProcessing(event, consumer, ttlMs) {
-    const result = await this.check(event, consumer, {
-      acquireLock: true,
-      lockTtlMs: ttlMs ?? this.defaultLockTtlMs
-    });
-    return result.lockAcquired ?? false;
-  }
-  async markCompleted(event, consumer, result, ttlMs) {
-    const key = this.makeKey(event.id, consumer);
-    const record = this.records.get(key);
-    const now = Date.now();
-    const updated = {
-      eventId: event.id,
-      eventType: event.type,
-      startedAt: record?.startedAt ?? new Date(),
-      completedAt: new Date(),
-      status: 'completed',
-      result,
-      consumer,
-      attempts: record?.attempts ?? 1,
-      expiresAt: now + (ttlMs ?? this.defaultTtlMs)
-    };
-    this.records.set(key, updated);
-  }
-  async markFailed(event, consumer, error) {
-    const key = this.makeKey(event.id, consumer);
-    const record = this.records.get(key);
-    const now = Date.now();
-    const errorStr = error instanceof Error ? error.message : String(error);
-    const updated = {
-      eventId: event.id,
-      eventType: event.type,
-      startedAt: record?.startedAt ?? new Date(),
-      completedAt: new Date(),
-      status: 'failed',
-      error: errorStr,
-      consumer,
-      attempts: record?.attempts ?? 1,
-      expiresAt: now + this.defaultTtlMs
-    };
-    this.records.set(key, updated);
-  }
-  async releaseLock(event, consumer) {
-    const key = this.makeKey(event.id, consumer);
-    this.records.delete(key);
-  }
-  async getRecord(eventId, consumer) {
-    const key = this.makeKey(eventId, consumer);
-    const record = this.records.get(key);
-    if (!record || record.expiresAt < Date.now()) {
-      return null;
-    }
-    // Return without internal expiresAt field
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const {
-      expiresAt: _,
-      ...publicRecord
-    } = record;
-    return publicRecord;
-  }
-  async cleanup() {
-    const now = Date.now();
-    let cleaned = 0;
-    for (const [key, record] of Array.from(this.records.entries())) {
-      if (record.expiresAt < now) {
-        this.records.delete(key);
-        cleaned++;
-      }
-    }
-    return cleaned;
-  }
-  /**
-   * Enforce max records limit using LRU-like eviction
-   */
-  enforceMaxRecords() {
-    if (this.records.size <= this.maxRecords) return;
-    // Sort by expires time (oldest first)
-    const entries = Array.from(this.records.entries()).sort((a, b) => a[1].expiresAt - b[1].expiresAt);
-    // Remove oldest 10%
-    const toRemove = Math.ceil(this.maxRecords * 0.1);
-    for (let i = 0; i < toRemove && i < entries.length; i++) {
-      this.records.delete(entries[i][0]);
-    }
-  }
-  /**
-   * Stop cleanup timer (for graceful shutdown)
-   */
-  dispose() {
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = undefined;
-    }
-  }
-  /**
-   * Clear all records (for testing)
-   */
-  clear() {
-    this.records.clear();
-  }
-  /**
-   * Get stats (for monitoring)
-   */
-  getStats() {
-    return {
-      size: this.records.size,
-      maxRecords: this.maxRecords
-    };
-  }
-}
-/**
- * Create an in-memory idempotency store
- *
- * @example
- * ```typescript
- * const store = createInMemoryIdempotencyStore({
- *   defaultTtlMs: 60 * 60 * 1000, // 1 hour
- *   maxRecords: 50000,
- * });
- *
- * // In your subscriber
- * const result = await store.check(event, 'my-subscriber');
- * if (result.isDuplicate) {
- *   return result.result; // Return cached result
- * }
- *
- * try {
- *   const processResult = await processEvent(event);
- *   await store.markCompleted(event, 'my-subscriber', processResult);
- *   return processResult;
- * } catch (error) {
- *   await store.markFailed(event, 'my-subscriber', error);
- *   throw error;
- * }
- * ```
- */
-function createInMemoryIdempotencyStore(config) {
-  return new InMemoryIdempotencyStore(config);
-}
-/**
- * Generate an idempotency key from event
- * Useful for custom implementations
- */
-function generateIdempotencyKey(event, consumer) {
-  return `idempotency:${consumer}:${event.id}`;
-}
-/**
- * Generate an idempotency key from correlation ID
- * Useful for request-level idempotency
- */
-function generateCorrelationKey(correlationId, operation) {
-  return `idempotency:correlation:${operation}:${correlationId}`;
-}
-
-exports.InMemoryIdempotencyStore = InMemoryIdempotencyStore;
-exports.createInMemoryIdempotencyStore = createInMemoryIdempotencyStore;
-exports.generateCorrelationKey = generateCorrelationKey;
-exports.generateIdempotencyKey = generateIdempotencyKey;