@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/cjs/event/event-decorators.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * Event Decorators
+ *
+ * @module event
+ *
+ * Decorators for registering event handlers with type safety.
+ *
+ * @example
+ * ```typescript
+ * // Single event handler
+ * @provide(UserCreatedHandler)
+ * @OnEvent(UserCreatedEvent, { priority: 1 })
+ * export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     console.log(`User ${event.userId} created`);
+ *   }
+ * }
+ *
+ * // Conditional handler
+ * @provide(PremiumFeatureHandler)
+ * @OnEvent(UserCreatedEvent)
+ * @When(event => event.user.isPremium)
+ * export class PremiumFeatureHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     // Only runs for premium users
+ *   }
+ * }
+ *
+ * // Multiple event handler
+ * @provide(UserActivityHandler)
+ * @OnEvents([UserCreatedEvent, UserUpdatedEvent, UserDeletedEvent])
+ * export class UserActivityHandler {
+ *   handle(event: UserCreatedEvent | UserUpdatedEvent | UserDeletedEvent) {
+ *     // Handles any of the specified events
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnEvent = OnEvent;
+exports.OnEvents = OnEvents;
+exports.When = When;
+exports.Event = Event;
+exports.isEventHandler = isEventHandler;
+exports.getEventClass = getEventClass;
+exports.getEventClasses = getEventClasses;
+exports.getEventOptions = getEventOptions;
+exports.getEventCondition = getEventCondition;
+exports.getEventMetadata = getEventMetadata;
+require("reflect-metadata");
+const event_interfaces_js_1 = require("./event.interfaces.js");
+// ============================================================================
+// @OnEvent Decorator
+// ============================================================================
+/**
+ * Mark a class as an event handler for a specific event type.
+ *
+ * @template T - Event type
+ * @param eventClass - Event class to handle
+ * @param options - Handler options (priority, async, retry, etc.)
+ *
+ * @example
+ * ```typescript
+ * @provide(UserCreatedHandler)
+ * @OnEvent(UserCreatedEvent)
+ * export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     console.log(`User ${event.userId} created`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With priority (lower = runs first)
+ * @OnEvent(UserCreatedEvent, { priority: 1 })
+ * export class FirstHandler {}
+ *
+ * @OnEvent(UserCreatedEvent, { priority: 2 })
+ * export class SecondHandler {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async handler with retry
+ * @OnEvent(UserCreatedEvent, {
+ *   async: true,
+ *   retry: 3,
+ *   retryDelay: 1000,
+ *   backoff: "exponential"
+ * })
+ * export class ResilientHandler {}
+ * ```
+ */
+function OnEvent(eventClass, options = {}) {
+    return function (target) {
+        // Store event class
+        Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_CLASS, eventClass, target);
+        // Store options with defaults
+        const mergedOptions = {
+            priority: 100,
+            async: false,
+            retry: 0,
+            timeout: 30000,
+            retryDelay: 1000,
+            backoff: "fixed",
+            ...options,
+        };
+        Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_OPTIONS, mergedOptions, target);
+        // Mark as event handler
+        Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.IS_EVENT_HANDLER, true, target);
+    };
+}
+// ============================================================================
+// @OnEvents Decorator
+// ============================================================================
+/**
+ * Mark a class as an event handler for multiple event types.
+ *
+ * @param eventClasses - Array of event classes to handle
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * @provide(UserActivityHandler)
+ * @OnEvents([UserCreatedEvent, UserUpdatedEvent, UserDeletedEvent])
+ * export class UserActivityHandler {
+ *   handle(event: UserCreatedEvent | UserUpdatedEvent | UserDeletedEvent) {
+ *     // Called for any of the specified events
+ *     this.analytics.trackUserActivity(event);
+ *   }
+ * }
+ * ```
+ */
+function OnEvents(eventClasses, options = {}) {
+    return function (target) {
+        // Store all event classes
+        Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_CLASSES, eventClasses, target);
+        // Store first event class for compatibility
+        if (eventClasses.length > 0) {
+            Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_CLASS, eventClasses[0], target);
+        }
+        // Store options with defaults
+        const mergedOptions = {
+            priority: 100,
+            async: false,
+            retry: 0,
+            timeout: 30000,
+            retryDelay: 1000,
+            backoff: "fixed",
+            ...options,
+        };
+        Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_OPTIONS, mergedOptions, target);
+        // Mark as event handler
+        Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.IS_EVENT_HANDLER, true, target);
+    };
+}
+// ============================================================================
+// @When Decorator
+// ============================================================================
+/**
+ * Add a condition to an event handler.
+ * Handler will only execute if condition returns true.
+ *
+ * @template T - Event type
+ * @param condition - Condition function or options object
+ *
+ * @example
+ * ```typescript
+ * // Simple condition function
+ * @provide(PremiumHandler)
+ * @OnEvent(UserCreatedEvent)
+ * @When(event => event.user.isPremium)
+ * export class PremiumHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     // Only runs for premium users
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With reason for debugging
+ * @When({
+ *   condition: event => event.user.region === "EU",
+ *   reason: "GDPR compliance for EU users"
+ * })
+ * export class GDPRHandler {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async condition
+ * @When(async event => {
+ *   const features = await featureService.getFeatures(event.userId);
+ *   return features.includes("premium");
+ * })
+ * export class FeatureFlagHandler {}
+ * ```
+ */
+function When(conditionOrOptions) {
+    return function (target) {
+        const whenOptions = typeof conditionOrOptions === "function"
+            ? { condition: conditionOrOptions }
+            : conditionOrOptions;
+        Reflect.defineMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_CONDITION, whenOptions, target);
+    };
+}
+// ============================================================================
+// @Event Decorator (for event classes)
+// ============================================================================
+/**
+ * Mark a class as an event with optional metadata.
+ * This is optional but provides additional documentation and versioning.
+ *
+ * @param metadata - Event metadata
+ *
+ * @example
+ * ```typescript
+ * @Event({
+ *   name: "user.created",
+ *   version: 1,
+ *   description: "Emitted when a new user is created",
+ *   tags: ["user", "auth"]
+ * })
+ * export class UserCreatedEvent {
+ *   constructor(
+ *     public readonly userId: string,
+ *     public readonly email: string,
+ *     public readonly timestamp: Date = new Date()
+ *   ) {}
+ * }
+ * ```
+ */
+function Event(metadata = {}) {
+    return function (target) {
+        // Store metadata on the event class itself
+        Reflect.defineMetadata("expressots:event:metadata", metadata, target);
+    };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Check if a class is an event handler.
+ */
+function isEventHandler(target) {
+    return Reflect.getMetadata(event_interfaces_js_1.EVENT_METADATA.IS_EVENT_HANDLER, target) === true;
+}
+/**
+ * Get the event class from a handler.
+ */
+function getEventClass(handler) {
+    return Reflect.getMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_CLASS, handler);
+}
+/**
+ * Get all event classes from a handler (for @OnEvents).
+ */
+function getEventClasses(handler) {
+    return Reflect.getMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_CLASSES, handler);
+}
+/**
+ * Get handler options.
+ */
+function getEventOptions(handler) {
+    return Reflect.getMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_OPTIONS, handler);
+}
+/**
+ * Get handler condition.
+ */
+function getEventCondition(handler) {
+    return Reflect.getMetadata(event_interfaces_js_1.EVENT_METADATA.EVENT_CONDITION, handler);
+}
+/**
+ * Get event metadata from an event class.
+ */
+function getEventMetadata(eventClass) {
+    return Reflect.getMetadata("expressots:event:metadata", eventClass);
+}

