@signaltree/events 7.3.5 → 7.4.0

package/dist/core/error-classification.cjs

@@ -0,0 +1,282 @@
+'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/error-classification.js

@@ -0,0 +1,276 @@
+/**
+ * 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);
+}
+
+export { DEFAULT_RETRY_CONFIGS, classifyError, createErrorClassifier, defaultErrorClassifier, isRetryableError };

package/dist/core/factory.cjs

@@ -0,0 +1,148 @@
+'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;