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

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.principal = exports.next = exports.cookies = exports.headers = exports.body = exports.query = exports.param = exports.response = exports.request = exports.injectHttpContext = void 0;
 exports.controller = controller;
 exports.Http = Http;
+exports.Version = Version;
 exports.All = All;
 exports.Get = Get;
 exports.Post = Post;
@@ -17,10 +18,14 @@ exports.getRenderMetadata = getRenderMetadata;
 exports.FileUpload = FileUpload;
 require("reflect-metadata");
 const core_1 = require("@expressots/core");
-const constants_1 = require("./constants");
-const resolver_multer_1 = require("./resolver-multer");
+const constants_js_1 = require("./constants.js");
+const resolver_multer_js_1 = require("./resolver-multer.js");
 const core_2 = require("@expressots/core");
-exports.injectHttpContext = (0, core_1.inject)(constants_1.TYPE.HttpContext);
+const path_pattern_compat_js_1 = require("./path-pattern-compat.js");
+// Explicit type annotation: without this, the inferred type pulls a
+// non-portable path from @expressots/core's internal decorator_utils,
+// which TS2742 rejects under NodeNext when emitting .d.ts files.
+exports.injectHttpContext = (0, core_1.inject)(constants_js_1.TYPE.HttpContext);
 /**
  * Controller decorator to define a new controller
  * @param path route path
@@ -29,29 +34,57 @@ exports.injectHttpContext = (0, core_1.inject)(constants_1.TYPE.HttpContext);
  */
 function controller(path, ...middleware) {
     return (target) => {
+        // Check for version metadata on the controller class
+        const controllerVersion = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.version, target);
+        // Translate any inline regex constraints in the controller-level
+        // prefix (`@controller("/users/:tenant(\\d+)")`) into a
+        // request-time validator. Keeps `@controller("/")` and the common
+        // case allocation-free.
+        const split = (0, path_pattern_compat_js_1.splitPathConstraints)(path);
+        const constraintMiddleware = (0, path_pattern_compat_js_1.createPathConstraintMiddleware)(split.constraints);
+        const effectivePath = split.path;
+        const effectiveMiddleware = constraintMiddleware
+            ? [constraintMiddleware, ...middleware]
+            : middleware;
         const currentMetadata = {
-            middleware,
-            path,
-            target,
+            middleware: effectiveMiddleware,
+            path: effectivePath,
+            target: target,
+            version: controllerVersion,
         };
-        const pathMetadata = Reflect.getOwnMetadata(constants_1.HTTP_CODE_METADATA.path, Reflect) || {};
-        const statusCodeMetadata = Reflect.getOwnMetadata(constants_1.HTTP_CODE_METADATA.statusCode, Reflect) || {};
-        const statusCodePathMapping = Reflect.getOwnMetadata(constants_1.HTTP_CODE_METADATA.httpCode, Reflect) || {};
+        const pathMetadata = Reflect.getOwnMetadata(constants_js_1.HTTP_CODE_METADATA.path, Reflect) || {};
+        const statusCodeMetadata = Reflect.getOwnMetadata(constants_js_1.HTTP_CODE_METADATA.statusCode, Reflect) || {};
+        const statusCodePathMapping = Reflect.getOwnMetadata(constants_js_1.HTTP_CODE_METADATA.httpCode, Reflect) || {};
         for (const key in pathMetadata) {
             if (statusCodeMetadata && statusCodeMetadata[key]) {
-                const realPath = pathMetadata[key]["path"] === "/" ? path : `${path}${pathMetadata[key]["path"]}`;
+                const methodPath = pathMetadata[key]["path"];
+                // Properly join controller and method paths. The controller
+                // path is the v8-cleaned `effectivePath` so the mapping key is
+                // consistent with what gets registered on Express.
+                let realPath;
+                if (methodPath === "/" || methodPath === "") {
+                    realPath = effectivePath;
+                }
+                else if (effectivePath === "/" || effectivePath === "") {
+                    realPath = methodPath.startsWith("/") ? methodPath : `/${methodPath}`;
+                }
+                else {
+                    const basePath = effectivePath.endsWith("/") ? effectivePath.slice(0, -1) : effectivePath;
+                    const subPath = methodPath.startsWith("/") ? methodPath : `/${methodPath}`;
+                    realPath = `${basePath}${subPath}`;
+                }
                 statusCodePathMapping[`${realPath}/-${pathMetadata[key]["method"].toLowerCase()}`] =
                     statusCodeMetadata[key];
             }
         }
-        Reflect.defineMetadata(constants_1.HTTP_CODE_METADATA.httpCode, statusCodePathMapping, Reflect);
-        Reflect.deleteMetadata(constants_1.HTTP_CODE_METADATA.statusCode, Reflect);
-        Reflect.deleteMetadata(constants_1.HTTP_CODE_METADATA.path, Reflect);
+        Reflect.defineMetadata(constants_js_1.HTTP_CODE_METADATA.httpCode, statusCodePathMapping, Reflect);
+        Reflect.deleteMetadata(constants_js_1.HTTP_CODE_METADATA.statusCode, Reflect);
+        Reflect.deleteMetadata(constants_js_1.HTTP_CODE_METADATA.path, Reflect);
         (0, core_1.decorate)((0, core_1.injectable)(), target);
-        Reflect.defineMetadata(constants_1.METADATA_KEY.controller, currentMetadata, target);
-        const previousMetadata = Reflect.getMetadata(constants_1.METADATA_KEY.controller, Reflect) || [];
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.controller, currentMetadata, target);
+        const previousMetadata = Reflect.getMetadata(constants_js_1.METADATA_KEY.controller, Reflect) || [];
         const newMetadata = [currentMetadata, ...previousMetadata];
