@expressots/adapter-express 3.0.0-beta.4.2 → 4.0.0-preview.1

package/lib/cjs/adapter-express/express-utils/setup-event-system.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupEventSystemForExpress = setupEventSystemForExpress;
+const core_1 = require("@expressots/core");
+/**
+ * Set up the ExpressoTS Event System with zero boilerplate.
+ *
+ * This function:
+ * 1. Registers all event system services (EventRegistry, EventEmitter, EventRecorder, EventFlowTracker)
+ * 2. Auto-discovers and registers all @OnEvent decorated handlers
+ * 3. Configures recording and flow tracking based on environment
+ * 4. Sets up replay emitter for development debugging
+ *
+ * @param container - The DI container
+ * @param options - Configuration options for the event system
+ * @returns Setup result with references to all event system services
+ *
+ * @example
+ * ```typescript
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     // Simple setup with defaults (recommended)
+ *     const { handlersDiscovered } = setupEventSystemForExpress(
+ *       this.config.Container
+ *     );
+ *     console.log(`Discovered ${handlersDiscovered} event handlers`);
+ *
+ *     // Or with custom options
+ *     setupEventSystemForExpress(this.config.Container, {
+ *       enableRecording: true,
+ *       maxRecordedEvents: 500,
+ *       defaultTimeout: 10000,
+ *       onError: (error, event, handler) => {
+ *         console.error(`Handler ${handler} failed:`, error);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+function setupEventSystemForExpress(container, options = {}) {
+    const isDev = process.env.NODE_ENV === "development" || process.env.NODE_ENV === undefined;
+    // Default options
+    const config = {
+        enableRecording: isDev,
+        enableFlowTracking: isDev,
+        maxRecordedEvents: 1000,
+        defaultTimeout: 30000,
+        autoDiscover: true,
+        ...options,
+    };
+    // Register EventRegistry (singleton)
+    if (!container.isBound(core_1.EventRegistry)) {
+        container.bind(core_1.EventRegistry).toSelf().inSingletonScope();
+    }
+    // Register EventEmitter (singleton)
+    if (!container.isBound(core_1.EventEmitter)) {
+        container.bind(core_1.EventEmitter).toSelf().inSingletonScope();
+    }
+    // Register EventRecorder (singleton)
+    if (!container.isBound(core_1.EventRecorder)) {
+        container.bind(core_1.EventRecorder).toSelf().inSingletonScope();
+    }
+    // Register EventFlowTracker (singleton)
+    if (!container.isBound(core_1.EventFlowTracker)) {
+        container.bind(core_1.EventFlowTracker).toSelf().inSingletonScope();
+    }
+    // Get instances
+    const registry = container.get(core_1.EventRegistry);
+    const emitter = container.get(core_1.EventEmitter);
+    const recorder = container.get(core_1.EventRecorder);
+    const flowTracker = container.get(core_1.EventFlowTracker);
+    // Auto-discover event handlers
+    let handlersDiscovered = 0;
+    if (config.autoDiscover) {
+        handlersDiscovered = registry.discoverHandlers(container);
+    }
+    // Configure emitter
+    const emitterConfig = {
+        enableRecording: config.enableRecording,
+        enableFlowTracking: config.enableFlowTracking,
+        maxRecordedEvents: config.maxRecordedEvents,
+        defaultTimeout: config.defaultTimeout,
+    };
+    if (config.onEmit) {
+        emitterConfig.onEmit = config.onEmit;
+    }
+    if (config.onHandlerComplete) {
+        emitterConfig.onHandlerComplete = config.onHandlerComplete;
+    }
+    if (config.onError) {
+        emitterConfig.onError = config.onError;
+    }
+    emitter.configure(emitterConfig);
+    // Configure recorder
+    recorder.configure({
+        maxEvents: config.maxRecordedEvents || 1000,
+        autoStart: config.enableRecording,
+    });
+    // Set up replay emitter (so recorded events can be replayed)
+    recorder.setReplayEmitter(async (event) => {
+        await emitter.emit(event);
+    });
+    return {
+        registry,
+        emitter,
+        recorder,
+        flowTracker,
+        handlersDiscovered,
+    };
+}

package/lib/cjs/adapter-express/express-utils/setup-interceptors.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupInterceptorsForExpress = setupInterceptorsForExpress;
+const core_1 = require("@expressots/core");
+/**
+ * Set up the ExpressoTS Interceptor System with zero boilerplate.
+ *
+ * This function:
+ * 1. Registers all interceptor infrastructure (InterceptorRegistry, InterceptorExecutor)
+ * 2. Optionally enables built-in interceptors (Performance, Logging, Timeout)
+ * 3. Registers custom interceptor classes
+ * 4. Initializes the interceptor registry
+ *
+ * @param container - The DI container
+ * @param options - Configuration options for the interceptor system
+ * @returns Setup result with references to interceptor services
+ *
+ * @example
+ * ```typescript
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     // Simple setup with performance interceptor
+ *     setupInterceptorsForExpress(this.config.Container, {
+ *       builtIn: { performance: true }
+ *     });
+ *
+ *     // Full setup with custom interceptors
+ *     setupInterceptorsForExpress(this.config.Container, {
+ *       builtIn: {
+ *         performance: true,
+ *         logging: true,
+ *         timeout: { defaultTimeout: 5000 }
+ *       },
+ *       customInterceptors: [CacheInterceptor, AuditInterceptor]
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+function setupInterceptorsForExpress(container, options = {}) {
+    // Default options
+    const config = {
+        autoDiscover: true,
+        ...options,
+    };
+    let interceptorsRegistered = 0;
+    // Register InterceptorRegistry (singleton)
+    if (!container.isBound(core_1.InterceptorRegistry)) {
+        container.bind(core_1.InterceptorRegistry).toSelf().inSingletonScope();
+    }
+    // Register InterceptorExecutor (singleton)
+    if (!container.isBound(core_1.InterceptorExecutor)) {
+        container.bind(core_1.InterceptorExecutor).toSelf().inSingletonScope();
+    }
+    // Register PerformanceInterceptorService (needed by PerformanceInterceptor)
+    if (!container.isBound(core_1.PerformanceInterceptorService)) {
+        container.bind(core_1.PerformanceInterceptorService).toSelf().inSingletonScope();
+    }
+    // Register built-in interceptors if enabled
+    if (config.builtIn?.performance) {
+        if (!container.isBound(core_1.PerformanceInterceptor)) {
+            container.bind(core_1.PerformanceInterceptor).toSelf().inSingletonScope();
+            interceptorsRegistered++;
+        }
+    }
+    if (config.builtIn?.logging) {
+        if (!container.isBound(core_1.LoggingInterceptor)) {
+            container.bind(core_1.LoggingInterceptor).toSelf().inSingletonScope();
+            interceptorsRegistered++;
+        }
+    }
+    if (config.builtIn?.timeout) {
+        if (!container.isBound(core_1.TimeoutInterceptor)) {
+            container.bind(core_1.TimeoutInterceptor).toSelf().inSingletonScope();
+            interceptorsRegistered++;
+        }
+    }
+    // Register custom interceptors
+    if (config.customInterceptors && config.customInterceptors.length > 0) {
+        for (const interceptorClass of config.customInterceptors) {
+            if (!container.isBound(interceptorClass)) {
+                container.bind(interceptorClass).toSelf().inSingletonScope();
+                interceptorsRegistered++;
+            }
+        }
+    }
+    // Get instances
+    const registry = container.get(core_1.InterceptorRegistry);
+    const executor = container.get(core_1.InterceptorExecutor);
+    // Initialize registry (auto-discovers interceptors from container bindings)
+    if (config.autoDiscover) {
+        registry.initialize();
+        // Update count from registry
+        interceptorsRegistered = registry.getAll().length;
+    }
+    return {
+        registry,
+        executor,
+        interceptorsRegistered,
+    };
+}

package/lib/cjs/adapter-express/express-utils/setup-lazy-loading.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Setup Lazy Loading for Express
+ *
+ * One-liner helper function to configure the lazy loading system.
+ *
+ * @module adapter-express
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupLazyLoadingForExpress = setupLazyLoadingForExpress;
+const core_1 = require("@expressots/core");
+const lazy_module_middleware_js_1 = require("./lazy-module-middleware.js");
+// ============================================================================
+// Setup Function
+// ============================================================================
+/**
+ * Set up the lazy loading system with one function call.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Zero-configuration lazy loading!
+ * - Auto-detects routes from @controller() decorators
+ * - Creates middleware for automatic module loading
+ * - Optional metrics and background warmup
+ *
+ * @example
+ * ```typescript
+ * // 1. Define lazy modules (routes auto-detected from @controller)
+ * // lazy-modules.ts
+ * export const AdminModule = CreateLazyModule([AdminController]);
+ * // Routes auto-detected: ["/admin"] from @controller("/admin")
+ *
+ * export const ReportsModule = CreateLazyModule([ReportsController]);
+ * // Routes auto-detected: ["/reports"] from @controller("/reports")
+ *
+ * // 2. Setup in app.ts (just pass the modules!)
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     const { middleware } = setupLazyLoadingForExpress(
+ *       this.config.Container,
+ *       {
+ *         lazyModules: [AdminModule, ReportsModule],
+ *         globalPrefix: "/api"  // Optional
+ *       }
+ *     );
+ *
+ *     // Add middleware - that's it!
+ *     if (middleware) {
+ *       this.Middleware.addMiddleware(middleware);
+ *     }
+ *   }
+ * }
+ *
+ * // Now:
+ * // - GET /api/admin/* → AdminModule auto-loads
+ * // - GET /api/reports/* → ReportsModule auto-loads
+ * // - No manual route mapping needed!
+ * ```
+ *
+ * @param container - The DI container
+ * @param options - Configuration options
+ * @returns Setup result with loader, manager, and middleware
+ *
+ * @public API
+ */
+function setupLazyLoadingForExpress(container, options = {}) {
+    const isDev = process.env.NODE_ENV === "development";
+    // Get or create provider manager
+    let provider;
+    try {
+        provider = container.get(core_1.ProviderManager);
+    }
+    catch {
+        // ProviderManager not available, create bindings manually
+        provider = null;
+    }
+    // ============================================
+    // Register Services
+    // ============================================
+    // Register LazyModuleLoader if not already bound
+    if (!container.isBound(core_1.LazyModuleLoader)) {
+        if (provider) {
+            provider.register(core_1.LazyModuleLoader, core_1.Scope.Singleton);
+        }
+        else {
+            container.bind(core_1.LazyModuleLoader).toSelf().inSingletonScope();
+        }
+    }
+    // Register LazyModuleManager if not already bound
+    if (!container.isBound(core_1.LazyModuleManager)) {
+        if (provider) {
+            provider.register(core_1.LazyModuleManager, core_1.Scope.Singleton);
+        }
+        else {
+            container.bind(core_1.LazyModuleManager).toSelf().inSingletonScope();
+        }
+    }
+    // Register LazyLoadMetrics if enabled
+    const enableMetrics = options.enableMetrics ?? isDev;
+    if (enableMetrics && !container.isBound(core_1.LazyLoadMetrics)) {
+        if (provider) {
+            provider.register(core_1.LazyLoadMetrics, core_1.Scope.Singleton);
+        }
+        else {
+            container.bind(core_1.LazyLoadMetrics).toSelf().inSingletonScope();
+        }
+    }
+    // Register LazyModuleWarmup if enabled
+    const enableWarmup = options.enableWarmup ?? true;
+    if (enableWarmup && !container.isBound(core_1.LazyModuleWarmup)) {
+        if (provider) {
+            provider.register(core_1.LazyModuleWarmup, core_1.Scope.Singleton);
+        }
+        else {
+            container.bind(core_1.LazyModuleWarmup).toSelf().inSingletonScope();
+        }
+    }
+    // ============================================
+    // Get Service Instances
+    // ============================================
+    const loader = container.get(core_1.LazyModuleLoader);
+    loader.setContainer(container);
+    const manager = container.get(core_1.LazyModuleManager);
+    const metrics = enableMetrics ? container.get(core_1.LazyLoadMetrics) : undefined;
+    const warmup = enableWarmup ? container.get(core_1.LazyModuleWarmup) : undefined;
+    // ============================================
+    // Register Lazy Modules
+    // ============================================
+    const lazyModules = options.lazyModules || [];
+    let lazyCount = 0;
+    let eagerCount = 0;
+    for (const lazyModule of lazyModules) {
+        // Check if module should always be loaded eagerly
+        const alwaysLoad = options.alwaysLoad || [];
+        const neverLoad = options.neverLoad || [];
+        if (alwaysLoad.includes(lazyModule.name)) {
+            // Load immediately
+            lazyModule.load().catch((err) => {
+                console.warn(`[Lazy Loading] Failed to eager-load ${lazyModule.name}:`, err);
+            });
+            eagerCount++;
+        }
+        else if (!neverLoad.includes(lazyModule.name)) {
+            // Register for lazy loading
+            loader.register(lazyModule);
+            lazyCount++;
+        }
+    }
+    // ============================================
+    // Log Summary
+    // ============================================
+    const logLevel = options.logLevel ?? "info";
+    if (logLevel !== "none") {
+        let logger;
+        try {
+            logger = container.get(core_1.Logger);
+        }
+        catch {
+            // Logger not available
+        }
+        const message = `[Lazy Loading] Registered ${lazyCount} lazy modules, ${eagerCount} eager modules`;
+        if (logger) {
+            logger.info(message);
+        }
+        else if (logLevel === "debug" || logLevel === "info") {
+            console.log(message);
+        }
+    }
+    // ============================================
+    // Start Warmup if Enabled
+    // ============================================
+    if (warmup && options.warmupConfig) {
+        // Schedule warmup to start after a delay
+        const warmupDelay = options.warmupConfig.delay ?? 5000;
+        setTimeout(() => {
+            warmup.start(options.warmupConfig).catch((err) => {
+                console.warn("[Lazy Loading] Warmup failed:", err);
+            });
+        }, warmupDelay);
+    }
+    // ============================================
+    // Create Auto-Load Middleware
+    // ============================================
+    let middleware;
+    let routeMappings = [];
+    if (lazyCount > 0 && options.enableAutoLoad !== false) {
+        // Create route mappings from lazy modules
+        routeMappings = (0, lazy_module_middleware_js_1.createRouteMappings)(lazyModules.filter((m) => !options.alwaysLoad?.includes(m.name)), options.routePrefixes);
+        // Create the middleware
+        middleware = (0, lazy_module_middleware_js_1.createLazyModuleMiddleware)({
+            routes: routeMappings,
+            loader,
+            globalPrefix: options.globalPrefix || "",
+            onLoadStart: (moduleName, path) => {
+                if (options.logLevel !== "none") {
+                    console.log(`[Lazy Loading] Loading '${moduleName}' (triggered by ${path})...`);
+                }
+            },
+            onLoadComplete: (moduleName, loadTimeMs) => {
+                metrics?.recordLoadTime(moduleName, loadTimeMs);
+            },
+            onLoadError: (moduleName, error) => {
+                console.error(`[Lazy Loading] Failed to load '${moduleName}':`, error.message);
+            },
+        });
+        if (options.logLevel !== "none") {
+            const routes = routeMappings
+                .map((r) => `${options.globalPrefix || ""}${r.prefix}`)
+                .join(", ");
+            console.log(`[Lazy Loading] Auto-load middleware active for routes: ${routes}`);
+        }
+    }
+    // ============================================
+    // Return Result
+    // ============================================
+    return {
+        loader,
+        manager,
+        metrics,
+        warmup,
+        middleware,
+        routeMappings,
+        lazyModulesCount: lazyCount,
+        eagerModulesCount: eagerCount,
+    };
+}

