@signaltree/events 7.3.6 → 7.4.1

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/{factory.cjs.js → dist/core/factory.cjs}

@@ -1,41 +1,6 @@
 'use strict';
 
-/**
- * Core event types - framework-agnostic definitions
- */
-/**
- * Priority configuration with SLA targets
- */
-const EVENT_PRIORITIES = {
-  critical: {
-    sla: 100,
-    weight: 10
-  },
-  // < 100ms
-  high: {
-    sla: 500,
-    weight: 7
-  },
-  // < 500ms
-  normal: {
-    sla: 2000,
-    weight: 5
-  },
-  // < 2s
-  low: {
-    sla: 30000,
-    weight: 3
-  },
-  // < 30s
-  bulk: {
-    sla: 300000,
-    weight: 1
-  } // < 5min
-};
-const DEFAULT_EVENT_VERSION = {
-  major: 1,
-  minor: 0
-};
+var types = require('./types.cjs');
 
 /**
  * Generate a UUID v7 (time-sortable)
@@ -92,7 +57,7 @@ function createEvent(type, data, options) {
   return {
     id,
     type,
-    version: options.version ?? DEFAULT_EVENT_VERSION,
+    version: options.version ?? types.DEFAULT_EVENT_VERSION,
     timestamp,
     correlationId,
     causationId: options.causationId,
@@ -147,7 +112,7 @@ function createEventFactory(config) {
       return {
         id,
         type,
-        version: options.version ?? DEFAULT_EVENT_VERSION,
+        version: options.version ?? types.DEFAULT_EVENT_VERSION,
         timestamp,
         correlationId,
         causationId: options.causationId,
@@ -177,8 +142,6 @@ function createEventFactory(config) {
   };
 }
 
-exports.DEFAULT_EVENT_VERSION = DEFAULT_EVENT_VERSION;
-exports.EVENT_PRIORITIES = EVENT_PRIORITIES;
 exports.createEvent = createEvent;
 exports.createEventFactory = createEventFactory;
 exports.generateCorrelationId = generateCorrelationId;

package/{factory.esm.js → dist/core/factory.js}

@@ -1,39 +1,4 @@
-/**
- * Core event types - framework-agnostic definitions
- */
-/**
- * Priority configuration with SLA targets
- */
-const EVENT_PRIORITIES = {
-  critical: {
-    sla: 100,
-    weight: 10
-  },
-  // < 100ms
-  high: {
-    sla: 500,
-    weight: 7
-  },
-  // < 500ms
-  normal: {
-    sla: 2000,
-    weight: 5
-  },
-  // < 2s
-  low: {
-    sla: 30000,
-    weight: 3
-  },
-  // < 30s
-  bulk: {
-    sla: 300000,
-    weight: 1
-  } // < 5min
-};
-const DEFAULT_EVENT_VERSION = {
-  major: 1,
-  minor: 0
-};
+import { DEFAULT_EVENT_VERSION } from './types.js';
 
 /**
  * Generate a UUID v7 (time-sortable)
@@ -175,4 +140,4 @@ function createEventFactory(config) {
   };
 }
 
-export { DEFAULT_EVENT_VERSION as D, EVENT_PRIORITIES as E, createEventFactory as a, generateCorrelationId as b, createEvent as c, generateEventId as g };
+export { createEvent, createEventFactory, generateCorrelationId, generateEventId };

package/dist/core/idempotency.cjs

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