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

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

@@ -0,0 +1,201 @@
+/**
+ * Event Registry
+ *
+ * @module event
+ *
+ * Central registry for event handlers with auto-discovery support.
+ */
+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";
+import { forEachBinding } from "../di/container-introspection.js";
+import { getEventClass, getEventClasses, getEventCondition, getEventOptions, isEventHandler, } from "./event-decorators.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.
+ */
+let EventRegistry = class EventRegistry {
+    /**
+     * Map of event class to handlers.
+     */
+    handlers = new Map();
+    /**
+     * Set of all registered handler classes.
+     */
+    handlerClasses = new Set();
+    /**
+     * Register a handler for an event.
+     */
+    register(eventClass, handlerClass, options = {}) {
+        if (!this.handlers.has(eventClass)) {
+            this.handlers.set(eventClass, []);
+        }
+        // Check if already registered
+        const existing = this.handlers.get(eventClass);
+        if (existing.some((h) => h.handlerClass === handlerClass)) {
+            return; // Already registered
+        }
+        // Get condition from decorator if present
+        const condition = getEventCondition(handlerClass);
+        // Merge options with decorator options
+        const decoratorOptions = getEventOptions(handlerClass) || {};
+        const mergedOptions = {
+            priority: 100,
+            async: false,
+            retry: 0,
+            timeout: 30000,
+            retryDelay: 1000,
+            backoff: "fixed",
+            ...decoratorOptions,
+            ...options,
+        };
+        const handler = {
+            handlerClass,
+            eventClass,
+            options: mergedOptions,
+            condition,
+        };
+        existing.push(handler);
+        this.handlerClasses.add(handlerClass);
+        // Sort by priority (lower = higher priority)
+        existing.sort((a, b) => (a.options.priority || 100) - (b.options.priority || 100));
+    }
+    /**
+     * Register a handler for multiple events.
+     */
+    registerMultiple(eventClasses, handlerClass, options = {}) {
+        for (const eventClass of eventClasses) {
+            this.register(eventClass, handlerClass, options);
+        }
+        // Store the event classes array on the first handler entry
+        if (eventClasses.length > 0) {
+            const handlers = this.handlers.get(eventClasses[0]);
+            if (handlers) {
+                const handler = handlers.find((h) => h.handlerClass === handlerClass);
+                if (handler) {
+                    handler.eventClasses = eventClasses;
+                }
+            }
+        }
+    }
+    /**
+     * Get all handlers for an event class.
+     */
+    getHandlers(eventClass) {
+        return (this.handlers.get(eventClass) || []);
+    }
+    /**
+     * Get all registered handlers.
+     */
+    getAllHandlers() {
+        const all = [];
+        for (const handlers of this.handlers.values()) {
+            all.push(...handlers);
+        }
+        return all;
+    }
+    /**
+     * Check if a handler is registered.
+     */
+    hasHandler(eventClass, handlerClass) {
+        const handlers = this.handlers.get(eventClass);
+        return handlers?.some((h) => h.handlerClass === handlerClass) || false;
+    }
+    /**
+     * Unregister a handler.
+     */
+    unregister(eventClass, handlerClass) {
+        const handlers = this.handlers.get(eventClass);
+        if (handlers) {
+            const index = handlers.findIndex((h) => h.handlerClass === handlerClass);
+            if (index !== -1) {
+                handlers.splice(index, 1);
+                this.handlerClasses.delete(handlerClass);
+            }
+        }
+    }
+    /**
+     * Clear all handlers.
+     */
+    clear() {
+        this.handlers.clear();
+        this.handlerClasses.clear();
+    }
+    /**
+     * 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) {
+        let discovered = 0;
+        forEachBinding(container, (binding) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const target = binding.implementationType;
+            if (!target || typeof target !== "function") {
+                return;
+            }
+            if (!isEventHandler(target)) {
+                return;
+            }
+            const eventClasses = getEventClasses(target);
+            const eventClass = getEventClass(target);
+            if (eventClasses && eventClasses.length > 0) {
+                this.registerMultiple(eventClasses, target, getEventOptions(target) || {});
+                discovered++;
+            }
+            else if (eventClass) {
+                this.register(eventClass, target, getEventOptions(target) || {});
+                discovered++;
+            }
+        });
+        return discovered;
+    }
+    /**
+     * Get handler classes for dependency resolution.
+     */
+    getHandlerClasses() {
+        return Array.from(this.handlerClasses);
+    }
+    /**
+     * Get all registered event classes.
+     */
+    getEventClasses() {
+        return Array.from(this.handlers.keys());
+    }
+    /**
+     * Get statistics about registered handlers.
+     */
+    getStatistics() {
+        const handlersPerEvent = {};
+        for (const [eventClass, handlers] of this.handlers.entries()) {
+            const name = eventClass.name || "UnknownEvent";
+            handlersPerEvent[name] = handlers.length;
+        }
+        return {
+            totalHandlers: this.handlerClasses.size,
+            totalEvents: this.handlers.size,
+            handlersPerEvent,
+        };
+    }
+};
+EventRegistry = __decorate([
+    injectable()
+], EventRegistry);
+export { EventRegistry };
+/**
+ * Create a standalone event registry (for testing).
+ */
+export function createEventRegistry() {
+    return new EventRegistry();
+}

