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

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

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONDITIONAL_MIDDLEWARE_SYMBOL = void 0;
+exports.isConditionalMiddleware = isConditionalMiddleware;
+exports.when = when;
+exports.unless = unless;
+/**
+ * Symbol to identify conditional middleware configuration objects.
+ * Used internally for type checking.
+ */
+exports.CONDITIONAL_MIDDLEWARE_SYMBOL = Symbol("ConditionalMiddleware");
+/**
+ * Type guard to check if an object is a ConditionalMiddlewareConfig.
+ */
+function isConditionalMiddleware(item) {
+    return (typeof item === "object" &&
+        item !== null &&
+        "condition" in item &&
+        "middleware" in item &&
+        typeof item.condition === "function");
+}
+/**
+ * Creates a conditional middleware configuration that executes the middleware
+ * when the condition evaluates to true.
+ *
+ * @param condition - Function that receives the Request and returns boolean or Promise<boolean>
+ * @param middleware - The middleware to execute when condition is true
+ * @returns ConditionalMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Phase 2: Class reference support - no 'new' keyword needed
+ * @Get("/admin",
+ *   when(req => req.hostname.startsWith("admin."), AdminMiddleware),
+ *   AuthMiddleware
+ * )
+ * async adminHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async condition with class reference (Phase 2)
+ * @Get("/api",
+ *   when(async req => {
+ *     const user = await getUser(req);
+ *     return user.isAdmin;
+ *   }, AdminMiddleware)
+ * )
+ * async apiHandler() {}
+ * ```
+ */
+function when(condition, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+middleware) {
+    return {
+        condition,
+        middleware: middleware,
+        skipOnFalse: true,
+    };
+}
+/**
+ * Creates a conditional middleware configuration that executes the middleware
+ * when the condition evaluates to false (inverse of `when`).
+ *
+ * @param condition - Function that receives the Request and returns boolean or Promise<boolean>
+ * @param middleware - The middleware to execute when condition is false
+ * @returns ConditionalMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Phase 2: Class reference support - no 'new' keyword needed
+ * @Get("/public",
+ *   unless(req => req.headers.authorization, AuthMiddleware)
+ * )
+ * async publicHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Skip authentication for public routes (Phase 2: class reference)
+ * @Get("/health",
+ *   unless(req => req.path.startsWith("/api"), AuthMiddleware)
+ * )
+ * async healthCheck() {}
+ * ```
+ */
+function unless(condition, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+middleware) {
+    return {
+        condition: (req) => {
+            const result = condition(req);
+            // Invert the condition: if condition returns Promise, return inverted Promise
+            if (result instanceof Promise) {
+                return result.then((value) => !value);
+            }
+            return !result;
+        },
+        middleware: middleware,
+        skipOnFalse: true,
+    };
+}

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

@@ -6,11 +6,28 @@ exports.TYPE = {
     Controller: Symbol.for("Controller"),
     HttpContext: Symbol.for("HttpContext"),
 };
