@signaltree/events 7.3.1

package/idempotency.esm.js

@@ -0,0 +1,701 @@
+/**
+ * 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}`;
+}
+
+export { DEFAULT_RETRY_CONFIGS as D, EventRegistry as E, InMemoryIdempotencyStore as I, classifyError as a, createErrorClassifier as b, createEventRegistry as c, defaultErrorClassifier as d, createInMemoryIdempotencyStore as e, generateCorrelationKey as f, generateIdempotencyKey as g, isRetryableError as i };

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";