-        Reflect.defineMetadata(constants_1.METADATA_KEY.controller, newMetadata, Reflect);
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.controller, newMetadata, Reflect);
     };
 }
 /**
@@ -70,7 +103,7 @@ function controller(path, ...middleware) {
 function Http(code) {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
     return (target, key, descriptor) => {
-        let httpCodeMetadata = Reflect.getOwnMetadata(constants_1.HTTP_CODE_METADATA.statusCode, Reflect);
+        let httpCodeMetadata = Reflect.getOwnMetadata(constants_js_1.HTTP_CODE_METADATA.statusCode, Reflect);
         if (httpCodeMetadata) {
             httpCodeMetadata[key] = code;
         }
@@ -78,7 +111,55 @@ function Http(code) {
             httpCodeMetadata = {};
             httpCodeMetadata[key] = code;
         }
-        Reflect.defineMetadata(constants_1.HTTP_CODE_METADATA.statusCode, httpCodeMetadata, Reflect);
+        Reflect.defineMetadata(constants_js_1.HTTP_CODE_METADATA.statusCode, httpCodeMetadata, Reflect);
+    };
+}
+/**
+ * Version decorator to define the API version for a controller or route method
+ * @param version API version (e.g., "1", "1.0", "v1", or 1)
+ * @returns ClassDecorator | MethodDecorator
+ * @example ```typescript
+ * @Version("1")
+ * @controller("/users")
+ * class UserController {}
+ *
+ * // Or at method level:
+ * @Version("2")
+ * @Get("/")
+ * getUsers() {
+ *   return "v2 users";
+ * }
+ * ```
+ * @public API
+ */
+function Version(version) {
+    // Normalize version to string format (e.g., "v1" or "1" -> "v1")
+    const normalizedVersion = typeof version === "number" ? `v${version}` : version.startsWith("v") ? version : `v${version}`;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (target, key, descriptor) => {
+        if (key !== undefined && descriptor !== undefined) {
+            // Method decorator - store version metadata for the method
+            // This will be read by enhancedHttpMethod/Method when they create metadata
+            Reflect.defineMetadata(constants_js_1.METADATA_KEY.version, normalizedVersion, target, key);
+            // Also update existing metadata if it exists
+            const metadataList = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controllerMethod, target.constructor);
+            if (metadataList) {
+                const methodMetadata = metadataList.find((m) => m.key === key);
+                if (methodMetadata) {
+                    methodMetadata.version = normalizedVersion;
+                }
+            }
+        }
+        else {
+            // Class decorator - store version metadata for the controller
+            // This will be read by controller decorator when it creates metadata
+            Reflect.defineMetadata(constants_js_1.METADATA_KEY.version, normalizedVersion, target);
+            // Also update existing metadata if it exists
+            const controllerMetadata = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controller, target);
+            if (controllerMetadata) {
+                controllerMetadata.version = normalizedVersion;
+            }
+        }
     };
 }
 /**
@@ -151,34 +232,47 @@ function Delete(path, ...middleware) {
  */
 function enhancedHttpMethod(method, path, ...middleware) {
     return (target, key) => {
+        // Check for version metadata on the method
+        const methodVersion = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.version, target, key);
+        // Express 5 / path-to-regexp v8 dropped inline regex constraints
+        // (`:id(\\d+)`). Split them out into a v8-compatible path + a
+        // request-time validator middleware so existing routes — and our
+        // {@link Patterns} / {@link pattern} public API — keep working.
+        const split = (0, path_pattern_compat_js_1.splitPathConstraints)(path);
+        const constraintMiddleware = (0, path_pattern_compat_js_1.createPathConstraintMiddleware)(split.constraints);
+        const effectivePath = split.path;
+        const effectiveMiddleware = constraintMiddleware
+            ? [constraintMiddleware, ...middleware]
+            : middleware;
         const metadata = {
-            key,
+            key: String(key),
             method,
-            middleware,
-            path,
-            target,
+            middleware: effectiveMiddleware,
+            path: effectivePath,
+            target: target,
+            version: methodVersion,
         };
         let metadataList = [];
-        let pathMetadata = Reflect.getOwnMetadata(constants_1.HTTP_CODE_METADATA.path, Reflect);
+        let pathMetadata = Reflect.getOwnMetadata(constants_js_1.HTTP_CODE_METADATA.path, Reflect);
         if (pathMetadata) {
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }
         else {
             pathMetadata = {};
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }
-        Reflect.defineMetadata(constants_1.HTTP_CODE_METADATA.path, pathMetadata, Reflect);
-        if (!Reflect.hasOwnMetadata(constants_1.METADATA_KEY.controllerMethod, target.constructor)) {
-            Reflect.defineMetadata(constants_1.METADATA_KEY.controllerMethod, metadataList, target.constructor);
+        Reflect.defineMetadata(constants_js_1.HTTP_CODE_METADATA.path, pathMetadata, Reflect);
+        if (!Reflect.hasOwnMetadata(constants_js_1.METADATA_KEY.controllerMethod, target.constructor)) {
+            Reflect.defineMetadata(constants_js_1.METADATA_KEY.controllerMethod, metadataList, target.constructor);
         }
         else {
-            metadataList = Reflect.getOwnMetadata(constants_1.METADATA_KEY.controllerMethod, target.constructor);
+            metadataList = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controllerMethod, target.constructor);
         }
         metadataList.push(metadata);
         const paramsInfo = Reflect.getMetadata("design:paramtypes", target, key) || [];
@@ -203,34 +297,44 @@ function enhancedHttpMethod(method, path, ...middleware) {
  */
 function Method(method, path, ...middleware) {
     return (target, key) => {
+        // Check for version metadata on the method
+        const methodVersion = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.version, target, key);
+        // Same path-to-regexp v8 compatibility shim as `enhancedHttpMethod`.
+        const split = (0, path_pattern_compat_js_1.splitPathConstraints)(path);
+        const constraintMiddleware = (0, path_pattern_compat_js_1.createPathConstraintMiddleware)(split.constraints);
+        const effectivePath = split.path;
+        const effectiveMiddleware = constraintMiddleware
+            ? [constraintMiddleware, ...middleware]
+            : middleware;
         const metadata = {
-            key,
+            key: String(key),
             method,
-            middleware,
-            path,
-            target,
+            middleware: effectiveMiddleware,
+            path: effectivePath,
+            target: target,
+            version: methodVersion,
         };
         let metadataList = [];
-        let pathMetadata = Reflect.getOwnMetadata(constants_1.HTTP_CODE_METADATA.path, Reflect);
+        let pathMetadata = Reflect.getOwnMetadata(constants_js_1.HTTP_CODE_METADATA.path, Reflect);
         if (pathMetadata) {
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }
         else {
             pathMetadata = {};
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }
-        Reflect.defineMetadata(constants_1.HTTP_CODE_METADATA.path, pathMetadata, Reflect);
-        if (!Reflect.hasOwnMetadata(constants_1.METADATA_KEY.controllerMethod, target.constructor)) {
-            Reflect.defineMetadata(constants_1.METADATA_KEY.controllerMethod, metadataList, target.constructor);
+        Reflect.defineMetadata(constants_js_1.HTTP_CODE_METADATA.path, pathMetadata, Reflect);
+        if (!Reflect.hasOwnMetadata(constants_js_1.METADATA_KEY.controllerMethod, target.constructor)) {
+            Reflect.defineMetadata(constants_js_1.METADATA_KEY.controllerMethod, metadataList, target.constructor);
         }
         else {
-            metadataList = Reflect.getOwnMetadata(constants_1.METADATA_KEY.controllerMethod, target.constructor);
+            metadataList = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controllerMethod, target.constructor);
         }
         metadataList.push(metadata);
     };
@@ -239,47 +343,47 @@ function Method(method, path, ...middleware) {
  * Parameter decorator to inject the request object
  * @returns ParameterDecorator
  */
-exports.request = paramDecoratorFactory(constants_1.PARAMETER_TYPE.REQUEST);
+exports.request = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.REQUEST);
 /**
  * Parameter decorator to inject the response object
  * @returns ParameterDecorator
  */
-exports.response = paramDecoratorFactory(constants_1.PARAMETER_TYPE.RESPONSE);
+exports.response = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.RESPONSE);
 /**
  * Parameter decorator to inject parameters from the route
  * @returns ParameterDecorator
  */
-exports.param = paramDecoratorFactory(constants_1.PARAMETER_TYPE.PARAMS);
+exports.param = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.PARAMS);
 /**
  * Parameter decorator to inject query parameters
  * @returns ParameterDecorator
  */