+// Import exception filter metadata keys from core to maintain compatibility
+const core_1 = require("@expressots/core");
 exports.METADATA_KEY = {
     controller: "inversify-express-utils:controller",
     controllerMethod: "inversify-express-utils:controller-method",
     controllerParameter: "inversify-express-utils:controller-parameter",
     httpContext: "inversify-express-utils:httpcontext",
+    version: "inversify-express-utils:version",
+    accept: "inversify-express-utils:accept",
+    consumes: "inversify-express-utils:consumes",
+    produces: "inversify-express-utils:produces",
+    csvOptions: "inversify-express-utils:csv-options",
+    xmlOptions: "inversify-express-utils:xml-options",
+    yamlOptions: "inversify-express-utils:yaml-options",
+    streamResponse: "inversify-express-utils:stream-response",
+    // Validation metadata
+    validationSchema: "inversify-express-utils:validation-schema",
+    validationOptions: "inversify-express-utils:validation-options",
+    // Re-export exception filter metadata keys from core for backward compatibility
+    exceptionFilter: core_1.EXCEPTION_FILTER_METADATA_KEY.exceptionFilter,
+    controllerExceptionFilters: core_1.EXCEPTION_FILTER_METADATA_KEY.controllerExceptionFilters,
+    methodExceptionFilters: core_1.EXCEPTION_FILTER_METADATA_KEY.methodExceptionFilters,
 };
 exports.HTTP_CODE_METADATA = {
     httpCode: "inversify-express-utils:httpcode",

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

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Accept = Accept;
+exports.Consumes = Consumes;
+exports.Produces = Produces;
+exports.CsvOptions = CsvOptions;
+exports.XmlOptions = XmlOptions;
+exports.YamlOptions = YamlOptions;
+exports.StreamResponse = StreamResponse;
+require("reflect-metadata");
+const constants_js_1 = require("./constants.js");
+/**
+ * Accept decorator to specify which content types this route accepts for responses.
+ * Used for content negotiation based on Accept header.
+ * @param contentTypes - Array of accepted content types (e.g., ["application/json", "application/xml"])
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @Accept("application/json", "application/xml")
+ * @Get("/users")
+ * getUsers() {
+ *   return [{ id: 1, name: "John" }];
+ * }
+ * ```
+ * @public API
+ */
+function Accept(...contentTypes) {
+    return (target, key) => {
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.accept, contentTypes, target, key);
+    };
+}
+/**
+ * Consumes decorator to specify which content types this route consumes for requests.
+ * Used for content negotiation based on Content-Type header.
+ * @param contentTypes - Array of consumed content types (e.g., ["application/json", "application/xml"])
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @Consumes("application/json", "application/xml")
+ * @Post("/users")
+ * createUser(@body() user: UserDto) {
+ *   return this.userService.create(user);
+ * }
+ * ```
+ * @public API
+ */
+function Consumes(...contentTypes) {
+    return (target, key) => {
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.consumes, contentTypes, target, key);
+    };
+}
+/**
+ * Produces decorator to specify which content types this route produces for responses.
+ * Alias for @Accept() decorator.
+ * @param contentTypes - Array of produced content types
+ * @returns MethodDecorator
+ * @public API
+ */
+function Produces(...contentTypes) {
+    return Accept(...contentTypes);
+}
+/**
+ * CsvOptions decorator to configure CSV formatting options for a route.
+ * @param options - CSV formatting options
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @CsvOptions({ fields: ["id", "name"], includeHeaders: true })
+ * @Get("/users")
+ * getUsers() {
+ *   return [{ id: 1, name: "John", email: "john@example.com" }];
+ * }
+ * ```
+ * @public API
+ */
+function CsvOptions(options) {
+    return (target, key) => {
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.csvOptions, options, target, key);
+    };
+}
+/**
+ * XmlOptions decorator to configure XML formatting options for a route.
+ * @param options - XML formatting options
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @XmlOptions({ rootElement: "users", itemElement: "user", prettyPrint: true })
+ * @Get("/users")
+ * getUsers() {
+ *   return [{ id: 1, name: "John" }];
+ * }
+ * ```
+ * @public API
+ */
+function XmlOptions(options) {
+    return (target, key) => {
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.xmlOptions, options, target, key);
+    };
+}
+/**
+ * YamlOptions decorator to configure YAML formatting options for a route.
+ * @param options - YAML formatting options
+ * @returns MethodDecorator
+ * @public API
+ */
+function YamlOptions(options) {
+    return (target, key) => {
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.yamlOptions, options, target, key);
+    };
+}
+/**
+ * StreamResponse decorator to indicate that the response should be streamed.
+ * Useful for large datasets.
+ * @returns MethodDecorator
+ * @example
+ * ```typescript
+ * @StreamResponse()
+ * @Get("/large-dataset")
+ * getLargeDataset() {
+ *   return this.dataService.streamLargeDataset(); // Returns async iterator
+ * }
+ * ```
+ * @public API
+ */
+function StreamResponse() {
+    return (target, key) => {
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.streamResponse, true, target, key);
+    };
+}

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,13 @@ 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);
+// 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 +33,46 @@ 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);
         const currentMetadata = {
             middleware,
             path,
-            target,
+            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
+                let realPath;
+                if (methodPath === "/" || methodPath === "") {
+                    realPath = path;
+                }
+                else if (path === "/" || path === "") {
+                    realPath = methodPath.startsWith("/") ? methodPath : `/${methodPath}`;
+                }
+                else {
+                    // Normalize: remove trailing slash from controller, ensure method has leading slash
+                    const basePath = path.endsWith("/") ? path.slice(0, -1) : path;
+                    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 +91,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 +99,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,15 +220,18 @@ 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);
         const metadata = {
-            key,
+            key: String(key),
             method,
             middleware,
             path,
-            target,
+            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,
@@ -173,12 +245,12 @@ function enhancedHttpMethod(method, path, ...middleware) {
                 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,15 +275,18 @@ 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);
         const metadata = {
-            key,
+            key: String(key),
             method,
             middleware,
             path,
-            target,
+            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,
@@ -225,12 +300,12 @@ function Method(method, path, ...middleware) {
                 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 +314,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 +379,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 +403,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 +440,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 +485,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; } });