package/lib/cjs/adapter-express/express-utils/utils.js

@@ -7,32 +7,33 @@ exports.getControllerMethodMetadata = getControllerMethodMetadata;
 exports.getControllerParameterMetadata = getControllerParameterMetadata;
 exports.cleanUpMetadata = cleanUpMetadata;
 exports.instanceOfIHttpActionResult = instanceOfIHttpActionResult;
+exports.getContentNegotiationMetadata = getContentNegotiationMetadata;
 const core_1 = require("@expressots/core");
-const constants_1 = require("./constants");
+const constants_js_1 = require("./constants.js");
 function getControllersFromContainer(container, forceControllers) {
-    if (container.isBound(constants_1.TYPE.Controller)) {
-        return container.getAll(constants_1.TYPE.Controller);
+    if (container.isBound(constants_js_1.TYPE.Controller)) {
+        return container.getAll(constants_js_1.TYPE.Controller);
     }
     if (forceControllers) {
         const logger = new core_1.Logger();
-        logger.error(constants_1.NO_CONTROLLERS_FOUND, "adapter-express");
-        throw new Error(constants_1.NO_CONTROLLERS_FOUND);
+        logger.error(constants_js_1.NO_CONTROLLERS_FOUND, "adapter-express");
+        throw new Error(constants_js_1.NO_CONTROLLERS_FOUND);
     }
     else {
         return [];
     }
 }
 function getControllersFromMetadata() {
-    const arrayOfControllerMetadata = Reflect.getMetadata(constants_1.METADATA_KEY.controller, Reflect) || [];
+    const arrayOfControllerMetadata = Reflect.getMetadata(constants_js_1.METADATA_KEY.controller, Reflect) || [];
     return arrayOfControllerMetadata.map((metadata) => metadata.target);
 }
 function getControllerMetadata(constructor) {
-    const controllerMetadata = Reflect.getOwnMetadata(constants_1.METADATA_KEY.controller, constructor);
+    const controllerMetadata = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controller, constructor);
     return controllerMetadata;
 }
 function getControllerMethodMetadata(constructor) {
-    const methodMetadata = Reflect.getOwnMetadata(constants_1.METADATA_KEY.controllerMethod, constructor);
-    const genericMetadata = Reflect.getMetadata(constants_1.METADATA_KEY.controllerMethod, Reflect.getPrototypeOf(constructor));
+    const methodMetadata = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controllerMethod, constructor);
+    const genericMetadata = Reflect.getMetadata(constants_js_1.METADATA_KEY.controllerMethod, Reflect.getPrototypeOf(constructor));
     if (genericMetadata !== undefined && methodMetadata !== undefined) {
         return methodMetadata.concat(genericMetadata);
     }
