@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * 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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventRegistry = void 0;
+exports.createEventRegistry = createEventRegistry;
+const inversify_js_1 = require("../di/inversify.js");
+const container_introspection_js_1 = require("../di/container-introspection.js");
+const event_decorators_js_1 = require("./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 {
+    constructor() {
+        /**
+         * Map of event class to handlers.
+         */
+        this.handlers = new Map();
+        /**
+         * Set of all registered handler classes.
+         */
+        this.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 = (0, event_decorators_js_1.getEventCondition)(handlerClass);
+        // Merge options with decorator options
+        const decoratorOptions = (0, event_decorators_js_1.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;
+        (0, container_introspection_js_1.forEachBinding)(container, (binding) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const target = binding.implementationType;
+            if (!target || typeof target !== "function") {
+                return;
+            }
+            if (!(0, event_decorators_js_1.isEventHandler)(target)) {
+                return;
+            }
+            const eventClasses = (0, event_decorators_js_1.getEventClasses)(target);
+            const eventClass = (0, event_decorators_js_1.getEventClass)(target);
+            if (eventClasses && eventClasses.length > 0) {
+                this.registerMultiple(eventClasses, target, (0, event_decorators_js_1.getEventOptions)(target) || {});
+                discovered++;
+            }
+            else if (eventClass) {
+                this.register(eventClass, target, (0, event_decorators_js_1.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,
+        };
+    }
+};
+exports.EventRegistry = EventRegistry;
+exports.EventRegistry = EventRegistry = __decorate([
+    (0, inversify_js_1.injectable)()
+], EventRegistry);
+/**
+ * Create a standalone event registry (for testing).
+ */
+function createEventRegistry() {
+    return new EventRegistry();
+}

package/lib/cjs/event/event.interfaces.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * 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"));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_METADATA = void 0;
+// ============================================================================
+// Decorator Metadata Keys
+// ============================================================================
+/**
+ * Metadata keys for event decorators.
+ */
+exports.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/cjs/event/index.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * 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"));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventFlowTracker = exports.EventFlowTracker = exports.createEventRecorder = exports.EventRecorder = exports.createEventEmitter = exports.EventEmitter = exports.createEventRegistry = exports.EventRegistry = exports.getEventMetadata = exports.getEventCondition = exports.getEventOptions = exports.getEventClasses = exports.getEventClass = exports.isEventHandler = exports.Event = exports.When = exports.OnEvents = exports.OnEvent = exports.EVENT_METADATA = void 0;
+// Interfaces
+var event_interfaces_js_1 = require("./event.interfaces.js");
+Object.defineProperty(exports, "EVENT_METADATA", { enumerable: true, get: function () { return event_interfaces_js_1.EVENT_METADATA; } });
+// Decorators
+var event_decorators_js_1 = require("./event-decorators.js");
+Object.defineProperty(exports, "OnEvent", { enumerable: true, get: function () { return event_decorators_js_1.OnEvent; } });
+Object.defineProperty(exports, "OnEvents", { enumerable: true, get: function () { return event_decorators_js_1.OnEvents; } });
+Object.defineProperty(exports, "When", { enumerable: true, get: function () { return event_decorators_js_1.When; } });
+Object.defineProperty(exports, "Event", { enumerable: true, get: function () { return event_decorators_js_1.Event; } });
+Object.defineProperty(exports, "isEventHandler", { enumerable: true, get: function () { return event_decorators_js_1.isEventHandler; } });
+Object.defineProperty(exports, "getEventClass", { enumerable: true, get: function () { return event_decorators_js_1.getEventClass; } });
+Object.defineProperty(exports, "getEventClasses", { enumerable: true, get: function () { return event_decorators_js_1.getEventClasses; } });
+Object.defineProperty(exports, "getEventOptions", { enumerable: true, get: function () { return event_decorators_js_1.getEventOptions; } });
+Object.defineProperty(exports, "getEventCondition", { enumerable: true, get: function () { return event_decorators_js_1.getEventCondition; } });
+Object.defineProperty(exports, "getEventMetadata", { enumerable: true, get: function () { return event_decorators_js_1.getEventMetadata; } });
+// Services
+var event_registry_js_1 = require("./event-registry.js");
+Object.defineProperty(exports, "EventRegistry", { enumerable: true, get: function () { return event_registry_js_1.EventRegistry; } });
+Object.defineProperty(exports, "createEventRegistry", { enumerable: true, get: function () { return event_registry_js_1.createEventRegistry; } });
+var event_emitter_js_1 = require("./event-emitter.js");
+Object.defineProperty(exports, "EventEmitter", { enumerable: true, get: function () { return event_emitter_js_1.EventEmitter; } });
+Object.defineProperty(exports, "createEventEmitter", { enumerable: true, get: function () { return event_emitter_js_1.createEventEmitter; } });
+var event_recorder_js_1 = require("./event-recorder.js");
+Object.defineProperty(exports, "EventRecorder", { enumerable: true, get: function () { return event_recorder_js_1.EventRecorder; } });
+Object.defineProperty(exports, "createEventRecorder", { enumerable: true, get: function () { return event_recorder_js_1.createEventRecorder; } });
+var event_flow_tracker_js_1 = require("./event-flow-tracker.js");
+Object.defineProperty(exports, "EventFlowTracker", { enumerable: true, get: function () { return event_flow_tracker_js_1.EventFlowTracker; } });
+Object.defineProperty(exports, "createEventFlowTracker", { enumerable: true, get: function () { return event_flow_tracker_js_1.createEventFlowTracker; } });

package/lib/cjs/framework-version.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAMEWORK_VERSION = void 0;
+/**
+ * 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.
+ */
+exports.FRAMEWORK_VERSION = "4.0.0-preview.3";

package/lib/cjs/index.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * ExpressoTS Core
+ *
+ * @packageDocumentation
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -14,11 +19,27 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./application"), exports);
-__exportStar(require("./console"), exports);
-__exportStar(require("./container-module"), exports);
-__exportStar(require("./decorator"), exports);
-__exportStar(require("./error"), exports);
-__exportStar(require("./middleware"), exports);
-__exportStar(require("./provider"), exports);
-__exportStar(require("./di/inversify"), exports);
+exports.initializePathResolution = void 0;
+__exportStar(require("./application/index.js"), exports);
+__exportStar(require("./config/index.js"), exports);
+__exportStar(require("./console/index.js"), exports);
+__exportStar(require("./container-module/index.js"), exports);
+__exportStar(require("./decorator/index.js"), exports);
+__exportStar(require("./error/index.js"), exports);
+__exportStar(require("./event/index.js"), exports);
+__exportStar(require("./interceptor/index.js"), exports);
+__exportStar(require("./lazy-loading/index.js"), exports);
+__exportStar(require("./lifecycle/index.js"), exports);
+__exportStar(require("./middleware/index.js"), exports);
+__exportStar(require("./provider/index.js"), exports);
+__exportStar(require("./render/index.js"), exports);
+__exportStar(require("./di/inversify.js"), exports);
+__exportStar(require("./authorization/index.js"), exports);
+__exportStar(require("./testing/index.js"), exports);
+/**
+ * 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.
+ */
+var index_js_1 = require("./path-resolver/index.js");
+Object.defineProperty(exports, "initializePathResolution", { enumerable: true, get: function () { return index_js_1.initializePathResolution; } });

package/lib/cjs/interceptor/conditional-interceptor.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whenInterceptor = whenInterceptor;
+exports.unlessInterceptor = unlessInterceptor;
+/**
+ * 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
+ */
+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
+ */
+function unlessInterceptor(condition, interceptor) {
+    return {
+        __isConditional: true,
+        condition,
+        interceptor,
+        type: "unless",
+    };
+}

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

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpressExecutionContext = void 0;
+exports.createExecutionContext = createExecutionContext;
+/**
+ * Implementation of ExecutionContext for Express adapter
+ *
+ * @layer internal
+ * @audience framework-developers
+ * @internal
+ */
+class ExpressExecutionContext {
+    constructor(request, response, container, controllerClass, handlerName) {
+        this.request = request;
+        this.response = response;
+        this.container = container;
+        this.controllerClass = controllerClass;
+        this.handlerName = handlerName;
+        this.data = new Map();
+    }
+    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);
+    }
+}
+exports.ExpressExecutionContext = ExpressExecutionContext;
+/**
+ * Factory for creating ExecutionContext instances
+ *
+ * @layer internal
+ * @audience framework-developers
+ * @internal
+ */
+function createExecutionContext(request, response, container, controllerClass, handlerName) {
+    return new ExpressExecutionContext(request, response, container, controllerClass, handlerName);
+}

package/lib/cjs/interceptor/index.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * 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() {}
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Core interfaces and types
+__exportStar(require("./interceptor.interface.js"), exports);
+__exportStar(require("./interceptor-constants.js"), exports);
+// Decorators
+__exportStar(require("./interceptor-decorators.js"), exports);
+// Registry and Executor
+__exportStar(require("./interceptor-registry.js"), exports);
+__exportStar(require("./interceptor-executor.js"), exports);
+// Conditional interceptors
+__exportStar(require("./conditional-interceptor.js"), exports);
+// Composition utilities
+__exportStar(require("./interceptor-composition.js"), exports);
+// Execution context
+__exportStar(require("./execution-context.js"), exports);
+// Built-in interceptors
+__exportStar(require("./interceptors/index.js"), exports);