package/lib/esm/event/event.interfaces.js

@@ -0,0 +1,51 @@
+/**
+ * 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"));
+ * ```
+ */
+// ============================================================================
+// Decorator Metadata Keys
+// ============================================================================
+/**
+ * Metadata keys for event decorators.
+ */
+export const EVENT_METADATA = {
+    EVENT_CLASS: Symbol("expressots:event:class"),
+    EVENT_CLASSES: Symbol("expressots:event:classes"),
+    EVENT_OPTIONS: Symbol("expressots:event:options"),
+    EVENT_CONDITION: Symbol("expressots:event:condition"),
+    IS_EVENT_HANDLER: Symbol("expressots:event:is-handler"),
+};

package/lib/esm/event/index.js

@@ -0,0 +1,58 @@
+/**
+ * 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"));
+ * ```
+ */
+// Interfaces
+export { EVENT_METADATA, } from "./event.interfaces.js";
+// Decorators
+export { OnEvent, OnEvents, When, Event, isEventHandler, getEventClass, getEventClasses, getEventOptions, getEventCondition, getEventMetadata, } from "./event-decorators.js";
+// Services
+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/index.mjs

@@ -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/interceptor/conditional-interceptor.js

@@ -0,0 +1,104 @@
+/**
+ * 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 function whenInterceptor(condition, interceptor) {
+    return {
+        __isConditional: true,
+        condition,
+        interceptor,
+        type: "when",
+    };
+}
+/**
+ * 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 function unlessInterceptor(condition, interceptor) {
+    return {
+        __isConditional: true,
+        condition,
+        interceptor,
+        type: "unless",
+    };
+}

package/lib/esm/interceptor/execution-context.js

@@ -0,0 +1,66 @@
+/**
+ * Implementation of ExecutionContext for Express adapter
+ *
+ * @layer internal
+ * @audience framework-developers
+ * @internal
+ */
+export class ExpressExecutionContext {
+    request;
+    response;
+    container;
+    controllerClass;
+    handlerName;
+    data = new Map();
+    constructor(request, response, container, controllerClass, handlerName) {
+        this.request = request;
+        this.response = response;
+        this.container = container;
+        this.controllerClass = controllerClass;
+        this.handlerName = handlerName;
+    }
+    getRequest() {
+        return this.request;
+    }
+    getResponse() {
+        return this.response;
+    }
+    getContainer() {
+        return this.container;
+    }
+    getScoped(identifier, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _scopeName) {
+        return this.container.get(identifier);
+    }
+    getClass() {
+        return this.controllerClass;
+    }
+    getHandler() {
+        return this.handlerName;
+    }
+    getRoute() {
+        return {
+            path: this.request.path,
+            method: this.request.method,
+            params: this.request.params,
+            query: this.request.query,
+        };
+    }
+    getData(key) {
+        return this.data.get(key);
+    }
+    setData(key, value) {
+        this.data.set(key, value);
+    }
+}
+/**
+ * Factory for creating ExecutionContext instances
+ *
+ * @layer internal
+ * @audience framework-developers
+ * @internal
+ */
+export function createExecutionContext(request, response, container, controllerClass, handlerName) {
+    return new ExpressExecutionContext(request, response, container, controllerClass, handlerName);
+}

package/lib/esm/interceptor/index.js

