@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/event/event.interfaces.d.ts

@@ -0,0 +1,528 @@
+/**
+ * Event System Interfaces
+ *
+ * @module event
+ *
+ * Type-safe, auto-discovered event system for decoupled, event-driven architecture.
+ *
+ * Features:
+ * - Type-safe event classes (not strings!)
+ * - Auto-discovery via @provide() decorator
+ * - Conditional handlers with @When()
+ * - Priority-based execution
+ * - Event replay and flow visualization
+ *
+ * @example
+ * ```typescript
+ * // Define type-safe event
+ * export class UserCreatedEvent {
+ *   constructor(
+ *     public readonly userId: string,
+ *     public readonly email: string,
+ *     public readonly timestamp: Date = new Date()
+ *   ) {}
+ * }
+ *
+ * // Create handler with auto-discovery
+ * @provide(UserCreatedHandler)
+ * @OnEvent(UserCreatedEvent)
+ * export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     console.log(`User ${event.userId} created`);
+ *   }
+ * }
+ *
+ * // Emit with full type safety
+ * eventEmitter.emit(new UserCreatedEvent("123", "user@example.com"));
+ * ```
+ */
+/**
+ * Base event class type.
+ * Events are plain classes with constructor parameters.
+ */
+export type EventClass<T = any> = new (...args: Array<any>) => T;
+/**
+ * Extract event instance type from event class.
+ */
+export type EventInstance<T extends EventClass> = InstanceType<T>;
+/**
+ * Event metadata attached to event classes.
+ */
+export interface EventMetadata {
+    /**
+     * Event name (defaults to class name).
+     */
+    name?: string;
+    /**
+     * Event version for schema evolution.
+     */
+    version?: number;
+    /**
+     * Event description for documentation.
+     */
+    description?: string;
+    /**
+     * Tags for filtering and organization.
+     */
+    tags?: Array<string>;
+}
+/**
+ * Event handler interface.
+ *
+ * Implement this interface to create type-safe event handlers.
+ *
+ * @template T - Event type this handler processes
+ *
+ * @example
+ * ```typescript
+ * @provide(UserCreatedHandler)
+ * @OnEvent(UserCreatedEvent)
+ * export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     console.log(`User ${event.userId} created at ${event.email}`);
+ *   }
+ * }
+ * ```
+ */
+export interface IEventHandler<T = unknown> {
+    /**
+     * Handle the event.
+     *
+     * @param event - The event instance to handle
+     * @returns void or Promise<void> for async handlers
+     */
+    handle(event: T): void | Promise<void>;
+}
+/**
+ * Handler class type for registration.
+ */
+export type EventHandlerClass<T = unknown> = new (...args: Array<unknown>) => IEventHandler<T>;
+/**
+ * Options for @OnEvent() decorator.
+ */
+export interface OnEventOptions {
+    /**
+     * Handler priority (lower = higher priority).
+     * Default: 100
+     *
+     * @example
+     * ```typescript
+     * @OnEvent(UserCreatedEvent, { priority: 1 }) // Runs first
+     * @OnEvent(UserCreatedEvent, { priority: 2 }) // Runs second
+     * ```
+     */
+    priority?: number;
+    /**
+     * Run handler asynchronously (fire-and-forget).
+     * Default: false
+     */
+    async?: boolean;
+    /**
+     * Number of retries on failure.
+     * Default: 0 (no retries)
+     */
+    retry?: number;
+    /**
+     * Timeout in milliseconds.
+     * Default: 30000 (30s)
+     */
+    timeout?: number;
+    /**
+     * Delay between retries in milliseconds.
+     * Default: 1000 (1s)
+     */
+    retryDelay?: number;
+    /**
+     * Backoff strategy for retries.
+     * Default: "fixed"
+     */
+    backoff?: "fixed" | "linear" | "exponential";
+    /**
+     * Custom error handler for this specific handler.
+     */
+    errorHandler?: (error: Error, event: any) => void;
+}
+/**
+ * Options for @When() decorator (conditional execution).
+ */
+export interface WhenOptions<T = unknown> {
+    /**
+     * Condition function that determines if handler should run.
+     */
+    condition: (event: T) => boolean | Promise<boolean>;
+    /**
+     * Optional reason for the condition (for debugging).
+     */
+    reason?: string;
+}
+/**
+ * Event emitter service interface.
+ *
+ * @example
+ * ```typescript
+ * @inject(IEventEmitter)
+ * private eventEmitter: IEventEmitter;
+ *
+ * async createUser(data: CreateUserDto) {
+ *   const user = await this.userRepo.create(data);
+ *   await this.eventEmitter.emit(new UserCreatedEvent(user.id, user.email));
+ *   return user;
+ * }
+ * ```
+ */
+export interface IEventEmitter {
+    /**
+     * Emit an event to all registered handlers.
+     *
+     * @param event - Event instance to emit
+     * @returns Promise that resolves when all sync handlers complete
+     *
+     * @example
+     * ```typescript
+     * await eventEmitter.emit(new UserCreatedEvent("123", "user@example.com"));
+     * ```
+     */
+    emit<T>(event: T): Promise<void>;
+    /**
+     * Emit an event and wait for all handlers (including async) to complete.
+     *
+     * @param event - Event instance to emit
+     * @returns Promise that resolves when ALL handlers complete
+     *
+     * @example
+     * ```typescript
+     * await eventEmitter.emitAndWait(new UserCreatedEvent("123", "user@example.com"));
+     * // All handlers, including async ones, have completed
+     * ```
+     */
+    emitAndWait<T>(event: T): Promise<void>;
+    /**
+     * Emit multiple events in sequence.
+     *
+     * @param events - Array of events to emit
+     * @returns Promise that resolves when all events are emitted
+     */
+    emitMany<T>(events: Array<T>): Promise<void>;
+    /**
+     * Check if there are any handlers for an event type.
+     *
+     * @param eventClass - Event class to check
+     * @returns true if handlers exist
+     */
+    hasHandlers<T>(eventClass: EventClass<T>): boolean;
+    /**
+     * Get the number of handlers for an event type.
+     *
+     * @param eventClass - Event class to check
+     * @returns Number of registered handlers
+     */
+    handlerCount<T>(eventClass: EventClass<T>): number;
+}
+/**
+ * Registered handler information.
+ */
+export interface RegisteredHandler<T = unknown> {
+    /**
+     * Handler class.
+     */
+    handlerClass: EventHandlerClass<T>;
+    /**
+     * Event class this handler listens to.
+     */
+    eventClass: EventClass<T>;
+    /**
+     * Handler options.
+     */
+    options: OnEventOptions;
+    /**
+     * Conditional execution predicate.
+     */
+    condition?: WhenOptions<T>;
+    /**
+     * Multiple event classes for @OnEvents().
+     */
+    eventClasses?: Array<EventClass>;
+}
+/**
+ * Event registry interface for managing handlers.
+ */
+export interface IEventRegistry {
+    /**
+     * 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;
+}
+/**
+ * Recorded event with metadata.
+ */
+export interface RecordedEvent<T = unknown> {
+    /**
+     * Unique event ID.
+     */
+    id: string;
+    /**
+     * Event class/type.
+     */
+    type: EventClass<T>;
+    /**
+     * Event type name (string).
+     */
+    typeName: string;
+    /**
+     * Event data.
+     */
+    data: T;
+    /**
+     * Timestamp when event was recorded.
+     */
+    timestamp: number;
+    /**
+     * Request/correlation ID (if available).
+     */
+    correlationId?: string;
+    /**
+     * Handler results.
+     */
+    handlerResults?: Array<{
+        handler: string;
+        duration: number;
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Event replay options.
+ */
+export interface ReplayOptions {
+    /**
+     * Start timestamp (inclusive).
+     */
+    fromTimestamp?: number;
+    /**
+     * End timestamp (inclusive).
+     */
+    toTimestamp?: number;
+    /**
+     * Filter by event types.
+     */
+    eventTypes?: Array<EventClass>;
+    /**
+     * Custom filter function.
+     */
+    filter?: (event: RecordedEvent<any>) => boolean;
+    /**
+     * Replay speed multiplier.
+     * 1 = real-time, 2 = 2x speed, 0 = instant
+     */
+    speed?: number;
+}
+/**
+ * Event recorder interface for replay and debugging.
+ */
+export interface IEventRecorder {
+    /**
+     * 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>;
+    /**
+     * Replay recorded events.
+     */
+    replay(options?: ReplayOptions): Promise<void>;
+    /**
+     * Export recorded events.
+     */
+    export(format: "json" | "csv" | "timeline"): string;
+    /**
+     * Clear recorded events.
+     */
+    clear(): void;
+}
+/**
+ * Event flow node.
+ */
+export interface EventFlowNode {
+    /**
+     * Event type name.
+     */
+    name: string;
+    /**
+     * Timestamp when event occurred.
+     */
+    timestamp: number;
+    /**
+     * Handlers that processed this event.
+     */
+    handlers: Array<string>;
+    /**
+     * Total duration of all handlers.
+     */
+    duration: number;
+    /**
+     * Child events triggered by handlers.
+     */
+    children?: Array<EventFlowNode>;
+}
+/**
+ * Event flow for a request.
+ */
+export interface EventFlow {
+    /**
+     * Request/correlation ID.
+     */
+    requestId: string;
+    /**
+     * Root events and their propagation.
+     */
+    events: Array<EventFlowNode>;
+    /**
+     * Total duration.
+     */
+    totalDuration: number;
+    /**
+     * Visualize the flow as ASCII art.
+     */
+    visualize(): string;
+}
+/**
+ * Event flow tracker interface.
+ */
+export interface IEventFlowTracker {
+    /**
+     * 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;
+    /**
+     * End tracking for a flow.
+     */
+    endFlow(requestId: string): EventFlow;
+    /**
+     * Get flow for a request.
+     */
+    getFlow(requestId: string): EventFlow | undefined;
+    /**
+     * Clear all flows.
+     */
+    clear(): void;
+}
+/**
+ * Result of executing a handler.
+ */
+export interface HandlerExecutionResult {
+    /**
+     * Handler class name.
+     */
+    handler: string;
+    /**
+     * Whether execution was successful.
+     */
+    success: boolean;
+    /**
+     * Execution duration in milliseconds.
+     */
+    duration: number;
+    /**
+     * Error if execution failed.
+     */
+    error?: Error;
+    /**
+     * Number of retries attempted.
+     */
+    retries?: number;
+    /**
+     * Whether handler was skipped due to condition.
+     */
+    skipped?: boolean;
+    /**
+     * Reason for skipping.
+     */
+    skipReason?: string;
+}
+/**
+ * Event system configuration options.
+ */
+export interface EventSystemConfig {
+    /**
+     * Enable event recording (default: only in development).
+     */
+    enableRecording?: boolean;
+    /**
+     * Enable flow tracking (default: only in development).
+     */
+    enableFlowTracking?: boolean;
+    /**
+     * Maximum recorded events to keep.
+     * Default: 1000
+     */
+    maxRecordedEvents?: number;
+    /**
+     * Default handler timeout in milliseconds.
+     * Default: 30000 (30s)
+     */
+    defaultTimeout?: number;
+    /**
+     * Global error handler for unhandled errors.
+     */
+    onError?: (error: Error, event: any, handler: string) => void;
+    /**
+     * Called when an event is emitted.
+     */
+    onEmit?: (event: any) => void;
+    /**
+     * Called when a handler completes.
+     */
+    onHandlerComplete?: (result: HandlerExecutionResult) => void;
+}
+/**
+ * Metadata keys for event decorators.
+ */
+export declare const EVENT_METADATA: {
+    readonly EVENT_CLASS: symbol;
+    readonly EVENT_CLASSES: symbol;
+    readonly EVENT_OPTIONS: symbol;
+    readonly EVENT_CONDITION: symbol;
+    readonly IS_EVENT_HANDLER: symbol;
+};

package/lib/esm/types/event/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Event System Module
+ *
+ * @module event
+ *
+ * Type-safe, auto-discovered event system for decoupled, event-driven architecture.
+ *
+ * Features:
+ * - Type-safe event classes (not strings!)
+ * - Auto-discovery via @provide() decorator
+ * - Conditional handlers with @When()
+ * - Priority-based execution
+ * - Event replay and flow visualization
+ * - Async handlers with retry/timeout
+ *
+ * @example
+ * ```typescript
+ * // Define type-safe event
+ * export class UserCreatedEvent {
+ *   constructor(
+ *     public readonly userId: string,
+ *     public readonly email: string,
+ *     public readonly timestamp: Date = new Date()
+ *   ) {}
+ * }
+ *
+ * // Create handler with auto-discovery
+ * @provide(UserCreatedHandler)
+ * @OnEvent(UserCreatedEvent)
+ * export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     console.log(`User ${event.userId} created`);
+ *   }
+ * }
+ *
+ * // Conditional handler
+ * @provide(PremiumHandler)
+ * @OnEvent(UserCreatedEvent)
+ * @When(event => event.user.isPremium)
+ * export class PremiumHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     // Only runs for premium users
+ *   }
+ * }
+ *
+ * // Emit with full type safety
+ * eventEmitter.emit(new UserCreatedEvent("123", "user@example.com"));
+ * ```
+ */
+export { EventClass, EventInstance, EventMetadata, IEventHandler, EventHandlerClass, OnEventOptions, WhenOptions, IEventEmitter, IEventRegistry, RegisteredHandler, IEventRecorder, RecordedEvent, ReplayOptions, IEventFlowTracker, EventFlow, EventFlowNode, HandlerExecutionResult, EventSystemConfig, EVENT_METADATA, } from "./event.interfaces.js";
+export { OnEvent, OnEvents, When, Event, isEventHandler, getEventClass, getEventClasses, getEventOptions, getEventCondition, getEventMetadata, } from "./event-decorators.js";
+export { EventRegistry, createEventRegistry } from "./event-registry.js";
+export { EventEmitter, createEventEmitter } from "./event-emitter.js";
+export { EventRecorder, createEventRecorder } from "./event-recorder.js";
+export { EventFlowTracker, createEventFlowTracker, } from "./event-flow-tracker.js";

package/lib/esm/types/framework-version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Framework version string surfaced in startup banners and diagnostics.
+ *
+ * This file is auto-synced from the root `package.json` by
+ * `scripts/sync-version.js` before each build. Do not edit by hand.
+ */
+export declare const FRAMEWORK_VERSION = "4.0.0-preview.3";

package/lib/esm/types/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ExpressoTS Core
+ *
+ * @packageDocumentation
+ */
+export * from "./application/index.js";
+export * from "./config/index.js";
+export * from "./console/index.js";
+export * from "./container-module/index.js";
+export * from "./decorator/index.js";
+export * from "./error/index.js";
+export * from "./event/index.js";
+export * from "./interceptor/index.js";
+export * from "./lazy-loading/index.js";
+export * from "./lifecycle/index.js";
+export * from "./middleware/index.js";
+export * from "./provider/index.js";
+export * from "./render/index.js";
+export * from "./di/inversify.js";
+export * from "./authorization/index.js";
+export * from "./testing/index.js";
+/**
+ * Path resolution utilities (for advanced use cases)
+ * Note: Path aliases are automatically resolved at build time by the CLI.
+ * These exports are available for manual/advanced scenarios only.
+ */
+export { initializePathResolution } from "./path-resolver/index.js";

package/lib/esm/types/interceptor/conditional-interceptor.d.ts

@@ -0,0 +1,91 @@
+import type { IInterceptor, InterceptorClass, ExecutionContext, ConditionalInterceptor } from "./interceptor.interface.js";
+/**
+ * Create a conditional interceptor that only runs when condition is true.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept conditional-interceptor
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `whenInterceptor()` to conditionally execute an interceptor based on request context.
+ *
+ * @example
+ * ```typescript
+ * // Only cache when x-cache header is present
+ * @Get("/data")
+ * @UseInterceptors(
+ *   whenInterceptor(ctx => ctx.getRequest().headers['x-cache'] === 'true', CacheInterceptor),
+ *   LoggingInterceptor
+ * )
+ * getData() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async condition support
+ * @Get("/premium")
+ * @UseInterceptors(
+ *   whenInterceptor(async ctx => {
+ *     const user = await getUser(ctx.getRequest());
+ *     return user.isPremium;
+ *   }, PremiumFeaturesInterceptor)
+ * )
+ * getPremiumData() {}
+ * ```
+ *
+ * @param condition - Function returning true if interceptor should run
+ * @param interceptor - Interceptor class or instance to conditionally execute
+ * @returns ConditionalInterceptor that can be used with @UseInterceptors()
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Returns a marker object identified by `__isConditional: true`
+ * - InterceptorExecutor evaluates condition at runtime
+ * - If condition returns true, interceptor is executed
+ * - If condition returns false, interceptor is skipped
+ *
+ * @public API
+ */
+export declare function whenInterceptor(condition: (context: ExecutionContext) => boolean | Promise<boolean>, interceptor: IInterceptor | InterceptorClass): ConditionalInterceptor;
+/**
+ * Create a conditional interceptor that runs unless condition is true.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept conditional-interceptor
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `unlessInterceptor()` to skip an interceptor when condition is true.
+ *
+ * @example
+ * ```typescript
+ * // Skip caching for authenticated requests
+ * @Get("/data")
+ * @UseInterceptors(
+ *   unlessInterceptor(ctx => ctx.getRequest().headers['authorization'], CacheInterceptor),
+ *   LoggingInterceptor
+ * )
+ * getData() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Skip rate limiting for internal requests
+ * @Post("/api")
+ * @UseInterceptors(
+ *   unlessInterceptor(ctx => ctx.getRequest().headers['x-internal'] === 'true', RateLimitInterceptor)
+ * )
+ * handleApi() {}
+ * ```
+ *
+ * @param condition - Function returning true if interceptor should be SKIPPED
+ * @param interceptor - Interceptor class or instance to conditionally skip
+ * @returns ConditionalInterceptor that can be used with @UseInterceptors()
+ *
+ * @public API
+ */
+export declare function unlessInterceptor(condition: (context: ExecutionContext) => boolean | Promise<boolean>, interceptor: IInterceptor | InterceptorClass): ConditionalInterceptor;