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

package/lib/esm/adapter-express/express-utils/lazy-module-middleware.js

@@ -0,0 +1,236 @@
+/**
+ * Lazy Module Auto-Load Middleware
+ *
+ * Automatically loads lazy modules when their routes are accessed.
+ * This provides seamless lazy loading without 404 errors.
+ *
+ * @module adapter-express
+ */
+import { Router } from "express";
+// ============================================================================
+// Lazy Module Middleware
+// ============================================================================
+/**
+ * Create middleware that auto-loads lazy modules when their routes are accessed.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Seamless lazy loading - no 404s! Modules load automatically
+ * when their routes are accessed for the first time.
+ *
+ * @example
+ * ```typescript
+ * const middleware = createLazyModuleMiddleware({
+ *   routes: [
+ *     { prefix: "/admin", moduleName: "AdminModule", loaded: false },
+ *     { prefix: "/reports", moduleName: "ReportsModule", loaded: false }
+ *   ],
+ *   loader: lazyModuleLoader,
+ *   globalPrefix: "/api"
+ * });
+ *
+ * app.use(middleware);
+ * ```
+ *
+ * @param config - Middleware configuration
+ * @returns Express middleware function
+ *
+ * @public API
+ */
+export function createLazyModuleMiddleware(config) {
+    const { routes, loader, globalPrefix = "" } = config;
+    // Create a map for O(1) prefix lookup
+    const routeMap = new Map();
+    for (const route of routes) {
+        const fullPrefix = globalPrefix + route.prefix;
+        routeMap.set(fullPrefix.toLowerCase(), route);
+    }
+    // Track modules currently being loaded (to prevent duplicate loads)
+    const loadingModules = new Set();
+    return async (req, res, next) => {
+        const path = req.path.toLowerCase();
+        // Find matching route prefix
+        let matchedRoute;
+        for (const [prefix, route] of routeMap.entries()) {
+            if (path.startsWith(prefix)) {
+                matchedRoute = route;
+                break;
+            }
+        }
+        // No matching lazy module route
+        if (!matchedRoute) {
+            return next();
+        }
+        // Already loaded
+        if (matchedRoute.loaded || loader.isLoaded(matchedRoute.moduleName)) {
+            matchedRoute.loaded = true;
+            return next();
+        }
+        // Currently loading - wait for it
+        if (loadingModules.has(matchedRoute.moduleName)) {
+            // Poll until loaded (with timeout)
+            const maxWait = 30000; // 30 seconds
+            const pollInterval = 50;
+            let waited = 0;
+            while (loadingModules.has(matchedRoute.moduleName) && waited < maxWait) {
+                await new Promise((resolve) => setTimeout(resolve, pollInterval));
+                waited += pollInterval;
+            }
+            if (loader.isLoaded(matchedRoute.moduleName)) {
+                matchedRoute.loaded = true;
+                return next();
+            }
+            else {
+                res.status(503).json({
+                    error: "Service Unavailable",
+                    message: `Module '${matchedRoute.moduleName}' is still loading. Please try again.`,
+                });
+                return;
+            }
+        }
+        // Start loading the module
+        loadingModules.add(matchedRoute.moduleName);
+        const startTime = Date.now();
+        config.onLoadStart?.(matchedRoute.moduleName, req.path);
+        try {
+            await loader.load(matchedRoute.moduleName);
+            matchedRoute.loaded = true;
+            const loadTime = Date.now() - startTime;
+            config.onLoadComplete?.(matchedRoute.moduleName, loadTime);
+            console.log(`[Lazy Loading] Module '${matchedRoute.moduleName}' loaded on-demand in ${loadTime}ms ` +
+                `(triggered by ${req.method} ${req.path})`);
+            loadingModules.delete(matchedRoute.moduleName);
+            // Dynamic route registration: If callbacks are provided, register routes
+            // and continue the request without redirecting
+            if (config.onRegisterRoutes && config.expressApp) {
+                try {
+                    const moduleRouter = Router();
+                    config.onRegisterRoutes(matchedRoute.moduleName, moduleRouter);
+                    // Mount the new routes (Express will pick them up for future requests)
+                    // For THIS request, we continue to let it fall through
+                    console.log(`[Lazy Loading] Dynamically registered routes for '${matchedRoute.moduleName}'`);
+                }
+                catch (registrationError) {
+                    console.warn(`[Lazy Loading] Dynamic route registration failed for '${matchedRoute.moduleName}':`, registrationError);
+                }
+            }
+            // Continue to next middleware - the routes should now be available
+            // This works because Express route matching happens per-request
+            // and the container now has the lazy module's controllers bound.
+            //
+            // If dynamic registration isn't set up, fall back to 307 redirect
+            if (config.onRegisterRoutes) {
+                // Re-emit the request through Express routing
+                // The route should now match a real handler
+                return next("route");
+            }
+            else {
+                // Fallback: 307 redirect for single round-trip (temporary redirect preserves method)
+                res.redirect(307, req.originalUrl);
+            }
+        }
+        catch (error) {
+            loadingModules.delete(matchedRoute.moduleName);
+            const err = error instanceof Error ? error : new Error(String(error));
+            config.onLoadError?.(matchedRoute.moduleName, err);
+            console.error(`[Lazy Loading] Failed to load module '${matchedRoute.moduleName}':`, err.message);
+            res.status(500).json({
+                error: "Module Load Failed",
+                message: `Failed to load module for route '${req.path}'. ${err.message}`,
+            });
+        }
+    };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Extract route prefixes from a lazy module.
+ *
+ * Uses auto-detected routes from CreateLazyModule (which analyzes @controller decorators),
+ * falls back to prefetchOn config, and finally infers from module name.
+ *
+ * @param lazyModule - The lazy module to analyze
+ * @returns Detected route prefixes
+ *
+ * @public API
+ */
+export function extractRoutePrefixes(lazyModule) {
+    const prefixes = [];
+    // 1. Use auto-detected routePrefixes from CreateLazyModule (best source!)
+    if (lazyModule.config.routePrefixes && lazyModule.config.routePrefixes.length > 0) {
+        return lazyModule.config.routePrefixes;
+    }
+    // 2. Try prefetchOn config as fallback
+    const prefetchOn = lazyModule.config.prefetchOn || [];
+    for (const prefetch of prefetchOn) {
+        const parts = prefetch.route.split("/").filter(Boolean);
+        if (parts.length > 0) {
+            prefixes.push("/" + parts[0]);
+        }
+    }
+    if (prefixes.length > 0) {
+        return [...new Set(prefixes)];
+    }
+    // 3. Last resort: infer from module name
+    // "AdminModule" -> "/admin", "UserSettingsModule" -> "/usersettings"
+    const inferredPrefix = "/" +
+        lazyModule.name
+            .replace(/Module$/i, "")
+            .replace(/([A-Z])/g, (match, p1, offset) => offset > 0 ? `-${p1.toLowerCase()}` : p1.toLowerCase());
+    return [inferredPrefix];
+}
+/**
+ * Create route mappings from lazy modules.
+ *
+ * Route detection priority:
+ * 1. Manual routePrefixMap (if provided)
+ * 2. Auto-detected from @controller() decorators (via CreateLazyModule)
+ * 3. prefetchOn config
+ * 4. Inferred from module name
+ *
+ * @param lazyModules - Array of lazy modules
+ * @param routePrefixMap - Optional manual prefix mappings { moduleName: prefix }
+ * @returns Array of route mappings
+ *
+ * @example
+ * ```typescript
+ * // Zero-config: routes auto-detected from controllers!
+ * const mappings = createRouteMappings([AdminModule, ReportsModule]);
+ * // Automatically maps @controller("/admin") -> /admin
+ *
+ * // Or with manual overrides
+ * const mappings = createRouteMappings(
+ *   [AdminModule, ReportsModule],
+ *   { "AdminModule": "/admin-panel" }  // Override auto-detection
+ * );
+ * ```
+ *
+ * @public API
+ */
+export function createRouteMappings(lazyModules, routePrefixMap) {
+    const mappings = [];
+    for (const module of lazyModules) {
+        // Use manual mapping if provided (highest priority)
+        if (routePrefixMap && routePrefixMap[module.name]) {
+            mappings.push({
+                prefix: routePrefixMap[module.name],
+                moduleName: module.name,
+                loaded: module.isLoaded,
+            });
+            continue;
+        }
+        // Use auto-detected prefixes (includes @controller detection)
+        const prefixes = extractRoutePrefixes(module);
+        for (const prefix of prefixes) {
+            mappings.push({
+                prefix,
+                moduleName: module.name,
+                loaded: module.isLoaded,
+            });
+        }
+    }
+    return mappings;
+}

package/lib/esm/adapter-express/express-utils/middleware-composition.js

@@ -0,0 +1,89 @@
+/**
+ * Symbol to identify composed middleware configuration objects.
+ * Used internally for type checking.
+ */
+export const COMPOSED_MIDDLEWARE_SYMBOL = Symbol("ComposedMiddleware");
+/**
+ * Type guard to check if an object is a ComposedMiddlewareConfig.
+ */
+export function isComposedMiddleware(item) {
+    return (typeof item === "object" &&
+        item !== null &&
+        COMPOSED_MIDDLEWARE_SYMBOL in item &&
+        "middleware" in item &&
+        "type" in item &&
+        Array.isArray(item.middleware) &&
+        (item.type === "combine" ||
+            item.type === "sequence"));
+}
+/**
+ * Combines multiple middleware into a single middleware that executes all of them sequentially.
+ * All middleware will execute in order. If any middleware calls `next(error)`, the error
+ * is propagated to Express's error handling system.
+ *
+ * @param middleware - Array of middleware to combine
+ * @returns ComposedMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Combine multiple middleware into a reusable group
+ * @Get("/api", combine(AuthMiddleware, LoggingMiddleware, RateLimitMiddleware))
+ * async apiHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Combine with conditional middleware (Phase 3)
+ * @Get("/admin",
+ *   when(req => req.method === "POST", combine(BodyParser, ValidationMiddleware)),
+ *   combine(AuthMiddleware, LoggingMiddleware)
+ * )
+ * async adminHandler() {}
+ * ```
+ */
+export function combine(...middleware) {
+    if (middleware.length === 0) {
+        throw new Error("combine() requires at least one middleware");
+    }
+    return {
+        middleware,
+        type: "combine",
+        [COMPOSED_MIDDLEWARE_SYMBOL]: true,
+    };
+}
+/**
+ * Sequences multiple middleware that execute one after another.
+ * Similar to `combine()`, but semantically indicates sequential execution
+ * where each middleware depends on the previous one completing successfully.
+ * If any middleware calls `next(error)`, execution stops and the error is propagated.
+ *
+ * @param middleware - Array of middleware to sequence
+ * @returns ComposedMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Sequence middleware where each depends on the previous
+ * @Get("/api", sequence(ValidateMiddleware, TransformMiddleware, ProcessMiddleware))
+ * async apiHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Sequence with conditional middleware
+ * @Get("/data",
+ *   when(req => req.method === "POST", sequence(BodyParser, ValidateMiddleware)),
+ *   sequence(AuthMiddleware, ProcessMiddleware)
+ * )
+ * async dataHandler() {}
+ * ```
+ */
+export function sequence(...middleware) {
+    if (middleware.length === 0) {
+        throw new Error("sequence() requires at least one middleware");
+    }
+    return {
+        middleware,
+        type: "sequence",
+        [COMPOSED_MIDDLEWARE_SYMBOL]: true,
+    };
+}

package/lib/esm/adapter-express/express-utils/permission-preloader.middleware.js

@@ -0,0 +1,45 @@
+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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { inject } from "@expressots/core";
+import { BaseMiddleware } from "./base-middleware.js";
+/**
+ * Middleware that preloads permissions for authenticated users
+ * Caches permissions in request-scoped SecurityContext
+ */
+export class PermissionPreloaderMiddleware extends BaseMiddleware {
+    securityContext;
+    async handler(req, res, next) {
+        try {
+            // Get HttpContext
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const httpContext = req.__expressotsHttpContext;
+            if (!httpContext) {
+                return next();
+            }
+            const principal = httpContext.user;
+            // Preload permissions if user is authenticated
+            if (principal && (await principal.isAuthenticated())) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const userId = principal.details?.id;
+                if (userId && this.securityContext) {
+                    await this.securityContext.preload(userId);
+                }
+            }
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    }
+}
+__decorate([
+    inject("ISecurityContext"),
+    __metadata("design:type", Object)
+], PermissionPreloaderMiddleware.prototype, "securityContext", void 0);

package/lib/esm/adapter-express/express-utils/resolver-multer.js

@@ -0,0 +1,30 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Logger } from "@expressots/core";
+/**
+ * Resolve package from the current working directory.
+ * @param packageName
+ * @param options
+ * @returns
+ */
+export function packageResolver(packageName) {
+    const logger = new Logger();
+    try {
+        const hasPackage = require.resolve(packageName, {
+            paths: [process.cwd()],
+        });
+        if (hasPackage) {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const packageResolved = require(hasPackage);
+            if (typeof packageResolved === "function") {
+                return packageResolved;
+            }
+            if (packageResolved.default && typeof packageResolved.default === "function") {
+                return packageResolved.default;
+            }
+            return packageResolved;
+        }
+    }
+    catch (error) {
+        logger.warn(`Package [${packageName}] not installed. Please install it using your package manager.`, "package-resolver");
+    }
+}

