@signaltree/events 7.3.5 → 7.4.0

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;

package/dist/core/idempotency.js

@@ -0,0 +1,247 @@
+/**
+ * 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 { InMemoryIdempotencyStore, createInMemoryIdempotencyStore, generateCorrelationKey, generateIdempotencyKey };