-exports.query = paramDecoratorFactory(constants_1.PARAMETER_TYPE.QUERY);
+exports.query = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.QUERY);
 /**
  * Parameter decorator to inject the request body
  * @returns ParameterDecorator
  */
-exports.body = paramDecoratorFactory(constants_1.PARAMETER_TYPE.BODY);
+exports.body = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.BODY);
 /**
  * Parameter decorator to inject the request headers
  * @returns ParameterDecorator
  */
-exports.headers = paramDecoratorFactory(constants_1.PARAMETER_TYPE.HEADERS);
+exports.headers = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.HEADERS);
 /**
  * Parameter decorator to inject the request cookies
  * @returns ParameterDecorator
  */
-exports.cookies = paramDecoratorFactory(constants_1.PARAMETER_TYPE.COOKIES);
+exports.cookies = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.COOKIES);
 /**
  * Parameter decorator next function
  * @returns ParameterDecorator
  */
-exports.next = paramDecoratorFactory(constants_1.PARAMETER_TYPE.NEXT);
+exports.next = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.NEXT);
 /**
  * Parameter decorator to inject the principal object obtained from AuthProvider
  * @returns ParameterDecorator
  */
-exports.principal = paramDecoratorFactory(constants_1.PARAMETER_TYPE.PRINCIPAL);
+exports.principal = paramDecoratorFactory(constants_js_1.PARAMETER_TYPE.PRINCIPAL);
 /**
  * Parameter decorator to inject the request user object
  * @returns ParameterDecorator
@@ -304,18 +408,18 @@ function params(type, parameterName) {
             parameterName,
             type,
         };
-        if (!Reflect.hasOwnMetadata(constants_1.METADATA_KEY.controllerParameter, target.constructor)) {
+        if (!Reflect.hasOwnMetadata(constants_js_1.METADATA_KEY.controllerParameter, target.constructor)) {
             parameterMetadataList.unshift(parameterMetadata);
         }
         else {
-            metadataList = Reflect.getOwnMetadata(constants_1.METADATA_KEY.controllerParameter, target.constructor);
+            metadataList = Reflect.getOwnMetadata(constants_js_1.METADATA_KEY.controllerParameter, target.constructor);
             if (metadataList[methodName]) {
                 parameterMetadataList = metadataList[methodName] || [];
             }
             parameterMetadataList.unshift(parameterMetadata);
         }
         metadataList[methodName] = parameterMetadataList;
-        Reflect.defineMetadata(constants_1.METADATA_KEY.controllerParameter, metadataList, target.constructor);
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.controllerParameter, metadataList, target.constructor);
     };
 }
 /**
@@ -328,11 +432,11 @@ function params(type, parameterName) {
 function Render(template, defaultData) {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     return (target, propertyKey, descriptor) => {
-        Reflect.defineMetadata(constants_1.RENDER_METADATA_KEY, { template, defaultData }, target, propertyKey);
+        Reflect.defineMetadata(constants_js_1.RENDER_METADATA_KEY, { template, defaultData }, target, propertyKey);
     };
 }
 function getRenderMetadata(target, propertyKey) {
-    return Reflect.getMetadata(constants_1.RENDER_METADATA_KEY, target, propertyKey) || {};
+    return Reflect.getMetadata(constants_js_1.RENDER_METADATA_KEY, target, propertyKey) || {};
 }
 /**
  * Converts a string value to the specified type.
@@ -365,15 +469,44 @@ function isResponse(obj) {
     return (typeof obj === "object" && obj !== null && "status" in obj && "json" in obj && "send" in obj);
 }
 /**
- * File upload decorator to handle file uploads
- * @param options
- * @param multerOptions
+ * File upload decorator to handle file uploads.
+ *
+ * This decorator integrates with the global upload configuration
+ * set via `Middleware.upload()` in app.ts. If global config exists,
+ * it will be used as defaults, with local options taking precedence.
+ *
+ * @param options - Field configuration (fieldName, maxCount, none, any)
+ * @param multerOptions - Optional multer options (overrides global config)
  * @default { none: true }
  * @returns MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * // In app.ts - configure globally (optional)
+ * this.Middleware.upload({
+ *   destination: './uploads',
+ *   limits: { fileSize: 10 * 1024 * 1024 }
+ * });
+ *
+ * // In controller - uses global config automatically
+ * @Post('avatar')
+ * @FileUpload({ fieldName: 'avatar' })
+ * uploadAvatar(req: Request) {
+ *   return req.file;
+ * }
+ *
+ * // Override global config for specific endpoint
+ * @Post('document')
+ * @FileUpload({ fieldName: 'doc' }, { limits: { fileSize: 50 * 1024 * 1024 } })
+ * uploadDocument(req: Request) {
+ *   return req.file;
+ * }
+ * ```
+ *
  * @public API
  */
 function FileUpload(options, multerOptions) {
-    const multer = (0, resolver_multer_1.packageResolver)("multer");
+    const multer = (0, resolver_multer_js_1.packageResolver)("multer");
     /* eslint-disable @typescript-eslint/no-explicit-any */
     let upload;
     let method = "none";
@@ -381,7 +514,40 @@ function FileUpload(options, multerOptions) {
         if (options === undefined) {
             options = { none: true };
         }
-        upload = multer(multerOptions);
+        // Get global upload configuration (set via Middleware.upload())
+        const globalConfig = (0, core_1.getGlobalUploadConfig)();
+        // Build final multer options, merging global config with local options
+        // Local options always take precedence over global config
+        const finalMulterOptions = {};
+        // Apply global config as defaults
+        if (globalConfig) {
+            if (globalConfig.destination) {
+                finalMulterOptions.dest = globalConfig.destination;
+            }
+            if (globalConfig.limits) {
+                finalMulterOptions.limits = globalConfig.limits;
+            }
+        }
+        // Apply local options (overrides global)
+        if (multerOptions) {
+            if (multerOptions.dest) {
+                finalMulterOptions.dest = multerOptions.dest;
+            }
+            if (multerOptions.limits) {
+                // Merge limits - local takes precedence
+                finalMulterOptions.limits = {
+                    ...finalMulterOptions.limits,
+                    ...multerOptions.limits,
+                };
+            }
+            if (multerOptions.storage) {
+                finalMulterOptions.storage = multerOptions.storage;
+            }
+            if (multerOptions.fileFilter) {
+                finalMulterOptions.fileFilter = multerOptions.fileFilter;
+            }
+        }
+        upload = multer(finalMulterOptions);
         method = inferMulterMethod(options);
     }
     return function (target, propertyKey, descriptor) {

package/lib/cjs/adapter-express/express-utils/exception-filter-decorators.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseFilters = exports.Catch = void 0;
+/**
+ * Re-export exception filter decorators from core for backward compatibility
+ * These decorators are now part of @expressots/core to avoid circular dependencies
+ * @public API
+ */
+var core_1 = require("@expressots/core");
+Object.defineProperty(exports, "Catch", { enumerable: true, get: function () { return core_1.Catch; } });
+Object.defineProperty(exports, "UseFilters", { enumerable: true, get: function () { return core_1.UseFilters; } });

package/lib/cjs/adapter-express/express-utils/guard-context-factory.js

@@ -0,0 +1,84 @@
+"use strict";
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardContextFactory = void 0;
+require("reflect-metadata");
+const core_1 = require("@expressots/core");
+const http_context_store_js_1 = require("./http-context-store.js");
+/**
+ * Factory for creating GuardContext from Express request/response
+ */
+let GuardContextFactory = class GuardContextFactory {
+    constructor(container, scopeExtractor) {
+        this.container = container;
+        this.scopeExtractor = scopeExtractor;
+    }
+    /**
+     * Create GuardContext from Express request/response
+     */
+    async create(req, res) {
+        // Get HttpContext (created by InversifyExpressServer's first middleware
+        // and stored in a per-request WeakMap; see http-context-store.ts).
+        const httpContext = (0, http_context_store_js_1.getHttpContext)(req);
+        if (!httpContext) {
+            throw new Error("HttpContext not found on request. Ensure InversifyExpressServer is properly configured.");
+        }
+        // Extract scope information
+        const scope = await this.scopeExtractor.extract(req);
+        // Extract route metadata
+        const route = {
+            controller: 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            req.__expressotsControllerName || "unknown",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            method: req.__expressotsMethod || "unknown",
+            path: req.path,
+            params: req.params,
+            query: req.query,
+        };
+        // Create guard context
+        // Note: httpContext.user is Principal from adapter-express, but GuardContext expects Principal from core
+        // They have the same structure, so this is compatible
+        // Note: httpContext.container is inversifyInterfaces.Container, but GuardContext expects Container from core
+        // They are compatible, so we cast it
+        const context = {
+            request: req,
+            response: res,
+            principal: httpContext.user, // Cast to core Principal type (same structure)
+            container: httpContext.container, // Request-scoped child container!
+            scope,
+            route,
+            getScoped: (identifier, scopeName) => {
+                // Resolve with scope awareness
+                // Note: scopeName is optional and can be used for custom scopes (e.g., tenant)
+                if (scopeName) {
+                    // For custom scopes, use named binding or scope registry
+                    // For now, fallback to regular get (can be enhanced later)
+                    return httpContext.container.get(identifier);
+                }
+                return httpContext.container.get(identifier);
+            },
+            getTenantId: () => scope.tenant,
+            getRequestId: () => scope.request,
+        };
+        return context;
+    }
+};
+exports.GuardContextFactory = GuardContextFactory;
+exports.GuardContextFactory = GuardContextFactory = __decorate([
+    (0, core_1.injectable)(),
+    __param(0, (0, core_1.inject)(core_1.Container)),
+    __param(1, (0, core_1.inject)("IScopeExtractor")),
+    __metadata("design:paramtypes", [Object, Object])
+], GuardContextFactory);

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

@@ -0,0 +1,115 @@
+"use strict";
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardMiddleware = void 0;
+const core_1 = require("@expressots/core");
+const core_2 = require("@expressots/core");
+const guard_context_factory_js_1 = require("./guard-context-factory.js");
+const core_3 = require("@expressots/core");
+/**
+ * Express middleware that executes guards before route handler
+ */
+let GuardMiddleware = class GuardMiddleware {
+    constructor(executor, contextFactory, container) {
+        this.executor = executor;
+        this.contextFactory = contextFactory;
+        this.container = container;
+        /**
+         * Express middleware function
+         */
+        this.execute = async (req, res, next) => {
+            // 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;
+            // Extract guards from route metadata (controller + method level)
+            const guards = this.extractGuards(req);
+            if (guards.length === 0) {
+                return next(); // No guards, proceed
+            }
+            // Start tracking guard execution
+            const guardNames = guards.map((g) => {
+                if (typeof g === "function") {
+                    return g.name || "UnknownGuard";
+                }
+                return g.constructor.name;
+            });
+            const guardStepName = `Guards: ${guardNames.join(", ")}`;
+            if (flowTracker?.isEnabled()) {
+                flowTracker.startStep("guard", guardStepName, {
+                    guardCount: guards.length,
+                    guardNames,
+                });
+            }
+            try {
+                // Create guard context
+                const context = await this.contextFactory.create(req, res);
+                // Execute guards
+                const result = await this.executor.execute(guards, context);
+                if (!result.allowed) {
+                    // End guard step with failure
+                    if (flowTracker?.isEnabled()) {
+                        flowTracker.failStep(result.error);
+                    }
+                    // Throw error to be caught by exception handler
+                    throw result.error || core_3.AppError.forbidden("Access denied");
+                }
+                // End guard step with success
+                if (flowTracker?.isEnabled()) {
+                    flowTracker.endStep("success");
+                }
+                next();
+            }
+            catch (error) {
+                // Store error on request for flow tracking
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                req.__expressotsFlowError =
+                    error instanceof Error ? error : new Error(String(error));
+                // End guard 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 === guardStepName && lastStep.status === "success") {
+                        // Step was already ended, don't end again
+                    }
+                    else {
+                        flowTracker.failStep(error instanceof Error ? error : undefined);
+                    }
+                }
+                next(error);
+            }
+        };
+    }
+    /**
+     * Extract guards from request metadata
+     * @private
+     */
+    extractGuards(req) {
+        // Extract from request metadata (set during route registration)
+        const reqWithGuards = req;
+        const controllerGuards = reqWithGuards.__expressotsControllerGuards || [];
+        const methodGuards = reqWithGuards.__expressotsMethodGuards || [];
+        return [...controllerGuards, ...methodGuards];
+    }
+};
+exports.GuardMiddleware = GuardMiddleware;
+exports.GuardMiddleware = GuardMiddleware = __decorate([
+    (0, core_1.injectable)(),
+    __param(0, (0, core_1.inject)(core_2.GuardExecutor)),
+    __param(1, (0, core_1.inject)(guard_context_factory_js_1.GuardContextFactory)),
+    __param(2, (0, core_1.inject)(core_1.Container)),
+    __metadata("design:paramtypes", [core_2.GuardExecutor,
+        guard_context_factory_js_1.GuardContextFactory,
+        core_1.Container])
+], GuardMiddleware);