@signaltree/events 7.3.6 → 7.4.1

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 };

package/dist/core/registry.cjs

@@ -0,0 +1,183 @@
+'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);
+}
+
+exports.EventRegistry = EventRegistry;
+exports.createEventRegistry = createEventRegistry;

package/dist/core/registry.js

@@ -0,0 +1,180 @@
+/**
+ * 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);
+}
+
+export { EventRegistry, createEventRegistry };

package/dist/core/types.cjs

@@ -0,0 +1,41 @@
+'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
+};
+
+exports.DEFAULT_EVENT_VERSION = DEFAULT_EVENT_VERSION;
+exports.EVENT_PRIORITIES = EVENT_PRIORITIES;

package/dist/core/types.js

@@ -0,0 +1,38 @@
+/**
+ * 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
+};
+
+export { DEFAULT_EVENT_VERSION, EVENT_PRIORITIES };