@@ -0,0 +1,48 @@
+/**
+ * Interceptor module - AOP (Aspect-Oriented Programming) for ExpressoTS
+ *
+ * @module interceptor
+ *
+ * Interceptors provide a powerful way to handle cross-cutting concerns like:
+ * - Logging
+ * - Caching
+ * - Response transformation
+ * - Performance tracking
+ * - Error handling
+ *
+ * @example
+ * ```typescript
+ * // Create a custom interceptor
+ * @Interceptor({ priority: 10 })
+ * @provide(MyInterceptor)
+ * export class MyInterceptor implements IInterceptor {
+ *   async intercept(context: ExecutionContext, next: CallHandler) {
+ *     console.log('Before...');
+ *     const result = await next.handle();
+ *     console.log('After...');
+ *     return result;
+ *   }
+ * }
+ *
+ * // Apply to a route
+ * @Get("/data")
+ * @UseInterceptors(MyInterceptor)
+ * getData() {}
+ * ```
+ */
+// Core interfaces and types
+export * from "./interceptor.interface.js";
+export * from "./interceptor-constants.js";
+// Decorators
+export * from "./interceptor-decorators.js";
+// Registry and Executor
+export * from "./interceptor-registry.js";
+export * from "./interceptor-executor.js";
+// Conditional interceptors
+export * from "./conditional-interceptor.js";
+// Composition utilities
+export * from "./interceptor-composition.js";
+// Execution context
+export * from "./execution-context.js";
+// Built-in interceptors
+export * from "./interceptors/index.js";

package/lib/esm/interceptor/interceptor-composition.js

@@ -0,0 +1,126 @@
+/**
+ * Compose multiple interceptors into a pipeline.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept interceptor-composition
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `pipeInterceptors()` to group interceptors that should run in sequence.
+ * Each interceptor wraps the next in the pipeline.
+ *
+ * @example
+ * ```typescript
+ * // All interceptors run in sequence
+ * @Get("/api/data")
+ * @UseInterceptors(
+ *   pipeInterceptors(
+ *     ValidationInterceptor,
+ *     TransformInterceptor,
+ *     CacheInterceptor,
+ *     LoggingInterceptor
+ *   )
+ * )
+ * getData() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reusable interceptor pipeline
+ * const apiPipeline = pipeInterceptors(
+ *   ValidationInterceptor,
+ *   TransformInterceptor,
+ *   LoggingInterceptor
+ * );
+ *
+ * @Get("/users")
+ * @UseInterceptors(apiPipeline)
+ * getUsers() {}
+ * ```
+ *
+ * @param interceptors - Interceptor classes or instances to compose
+ * @returns ComposedInterceptor that can be used with @UseInterceptors()
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Returns a marker object identified by `__isComposed: true`
+ * - InterceptorExecutor flattens composed interceptors
+ * - All interceptors are executed in pipeline order
+ * - `mode: "pipe"` indicates sequential pipeline execution
+ *
+ * @public API
+ */
+export function pipeInterceptors(...interceptors) {
+    return {
+        __isComposed: true,
+        interceptors,
+        mode: "pipe",
+    };
+}
+/**
+ * Combine multiple interceptors with all-must-pass semantics.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept interceptor-composition
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `combineInterceptors()` to group interceptors that all must complete successfully.
+ * Semantically indicates that all interceptors are required.
+ *
+ * @example
+ * ```typescript
+ * // All interceptors must pass
+ * @Post("/secure")
+ * @UseInterceptors(
+ *   combineInterceptors(
+ *     AuthInterceptor,
+ *     RateLimitInterceptor,
+ *     ValidationInterceptor
+ *   )
+ * )
+ * secureEndpoint() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reusable security interceptor group
+ * const securityInterceptors = combineInterceptors(
+ *   AuthInterceptor,
+ *   RateLimitInterceptor,
+ *   CSRFInterceptor
+ * );
+ *
+ * @Post("/api")
+ * @UseInterceptors(securityInterceptors)
+ * handleApi() {}
+ * ```
+ *
+ * @param interceptors - Interceptor classes or instances to combine
+ * @returns ComposedInterceptor that can be used with @UseInterceptors()
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Returns a marker object identified by `__isComposed: true`
+ * - InterceptorExecutor flattens composed interceptors
+ * - All interceptors are executed in pipeline order
+ * - `mode: "combine"` indicates all-must-pass semantics
+ *
+ * **Note**: Functionally identical to `pipeInterceptors()` but semantically
+ * indicates that ALL interceptors are required (similar to AND logic).
+ *
+ * @public API
+ */
+export function combineInterceptors(...interceptors) {
+    return {
+        __isComposed: true,
+        interceptors,
+        mode: "combine",
+    };
+}

package/lib/esm/interceptor/interceptor-constants.js

@@ -0,0 +1,17 @@
+/**
+ * Metadata keys for interceptor decorators
+ */
+export const INTERCEPTOR_METADATA_KEY = {
+    /**
+     * Key for @Interceptor() decorator metadata
+     */
+    interceptor: "expressots:interceptor",
+    /**
+     * Key for controller-level interceptors via @UseInterceptors()
+     */
+    controllerInterceptors: "expressots:controller_interceptors",
+    /**
+     * Key for method-level interceptors via @UseInterceptors()
+     */
+    methodInterceptors: "expressots:method_interceptors",
+};