@@ -42,8 +43,8 @@ function getControllerMethodMetadata(constructor) {
     return methodMetadata;
 }
 function getControllerParameterMetadata(constructor) {
-    const parameterMetadata = Reflect.getOwnMetadata(constants_1.METADATA_KEY.controllerParameter, constructor);
-    const genericMetadata = Reflect.getMetadata(constants_1.METADATA_KEY.controllerParameter, Reflect.getPrototypeOf(constructor));
+    const parameterMetadata = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controllerParameter, constructor);
+    const genericMetadata = Reflect.getMetadata(constants_js_1.METADATA_KEY.controllerParameter, Reflect.getPrototypeOf(constructor));
     if (genericMetadata !== undefined && parameterMetadata !== undefined) {
         return { ...parameterMetadata, ...genericMetadata };
     }
@@ -53,8 +54,25 @@ function getControllerParameterMetadata(constructor) {
     return parameterMetadata;
 }
 function cleanUpMetadata() {
-    Reflect.defineMetadata(constants_1.METADATA_KEY.controller, [], Reflect);
+    Reflect.defineMetadata(constants_js_1.METADATA_KEY.controller, [], Reflect);
 }
 function instanceOfIHttpActionResult(value) {
     return value != null && typeof value.executeAsync === "function";
 }
+/**
+ * Gets content negotiation metadata from a controller method.
+ * @param target - Controller instance
+ * @param propertyKey - Method name
+ * @returns Content negotiation metadata
+ */
+function getContentNegotiationMetadata(target, propertyKey) {
+    return {
+        accept: Reflect.getMetadata(constants_js_1.METADATA_KEY.accept, target, propertyKey),
+        consumes: Reflect.getMetadata(constants_js_1.METADATA_KEY.consumes, target, propertyKey),
+        produces: Reflect.getMetadata(constants_js_1.METADATA_KEY.produces, target, propertyKey),
+        csvOptions: Reflect.getMetadata(constants_js_1.METADATA_KEY.csvOptions, target, propertyKey),
+        xmlOptions: Reflect.getMetadata(constants_js_1.METADATA_KEY.xmlOptions, target, propertyKey),
+        yamlOptions: Reflect.getMetadata(constants_js_1.METADATA_KEY.yamlOptions, target, propertyKey),
+        streamResponse: Reflect.getMetadata(constants_js_1.METADATA_KEY.streamResponse, target, propertyKey),
+    };
+}