@signaltree/events 7.3.5 → 7.4.0

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

package/dist/core/validation.cjs

@@ -0,0 +1,185 @@
+'use strict';
+
+var zod = require('zod');
+
+/**
+ * Event validation using Zod schemas
+ *
+ * Provides:
+ * - Base schemas for common event fields
+ * - Factory function to create event schemas
+ * - Runtime validation with detailed errors
+ */
+// ============================================================================
+// Base Schemas
+// ============================================================================
+/**
+ * Schema for event actor
+ */
+const EventActorSchema = zod.z.object({
+  id: zod.z.string().min(1),
+  type: zod.z.enum(['user', 'system', 'admin', 'webhook']),
+  name: zod.z.string().optional()
+});
+/**
+ * Schema for event version
+ */
+const EventVersionSchema = zod.z.object({
+  major: zod.z.number().int().min(1),
+  minor: zod.z.number().int().min(0)
+});
+/**
+ * Schema for event metadata
+ */
+const EventMetadataSchema = zod.z.object({
+  source: zod.z.string().min(1),
+  environment: zod.z.string().min(1),
+  ip: zod.z.string().optional(),
+  userAgent: zod.z.string().optional()
+}).passthrough(); // Allow additional properties
+/**
+ * Schema for aggregate info
+ */
+const AggregateSchema = zod.z.object({
+  type: zod.z.string().min(1),
+  id: zod.z.string().min(1)
+}).optional();
+/**
+ * Base event schema without data field
+ */
+const BaseEventSchema = zod.z.object({
+  id: zod.z.string().uuid(),
+  type: zod.z.string().min(1),
+  version: EventVersionSchema,
+  timestamp: zod.z.string().datetime(),
+  correlationId: zod.z.string().uuid(),
+  causationId: zod.z.string().uuid().optional(),
+  actor: EventActorSchema,
+  metadata: EventMetadataSchema,
+  priority: zod.z.enum(['critical', 'high', 'normal', 'low', 'bulk']).optional(),
+  aggregate: AggregateSchema
+});
+// ============================================================================
+// Schema Factory
+// ============================================================================
+/**
+ * Create a typed event schema with Zod validation
+ *
+ * @param eventType - The event type string (e.g., 'TradeProposalCreated')
+ * @param dataSchema - Zod schema for the event's data field
+ * @returns Complete event schema
+ *
+ * @example
+ * ```typescript
+ * const TradeProposalCreatedSchema = createEventSchema('TradeProposalCreated', {
+ *   tradeId: z.string().uuid(),
+ *   initiatorId: z.string().uuid(),
+ *   recipientId: z.string().uuid(),
+ *   vehicleOfferedId: z.string().uuid(),
+ *   terms: z.object({
+ *     cashDifference: z.number().optional(),
+ *   }),
+ * });
+ *
+ * type TradeProposalCreated = z.infer<typeof TradeProposalCreatedSchema>;
+ * ```
+ */
+function createEventSchema(eventType, dataSchema) {
+  return BaseEventSchema.extend({
+    type: zod.z.literal(eventType),
+    data: zod.z.object(dataSchema)
+  });
+}
+/**
+ * Create event schema from existing Zod object
+ */
+function createEventSchemaFromZod(eventType, dataSchema) {
+  return BaseEventSchema.extend({
+    type: zod.z.literal(eventType),
+    data: dataSchema
+  });
+}
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Custom error class for event validation failures
+ */
+class EventValidationError extends Error {
+  zodError;
+  event;
+  constructor(message, zodError, event) {
+    super(message);
+    this.zodError = zodError;
+    this.event = event;
+    this.name = 'EventValidationError';
+  }
+  /**
+   * Get formatted error messages
+   */
+  get issues() {
+    return this.zodError.issues.map(issue => {
+      const path = issue.path.join('.');
+      return path ? `${path}: ${issue.message}` : issue.message;
+    });
+  }
+}
+/**
+ * Validate an event against a schema, throwing on failure
+ *
+ * @param schema - Zod schema to validate against
+ * @param event - Event to validate
+ * @returns Validated and typed event
+ * @throws EventValidationError if validation fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const validEvent = validateEvent(TradeProposalCreatedSchema, rawEvent);
+ *   // validEvent is typed as TradeProposalCreated
+ * } catch (error) {
+ *   if (error instanceof EventValidationError) {
+ *     console.error('Validation failed:', error.issues);
+ *   }
+ * }
+ * ```
+ */
+function validateEvent(schema, event) {
+  const result = schema.safeParse(event);
+  if (!result.success) {
+    throw new EventValidationError(`Event validation failed: ${result.error.issues.map(i => i.message).join(', ')}`, result.error, event);
+  }
+  return result.data;
+}
+/**
+ * Check if an event is valid without throwing
+ *
+ * @param schema - Zod schema to validate against
+ * @param event - Event to check
+ * @returns true if valid, false otherwise
+ */
+function isValidEvent(schema, event) {
+  return schema.safeParse(event).success;
+}
+/**
+ * Parse an event, returning result with success/error
+ *
+ * @param schema - Zod schema to parse with
+ * @param event - Event to parse
+ * @returns SafeParseResult with data or error
+ */
+function parseEvent(schema, event) {
+  return schema.safeParse(event);
+}
+
+exports.AggregateSchema = AggregateSchema;
+exports.BaseEventSchema = BaseEventSchema;
+exports.EventActorSchema = EventActorSchema;
+exports.EventMetadataSchema = EventMetadataSchema;
+exports.EventValidationError = EventValidationError;
+exports.EventVersionSchema = EventVersionSchema;
+exports.createEventSchema = createEventSchema;
+exports.createEventSchemaFromZod = createEventSchemaFromZod;
+exports.isValidEvent = isValidEvent;
+exports.parseEvent = parseEvent;
+exports.validateEvent = validateEvent;

