@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/types/event/event-flow-tracker.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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)
+ * ```
+ */
+import { EventFlow, IEventFlowTracker } from "./event.interfaces.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.
+ */
+export declare class EventFlowTracker implements IEventFlowTracker {
+    private flows;
+    private maxFlows;
+    /**
+     * Configure the tracker.
+     */
+    configure(options: {
+        maxFlows?: number;
+    }): void;
+    /**
+     * Start tracking a new flow.
+     */
+    startFlow(requestId: string): void;
+    /**
+     * Record an event in the current flow.
+     */
+    recordEvent(requestId: string, eventName: string, handlers: Array<string>, duration: number): void;
+    /**
+     * Push an event onto the stack (for tracking nested events).
+     */
+    pushEvent(requestId: string, eventName: string): void;
+    /**
+     * Pop the current event from the stack.
+     */
+    popEvent(requestId: string, handlers: Array<string>, duration: number): void;
+    /**
+     * End tracking for a flow.
+     */
+    endFlow(requestId: string): EventFlow;
+    /**
+     * Get flow for a request.
+     */
+    getFlow(requestId: string): EventFlow | undefined;
+    /**
+     * Clear all flows.
+     */
+    clear(): void;
+    /**
+     * Get active flow count.
+     */
+    activeFlowCount(): number;
+    /**
+     * Create an empty flow.
+     */
+    private createEmptyFlow;
+    /**
+     * Visualize a flow as ASCII art.
+     */
+    private visualizeFlow;
+    /**
+     * Visualize a single node and its children.
+     */
+    private visualizeNode;
+}
+/**
+ * Create a standalone event flow tracker (for testing).
+ */
+export declare function createEventFlowTracker(): EventFlowTracker;

package/lib/esm/types/event/event-recorder.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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);
+ * ```
+ */
+import { EventClass, IEventRecorder, RecordedEvent, ReplayOptions } from "./event.interfaces.js";
+/**
+ * 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.
+ */
+export declare class EventRecorder implements IEventRecorder {
+    private events;
+    private recording;
+    private maxEvents;
+    private replayEmitter?;
+    constructor();
+    /**
+     * Configure the recorder.
+     */
+    configure(options: {
+        maxEvents?: number;
+        autoStart?: boolean;
+    }): void;
+    /**
+     * Set the emitter function for replay.
+     */
+    setReplayEmitter(emitter: (event: unknown) => Promise<void>): void;
+    /**
+     * Start recording events.
+     */
+    startRecording(): void;
+    /**
+     * Stop recording events.
+     */
+    stopRecording(): void;
+    /**
+     * Check if currently recording.
+     */
+    isRecording(): boolean;
+    /**
+     * Record an event.
+     */
+    record<T>(event: T, handlerResults?: RecordedEvent["handlerResults"]): void;
+    /**
+     * Get all recorded events.
+     */
+    getRecordedEvents(): Array<RecordedEvent>;
+    /**
+     * Get events filtered by type.
+     */
+    getEventsByType<T>(eventClass: EventClass<T>): Array<RecordedEvent<T>>;
+    /**
+     * Get events in a time range.
+     */
+    getEventsInRange(from: number, to?: number): Array<RecordedEvent>;
+    /**
+     * Replay recorded events.
+     */
+    replay(options?: ReplayOptions): Promise<void>;
+    /**
+     * Export recorded events.
+     */
+    export(format: "json" | "csv" | "timeline"): string;
+    /**
+     * Export as JSON.
+     */
+    private exportJson;
+    /**
+     * Export as CSV.
+     */
+    private exportCsv;
+    /**
+     * Export as ASCII timeline.
+     */
+    private exportTimeline;
+    /**
+     * Clear recorded events.
+     */
+    clear(): void;
+    /**
+     * Get event count.
+     */
+    count(): number;
+    /**
+     * Get latest event.
+     */
+    latest(): RecordedEvent | undefined;
+    /**
+     * Get first event.
+     */
+    first(): RecordedEvent | undefined;
+}
+/**
+ * Create a standalone event recorder (for testing).
+ */
+export declare function createEventRecorder(): EventRecorder;

package/lib/esm/types/event/event-registry.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Event Registry
+ *
+ * @module event
+ *
+ * Central registry for event handlers with auto-discovery support.
+ */
+import { Container } from "../di/inversify.js";
+import { EventClass, EventHandlerClass, IEventRegistry, OnEventOptions, RegisteredHandler } from "./event.interfaces.js";
+/**
+ * Event registry implementation.
+ *
+ * Manages registration and discovery of event handlers.
+ *
+ * NOTE: This class uses @injectable() instead of @provide() because
+ * it must be registered as a Singleton by the application to ensure
+ * all components share the same registry instance. The @provide decorator
+ * would auto-register it with a different scope, causing multiple instances.
+ */
+export declare class EventRegistry implements IEventRegistry {
+    /**
+     * Map of event class to handlers.
+     */
+    private handlers;
+    /**
+     * Set of all registered handler classes.
+     */
+    private handlerClasses;
+    /**
+     * Register a handler for an event.
+     */
+    register<T>(eventClass: EventClass<T>, handlerClass: EventHandlerClass<T>, options?: OnEventOptions): void;
+    /**
+     * Register a handler for multiple events.
+     */
+    registerMultiple<T>(eventClasses: Array<EventClass>, handlerClass: EventHandlerClass<T>, options?: OnEventOptions): void;
+    /**
+     * Get all handlers for an event class.
+     */
+    getHandlers<T>(eventClass: EventClass<T>): Array<RegisteredHandler<T>>;
+    /**
+     * Get all registered handlers.
+     */
+    getAllHandlers(): Array<RegisteredHandler>;
+    /**
+     * Check if a handler is registered.
+     */
+    hasHandler<T>(eventClass: EventClass<T>, handlerClass: EventHandlerClass<T>): boolean;
+    /**
+     * Unregister a handler.
+     */
+    unregister<T>(eventClass: EventClass<T>, handlerClass: EventHandlerClass<T>): void;
+    /**
+     * Clear all handlers.
+     */
+    clear(): void;
+    /**
+     * Auto-discover and register handlers from container.
+     *
+     * This scans all bound services in the container and registers
+     * any that are decorated with @OnEvent or @OnEvents.
+     */
+    discoverHandlers(container: Container): number;
+    /**
+     * Get handler classes for dependency resolution.
+     */
+    getHandlerClasses(): Array<EventHandlerClass>;
+    /**
+     * Get all registered event classes.
+     */
+    getEventClasses(): Array<EventClass>;
+    /**
+     * Get statistics about registered handlers.
+     */
+    getStatistics(): {
+        totalHandlers: number;
+        totalEvents: number;
+        handlersPerEvent: Record<string, number>;
+    };
+}
+/**
+ * Create a standalone event registry (for testing).
+ */
+export declare function createEventRegistry(): EventRegistry;