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

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/path-pattern-compat.js

@@ -0,0 +1,125 @@
+/**
+ * Split `:name(regex)` segments out of an Express-style route path.
+ *
+ * The walker honours balanced parens inside the regex (e.g.
+ * `(\\d{4})` or `((a|b)+)`), which is more forgiving than a naive
+ * single-pass regex match would be. Returns the original path and an
+ * empty constraints list when no inline patterns are found, so this is
+ * a no-op for the common case.
+ */
+export function splitPathConstraints(path) {
+    // Defensive: hand a non-string straight back. The decorators occasionally
+    // see `undefined` or `null` paths in older test fixtures and we don't
+    // want to crash decorator-time evaluation just because of input shape.
+    if (typeof path !== "string") {
+        return { path: path, constraints: [] };
+    }
+    const constraints = [];
+    let out = "";
+    let i = 0;
+    while (i < path.length) {
+        const ch = path[i];
+        if (ch !== ":") {
+            out += ch;
+            i++;
+            continue;
+        }
+        // Found a `:` — scan the following identifier (matches `[A-Za-z0-9_]+`,
+        // same character class path-to-regexp v8 accepts).
+        const start = i;
+        i++;
+        let nameEnd = i;
+        while (nameEnd < path.length && /[A-Za-z0-9_]/.test(path[nameEnd])) {
+            nameEnd++;
+        }
+        if (nameEnd === i) {
+            // `:` not followed by an identifier — leave it to path-to-regexp.
+            out += ":";
+            continue;
+        }
+        const paramName = path.slice(i, nameEnd);
+        out += `:${paramName}`;
+        i = nameEnd;
+        // Optional inline `(...regex...)` immediately after the name.
+        if (path[i] !== "(") {
+            continue;
+        }
+        let depth = 1;
+        let j = i + 1;
+        while (j < path.length && depth > 0) {
+            const c = path[j];
+            if (c === "\\" && j + 1 < path.length) {
+                j += 2;
+                continue;
+            }
+            if (c === "(")
+                depth++;
+            else if (c === ")")
+                depth--;
+            j++;
+        }
+        if (depth !== 0) {
+            // Unbalanced — leave the original path intact and let path-to-regexp
+            // raise its own (better-located) error.
+            out += path.slice(i);
+            i = path.length;
+            break;
+        }
+        const rawPattern = path.slice(i + 1, j - 1);
+        try {
+            constraints.push({
+                paramName,
+                regex: new RegExp(`^(?:${rawPattern})$`),
+                rawPattern,
+            });
+        }
+        catch {
+            // The regex inside the parens is malformed. We don't want a
+            // decorator-time crash — fall back to dropping the constraint so
+            // the route at least registers; runtime validation simply won't
+            // run for this param.
+        }
+        // Consume the `(...)` segment without re-emitting it into `out`,
+        // since path-to-regexp v8 doesn't accept the syntax.
+        i = j;
+        // Quietly consume a trailing redundant `?` (older code wrote
+        // `:foo(\\d+)?`); v8 spells optional segments with `{...}` braces,
+        // and "drop the constraint, keep the param" is the sane fallback.
+        if (path[i] === "?") {
+            i++;
+        }
+        // Path-to-regexp v6 supported quantifier suffixes (`+`, `*`); v8
+        // dropped them. We strip them silently for the same reason.
+        while (path[i] === "+" || path[i] === "*") {
+            i++;
+        }
+        void start;
+    }
+    return { path: out, constraints };
+}
+/**
+ * Build a middleware that enforces the given param-level regex
+ * constraints on `req.params`. Returns `null` when the list is empty
+ * (so callers can avoid wiring an unnecessary middleware).
+ *
+ * When a constraint fails, the middleware delegates to `next()` without
+ * a value; the framework's NotFound handler then converts that into a
+ * 404 — same observable behaviour as Express 4's "no route matched".
+ */
+export function createPathConstraintMiddleware(constraints) {
+    if (constraints.length === 0)
+        return null;
+    return (req, res, next) => {
+        for (const c of constraints) {
+            const value = req.params?.[c.paramName];
+            // Express 5 sometimes hands back `string[]` for splat params, but
+            // inline-regex params are always scalar strings; coerce defensively.
+            const scalar = Array.isArray(value) ? value.join("/") : value;
+            if (typeof scalar !== "string" || !c.regex.test(scalar)) {
+                // Skip to the next handler so the framework's 404 path runs.
+                return next("route");
+            }
+        }
+        next();
+    };
+}

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,100 @@
+/**
+ * Route parameter patterns for common use cases.
+ *
+ * Express 5 / path-to-regexp v8 dropped the inline-regex form
+ * (`:id(\\d+)`), so the framework no longer hands these patterns to
+ * the underlying matcher verbatim. Instead, the HTTP-method decorators
+ * (`@Get`, `@Post`, …) parse the constraint out of the path at decorator
+ * time, register the route under a plain `:id` placeholder, and inject
+ * a small validator middleware that 404s when the captured value
+ * doesn't match. The user-facing semantics are unchanged: a path that
+ * uses `Patterns.NUMERIC_ID` still rejects `/users/abc` and only
+ * dispatches the handler for matches like `/users/123`.
+ *
+ * @example
+ * ```typescript
+ * import { Patterns, pattern } from "@expressots/adapter-express";
+ *
+ * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
+ * getUserById(@param("id") id: number) {
+ *   // Only dispatches for numeric IDs like /users/123
+ * }
+ *
+ * @Get(`/documents/${pattern("uuid", Patterns.UUID)}`)
+ * getDocument(@param("uuid") uuid: string) {
+ *   // Only dispatches for 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 {};