package/lib/esm/adapter-express/express-utils/route-constraints.js

@@ -0,0 +1,91 @@
+/**
+ * Route parameter patterns for common use cases.
+ * These are Express regex patterns that can be used in route paths.
+ *
+ * @example
+ * ```typescript
+ * import { Patterns, pattern } from "@expressots/adapter-express";
+ *
+ * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
+ * getUserById(@param("id") id: number) {
+ *   // Only matches numeric IDs like /users/123
+ * }
+ *
+ * @Get(`/documents/${pattern("uuid", Patterns.UUID)}`)
+ * getDocument(@param("uuid") uuid: string) {
+ *   // Only matches valid UUIDs
+ * }
+ * ```
+ *
+ * @public API
+ */
+export const Patterns = {
+    /**
+     * Matches one or more digits (numeric ID)
+     * Example: /users/123 ✅, /users/abc ❌
+     */
+    NUMERIC_ID: "(\\d+)",
+    /**
+     * Matches a valid UUID v4 format
+     * Example: /documents/550e8400-e29b-41d4-a716-446655440000 ✅
+     */
+    UUID: "([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})",
+    /**
+     * Matches lowercase letters, numbers, and hyphens (URL-friendly slug)
+     * Example: /posts/my-awesome-post ✅, /posts/My_Post ❌
+     */
+    SLUG: "([a-z0-9-]+)",
+    /**
+     * Matches alphanumeric characters (letters and numbers only)
+     * Example: /codes/ABC123 ✅, /codes/ABC-123 ❌
+     */
+    ALPHANUMERIC: "([a-zA-Z0-9]+)",
+    /**
+     * Matches lowercase letters only
+     * Example: /tags/javascript ✅, /tags/JavaScript ❌
+     */
+    LOWERCASE: "([a-z]+)",
+    /**
+     * Matches uppercase letters only
+     * Example: /codes/USD ✅, /codes/usd ❌
+     */
+    UPPERCASE: "([A-Z]+)",
+    /**
+     * Matches email format (basic validation)
+     * Example: /users/user@example.com ✅
+     */
+    EMAIL: "([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})",
+    /**
+     * Matches hexadecimal string (e.g., color codes, hash)
+     * Example: /colors/ff5733 ✅, /colors/xyz ❌
+     */
+    HEXADECIMAL: "([0-9a-fA-F]+)",
+    /**
+     * Matches MongoDB ObjectId format (24 hex characters)
+     * Example: /documents/507f1f77bcf86cd799439011 ✅
+     */
+    MONGO_ID: "([0-9a-fA-F]{24})",
+};
+/**
+ * Helper function to build route parameter patterns.
+ * This is optional - you can also use Patterns directly in template strings.
+ *
+ * @param paramName - The parameter name (e.g., "id", "uuid")
+ * @param pattern - The pattern from Patterns
+ * @returns The formatted route parameter with pattern
+ *
+ * @example
+ * ```typescript
+ * import { pattern, Patterns } from "@expressots/adapter-express";
+ *
+ * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
+ * getUserById(@param("id") id: number) {
+ *   // Route: /users/:id(\\d+)
+ * }
+ * ```
+ *
+ * @public API
+ */
+export function pattern(paramName, patternValue) {
+    return `:${paramName}(${patternValue})`;
+}

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

@@ -0,0 +1 @@
+export {};

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);
+    }
+}