package/lib/cjs/event/event-emitter.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Event Emitter Service
+ *
+ * @module event
+ *
+ * Type-safe event emitter with support for:
+ * - Priority-based handler execution
+ * - Conditional handlers
+ * - Async handlers with retry
+ * - Event recording and flow tracking
+ *
+ * @example
+ * ```typescript
+ * @inject(EventEmitter)
+ * private eventEmitter: EventEmitter;
+ *
+ * async createUser(data: CreateUserDto) {
+ *   const user = await this.userRepo.create(data);
+ *   await this.eventEmitter.emit(new UserCreatedEvent(user.id, user.email));
+ *   return user;
+ * }
+ * ```
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventEmitter = void 0;
+exports.createEventEmitter = createEventEmitter;
+const inversify_js_1 = require("../di/inversify.js");
+const logger_provider_js_1 = require("../provider/logger/logger.provider.js");
+const event_flow_tracker_js_1 = require("./event-flow-tracker.js");
+const event_recorder_js_1 = require("./event-recorder.js");
+const event_registry_js_1 = require("./event-registry.js");
+/**
+ * Default event system configuration.
+ */
+const DEFAULT_CONFIG = {
+    enableRecording: process.env.NODE_ENV === "development",
+    enableFlowTracking: process.env.NODE_ENV === "development",
+    maxRecordedEvents: 1000,
+    defaultTimeout: 30000,
+};
+/**
+ * Event emitter service.
+ *
+ * Dispatches events to registered handlers with full type safety.
+ *
+ * NOTE: This class uses @injectable() instead of @provide() because
+ * it must be registered as a Singleton by the application to ensure
+ * the same instance is used throughout the request lifecycle.
+ */
+let EventEmitter = class EventEmitter {
+    constructor(registry, container, recorder, flowTracker, logger) {
+        this.registry = registry;
+        this.container = container;
+        this.recorder = recorder;
+        this.flowTracker = flowTracker;
+        this.logger = logger;
+        this.config = { ...DEFAULT_CONFIG };
+    }
+    /**
+     * Configure the event emitter.
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Set correlation ID for tracking.
+     */
+    setCorrelationId(id) {
+        this.currentCorrelationId = id;
+    }
+    /**
+     * Emit an event to all registered handlers.
+     * Waits for sync handlers, fires async handlers in background.
+     */
+    async emit(event) {
+        const eventClass = event.constructor;
+        const handlers = this.registry.getHandlers(eventClass);
+        if (handlers.length === 0) {
+            return;
+        }
+        // Notify config callback
+        if (this.config.onEmit) {
+            this.config.onEmit(event);
+        }
+        const results = [];
+        const asyncPromises = [];
+        for (const handler of handlers) {
+            if (handler.options.async) {
+                // Fire async handlers in background
+                asyncPromises.push(this.executeHandler(handler, event).then((result) => {
+                    results.push(result);
+                }));
+            }
+            else {
+                // Wait for sync handlers
+                const result = await this.executeHandler(handler, event);
+                results.push(result);
+            }
+        }
+        // Record event if enabled
+        if (this.config.enableRecording && this.recorder) {
+            this.recorder.record(event, this.formatResultsForRecording(results));
+        }
+        // Don't wait for async handlers
+        if (asyncPromises.length > 0) {
+            Promise.all(asyncPromises).catch((error) => {
+                this.logger?.error("Async event handler failed", error);
+            });
+        }
+    }
+    /**
+     * Emit an event and wait for ALL handlers (including async).
+     */
+    async emitAndWait(event) {
+        const eventClass = event.constructor;
+        const handlers = this.registry.getHandlers(eventClass);
+        if (handlers.length === 0) {
+            return;
+        }
+        // Notify config callback
+        if (this.config.onEmit) {
+            this.config.onEmit(event);
+        }
+        const results = [];
+        // Execute all handlers in order, waiting for each
+        for (const handler of handlers) {
+            const result = await this.executeHandler(handler, event);
+            results.push(result);
+        }
+        // Record event if enabled
+        if (this.config.enableRecording && this.recorder) {
+            this.recorder.record(event, this.formatResultsForRecording(results));
+        }
+    }
+    /**
+     * Emit multiple events in sequence.
+     */
+    async emitMany(events) {
+        for (const event of events) {
+            await this.emit(event);
+        }
+    }
+    /**
+     * Check if there are any handlers for an event type.
+     */
+    hasHandlers(eventClass) {
+        return this.registry.getHandlers(eventClass).length > 0;
+    }
+    /**
+     * Get the number of handlers for an event type.
+     */
+    handlerCount(eventClass) {
+        return this.registry.getHandlers(eventClass).length;
+    }
+    /**
+     * Execute a single handler.
+     */
+    async executeHandler(handler, event) {
+        const handlerName = handler.handlerClass.name;
+        const startTime = Date.now();
+        // Check condition
+        if (handler.condition) {
+            const shouldRun = await this.evaluateCondition(handler.condition, event);
+            if (!shouldRun) {
+                return {
+                    handler: handlerName,
+                    success: true,
+                    duration: Date.now() - startTime,
+                    skipped: true,
+                    skipReason: handler.condition.reason || "Condition not met",
+                };
+            }
+        }
+        // Get handler instance from container
+        let instance;
+        try {
+            instance = this.container.get(handler.handlerClass);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.handleError(err, event, handlerName);
+            return {
+                handler: handlerName,
+                success: false,
+                duration: Date.now() - startTime,
+                error: err,
+            };
+        }
+        // Execute with retry logic
+        const options = handler.options;
+        let lastError;
+        let retries = 0;
+        while (retries <= (options.retry || 0)) {
+            try {
+                // Execute with timeout
+                await this.executeWithTimeout(() => instance.handle(event), options.timeout || this.config.defaultTimeout || 30000, handlerName);
+                const result = {
+                    handler: handlerName,
+                    success: true,
+                    duration: Date.now() - startTime,
+                    retries: retries > 0 ? retries : undefined,
+                };
+                // Notify config callback
+                if (this.config.onHandlerComplete) {
+                    this.config.onHandlerComplete(result);
+                }
+                // Track flow if enabled
+                if (this.config.enableFlowTracking &&
+                    this.flowTracker &&
+                    this.currentCorrelationId) {
+                    this.flowTracker.recordEvent(this.currentCorrelationId, event.constructor.name, [handlerName], result.duration);
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                retries++;
+                if (retries <= (options.retry || 0)) {
+                    // Calculate delay based on backoff strategy
+                    const delay = this.calculateBackoffDelay(options.retryDelay || 1000, retries, options.backoff || "fixed");
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All retries failed
+        const result = {
+            handler: handlerName,
+            success: false,
+            duration: Date.now() - startTime,
+            error: lastError,
+            retries: retries > 0 ? retries - 1 : undefined,
+        };
+        // Handle error
+        if (lastError) {
+            if (options.errorHandler) {
+                options.errorHandler(lastError, event);
+            }
+            else {
+                this.handleError(lastError, event, handlerName);
+            }
+        }
+        // Notify config callback
+        if (this.config.onHandlerComplete) {
+            this.config.onHandlerComplete(result);
+        }
+        return result;
+    }
+    /**
+     * Evaluate a condition.
+     */
+    async evaluateCondition(condition, event) {
+        try {
+            const result = condition.condition(event);
+            return result instanceof Promise ? await result : result;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger?.error(`Condition evaluation failed: ${err.message}`);
+            return false;
+        }
+    }
+    /**
+     * Execute a function with timeout.
+     */
+    async executeWithTimeout(fn, timeout, handlerName) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`Handler ${handlerName} timed out after ${timeout}ms`));
+            }, timeout);
+            timeoutId.unref();
+            const result = fn();
+            if (result instanceof Promise) {
+                result
+                    .then((value) => {
+                    clearTimeout(timeoutId);
+                    resolve(value);
+                })
+                    .catch((error) => {
+                    clearTimeout(timeoutId);
+                    reject(error);
+                });
+            }
+            else {
+                clearTimeout(timeoutId);
+                resolve(result);
+            }
+        });
+    }
+    /**
+     * Calculate backoff delay.
+     */
+    calculateBackoffDelay(baseDelay, attempt, strategy) {
+        switch (strategy) {
+            case "linear":
+                return baseDelay * attempt;
+            case "exponential":
+                return baseDelay * Math.pow(2, attempt - 1);
+            case "fixed":
+            default:
+                return baseDelay;
+        }
+    }
+    /**
+     * Sleep for a duration.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref();
+        });
+    }
+    /**
+     * Handle an error.
+     */
+    handleError(error, event, handlerName) {
+        if (this.config.onError) {
+            this.config.onError(error, event, handlerName);
+        }
+        else {
+            const eventName = event?.constructor?.name ||
+                "UnknownEvent";
+            this.logger?.error(`Event handler ${handlerName} failed: ${error.message} (event: ${eventName})`);
+        }
+    }
+    /**
+     * Format results for recording.
+     */
+    formatResultsForRecording(results) {
+        return results.map((r) => ({
+            handler: r.handler,
+            duration: r.duration,
+            success: r.success,
+            error: r.error?.message,
+        }));
+    }
+};
+exports.EventEmitter = EventEmitter;
+exports.EventEmitter = EventEmitter = __decorate([
+    (0, inversify_js_1.injectable)(),
+    __param(0, (0, inversify_js_1.inject)(event_registry_js_1.EventRegistry)),
+    __param(1, (0, inversify_js_1.inject)(inversify_js_1.Container)),
+    __param(2, (0, inversify_js_1.inject)(event_recorder_js_1.EventRecorder)),
+    __param(2, (0, inversify_js_1.optional)()),
+    __param(3, (0, inversify_js_1.inject)(event_flow_tracker_js_1.EventFlowTracker)),
+    __param(3, (0, inversify_js_1.optional)()),
+    __param(4, (0, inversify_js_1.inject)(logger_provider_js_1.Logger)),
+    __param(4, (0, inversify_js_1.optional)()),
+    __metadata("design:paramtypes", [event_registry_js_1.EventRegistry,
+        inversify_js_1.Container,
+        event_recorder_js_1.EventRecorder,
+        event_flow_tracker_js_1.EventFlowTracker,
+        logger_provider_js_1.Logger])
+], EventEmitter);
+/**
+ * Create a standalone event emitter (for testing).
+ */
+function createEventEmitter(registry, container, recorder, flowTracker) {
+    const emitter = new EventEmitter(registry, container, recorder, flowTracker, undefined);
+    return emitter;
+}