@signaltree/events 7.3.5 → 7.3.6

package/index.cjs.js

@@ -0,0 +1,207 @@
+'use strict';
+
+var factory = require('./factory.cjs.js');
+var zod = require('zod');
+var idempotency = require('./idempotency.cjs.js');
+
+/**
+ * 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.DEFAULT_EVENT_VERSION = factory.DEFAULT_EVENT_VERSION;
+exports.EVENT_PRIORITIES = factory.EVENT_PRIORITIES;
+exports.createEvent = factory.createEvent;
+exports.createEventFactory = factory.createEventFactory;
+exports.generateCorrelationId = factory.generateCorrelationId;
+exports.generateEventId = factory.generateEventId;
+Object.defineProperty(exports, "z", {
+    enumerable: true,
+    get: function () { return zod.z; }
+});
+exports.DEFAULT_RETRY_CONFIGS = idempotency.DEFAULT_RETRY_CONFIGS;
+exports.EventRegistry = idempotency.EventRegistry;
+exports.InMemoryIdempotencyStore = idempotency.InMemoryIdempotencyStore;
+exports.classifyError = idempotency.classifyError;
+exports.createErrorClassifier = idempotency.createErrorClassifier;
+exports.createEventRegistry = idempotency.createEventRegistry;
+exports.createInMemoryIdempotencyStore = idempotency.createInMemoryIdempotencyStore;
+exports.defaultErrorClassifier = idempotency.defaultErrorClassifier;
+exports.generateCorrelationKey = idempotency.generateCorrelationKey;
+exports.generateIdempotencyKey = idempotency.generateIdempotencyKey;
+exports.isRetryableError = idempotency.isRetryableError;
+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;