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

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

@@ -26,11 +26,68 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InversifyExpressServer = void 0;
 /* eslint-disable @typescript-eslint/no-unused-vars */
 const express_1 = __importStar(require("express"));
-const base_middleware_1 = require("./base-middleware");
-const utils_1 = require("./utils");
-const constants_1 = require("./constants");
-const httpResponseMessage_1 = require("./httpResponseMessage");
-const decorators_1 = require("./decorators");
+const core_1 = require("@expressots/core");
+const guard_context_factory_js_1 = require("./guard-context-factory.js");
+const base_middleware_js_1 = require("./base-middleware.js");
+const utils_js_1 = require("./utils.js");
+const validation_decorators_js_1 = require("./validation-decorators.js");
+const constants_js_1 = require("./constants.js");
+const httpResponseMessage_js_1 = require("./httpResponseMessage.js");
+const decorators_js_1 = require("./decorators.js");
+const conditional_middleware_js_1 = require("./conditional-middleware.js");
+const middleware_composition_js_1 = require("./middleware-composition.js");
+const guard_utils_js_1 = require("./guard-utils.js");
+const guard_middleware_js_1 = require("./guard-middleware.js");
+const interceptor_middleware_js_1 = require("./interceptor-middleware.js");
+const http_context_store_js_1 = require("./http-context-store.js");
+// Lazy-load route registry from @expressots/core. Static import because
+// `getRouteRegistry` is part of the core's public surface; we just guard
+// against it being undefined to keep this non-critical (suggestions are
+// optional).
+const core_2 = require("@expressots/core");
+function getRouteRegistryModule() {
+    if (typeof core_2.getRouteRegistry !== "function")
+        return null;
+    return { getRouteRegistry: core_2.getRouteRegistry };
+}
+/**
+ * Properly join route path segments, handling:
+ * - Controller "/" + method "/users" = "/users"
+ * - Controller "/api" + method "users" = "/api/users"
+ * - Controller "/api/" + method "/users" = "/api/users"
+ * - Controller "/" + method "/" = "/"
+ */
+function joinRoutePaths(...segments) {
+    const parts = [];
+    for (const segment of segments) {
+        if (!segment || segment === "")
+            continue;
+        // For root path only, skip if we have parts
+        if (segment === "/" && parts.length > 0)
+            continue;
+        // Remove trailing slash
+        let cleaned = segment.endsWith("/") && segment.length > 1 ? segment.slice(0, -1) : segment;
+        // Handle leading slash
+        if (parts.length > 0) {
+            // Ensure leading slash for non-first segments
+            cleaned = cleaned.startsWith("/") ? cleaned : `/${cleaned}`;
+        }
+        else {
+            // First segment - ensure starts with /
+            cleaned = cleaned.startsWith("/") ? cleaned : `/${cleaned}`;
+        }
+        if (cleaned && cleaned !== "/") {
+            parts.push(cleaned);
+        }
+        else if (parts.length === 0) {
+            parts.push("/");
+        }
+    }
+    if (parts.length === 0)
+        return "/";
+    // Join and normalize double slashes
+    return parts.join("").replace(/\/+/g, "/");
+}
 class InversifyExpressServer {
     /**
      * Wrapper for the express server.
@@ -47,12 +104,12 @@ class InversifyExpressServer {
         this._forceControllers = forceControllers;
         this._router = customRouter || (0, express_1.Router)();
         this._routingConfig = routingConfig || {
-            rootPath: constants_1.DEFAULT_ROUTING_ROOT_PATH,
+            rootPath: constants_js_1.DEFAULT_ROUTING_ROOT_PATH,
         };
         this._app = customApp || (0, express_1.default)();
         if (authProvider) {
             this._AuthProvider = authProvider;
-            container.bind(constants_1.TYPE.AuthProvider).to(this._AuthProvider);
+            container.bind(constants_js_1.TYPE.AuthProvider).to(this._AuthProvider);
         }
     }
     /**
@@ -85,46 +142,169 @@ class InversifyExpressServer {
      * Applies all routes and configuration to the server, returning the express application.
      */
     build() {
-        // The very first middleware to be invoked
-        // it creates a new httpContext and attaches it to the
-        // current request as metadata using Reflect
-        this._app.all("*", (req, res, next) => {
-            void (async () => {
-                const httpContext = await this._createHttpContext(req, res, next);
-                Reflect.defineMetadata(constants_1.METADATA_KEY.httpContext, httpContext, req);
+        // The very first middleware to be invoked: create an HttpContext per
+        // request and attach it via a WeakMap (see ./http-context-store).
+        // This is cheaper than the previous `Reflect.defineMetadata` call
+        // because it bypasses reflect-metadata's string-keyed map.
+        //
+        // We use `app.use(handler)` (no path arg) which runs for every request
+        // regardless of method or path — the same behavior as the previous
+        // `app.all("*", ...)` registration but without a path-to-regexp pattern,
+        // so it is forward-compatible with Express 5 / path-to-regexp v8.
+        this._app.use((req, res, next) => {
+            this._createHttpContext(req, res, next)
+                .then((httpContext) => {
+                (0, http_context_store_js_1.setHttpContext)(req, httpContext);
                 next();
-            })();
+            })
+                .catch(next);
         });
         // register server-level middleware before anything else
         if (this._configFn) {
             this._configFn.apply(undefined, [this._app]);
         }
         this.registerControllers();
+        this.registerNotFoundHandler();
         // register error handlers after controllers
         if (this._errorConfigFn) {
             this._errorConfigFn.apply(undefined, [this._app]);
         }
         return this._app;
     }
+    /**
+     * Install a catch-all 404 handler that runs after every registered route.
+     *
+     * When the user has the suggestions feature enabled (default in development),
+     * this consults the route registry, computes "Did you mean ...?" suggestions
+     * via `getErrorHints` from `@expressots/core`, logs them through the framework
+     * Logger, and returns a structured RFC-7807-style JSON 404 instead of the
+     * default Express HTML.
+     *
+     * Users who want the legacy Express HTML 404 can opt out by configuring the
+     * Logger with `suggestions.enabled = false` (this also disables the JSON
+     * envelope so they can install their own 404 handler in the error-config fn).
+     *
+     * @private
+     */
+    registerNotFoundHandler() {
+        this._app.use((req, res, next) => {
+            if (res.headersSent) {
+                return next();
+            }
+            const suggestionsConfig = this.resolveSuggestionsConfig();
+            if (!suggestionsConfig.enabled) {
+                return next();
+            }
+            const requestedPath = req.originalUrl || req.url;
+            const requestedMethod = req.method;
+            const hints = (0, core_1.getErrorHints)(new Error(`Route '${requestedMethod} ${requestedPath}' not found`), {
+                path: requestedPath,
+                method: requestedMethod,
+                statusCode: 404,
+            }, suggestionsConfig);
+            if (hints.length > 0) {
+                try {
+                    const formatted = (0, core_1.formatSuggestions)(hints);
+                    if (formatted) {
+                        const logger = this.resolveLogger();
+                        if (logger) {
+                            logger.warn(`Route not found: ${requestedMethod} ${requestedPath}${formatted}`, "router-404");
+                        }
+                        else {
+                            // eslint-disable-next-line no-console
+                            console.warn(`[router-404] Route not found: ${requestedMethod} ${requestedPath}${formatted}`);
+                        }
+                    }
+                }
+                catch {
+                    // Suggestion logging is best-effort; never fail the request because of it.
+                }
+            }
+            const routeSuggestion = hints.find((hint) => hint.type === "route");
+            const actionHint = hints.find((hint) => hint.type === "hint");
+            const body = {
+                type: "https://expressots.dev/errors/not-found",
+                title: "Route Not Found",
+                status: 404,
+                detail: `Route '${requestedMethod} ${requestedPath}' does not exist`,
+                instance: requestedPath,
+                timestamp: new Date().toISOString(),
+            };
+            if (routeSuggestion?.routes && routeSuggestion.routes.length > 0) {
+                body.suggestions = routeSuggestion.routes.map((suggestion) => ({
+                    method: suggestion.route.method,
+                    path: suggestion.route.fullPath || suggestion.route.path,
+                    similarity: Math.round(suggestion.similarity * 100),
+                    reason: suggestion.reason,
+                }));
+            }
+            else if (actionHint?.actions && actionHint.actions.length > 0) {
+                body.actions = actionHint.actions;
+            }
+            res.status(404).type("application/json").send(JSON.stringify(body));
+        });
+    }
+    /**
+     * Resolve the user-configured suggestions config, falling back to the
+     * env-aware default when the Logger is not bound or has no overrides.
+     *
+     * @private
+     */
+    resolveSuggestionsConfig() {
+        const fallback = (0, core_1.getDefaultSuggestionsConfig)();
+        const logger = this.resolveLogger();
+        if (!logger) {
+            return fallback;
+        }
+        try {
+            const loggerConfig = logger.getConfig?.();
+            if (loggerConfig?.suggestions) {
+                return { ...fallback, ...loggerConfig.suggestions };
+            }
+        }
+        catch {
+            // Logger may not expose getConfig in older versions; fall through.
+        }
+        return fallback;
+    }
+    /**
+     * Resolve the framework Logger from DI when available.
+     *
+     * @private
+     */
+    resolveLogger() {
+        try {
+            // The `Logger` symbol is the constructor itself in our DI bindings.
+            if (this._container.isBound(core_1.Logger)) {
+                return this._container.get(core_1.Logger);
+            }
+        }
+        catch {
+            // not bound yet
+        }
+        return undefined;
+    }
     registerControllers() {
         // Fake HttpContext is needed during registration
-        this._container.bind(constants_1.TYPE.HttpContext).toConstantValue({});
-        const constructors = (0, utils_1.getControllersFromMetadata)();
+        this._container.bind(constants_js_1.TYPE.HttpContext).toConstantValue({});
+        // Initialize interceptor system if not already bound
+        this.initializeInterceptorSystem();
+        const constructors = (0, utils_js_1.getControllersFromMetadata)();
         constructors.forEach((constructor) => {
             const { name } = constructor;
-            if (this._container.isBoundNamed(constants_1.TYPE.Controller, name)) {
-                throw new Error((0, constants_1.DUPLICATED_CONTROLLER_NAME)(name));
+            if (this._container.isBoundNamed(constants_js_1.TYPE.Controller, name)) {
+                throw new Error((0, constants_js_1.DUPLICATED_CONTROLLER_NAME)(name));
             }
             this._container
-                .bind(constants_1.TYPE.Controller)
+                .bind(constants_js_1.TYPE.Controller)
                 .to(constructor)
                 .whenTargetNamed(name);
         });
-        const controllers = (0, utils_1.getControllersFromContainer)(this._container, this._forceControllers);
+        const controllers = (0, utils_js_1.getControllersFromContainer)(this._container, this._forceControllers);
         controllers.forEach((controller) => {
-            const controllerMetadata = (0, utils_1.getControllerMetadata)(controller.constructor);
-            const methodMetadata = (0, utils_1.getControllerMethodMetadata)(controller.constructor);
-            const parameterMetadata = (0, utils_1.getControllerParameterMetadata)(controller.constructor);
+            const controllerMetadata = (0, utils_js_1.getControllerMetadata)(controller.constructor);
+            const methodMetadata = (0, utils_js_1.getControllerMethodMetadata)(controller.constructor);
+            const parameterMetadata = (0, utils_js_1.getControllerParameterMetadata)(controller.constructor);
             if (controllerMetadata && methodMetadata) {
                 const controllerMiddleware = this.resolveMiddleware(...controllerMetadata.middleware);
                 methodMetadata.forEach((metadata) => {
@@ -132,21 +312,168 @@ class InversifyExpressServer {
                     if (parameterMetadata) {
                         paramList = parameterMetadata[metadata.key] || [];
                     }
-                    const handler = this.handlerFactory(controllerMetadata.target.name, metadata.key, paramList);
+                    // Create base handler
+                    let handler = this.handlerFactory(controllerMetadata.target.name, metadata.key, paramList, controller.constructor, // Pass controller constructor for metadata
+                    metadata);
+                    // Wrap handler with interceptor middleware if interceptors are defined
+                    const interceptors = this.extractInterceptors(controller.constructor, metadata.key);
+                    if (interceptors.length > 0 && this.isInterceptorSystemReady()) {
+                        handler = this.wrapWithInterceptors(handler, controller.constructor, metadata.key);
+                    }
                     const routeMiddleware = this.resolveMiddleware(...metadata.middleware);
-                    this._router[metadata.method](`${controllerMetadata.path}${metadata.path}`, ...controllerMiddleware, ...routeMiddleware, handler);
+                    // Determine version: method-level version overrides controller-level version
+                    const version = metadata.version || controllerMetadata.version;
+                    const versionPrefix = version ? `/${version}` : "";
+                    // Properly join paths to avoid issues like "/api" + "users" = "/apiusers"
+                    const routePath = joinRoutePaths(versionPrefix, controllerMetadata.path, metadata.path);
+                    const fullPath = joinRoutePaths(this._routingConfig.rootPath, routePath);
+                    // Register route for suggestions system (synchronous approach)
+                    try {
+                        const module = getRouteRegistryModule();
+                        if (module && module.getRouteRegistry) {
+                            const registry = module.getRouteRegistry();
+                            registry.register(metadata.method, routePath, fullPath);
+                        }
+                    }
+                    catch {
+                        // Route registry not available, skip registration (non-critical)
+                        // This allows the app to work even if suggestions module isn't available
+                    }
+                    this._router[metadata.method](routePath, ...controllerMiddleware, ...routeMiddleware, handler);
                 });
             }
         });
         this._app.use(this._routingConfig.rootPath, this._router);
     }
+    /**
+     * Initialize the interceptor system by binding required components
+     * @private
+     */
+    initializeInterceptorSystem() {
+        try {
+            // Bind InterceptorRegistry if not already bound
+            if (!this._container.isBound(core_1.InterceptorRegistry)) {
+                this._container.bind(core_1.InterceptorRegistry).toSelf().inSingletonScope();
+            }
+            // Bind InterceptorExecutor if not already bound
+            if (!this._container.isBound(core_1.InterceptorExecutor)) {
+                this._container.bind(core_1.InterceptorExecutor).toSelf().inSingletonScope();
+            }
+            // Bind InterceptorMiddleware if not already bound
+            if (!this._container.isBound(interceptor_middleware_js_1.InterceptorMiddleware)) {
+                this._container.bind(interceptor_middleware_js_1.InterceptorMiddleware).toSelf().inSingletonScope();
+            }
+        }
+        catch {
+            // Interceptor system initialization failed (non-critical)
+            // Routes will work without interceptors
+        }
+    }
+    /**
+     * Check if the interceptor system is properly initialized
+     * @private
+     */
+    isInterceptorSystemReady() {
+        try {
+            return (this._container.isBound(core_1.InterceptorExecutor) &&
+                this._container.isBound(interceptor_middleware_js_1.InterceptorMiddleware));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Extract interceptors from controller and method metadata
+     * @private
+     */
+    extractInterceptors(controllerClass, methodName) {
+        try {
+            // Get controller-level interceptors
+            const controllerInterceptors = Reflect.getMetadata(core_1.INTERCEPTOR_METADATA_KEY.controllerInterceptors, controllerClass) || [];
+            // Get method-level interceptors
+            const methodInterceptors = Reflect.getMetadata(core_1.INTERCEPTOR_METADATA_KEY.methodInterceptors, controllerClass, methodName) || [];
+            // Combine: controller + method level
+            return [...controllerInterceptors, ...methodInterceptors];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Wrap a handler with interceptor middleware
+     * @private
+     */
+    wrapWithInterceptors(handler, controllerClass, methodName) {
+        try {
+            const interceptorMiddleware = (0, interceptor_middleware_js_1.createInterceptorMiddleware)(this._container, controllerClass, methodName, handler);
+            return interceptorMiddleware;
+        }
+        catch {
+            // Fall back to original handler if interceptor wrapping fails
+            return handler;
+        }
+    }
+    /**
+     * Checks if a middleware item is a class constructor (not an instance).
+     * Handles classes that extend ExpressoMiddleware (which has abstract use method).
+     * Note: Abstract methods don't exist at runtime, so we check for concrete implementations.
+     */
+    isMiddlewareClass(middlewareItem) {
+        // Must be a function (class constructor)
+        if (typeof middlewareItem !== "function") {
+            return false;
+        }
+        // Must not be a conditional or composed middleware config
+        if ((0, conditional_middleware_js_1.isConditionalMiddleware)(middlewareItem) || (0, middleware_composition_js_1.isComposedMiddleware)(middlewareItem)) {
+            return false;
+        }
+        // Must have a prototype
+        if (middlewareItem.prototype === undefined) {
+            return false;
+        }
+        // Check if it has a 'use' method in its prototype
+        // Classes that extend ExpressoMiddleware must implement the abstract use() method
+        // so it will be in the prototype at runtime
+        const prototype = middlewareItem.prototype;
+        // Check for 'use' method directly in prototype (most common case)
+        if ("use" in prototype && typeof prototype.use === "function") {
+            return true;
+        }
+        // Also check prototype chain in case use() is defined in a parent class
+        // This handles cases where the method might be inherited (optimized: only if not found directly)
+        let currentPrototype = Object.getPrototypeOf(prototype);
+        while (currentPrototype && currentPrototype !== Object.prototype) {
+            if ("use" in currentPrototype &&
+                typeof currentPrototype.use === "function") {
+                return true;
+            }
+            currentPrototype = Object.getPrototypeOf(currentPrototype);
+        }
+        return false;
+    }
     isExpressoMiddleware(middlewareItem) {
         return (typeof middlewareItem === "object" &&
+            middlewareItem !== null &&
             "use" in middlewareItem &&
-            typeof middlewareItem.use === "function");
+            typeof middlewareItem.use === "function" &&
+            !(0, conditional_middleware_js_1.isConditionalMiddleware)(middlewareItem) &&
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            !this.isMiddlewareClass(middlewareItem));
     }
     resolveMiddleware(...middleware) {
         return middleware.map((middlewareItem) => {
+            // Handle composed middleware first (Phase 3: Middleware Composition)
+            if ((0, middleware_composition_js_1.isComposedMiddleware)(middlewareItem)) {
+                return this.createComposedMiddlewareHandler(middlewareItem);
+            }
+            // Handle conditional middleware
+            if ((0, conditional_middleware_js_1.isConditionalMiddleware)(middlewareItem)) {
+                return this.createConditionalMiddlewareHandler(middlewareItem);
+            }
+            // Handle class constructors (Phase 2: Class Reference Support)
+            if (this.isMiddlewareClass(middlewareItem)) {
+                return this.createLazyMiddlewareHandler(middlewareItem);
+            }
             if (this.isExpressoMiddleware(middlewareItem)) {
                 return (req, res, next) => {
                     middlewareItem.use(req, res, next);
@@ -156,7 +483,7 @@ class InversifyExpressServer {
                 return middlewareItem;
             }
             const middlewareInstance = this._container.get(middlewareItem);
-            if (middlewareInstance instanceof base_middleware_1.BaseMiddleware) {
+            if (middlewareInstance instanceof base_middleware_js_1.BaseMiddleware) {
                 return (req, res, next) => {
                     const mReq = this._container.get(middlewareItem);
                     mReq.httpContext = this._getHttpContext(req);
@@ -166,6 +493,239 @@ class InversifyExpressServer {
             return middlewareInstance;
         });
     }
+    /**
+     * Creates a lazy middleware handler for class constructors.
+     * Supports both container-bound middleware (via @provide()) and direct instantiation.
+     *
+     * Performance: Instances are created per-request to support request-scoped state.
+     * For better performance with stateless middleware, use container-bound middleware
+     * with proper scoping (singleton/request scope) via @provide().
+     *
+     * Note: If container resolution fails (e.g., base class missing @injectable()),
+     * falls back to direct instantiation for backward compatibility.
+     */
+    createLazyMiddlewareHandler(MiddlewareClass) {
+        // Pre-check if container-bound at route registration time (performance optimization)
+        const isContainerBound = this._container.isBound(MiddlewareClass);
+        let containerResolutionFailed = false;
+        // Cache instance for non-container-bound middleware (singleton per handler)
+        // Container-bound middleware relies on container scoping (singleton/request scope)
+        let cachedInstance;
+        return (req, res, next) => {
+            try {
+                let instance;
+                // Try container resolution first if bound and not previously failed
+                if (isContainerBound && !containerResolutionFailed) {
+                    try {
+                        // Resolve from container (supports DI, scoping, etc.)
+                        // Container handles singleton/request scope automatically
+                        instance = this._container.get(MiddlewareClass);
+                    }
+                    catch (containerError) {
+                        // Container resolution failed (e.g., base class missing @injectable())
+                        // Mark as failed and fall back to direct instantiation
+                        containerResolutionFailed = true;
+                        try {
+                            // Create and cache instance if not already cached
+                            if (!cachedInstance) {
+                                cachedInstance = new MiddlewareClass();
+                            }
+                            instance = cachedInstance;
+                        }
+                        catch (instantiationError) {
+                            next(instantiationError);
+                            return;
+                        }
+                    }
+                }
+                else {
+                    // Create instance directly (no DI support or container not available)
+                    // Cache instance for reuse across requests (singleton per handler)
+                    if (!cachedInstance) {
+                        try {
+                            cachedInstance = new MiddlewareClass();
+                        }
+                        catch (instantiationError) {
+                            next(instantiationError);
+                            return;
+                        }
+                    }
+                    instance = cachedInstance;
+                }
+                // Execute middleware (supports both sync and async)
+                // The middleware's use() method should call next() itself
+                // We pass the next function directly - when middleware calls next(),
+                // it will continue the Express middleware chain (or the composition chain)
+                try {
+                    const result = instance.use(req, res, next);
+                    // Handle async middleware that returns a Promise
+                    // If it returns a Promise, return it so the chain can await it
+                    if (result !== undefined && result !== null) {
+                        const resultObj = result;
+                        if (typeof resultObj === "object" &&
+                            resultObj !== null &&
+                            "then" in resultObj &&
+                            typeof resultObj.then === "function") {
+                            // Return the Promise so the chain can await it
+                            // The middleware should have already called next(), but the chain
+                            // will wait for the Promise to resolve/reject
+                            return result.catch((error) => {
+                                // If the Promise rejects and next() wasn't called with error, call it now
+                                next(error);
+                            });
+                        }
+                    }
+                    // Synchronous middleware - returns void, chain relies on next() being called
+                }
+                catch (useError) {
+                    // If use() throws synchronously, pass error to next()
+                    next(useError);
+                }
+            }
+            catch (error) {
+                // Catch any other errors
+                next(error);
+            }
+        };
+    }
+    /**
+     * Creates a request handler for conditional middleware.
+     * Evaluates the condition and executes the wrapped middleware if condition is true.
+     */
+    createConditionalMiddlewareHandler(config) {
+        // Resolve the wrapped middleware once (at route registration time)
+        const wrappedMiddlewareHandlers = this.resolveMiddleware(config.middleware);
+        return async (req, res, next) => {
+            try {
+                // Evaluate the condition (supports both sync and async)
+                const conditionResult = await config.condition(req);
+                // Determine if middleware should execute based on condition and skipOnFalse flag
+                const shouldExecute = config.skipOnFalse !== false ? conditionResult : !conditionResult;
+                if (shouldExecute) {
+                    // Condition met, execute the wrapped middleware
+                    // The wrapped middleware handlers are already Express RequestHandlers,
+                    // so we can execute them directly. They will call next() when done,
+                    // which will continue to the next middleware in the route.
+                    if (wrappedMiddlewareHandlers.length === 0) {
+                        // No middleware to execute, just continue
+                        next();
+                    }
+                    else if (wrappedMiddlewareHandlers.length === 1) {
+                        // Single middleware, execute it directly
+                        wrappedMiddlewareHandlers[0](req, res, next);
+                    }
+                    else {
+                        // Multiple middleware, execute them sequentially
+                        await this.executeMiddlewareChain(wrappedMiddlewareHandlers, req, res, next);
+                    }
+                }
+                else {
+                    // Condition not met, skip middleware and continue to next middleware in route
+                    next();
+                }
+            }
+            catch (error) {
+                // If condition evaluation throws, pass error to error handler
+                next(error);
+            }
+        };
+    }
+    /**
+     * Creates a request handler for composed middleware (Phase 3: Middleware Composition).
+     * Executes all middleware in the composition sequentially.
+     * Both 'combine' and 'sequence' types behave the same way - they execute middleware
+     * sequentially and propagate errors normally (Express handles errors via next(error)).
+     *
+     * @param config - ComposedMiddlewareConfig containing the middleware array and type
+     * @returns Express RequestHandler
+     */
+    createComposedMiddlewareHandler(config) {
+        // Resolve all middleware in the composition to Express RequestHandlers
+        const resolvedHandlers = config.middleware.flatMap((mw) => this.resolveMiddleware(mw));
+        return async (req, res, next) => {
+            try {
+                if (resolvedHandlers.length === 0) {
+                    // No middleware to execute, just continue
+                    next();
+                    return;
+                }
+                // Execute all middleware sequentially
+                // Both 'combine' and 'sequence' use the same execution logic
+                // Express's error handling (via next(error)) naturally stops execution
+                await this.executeMiddlewareChain(resolvedHandlers, req, res, next);
+            }
+            catch (error) {
+                // If execution throws an error, pass it to Express error handler
+                next(error);
+            }
+        };
+    }
+    /**
+     * Executes a chain of middleware handlers sequentially.
+     * Each middleware calls next() to proceed to the next one.
+     * Handles both synchronous and asynchronous middleware.
+     */
+    executeMiddlewareChain(handlers, req, res, next) {
+        return new Promise((resolve, reject) => {
+            let index = 0;
+            const runNext = (err) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                if (index >= handlers.length) {
+                    // All middleware executed successfully, call Express next() to continue to route handler
+                    next();
+                    resolve();
+                    return;
+                }
+                const handler = handlers[index++];
+                try {
+                    // Execute the handler
+                    // Express middleware handlers can:
+                    // 1. Call next() synchronously
+                    // 2. Call next() asynchronously
+                    // 3. Return a Promise
+                    // 4. Return nothing (void)
+                    const result = handler(req, res, (err) => {
+                        if (err) {
+                            reject(err);
+                        }
+                        else {
+                            // Handler called next() successfully, proceed to next middleware
+                            runNext();
+                        }
+                    });
+                    // If handler returns a Promise, wait for it
+                    // Note: Even if handler returns a Promise, it should still call next()
+                    // But we handle the Promise in case it doesn't
+                    // Check if result exists and is a Promise-like object (thenable)
+                    if (result !== undefined && result !== null) {
+                        const resultObj = result;
+                        if (typeof resultObj === "object" &&
+                            resultObj !== null &&
+                            "then" in resultObj &&
+                            typeof resultObj.then === "function") {
+                            result
+                                .then(() => {
+                                // If Promise resolves and next wasn't called, proceed
+                                if (index <= handlers.length) {
+                                    runNext();
+                                }
+                            })
+                                .catch(reject);
+                        }
+                    }
+                    // If handler doesn't return a Promise and doesn't call next(),
+                    // we rely on the handler to call next() itself
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            runNext();
+        });
+    }
     copyHeadersTo(headers, target) {
         for (const name of Object.keys(headers)) {
             const headerValue = headers[name];
@@ -186,43 +746,245 @@ class InversifyExpressServer {
             res.sendStatus(message.statusCode);
         }
     }
-    handlerFactory(controllerName, key, parameterMetadata) {
-        return async (req, res, next) => {
+    handlerFactory(controllerName, key, parameterMetadata, controllerConstructor, methodMetadata) {
+        // Extract guards from controller and method metadata
+        const controllerGuards = controllerConstructor
+            ? (0, guard_utils_js_1.getControllerGuards)(controllerConstructor)
+            : [];
+        const methodGuards = controllerConstructor ? (0, guard_utils_js_1.getMethodGuards)(controllerConstructor, key) : [];
+        const allGuards = [...controllerGuards, ...methodGuards];
+        // Create guard middleware if guards exist
+        let guardMiddleware = null;
+        if (allGuards.length > 0) {
             try {
-                const args = this.extractParameters(req, res, next, parameterMetadata);
-                const httpContext = this._getHttpContext(req);
-                httpContext.container.bind(constants_1.TYPE.HttpContext).toConstantValue(httpContext);
-                // invoke controller's action
-                const controller = httpContext.container.getNamed(constants_1.TYPE.Controller, controllerName);
-                const value = await controller[key](...args);
-                const { template, defaultData } = (0, decorators_1.getRenderMetadata)(controller, key);
-                if (template) {
-                    const data = value || defaultData || {};
-                    res.render(template, data);
+                // Check if guard system is initialized (use class identifiers, not strings)
+                if (this._container.isBound(core_1.GuardExecutor) &&
+                    this._container.isBound(guard_context_factory_js_1.GuardContextFactory) &&
+                    this._container.isBound(guard_middleware_js_1.GuardMiddleware)) {
+                    const guardMiddlewareInstance = this._container.get(guard_middleware_js_1.GuardMiddleware);
+                    guardMiddleware = guardMiddlewareInstance.execute;
                 }
-                else if (value instanceof httpResponseMessage_1.HttpResponseMessage) {
-                    await this.handleHttpResponseMessage(value, res);
+            }
+            catch (error) {
+                // Guard system not initialized, continue without guards
+                console.error("[Guard System] Failed to initialize:", error);
+            }
+        }
+        // Create handler function
+        const handler = async (req, res, next) => {
+            try {
+                // Attach controller and method metadata to request for exception handler middleware
+                // This provides a reliable fallback if route stack extraction fails
+                if (controllerConstructor) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsController = controllerConstructor;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsMethod = key;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsControllerName = controllerName;
+                    // Attach guards to request for guard middleware
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsControllerGuards = controllerGuards;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsMethodGuards = methodGuards;
                 }
-                else if ((0, utils_1.instanceOfIHttpActionResult)(value)) {
-                    const httpResponseMessage = await value.executeAsync();
-                    await this.handleHttpResponseMessage(httpResponseMessage, res);
+                // Execute guard middleware if guards exist
+                if (guardMiddleware && allGuards.length > 0) {
+                    // Express 5 typings expect the handler to return `void`. We cannot
+                    // `return` the call because the express handler signature is
+                    // `(req, res, next) => void | Promise<void>` in v5; chaining the
+                    // expression off `return` makes TS infer `unknown`. Invoke it
+                    // for-effect and return.
+                    guardMiddleware(req, res, async (err) => {
+                        if (err) {
+                            next(err);
+                            return;
+                        }
+                        // Guards passed, continue to route handler
+                        await this.executeRouteHandler(req, res, next, controllerName, key, parameterMetadata, controllerConstructor);
+                    });
+                    return;
                 }
-                else if (value instanceof Function) {
-                    value();
+                // No guards, execute route handler directly
+                await this.executeRouteHandler(req, res, next, controllerName, key, parameterMetadata, controllerConstructor);
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+        return handler;
+    }
+    async executeRouteHandler(req, res, next, controllerName, key, parameterMetadata, controllerConstructor) {
+        // Get request ID for flow tracking
+        const requestContext = core_1.ContextManager.getCurrentContext();
+        const requestId = requestContext?.requestId;
+        const flowTracker = requestId ? (0, core_1.findFlowTracker)(requestId) : undefined;
+        const controllerStepName = `${controllerName}.${key}`;
+        try {
+            let args = this.extractParameters(req, res, next, parameterMetadata);
+            const httpContext = this._getHttpContext(req);
+            httpContext.container.bind(constants_js_1.TYPE.HttpContext).toConstantValue(httpContext);
+            // Validate parameters if validation service is enabled
+            const validationService = this.getValidationService();
+            if (validationService?.isEnabled() && controllerConstructor) {
+                // Check if there are actually validation metadata (has @validatedBody, @validatedQuery, etc.)
+                const validationMetadata = (0, validation_decorators_js_1.getValidationMetadata)(controllerConstructor, key);
+                const hasValidatedParams = validationMetadata.length > 0;
+                if (hasValidatedParams) {
+                    // Start validation step only if there are validated parameters
+                    if (flowTracker?.isEnabled()) {
+                        flowTracker.startStep("validation", `Validation: ${controllerName}.${key}`);
+                    }
+                    const validatedArgs = await validationService.validateParameters(req, res, controllerConstructor, key, args);
+                    if (validatedArgs === null) {
+                        // Validation failed, response already sent
+                        // Create a validation error to store on request
+                        const validationError = new Error("Validation failed");
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        req.__expressotsFlowError = validationError;
+                        if (flowTracker?.isEnabled()) {
+                            flowTracker.failStep(validationError);
+                        }
+                        return;
+                    }
+                    // End validation step
+                    if (flowTracker?.isEnabled()) {
+                        flowTracker.endStep("success");
+                    }
+                    args = validatedArgs;
                 }
-                else if (!res.headersSent) {
-                    if (value !== undefined) {
-                        res.send(value);
+                else {
+                    // No validation metadata, but validation service might still run smart detection
+                    // Only track if smart detection actually finds something to validate
+                    const validatedArgs = await validationService.validateParameters(req, res, controllerConstructor, key, args);
+                    if (validatedArgs === null) {
+                        // Smart detection found validation errors
+                        return;
                     }
+                    args = validatedArgs;
                 }
             }
-            catch (err) {
-                next(err);
+            // Start controller step
+            if (flowTracker?.isEnabled()) {
+                flowTracker.startStep("controller", controllerStepName, {
+                    controller: controllerName,
+                    method: key,
+                });
             }
-        };
+            // invoke controller's action
+            const controller = httpContext.container.getNamed(constants_js_1.TYPE.Controller, controllerName);
+            const value = await controller[key](...args);
+            // End controller step
+            if (flowTracker?.isEnabled()) {
+                flowTracker.endStep("success");
+            }
+            const { template, defaultData } = (0, decorators_js_1.getRenderMetadata)(controller, key);
+            if (template) {
+                const data = value || defaultData || {};
+                res.render(template, data);
+            }
+            else if (value instanceof httpResponseMessage_js_1.HttpResponseMessage) {
+                await this.handleHttpResponseMessage(value, res);
+            }
+            else if ((0, utils_js_1.instanceOfIHttpActionResult)(value)) {
+                const httpResponseMessage = await value.executeAsync();
+                await this.handleHttpResponseMessage(httpResponseMessage, res);
+            }
+            else if (value instanceof Function) {
+                value();
+            }
+            else if (!res.headersSent) {
+                // Smart response handling: Auto-404 for GET requests returning null/undefined
+                // This is a common pattern where null means "resource not found"
+                if (value === null || value === undefined) {
+                    const method = req.method.toUpperCase();
+                    // For GET requests, null/undefined typically means "not found"
+                    // For DELETE requests, undefined means "successfully deleted" (204 No Content is already set)
+                    if (method === "GET") {
+                        // Extract resource info from path for helpful error message
+                        const pathParts = req.path.split("/").filter(Boolean);
+                        const resource = pathParts[pathParts.length - 2] || "Resource";
+                        // Express 5's path-to-regexp v8 widens param values to
+                        // `string | string[]` because array-style params are now first
+                        // class. Coerce to string for the NotFoundError signature.
+                        const rawId = req.params?.id ?? pathParts[pathParts.length - 1];
+                        const id = Array.isArray(rawId) ? rawId.join("/") : rawId;
+                        throw new core_1.NotFoundError(resource, id);
+                    }
+                    // For other methods (DELETE, PUT, PATCH), undefined is valid (204 No Content)
+                    // The HttpStatusCodeMiddleware already sets appropriate status codes
+                    if (method !== "DELETE" && method !== "PUT" && method !== "PATCH") {
+                        // For POST or other methods with null/undefined, send empty response
+                        res.end();
+                    }
+                    // For DELETE/PUT/PATCH, the middleware already set 204, just end the response
+                    else {
+                        res.end();
+                    }
+                }
+                else {
+                    // Try content negotiation if enabled
+                    const cnMetadata = (0, utils_js_1.getContentNegotiationMetadata)(controller, key);
+                    const contentNegotiationService = this.getContentNegotiationService();
+                    if (contentNegotiationService?.isEnabled()) {
+                        const handled = await contentNegotiationService.handleResponse(req, res, value, cnMetadata.accept || cnMetadata.produces);
+                        if (handled) {
+                            return; // Response already sent
+                        }
+                    }
+                    // Fallback to default behavior (backward compatible)
+                    res.send(value);
+                }
+            }
+        }
+        catch (err) {
+            // Store error on request for flow tracking
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            req.__expressotsFlowError = err instanceof Error ? err : new Error(String(err));
+            // End controller step with failure if not already ended
+            if (flowTracker?.isEnabled()) {
+                const currentFlow = flowTracker.getFlow();
+                const lastStep = currentFlow.steps[currentFlow.steps.length - 1];
+                if (lastStep && lastStep.name === controllerStepName && lastStep.status === "success") {
+                    // Step was already ended, don't end again
+                }
+                else {
+                    flowTracker.failStep(err instanceof Error ? err : undefined);
+                }
+            }
+            next(err);
+        }
     }
     _getHttpContext(req) {
-        return Reflect.getMetadata(constants_1.METADATA_KEY.httpContext, req);
+        return (0, http_context_store_js_1.getHttpContext)(req);
+    }
+    /**
+     * Sets the content negotiation service instance.
+     * @param service - Content negotiation service instance
+     */
+    setContentNegotiationService(service) {
+        this._contentNegotiationService = service;
+    }
+    /**
+     * Gets the content negotiation service if available.
+     * @returns Content negotiation service or undefined
+     */
+    getContentNegotiationService() {
+        return this._contentNegotiationService;
+    }
+    /**
+     * Sets the validation service instance.
+     * @param service - Validation service instance
+     */
+    setValidationService(service) {
+        this._validationService = service;
+    }
+    /**
+     * Gets the validation service if available.
+     * @returns Validation service or undefined
+     */
+    getValidationService() {
+        return this._validationService;
     }
     async _createHttpContext(req, res, next) {
         const principal = await this._getCurrentUser(req, res, next);
@@ -236,8 +998,9 @@ class InversifyExpressServer {
         };
     }
     async _getCurrentUser(req, res, next) {
-        if (this._AuthProvider !== undefined) {
-            const authProvider = this._container.get(constants_1.TYPE.AuthProvider);
+        // Check if AuthProvider is available (either via constructor or bound via setupAuthorizationForExpress)
+        if (this._AuthProvider !== undefined || this._container.isBound(constants_js_1.TYPE.AuthProvider)) {
+            const authProvider = this._container.get(constants_js_1.TYPE.AuthProvider);
             return authProvider.getUser(req, res, next);
         }
         return Promise.resolve({
@@ -254,28 +1017,28 @@ class InversifyExpressServer {
         }
         params.forEach(({ type, index, parameterName, injectRoot }) => {
             switch (type) {
-                case constants_1.PARAMETER_TYPE.REQUEST:
+                case constants_js_1.PARAMETER_TYPE.REQUEST:
                     args[index] = req;
                     break;
-                case constants_1.PARAMETER_TYPE.NEXT:
+                case constants_js_1.PARAMETER_TYPE.NEXT:
                     args[index] = next;
                     break;
-                case constants_1.PARAMETER_TYPE.PARAMS:
+                case constants_js_1.PARAMETER_TYPE.PARAMS:
                     args[index] = this.getParam(req, "params", injectRoot, parameterName);
                     break;
-                case constants_1.PARAMETER_TYPE.QUERY:
+                case constants_js_1.PARAMETER_TYPE.QUERY:
                     args[index] = this.getParam(req, "query", injectRoot, parameterName);
                     break;
-                case constants_1.PARAMETER_TYPE.BODY:
+                case constants_js_1.PARAMETER_TYPE.BODY:
                     args[index] = req.body;
                     break;
-                case constants_1.PARAMETER_TYPE.HEADERS:
+                case constants_js_1.PARAMETER_TYPE.HEADERS:
                     args[index] = this.getParam(req, "headers", injectRoot, parameterName);
                     break;
-                case constants_1.PARAMETER_TYPE.COOKIES:
+                case constants_js_1.PARAMETER_TYPE.COOKIES:
                     args[index] = this.getParam(req, "cookies", injectRoot, parameterName);
                     break;
-                case constants_1.PARAMETER_TYPE.PRINCIPAL:
+                case constants_js_1.PARAMETER_TYPE.PRINCIPAL:
                     args[index] = this._getPrincipal(req);
                     break;
                 default: