@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/event/event-flow-tracker.js

@@ -0,0 +1,230 @@
+/**
+ * Event Flow Tracker
+ *
+ * @module event
+ *
+ * Tracks event propagation flow for debugging and visualization.
+ *
+ * @example
+ * ```typescript
+ * const tracker = container.get(EventFlowTracker);
+ * const flow = tracker.getFlow(requestId);
+ * console.log(flow.visualize());
+ *
+ * // Output:
+ * // UserCreatedEvent (234ms)
+ * // ├─> SendWelcomeEmail (100ms)
+ * // │   └─> WelcomeEmailSentEvent (50ms)
+ * // │       └─> LogAnalytics (5ms)
+ * // └─> CreateUserProfile (130ms)
+ * //     └─> UserProfileCreatedEvent (10ms)
+ * ```
+ */
+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;
+};
+import { injectable } from "../di/inversify.js";
+/**
+ * Event flow tracker implementation.
+ *
+ * NOTE: This class uses @injectable() instead of @provide() because
+ * it must be registered as a Singleton by the application to ensure
+ * all event flows are tracked in the same instance.
+ */
+let EventFlowTracker = class EventFlowTracker {
+    flows = new Map();
+    maxFlows = 100;
+    /**
+     * Configure the tracker.
+     */
+    configure(options) {
+        if (options.maxFlows !== undefined) {
+            this.maxFlows = options.maxFlows;
+        }
+    }
+    /**
+     * Start tracking a new flow.
+     */
+    startFlow(requestId) {
+        // Clean up old flows if at capacity
+        if (this.flows.size >= this.maxFlows) {
+            const oldest = Array.from(this.flows.keys())[0];
+            this.flows.delete(oldest);
+        }
+        this.flows.set(requestId, {
+            requestId,
+            startTime: Date.now(),
+            events: [],
+        });
+    }
+    /**
+     * Record an event in the current flow.
+     */
+    recordEvent(requestId, eventName, handlers, duration) {
+        const flow = this.flows.get(requestId);
+        if (!flow) {
+            return;
+        }
+        const node = {
+            name: eventName,
+            timestamp: Date.now(),
+            handlers,
+            duration,
+            children: [],
+        };
+        // Add to flow
+        if (flow.currentEvent) {
+            // This is a child event triggered by a handler
+            if (!flow.currentEvent.children) {
+                flow.currentEvent.children = [];
+            }
+            flow.currentEvent.children.push(node);
+        }
+        else {
+            // This is a root event
+            flow.events.push(node);
+        }
+    }
+    /**
+     * Push an event onto the stack (for tracking nested events).
+     */
+    pushEvent(requestId, eventName) {
+        const flow = this.flows.get(requestId);
+        if (!flow) {
+            return;
+        }
+        const node = {
+            name: eventName,
+            timestamp: Date.now(),
+            handlers: [],
+            duration: 0,
+        };
+        if (flow.currentEvent) {
+            // This is a child event
+            if (!flow.currentEvent.children) {
+                flow.currentEvent.children = [];
+            }
+            flow.currentEvent.children.push(node);
+        }
+        else {
+            flow.events.push(node);
+        }
+        // Make this the current event (for tracking children)
+        // Store parent reference for popping
+        node._parent = flow.currentEvent;
+        flow.currentEvent = node;
+    }
+    /**
+     * Pop the current event from the stack.
+     */
+    popEvent(requestId, handlers, duration) {
+        const flow = this.flows.get(requestId);
+        if (!flow || !flow.currentEvent) {
+            return;
+        }
+        flow.currentEvent.handlers = handlers;
+        flow.currentEvent.duration = duration;
+        // Pop to parent
+        const parent = flow.currentEvent._parent;
+        flow.currentEvent = parent;
+    }
+    /**
+     * End tracking for a flow.
+     */
+    endFlow(requestId) {
+        const flow = this.flows.get(requestId);
+        if (!flow) {
+            return this.createEmptyFlow(requestId);
+        }
+        const totalDuration = Date.now() - flow.startTime;
+        return {
+            requestId,
+            events: flow.events,
+            totalDuration,
+            visualize: () => this.visualizeFlow(flow.events, totalDuration),
+        };
+    }
+    /**
+     * Get flow for a request.
+     */
+    getFlow(requestId) {
+        const flow = this.flows.get(requestId);
+        if (!flow) {
+            return undefined;
+        }
+        const totalDuration = Date.now() - flow.startTime;
+        return {
+            requestId,
+            events: flow.events,
+            totalDuration,
+            visualize: () => this.visualizeFlow(flow.events, totalDuration),
+        };
+    }
+    /**
+     * Clear all flows.
+     */
+    clear() {
+        this.flows.clear();
+    }
+    /**
+     * Get active flow count.
+     */
+    activeFlowCount() {
+        return this.flows.size;
+    }
+    /**
+     * Create an empty flow.
+     */
+    createEmptyFlow(requestId) {
+        return {
+            requestId,
+            events: [],
+            totalDuration: 0,
+            visualize: () => "No events recorded for this flow.",
+        };
+    }
+    /**
+     * Visualize a flow as ASCII art.
+     */
+    visualizeFlow(events, totalDuration) {
+        if (events.length === 0) {
+            return "No events recorded.";
+        }
+        const lines = [];
+        for (let i = 0; i < events.length; i++) {
+            this.visualizeNode(events[i], lines, "", i === events.length - 1);
+        }
+        lines.push("");
+        lines.push(`Total Duration: ${totalDuration}ms`);
+        return lines.join("\n");
+    }
+    /**
+     * Visualize a single node and its children.
+     */
+    visualizeNode(node, lines, prefix, isLast) {
+        // Build the connector
+        const connector = isLast ? "└─>" : "├─>";
+        const handlerList = node.handlers.length > 0 ? ` [${node.handlers.join(", ")}]` : "";
+        lines.push(`${prefix}${connector} ${node.name} (${node.duration}ms)${handlerList}`);
+        // Visualize children
+        if (node.children && node.children.length > 0) {
+            const childPrefix = prefix + (isLast ? "    " : "│   ");
+            for (let i = 0; i < node.children.length; i++) {
+                this.visualizeNode(node.children[i], lines, childPrefix, i === node.children.length - 1);
+            }
+        }
+    }
+};
+EventFlowTracker = __decorate([
+    injectable()
+], EventFlowTracker);
+export { EventFlowTracker };
+/**
+ * Create a standalone event flow tracker (for testing).
+ */
+export function createEventFlowTracker() {
+    return new EventFlowTracker();
+}

