@signaltree/events 7.3.5 → 7.3.6

package/idempotency.cjs.js

@@ -0,0 +1,713 @@
+'use strict';
+
+/**
+ * Event Registry class - manages all registered event types
+ *
+ * @example
+ * ```typescript
+ * const registry = createEventRegistry();
+ *
+ * // Register events
+ * registry.register({
+ *   type: 'TradeProposalCreated',
+ *   schema: TradeProposalCreatedSchema,
+ *   priority: 'high',
+ *   description: 'Emitted when a user proposes a trade',
+ *   category: 'trade',
+ * });
+ *
+ * // Validate events
+ * const validated = registry.validate(rawEvent);
+ *
+ * // Get schema for event type
+ * const schema = registry.getSchema('TradeProposalCreated');
+ * ```
+ */
+class EventRegistry {
+  events = new Map();
+  config;
+  constructor(config = {}) {
+    this.config = {
+      strict: config.strict ?? false,
+      warnOnDeprecated: config.warnOnDeprecated ?? true
+    };
+  }
+  /**
+   * Register an event type with its schema
+   */
+  register(event) {
+    if (this.events.has(event.type)) {
+      throw new Error(`Event type '${event.type}' is already registered`);
+    }
+    this.events.set(event.type, event);
+    return this;
+  }
+  /**
+   * Register multiple events at once
+   */
+  registerMany(events) {
+    for (const event of events) {
+      this.register(event);
+    }
+    return this;
+  }
+  /**
+   * Get schema for an event type
+   */
+  getSchema(type) {
+    return this.events.get(type)?.schema;
+  }
+  /**
+   * Get registered event info
+   */
+  getEvent(type) {
+    return this.events.get(type);
+  }
+  /**
+   * Check if event type is registered
+   */
+  has(type) {
+    return this.events.has(type);
+  }
+  /**
+   * Get default priority for event type
+   */
+  getPriority(type) {
+    return this.events.get(type)?.priority ?? 'normal';
+  }
+  /**
+   * Validate an event against its registered schema
+   *
+   * @throws Error if event type is unknown (in strict mode) or validation fails
+   */
+  validate(event) {
+    if (typeof event !== 'object' || event === null) {
+      throw new Error('Event must be an object');
+    }
+    const eventObj = event;
+    const type = eventObj['type'];
+    if (!type) {
+      throw new Error('Event must have a type field');
+    }
+    const registered = this.events.get(type);
+    if (!registered) {
+      if (this.config.strict) {
+        throw new Error(`Unknown event type: ${type}`);
+      }
+      // In non-strict mode, return as-is (no validation)
+      return event;
+    }
+    // Warn about deprecated events
+    if (registered.deprecated && this.config.warnOnDeprecated) {
+      console.warn(`[EventRegistry] Event '${type}' is deprecated. ${registered.deprecationMessage ?? ''}`);
+    }
+    const result = registered.schema.safeParse(event);
+    if (!result.success) {
+      const errors = result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`);
+      throw new Error(`Event validation failed for '${type}': ${errors.join(', ')}`);
+    }
+    return result.data;
+  }
+  /**
+   * Check if event is valid without throwing
+   */
+  isValid(event) {
+    try {
+      this.validate(event);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get all registered event types
+   */
+  getAllTypes() {
+    return Array.from(this.events.keys());
+  }
+  /**
+   * Get all registered events
+   */
+  getAll() {
+    return Array.from(this.events.values());
+  }
+  /**
+   * Get events by category
+   */
+  getByCategory(category) {
+    return this.getAll().filter(e => e.category === category);
+  }
+  /**
+   * Get event catalog for documentation
+   */
+  getCatalog() {
+    return this.getAll().map(e => ({
+      type: e.type,
+      category: e.category,
+      priority: e.priority,
+      description: e.description,
+      deprecated: e.deprecated ?? false
+    }));
+  }
+  /**
+   * Export registry as JSON schema (for external tools)
+   */
+  toJSONSchema() {
+    const schemas = {};
+    for (const [type, event] of Array.from(this.events.entries())) {
+      // Note: This is a simplified JSON schema export
+      // For full compatibility, use zod-to-json-schema package
+      schemas[type] = {
+        type: 'object',
+        description: event.description,
+        deprecated: event.deprecated,
+        priority: event.priority,
+        category: event.category
+      };
+    }
+    return {
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      title: 'Event Registry',
+      definitions: schemas
+    };
+  }
+}
+/**
+ * Create a new event registry
+ */
+function createEventRegistry(config) {
+  return new EventRegistry(config);
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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.DEFAULT_RETRY_CONFIGS = DEFAULT_RETRY_CONFIGS;
+exports.EventRegistry = EventRegistry;
+exports.InMemoryIdempotencyStore = InMemoryIdempotencyStore;
+exports.classifyError = classifyError;
+exports.createErrorClassifier = createErrorClassifier;
+exports.createEventRegistry = createEventRegistry;
+exports.createInMemoryIdempotencyStore = createInMemoryIdempotencyStore;
+exports.defaultErrorClassifier = defaultErrorClassifier;
+exports.generateCorrelationKey = generateCorrelationKey;
+exports.generateIdempotencyKey = generateIdempotencyKey;
+exports.isRetryableError = isRetryableError;