package/{index.esm.js → dist/core/validation.js}

@@ -1,7 +1,4 @@
-export { D as DEFAULT_EVENT_VERSION, E as EVENT_PRIORITIES, c as createEvent, a as createEventFactory, b as generateCorrelationId, g as generateEventId } from './factory.esm.js';
 import { z } from 'zod';
-export { z } from 'zod';
-export { D as DEFAULT_RETRY_CONFIGS, E as EventRegistry, I as InMemoryIdempotencyStore, a as classifyError, b as createErrorClassifier, c as createEventRegistry, e as createInMemoryIdempotencyStore, d as defaultErrorClassifier, f as generateCorrelationKey, g as generateIdempotencyKey, i as isRetryableError } from './idempotency.esm.js';
 
 /**
  * Event validation using Zod schemas
@@ -173,4 +170,4 @@ function parseEvent(schema, event) {
   return schema.safeParse(event);
 }
 
-export { BaseEventSchema, EventActorSchema, EventMetadataSchema, EventValidationError, EventVersionSchema, createEventSchema, createEventSchemaFromZod, isValidEvent, parseEvent, validateEvent };
+export { AggregateSchema, BaseEventSchema, EventActorSchema, EventMetadataSchema, EventValidationError, EventVersionSchema, createEventSchema, createEventSchemaFromZod, isValidEvent, parseEvent, validateEvent };

package/dist/index.cjs

@@ -0,0 +1,43 @@
+'use strict';
+
+var types = require('./core/types.cjs');
+var validation = require('./core/validation.cjs');
+var registry = require('./core/registry.cjs');
+var factory = require('./core/factory.cjs');
+var errorClassification = require('./core/error-classification.cjs');
+var idempotency = require('./core/idempotency.cjs');
+var zod = require('zod');
+
+
+
+exports.DEFAULT_EVENT_VERSION = types.DEFAULT_EVENT_VERSION;
+exports.EVENT_PRIORITIES = types.EVENT_PRIORITIES;
+exports.BaseEventSchema = validation.BaseEventSchema;
+exports.EventActorSchema = validation.EventActorSchema;
+exports.EventMetadataSchema = validation.EventMetadataSchema;
+exports.EventValidationError = validation.EventValidationError;
+exports.EventVersionSchema = validation.EventVersionSchema;
+exports.createEventSchema = validation.createEventSchema;
+exports.createEventSchemaFromZod = validation.createEventSchemaFromZod;
+exports.isValidEvent = validation.isValidEvent;
+exports.parseEvent = validation.parseEvent;
+exports.validateEvent = validation.validateEvent;
+exports.EventRegistry = registry.EventRegistry;
+exports.createEventRegistry = registry.createEventRegistry;
+exports.createEvent = factory.createEvent;
+exports.createEventFactory = factory.createEventFactory;
+exports.generateCorrelationId = factory.generateCorrelationId;
+exports.generateEventId = factory.generateEventId;
+exports.DEFAULT_RETRY_CONFIGS = errorClassification.DEFAULT_RETRY_CONFIGS;
+exports.classifyError = errorClassification.classifyError;
+exports.createErrorClassifier = errorClassification.createErrorClassifier;
+exports.defaultErrorClassifier = errorClassification.defaultErrorClassifier;
+exports.isRetryableError = errorClassification.isRetryableError;
+exports.InMemoryIdempotencyStore = idempotency.InMemoryIdempotencyStore;
+exports.createInMemoryIdempotencyStore = idempotency.createInMemoryIdempotencyStore;
+exports.generateCorrelationKey = idempotency.generateCorrelationKey;
+exports.generateIdempotencyKey = idempotency.generateIdempotencyKey;
+Object.defineProperty(exports, "z", {
+	enumerable: true,
+	get: function () { return zod.z; }
+});

package/dist/index.js

@@ -0,0 +1,7 @@
+export { DEFAULT_EVENT_VERSION, EVENT_PRIORITIES } from './core/types.js';
+export { BaseEventSchema, EventActorSchema, EventMetadataSchema, EventValidationError, EventVersionSchema, createEventSchema, createEventSchemaFromZod, isValidEvent, parseEvent, validateEvent } from './core/validation.js';
+export { EventRegistry, createEventRegistry } from './core/registry.js';
+export { createEvent, createEventFactory, generateCorrelationId, generateEventId } from './core/factory.js';
+export { DEFAULT_RETRY_CONFIGS, classifyError, createErrorClassifier, defaultErrorClassifier, isRetryableError } from './core/error-classification.js';
+export { InMemoryIdempotencyStore, createInMemoryIdempotencyStore, generateCorrelationKey, generateIdempotencyKey } from './core/idempotency.js';
+export { z } from 'zod';