package/lib/esm/event/event-recorder.js

@@ -0,0 +1,286 @@
+/**
+ * Event Recorder
+ *
+ * @module event
+ *
+ * Records events for replay and debugging.
+ * Enabled by default in development mode.
+ *
+ * @example
+ * ```typescript
+ * const recorder = container.get(EventRecorder);
+ *
+ * // Replay last minute of events
+ * await recorder.replay({
+ *   fromTimestamp: Date.now() - 60000,
+ * });
+ *
+ * // Replay only UserCreatedEvent events
+ * await recorder.replay({
+ *   eventTypes: [UserCreatedEvent],
+ * });
+ *
+ * // Export event timeline
+ * const timeline = recorder.export("timeline");
+ * console.log(timeline);
+ * ```
+ */
+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);
+};
+import { injectable } from "../di/inversify.js";
+/**
+ * Generate a unique ID.
+ */
+function generateId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Event recorder implementation.
+ *
+ * NOTE: This class uses @injectable() instead of @provide() because
+ * it must be registered as a Singleton by the application to ensure
+ * all events are recorded in the same instance.
+ */
+let EventRecorder = class EventRecorder {
+    events = [];
+    recording = false;
+    maxEvents = 1000;
+    replayEmitter;
+    constructor() {
+        // Start recording in development by default
+        if (process.env.NODE_ENV === "development") {
+            this.startRecording();
+        }
+    }
+    /**
+     * Configure the recorder.
+     */
+    configure(options) {
+        if (options.maxEvents !== undefined) {
+            this.maxEvents = options.maxEvents;
+        }
+        if (options.autoStart) {
+            this.startRecording();
+        }
+    }
+    /**
+     * Set the emitter function for replay.
+     */
+    setReplayEmitter(emitter) {
+        this.replayEmitter = emitter;
+    }
+    /**
+     * Start recording events.
+     */
+    startRecording() {
+        this.recording = true;
+    }
+    /**
+     * Stop recording events.
+     */
+    stopRecording() {
+        this.recording = false;
+    }
+    /**
+     * Check if currently recording.
+     */
+    isRecording() {
+        return this.recording;
+    }
+    /**
+     * Record an event.
+     */
+    record(event, handlerResults) {
+        if (!this.recording) {
+            return;
+        }
+        const eventClass = event?.constructor;
+        const recorded = {
+            id: generateId(),
+            type: eventClass,
+            typeName: eventClass?.name || "UnknownEvent",
+            data: event,
+            timestamp: Date.now(),
+            handlerResults,
+        };
+        this.events.push(recorded);
+        // Trim if over max
+        if (this.events.length > this.maxEvents) {
+            this.events = this.events.slice(-this.maxEvents);
+        }
+    }
+    /**
+     * Get all recorded events.
+     */
+    getRecordedEvents() {
+        return [...this.events];
+    }
+    /**
+     * Get events filtered by type.
+     */
+    getEventsByType(eventClass) {
+        return this.events.filter((e) => e.type === eventClass);
+    }
+    /**
+     * Get events in a time range.
+     */
+    getEventsInRange(from, to = Date.now()) {
+        return this.events.filter((e) => e.timestamp >= from && e.timestamp <= to);
+    }
+    /**
+     * Replay recorded events.
+     */
+    async replay(options = {}) {
+        if (!this.replayEmitter) {
+            throw new Error("Replay emitter not set. Call setReplayEmitter() first.");
+        }
+        // Filter events
+        let filtered = [...this.events];
+        if (options.fromTimestamp !== undefined) {
+            filtered = filtered.filter((e) => e.timestamp >= options.fromTimestamp);
+        }
+        if (options.toTimestamp !== undefined) {
+            filtered = filtered.filter((e) => e.timestamp <= options.toTimestamp);
+        }
+        if (options.eventTypes && options.eventTypes.length > 0) {
+            filtered = filtered.filter((e) => options.eventTypes.includes(e.type));
+        }
+        if (options.filter) {
+            filtered = filtered.filter(options.filter);
+        }
+        // Sort by timestamp
+        filtered.sort((a, b) => a.timestamp - b.timestamp);
+        // Replay events
+        const speed = options.speed ?? 0;
+        let lastTimestamp = filtered.length > 0 ? filtered[0].timestamp : 0;
+        for (const event of filtered) {
+            // Apply speed delay
+            if (speed > 0 && event.timestamp > lastTimestamp) {
+                const delay = (event.timestamp - lastTimestamp) / speed;
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, delay);
+                    timer.unref();
+                });
+            }
+            lastTimestamp = event.timestamp;
+            // Replay the event
+            await this.replayEmitter(event.data);
+        }
+    }
+    /**
+     * Export recorded events.
+     */
+    export(format) {
+        switch (format) {
+            case "json":
+                return this.exportJson();
+            case "csv":
+                return this.exportCsv();
+            case "timeline":
+                return this.exportTimeline();
+            default:
+                return this.exportJson();
+        }
+    }
+    /**
+     * Export as JSON.
+     */
+    exportJson() {
+        return JSON.stringify(this.events.map((e) => ({
+            id: e.id,
+            type: e.typeName,
+            data: e.data,
+            timestamp: e.timestamp,
+            date: new Date(e.timestamp).toISOString(),
+            handlerResults: e.handlerResults,
+        })), null, 2);
+    }
+    /**
+     * Export as CSV.
+     */
+    exportCsv() {
+        const lines = ["id,type,timestamp,date,handlers,success"];
+        for (const event of this.events) {
+            const handlers = event.handlerResults?.map((h) => h.handler).join(";") || "";
+            const success = event.handlerResults?.every((h) => h.success) ?? true;
+            lines.push(`${event.id},${event.typeName},${event.timestamp},${new Date(event.timestamp).toISOString()},${handlers},${success}`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Export as ASCII timeline.
+     */
+    exportTimeline() {
+        if (this.events.length === 0) {
+            return "No events recorded.";
+        }
+        const lines = ["Event Timeline", "═".repeat(60), ""];
+        let lastTimestamp = 0;
+        for (const event of this.events) {
+            // Calculate time delta
+            const delta = lastTimestamp > 0 ? `+${event.timestamp - lastTimestamp}ms` : "START";
+            lastTimestamp = event.timestamp;
+            // Format timestamp
+            const time = new Date(event.timestamp).toISOString().substring(11, 23);
+            // Build event line
+            const handlers = event.handlerResults?.length || 0;
+            const success = event.handlerResults?.every((h) => h.success) ?? true;
+            const status = success ? "✓" : "✗";
+            const duration = event.handlerResults?.reduce((sum, h) => sum + h.duration, 0) || 0;
+            lines.push(`${time} │ ${status} ${event.typeName.padEnd(30)} │ ${handlers} handlers │ ${duration}ms │ ${delta}`);
+            // Add handler details
+            if (event.handlerResults) {
+                for (const handler of event.handlerResults) {
+                    const handlerStatus = handler.success ? "  ✓" : "  ✗";
+                    lines.push(`           │ ${handlerStatus} ${handler.handler.padEnd(28)} │ ${handler.duration}ms`);
+                }
+            }
+        }
+        lines.push("");
+        lines.push("═".repeat(60));
+        lines.push(`Total: ${this.events.length} events`);
+        return lines.join("\n");
+    }
+    /**
+     * Clear recorded events.
+     */
+    clear() {
+        this.events = [];
+    }
+    /**
+     * Get event count.
+     */
+    count() {
+        return this.events.length;
+    }
+    /**
+     * Get latest event.
+     */
+    latest() {
+        return this.events[this.events.length - 1];
+    }
+    /**
+     * Get first event.
+     */
+    first() {
+        return this.events[0];
+    }
+};
+EventRecorder = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [])
+], EventRecorder);
+export { EventRecorder };
+/**
+ * Create a standalone event recorder (for testing).
+ */
+export function createEventRecorder() {
+    return new EventRecorder();
+}