@expressots/adapter-express 3.0.0 → 4.0.0-preview.3

package/lib/esm/adapter-express/express-utils/scope-extractor.js

@@ -0,0 +1,63 @@
+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 "@expressots/core";
+/**
+ * Extracts scope information from requests
+ * Supports tenant extraction from subdomain, header, or param
+ * Note: This is bound manually in setupAuthorizationForExpress() to allow user overrides
+ */
+let ScopeExtractor = class ScopeExtractor {
+    async extract(req) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const sessionId = req.session?.id;
+        return {
+            tenant: this.extractTenant(req),
+            request: this.generateRequestId(req),
+            session: sessionId,
+            transaction: req.headers["x-transaction-id"],
+        };
+    }
+    /**
+     * Extract tenant ID from multiple sources
+     * @private
+     */
+    extractTenant(req) {
+        // Try subdomain first
+        if (req.subdomains && req.subdomains.length > 0) {
+            return req.subdomains[0];
+        }
+        // Try header
+        const headerTenant = req.headers["x-tenant-id"];
+        if (headerTenant) {
+            return headerTenant;
+        }
+        // Try route parameter
+        const paramTenant = req.params.tenantId;
+        if (paramTenant) {
+            return paramTenant;
+        }
+        return undefined;
+    }
+    /**
+     * Generate or retrieve request ID
+     * @private
+     */
+    generateRequestId(req) {
+        // Try to get existing request ID (if set by middleware)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const existingId = req.id;
+        if (existingId) {
+            return existingId;
+        }
+        // Generate new ID
+        return `req-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    }
+};
+ScopeExtractor = __decorate([
+    injectable()
+], ScopeExtractor);
+export { ScopeExtractor };

package/lib/esm/adapter-express/express-utils/setup-authorization.js

@@ -0,0 +1,68 @@
+import { setupAuthorization } from "@expressots/core";
+import { ScopeExtractor } from "./scope-extractor.js";
+import { GuardContextFactory } from "./guard-context-factory.js";
+import { GuardMiddleware } from "./guard-middleware.js";
+import { PermissionPreloaderMiddleware } from "./permission-preloader.middleware.js";
+import { TYPE } from "./constants.js";
+/**
+ * Express-specific authorization setup
+ * Automatically registers all adapter-specific services and middleware
+ *
+ * @param container - DI container
+ * @param config - Authorization configuration
+ * @param middleware - Optional middleware manager to add PermissionPreloaderMiddleware
+ * @param authProvider - Optional AuthProvider class (if not already bound)
+ *
+ * @example
+ * ```typescript
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     setupAuthorizationForExpress(
+ *       this.config.Container,
+ *       {
+ *         enablePreloading: true,
+ *         enableCaching: true,
+ *         permissionHierarchy: {
+ *           admin: ["moderator", "user"],
+ *           moderator: ["user"],
+ *         },
+ *       },
+ *       this.Middleware,
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export function setupAuthorizationForExpress(container, config = {}, middleware, authProvider) {
+    // Setup core authorization system
+    setupAuthorization(container, config);
+    // Register adapter-specific services
+    if (!container.isBound("IScopeExtractor")) {
+        container.bind("IScopeExtractor").to(ScopeExtractor).inSingletonScope();
+    }
+    if (!container.isBound(GuardContextFactory)) {
+        container.bind(GuardContextFactory).toSelf().inSingletonScope();
+    }
+    if (!container.isBound(GuardMiddleware)) {
+        container.bind(GuardMiddleware).toSelf().inSingletonScope();
+    }
+    // Bind AuthProvider if provided and not already bound
+    if (authProvider && !container.isBound(TYPE.AuthProvider)) {
+        container.bind(TYPE.AuthProvider).to(authProvider).inSingletonScope();
+    }
+    // Add permission preloader middleware if enabled and middleware manager provided
+    // PermissionPreloaderMiddleware extends BaseMiddleware which has a handler() method
+    // The middleware system accepts BaseMiddleware instances as IExpressoMiddleware
+    if (config.enablePreloading !== false && middleware) {
+        // Bind PermissionPreloaderMiddleware if not already bound
+        if (!container.isBound(PermissionPreloaderMiddleware)) {
+            container.bind(PermissionPreloaderMiddleware).toSelf().inSingletonScope();
+        }
+        // Get instance from container (DI will inject dependencies)
+        // Cast to IExpressoMiddleware - BaseMiddleware instances are handled specially
+        // by the middleware resolution system (see inversify-express-server.ts)
+        const middlewareInstance = container.get(PermissionPreloaderMiddleware);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        middleware.add(middlewareInstance);
+    }
+}

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

@@ -0,0 +1,110 @@
+import { EventRegistry, EventEmitter, EventRecorder, EventFlowTracker, } from "@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
+ */
+export 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(EventRegistry)) {
+        container.bind(EventRegistry).toSelf().inSingletonScope();
+    }
+    // Register EventEmitter (singleton)
+    if (!container.isBound(EventEmitter)) {
+        container.bind(EventEmitter).toSelf().inSingletonScope();
+    }
+    // Register EventRecorder (singleton)
+    if (!container.isBound(EventRecorder)) {
+        container.bind(EventRecorder).toSelf().inSingletonScope();
+    }
+    // Register EventFlowTracker (singleton)
+    if (!container.isBound(EventFlowTracker)) {
+        container.bind(EventFlowTracker).toSelf().inSingletonScope();
+    }
+    // Get instances
+    const registry = container.get(EventRegistry);
+    const emitter = container.get(EventEmitter);
+    const recorder = container.get(EventRecorder);
+    const flowTracker = container.get(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/esm/adapter-express/express-utils/setup-interceptors.js

@@ -0,0 +1,100 @@
+import { InterceptorRegistry, InterceptorExecutor, PerformanceInterceptorService, PerformanceInterceptor, LoggingInterceptor, TimeoutInterceptor, } from "@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
+ */
+export function setupInterceptorsForExpress(container, options = {}) {
+    // Default options
+    const config = {
+        autoDiscover: true,
+        ...options,
+    };
+    let interceptorsRegistered = 0;
+    // Register InterceptorRegistry (singleton)
+    if (!container.isBound(InterceptorRegistry)) {
+        container.bind(InterceptorRegistry).toSelf().inSingletonScope();
+    }
+    // Register InterceptorExecutor (singleton)
+    if (!container.isBound(InterceptorExecutor)) {
+        container.bind(InterceptorExecutor).toSelf().inSingletonScope();
+    }
+    // Register PerformanceInterceptorService (needed by PerformanceInterceptor)
+    if (!container.isBound(PerformanceInterceptorService)) {
+        container.bind(PerformanceInterceptorService).toSelf().inSingletonScope();
+    }
+    // Register built-in interceptors if enabled
+    if (config.builtIn?.performance) {
+        if (!container.isBound(PerformanceInterceptor)) {
+            container.bind(PerformanceInterceptor).toSelf().inSingletonScope();
+            interceptorsRegistered++;
+        }
+    }
+    if (config.builtIn?.logging) {
+        if (!container.isBound(LoggingInterceptor)) {
+            container.bind(LoggingInterceptor).toSelf().inSingletonScope();
+            interceptorsRegistered++;
+        }
+    }
+    if (config.builtIn?.timeout) {
+        if (!container.isBound(TimeoutInterceptor)) {
+            container.bind(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(InterceptorRegistry);
+    const executor = container.get(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/esm/adapter-express/express-utils/setup-lazy-loading.js

@@ -0,0 +1,225 @@
+/**
+ * Setup Lazy Loading for Express
+ *
+ * One-liner helper function to configure the lazy loading system.
+ *
+ * @module adapter-express
+ */
+import { LazyModuleLoader, LazyModuleManager, LazyLoadMetrics, LazyModuleWarmup, Scope, ProviderManager, Logger, } from "@expressots/core";
+import { createLazyModuleMiddleware, createRouteMappings, } from "./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
+ */
+export function setupLazyLoadingForExpress(container, options = {}) {
+    const isDev = process.env.NODE_ENV === "development";
+    // Get or create provider manager
+    let provider;
+    try {
+        provider = container.get(ProviderManager);
+    }
+    catch {
+        // ProviderManager not available, create bindings manually
+        provider = null;
+    }
+    // ============================================
+    // Register Services
+    // ============================================
+    // Register LazyModuleLoader if not already bound
+    if (!container.isBound(LazyModuleLoader)) {
+        if (provider) {
+            provider.register(LazyModuleLoader, Scope.Singleton);
+        }
+        else {
+            container.bind(LazyModuleLoader).toSelf().inSingletonScope();
+        }
+    }
+    // Register LazyModuleManager if not already bound
+    if (!container.isBound(LazyModuleManager)) {
+        if (provider) {
+            provider.register(LazyModuleManager, Scope.Singleton);
+        }
+        else {
+            container.bind(LazyModuleManager).toSelf().inSingletonScope();
+        }
+    }
+    // Register LazyLoadMetrics if enabled
+    const enableMetrics = options.enableMetrics ?? isDev;
+    if (enableMetrics && !container.isBound(LazyLoadMetrics)) {
+        if (provider) {
+            provider.register(LazyLoadMetrics, Scope.Singleton);
+        }
+        else {
+            container.bind(LazyLoadMetrics).toSelf().inSingletonScope();
+        }
+    }
+    // Register LazyModuleWarmup if enabled
+    const enableWarmup = options.enableWarmup ?? true;
+    if (enableWarmup && !container.isBound(LazyModuleWarmup)) {
+        if (provider) {
+            provider.register(LazyModuleWarmup, Scope.Singleton);
+        }
+        else {
+            container.bind(LazyModuleWarmup).toSelf().inSingletonScope();
+        }
+    }
+    // ============================================
+    // Get Service Instances
+    // ============================================
+    const loader = container.get(LazyModuleLoader);
+    loader.setContainer(container);
+    const manager = container.get(LazyModuleManager);
+    const metrics = enableMetrics ? container.get(LazyLoadMetrics) : undefined;
+    const warmup = enableWarmup ? container.get(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(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 = createRouteMappings(lazyModules.filter((m) => !options.alwaysLoad?.includes(m.name)), options.routePrefixes);
+        // Create the middleware
+        middleware = 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/esm/adapter-express/express-utils/utils.js

@@ -0,0 +1,68 @@
+import { Logger } from "@expressots/core";
+import { METADATA_KEY, NO_CONTROLLERS_FOUND, TYPE } from "./constants.js";
+export function getControllersFromContainer(container, forceControllers) {
+    if (container.isBound(TYPE.Controller)) {
+        return container.getAll(TYPE.Controller);
+    }
+    if (forceControllers) {
+        const logger = new Logger();
+        logger.error(NO_CONTROLLERS_FOUND, "adapter-express");
+        throw new Error(NO_CONTROLLERS_FOUND);
+    }
+    else {
+        return [];
+    }
+}
+export function getControllersFromMetadata() {
+    const arrayOfControllerMetadata = Reflect.getMetadata(METADATA_KEY.controller, Reflect) || [];
+    return arrayOfControllerMetadata.map((metadata) => metadata.target);
+}
+export function getControllerMetadata(constructor) {
+    const controllerMetadata = Reflect.getOwnMetadata(METADATA_KEY.controller, constructor);
+    return controllerMetadata;
+}
+export function getControllerMethodMetadata(constructor) {
+    const methodMetadata = Reflect.getOwnMetadata(METADATA_KEY.controllerMethod, constructor);
+    const genericMetadata = Reflect.getMetadata(METADATA_KEY.controllerMethod, Reflect.getPrototypeOf(constructor));
+    if (genericMetadata !== undefined && methodMetadata !== undefined) {
+        return methodMetadata.concat(genericMetadata);
+    }
+    if (genericMetadata !== undefined) {
+        return genericMetadata;
+    }
+    return methodMetadata;
+}
+export function getControllerParameterMetadata(constructor) {
+    const parameterMetadata = Reflect.getOwnMetadata(METADATA_KEY.controllerParameter, constructor);
+    const genericMetadata = Reflect.getMetadata(METADATA_KEY.controllerParameter, Reflect.getPrototypeOf(constructor));
+    if (genericMetadata !== undefined && parameterMetadata !== undefined) {
+        return { ...parameterMetadata, ...genericMetadata };
+    }
+    if (genericMetadata !== undefined) {
+        return genericMetadata;
+    }
+    return parameterMetadata;
+}
+export function cleanUpMetadata() {
+    Reflect.defineMetadata(METADATA_KEY.controller, [], Reflect);
+}
+export 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
+ */
+export function getContentNegotiationMetadata(target, propertyKey) {
+    return {
+        accept: Reflect.getMetadata(METADATA_KEY.accept, target, propertyKey),
+        consumes: Reflect.getMetadata(METADATA_KEY.consumes, target, propertyKey),
+        produces: Reflect.getMetadata(METADATA_KEY.produces, target, propertyKey),
+        csvOptions: Reflect.getMetadata(METADATA_KEY.csvOptions, target, propertyKey),
+        xmlOptions: Reflect.getMetadata(METADATA_KEY.xmlOptions, target, propertyKey),
+        yamlOptions: Reflect.getMetadata(METADATA_KEY.yamlOptions, target, propertyKey),
+        streamResponse: Reflect.getMetadata(METADATA_KEY.streamResponse, target, propertyKey),
+    };
+}