@catbee/utils 0.0.8-rc.0 → 0.0.8-rc.2

package/build/esm/utils/decorators.utils.js

@@ -21,91 +21,153 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
-    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (g && (g = 0, op[0] && (_ = 0)), _) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+import 'reflect-metadata';
+import { getLogger } from './logger.utils';
+import { createFinalErrorResponse } from './response.utils';
+import { HttpStatusCodes } from './http-status-codes';
+import { rateLimit } from 'express-rate-limit';
+import { TTLCache } from './cache.utils';
+// Metadata keys
+const ROUTES_KEY = Symbol('routes');
+const MIDDLEWARE_KEY = Symbol('middlewares');
+const PARAMS_KEY = Symbol('params');
+const HTTP_CODE_KEY = Symbol('httpCode');
+const HEADER_KEY = Symbol('headers');
+const BEFORE_KEY = Symbol('before');
+const AFTER_KEY = Symbol('after');
+const ROLES_KEY = Symbol('roles');
+const REDIRECT_KEY = Symbol('redirect');
+const CACHE_KEY = Symbol('cache');
+const RATE_LIMIT_KEY = Symbol('rateLimit');
+const CONTENT_TYPE_KEY = Symbol('contentType');
+const VERSION_KEY = Symbol('version');
+const TIMEOUT_KEY = Symbol('timeout');
+const LOG_KEY = Symbol('log');
+/**
+ * RateLimiter cache that uses TTLCache for automatic TTL and LRU handling.
+ */
+class RateLimiterCache {
+    cache;
+    constructor(maxSize = 100, ttlMs = 5 * 60 * 1000) {
+        this.cache = new TTLCache({
+            maxSize,
+            ttlMs
+        });
     }
-};
-var __read = (this && this.__read) || function (o, n) {
-    var m = typeof Symbol === "function" && o[Symbol.iterator];
-    if (!m) return o;
-    var i = m.call(o), r, ar = [], e;
-    try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    generateKey(options) {
+        return `${options.max}:${options.windowMs}:${options.standardHeaders}:${options.legacyHeaders}`;
     }
-    catch (error) { e = { error: error }; }
-    finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
+    get(options) {
+        const key = this.generateKey(options);
+        const cached = this.cache.get(key);
+        if (cached) {
+            return cached.limiter;
         }
-        finally { if (e) throw e.error; }
+        // Create new limiter
+        const limiter = rateLimit({
+            ...options,
+            handler: (req, res) => {
+                const errorResponse = createFinalErrorResponse(req, HttpStatusCodes.TOO_MANY_REQUESTS, 'Too Many Requests');
+                res.status(HttpStatusCodes.TOO_MANY_REQUESTS).json(errorResponse);
+            }
+        });
+        // Store in cache
+        this.cache.set(key, {
+            limiter,
+            config: key
+        });
+        return limiter;
     }
-    return ar;
-};
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size();
+    }
+    destroy() {
+        this.cache.destroy();
+    }
+}
+// Global cache instance
+const rateLimiterCache = new RateLimiterCache();
+export class DIContainer {
+    instances = new Map();
+    constructing = new Map();
+    register(target) {
+        // Mark as injectable, but do not instantiate yet
+        if (!this.instances.has(target) && !this.constructing.has(target)) {
+            // No-op: instantiation is deferred until get()
         }
     }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
-var __values = (this && this.__values) || function(o) {
-    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
-    if (m) return m.call(o);
-    if (o && typeof o.length === "number") return {
-        next: function () {
-            if (o && i >= o.length) o = void 0;
-            return { value: o && o[i++], done: !o };
+    get(target) {
+        // Return existing instance if available
+        if (this.instances.has(target)) {
+            return this.instances.get(target);
+        }
+        // If currently constructing, return the proxy (for circular refs)
+        if (this.constructing.has(target)) {
+            return this.constructing.get(target);
         }
+        // Mark as constructing (for circular dependency support)
+        let proxy = {};
+        this.constructing.set(target, proxy);
+        // Resolve constructor dependencies
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target) || [];
+        const dependencies = paramTypes.map(dep => this.get(dep));
+        const instance = new target(...dependencies);
+        // Copy instance properties to proxy (for circular refs)
+        Object.assign(proxy, instance);
+        // Replace proxy with real instance
+        this.instances.set(target, proxy);
+        this.constructing.delete(target);
+        // Copy prototype (for instanceof checks)
+        Object.setPrototypeOf(proxy, target.prototype);
+        return proxy;
+    }
+    clear() {
+        this.instances.clear();
+        this.constructing.clear();
+    }
+}
+const diContainer = new DIContainer();
+function normalizeHeaderValue(value) {
+    if (typeof value === 'undefined')
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && value.every(item => typeof item === 'string')) {
+        return value;
+    }
+    return String(value);
+}
+/**
+ * Injectable decorator for marking classes as injectable.
+ *
+ * @returns Class decorator that marks a class as injectable and registers it with the DI container.
+ */
+export function Injectable() {
+    return target => {
+        Reflect.defineMetadata('injectable', true, target);
+        diContainer.register(target);
     };
-    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
-};
-import 'reflect-metadata';
-import { HttpStatusCodes } from './http-status-codes';
-import { ForbiddenException } from './exception.utils';
-// Metadata keys
-var ROUTES_KEY = Symbol('routes');
-var MIDDLEWARE_KEY = Symbol('middlewares');
-var PARAMS_KEY = Symbol('params');
-var HTTP_CODE_KEY = Symbol('httpCode');
-var HEADER_KEY = Symbol('headers');
-var BEFORE_KEY = Symbol('before');
-var AFTER_KEY = Symbol('after');
-var ROLES_KEY = Symbol('roles');
-var REDIRECT_KEY = Symbol('redirect');
+}
+/**
+ * Inject decorator for injecting dependencies into class properties.
+ *
+ * @param targetClass - The class to inject
+ * @returns Property decorator that injects the specified class into the property
+ */
+export function Inject(targetClass) {
+    return (target, propertyKey) => {
+        Object.defineProperty(target, propertyKey, {
+            get: function () {
+                return diContainer.get(targetClass);
+            },
+            enumerable: true,
+            configurable: true
+        });
+    };
+}
 /**
  * Factory function that creates HTTP method decorators.
  *
@@ -113,12 +175,12 @@ var REDIRECT_KEY = Symbol('redirect');
  * @returns A method decorator function
  */
 function createRouteDecorator(method) {
-    return function (path) {
-        return function (target, propertyKey, descriptor) {
-            var routes = Reflect.getMetadata(ROUTES_KEY, target.constructor) || [];
+    return (path) => {
+        return (target, propertyKey, descriptor) => {
+            const routes = Reflect.getMetadata(ROUTES_KEY, target.constructor) || [];
             routes.push({
-                path: path,
-                method: method,
+                path,
+                method,
                 handlerName: propertyKey
             });
             Reflect.defineMetadata(ROUTES_KEY, routes, target.constructor);
@@ -139,7 +201,7 @@ function createRouteDecorator(method) {
  * }
  * ```
  */
-export var Get = createRouteDecorator('get');
+export const Get = createRouteDecorator('get');
 /**
  * Decorator for POST HTTP method routes.
  *
@@ -154,56 +216,56 @@ export var Get = createRouteDecorator('get');
  * }
  * ```
  */
-export var Post = createRouteDecorator('post');
+export const Post = createRouteDecorator('post');
 /**
  * Decorator for PUT HTTP method routes.
  *
  * @param path - URL path for the route
  * @returns Method decorator
  */
-export var Put = createRouteDecorator('put');
+export const Put = createRouteDecorator('put');
 /**
  * Decorator for PATCH HTTP method routes.
  *
  * @param path - URL path for the route
  * @returns Method decorator
  */
-export var Patch = createRouteDecorator('patch');
+export const Patch = createRouteDecorator('patch');
 /**
  * Decorator for DELETE HTTP method routes.
  *
  * @param path - URL path for the route
  * @returns Method decorator
  */
-export var Delete = createRouteDecorator('delete');
+export const Delete = createRouteDecorator('delete');
 /**
  * Decorator for OPTIONS HTTP method routes.
  *
  * @param path - URL path for the route
  * @returns Method decorator
  */
-export var Options = createRouteDecorator('options');
+export const Options = createRouteDecorator('options');
 /**
  * Decorator for HEAD HTTP method routes.
  *
  * @param path - URL path for the route
  * @returns Method decorator
  */
-export var Head = createRouteDecorator('head');
+export const Head = createRouteDecorator('head');
 /**
  * Decorator for TRACE HTTP method routes.
  *
  * @param path - URL path for the route
  * @returns Method decorator
  */
-export var Trace = createRouteDecorator('trace');
+export const Trace = createRouteDecorator('trace');
 /**
  * Decorator for CONNECT HTTP method routes.
  *
  * @param path - URL path for the route
  * @returns Method decorator
  */
-export var Connect = createRouteDecorator('connect');
+export const Connect = createRouteDecorator('connect');
 /**
  * Decorator that marks a class as a controller with a base path.
  * Used as the entry point for routing configuration.
@@ -220,7 +282,7 @@ export var Connect = createRouteDecorator('connect');
  * ```
  */
 export function Controller(basePath) {
-    return function (target) {
+    return target => {
         Reflect.defineMetadata('basePath', basePath, target);
     };
 }
@@ -240,14 +302,10 @@ export function Controller(basePath) {
  * }
  * ```
  */
-export function Use() {
-    var middlewares = [];
-    for (var _i = 0; _i < arguments.length; _i++) {
-        middlewares[_i] = arguments[_i];
-    }
-    return function (target, propertyKey, _descriptor) {
-        var existing = Reflect.getMetadata(MIDDLEWARE_KEY, target, propertyKey) || [];
-        Reflect.defineMetadata(MIDDLEWARE_KEY, __spreadArray(__spreadArray([], __read(existing), false), __read(middlewares), false), target, propertyKey);
+export function Use(...middlewares) {
+    return (target, propertyKey, _descriptor) => {
+        const existing = Reflect.getMetadata(MIDDLEWARE_KEY, target, propertyKey) || [];
+        Reflect.defineMetadata(MIDDLEWARE_KEY, [...existing, ...middlewares], target, propertyKey);
     };
 }
 /**
@@ -258,12 +316,12 @@ export function Use() {
  * @returns Parameter decorator function
  */
 function createParamDecorator(type, key) {
-    return function (paramKey) {
-        return function (target, propertyKey, parameterIndex) {
-            var params = Reflect.getMetadata(PARAMS_KEY, target, propertyKey) || [];
+    return (paramKey) => {
+        return (target, propertyKey, parameterIndex) => {
+            const params = Reflect.getMetadata(PARAMS_KEY, target, propertyKey) || [];
             // Ensure parameters are ordered by index
-            params.push({ index: parameterIndex, type: type, key: paramKey || key });
-            params.sort(function (a, b) { return a.index - b.index; });
+            params.push({ index: parameterIndex, type, key: paramKey || key });
+            params.sort((a, b) => a.index - b.index);
             Reflect.defineMetadata(PARAMS_KEY, params, target, propertyKey);
         };
     };
@@ -282,7 +340,7 @@ function createParamDecorator(type, key) {
  * }
  * ```
  */
-export var Query = createParamDecorator('query');
+export const Query = createParamDecorator('query');
 /**
  * Decorator that extracts route parameters from request.
  *
@@ -297,7 +355,7 @@ export var Query = createParamDecorator('query');
  * }
  * ```
  */
-export var Param = createParamDecorator('param');
+export const Param = createParamDecorator('param');
 /**
  * Decorator that extracts body or body property from request.
  *
@@ -317,7 +375,7 @@ export var Param = createParamDecorator('param');
  * }
  * ```
  */
-export var Body = createParamDecorator('body');
+export const Body = createParamDecorator('body');
 /**
  * Decorator that injects the entire request object.
  *
@@ -332,7 +390,7 @@ export var Body = createParamDecorator('body');
  * }
  * ```
  */
-export var Req = createParamDecorator('req');
+export const Req = createParamDecorator('req');
 /**
  * Decorator that injects the response object.
  *
@@ -347,7 +405,7 @@ export var Req = createParamDecorator('req');
  * }
  * ```
  */
-export var Res = createParamDecorator('res');
+export const Res = createParamDecorator('res');
 /**
  * Decorator that sets a custom HTTP status code for a response.
  *
@@ -365,15 +423,15 @@ export var Res = createParamDecorator('res');
  * ```
  */
 export function HttpCode(status) {
-    return function (target, propertyKey, _descriptor) {
+    return (target, propertyKey, _descriptor) => {
         Reflect.defineMetadata(HTTP_CODE_KEY, status, target, propertyKey);
     };
 }
 /**
  * Decorator that adds a custom HTTP header to the response.
  *
- * @param name - Header name
- * @param value - Header value
+ * @param header - Header name-value pairs or a single header name and value
+ * @param value - Header value if a single header name is provided
  * @returns Method decorator
  *
  * @example
@@ -384,13 +442,53 @@ export function HttpCode(status) {
  *   // Response will include the Cache-Control header
  *   return { data: '...' };
  * }
- * ```
  */
 export function Header(name, value) {
-    return function (target, propertyKey, _descriptor) {
-        var headers = Reflect.getMetadata(HEADER_KEY, target, propertyKey) || {};
-        headers[name] = value;
-        Reflect.defineMetadata(HEADER_KEY, headers, target, propertyKey);
+    return Headers(name, value);
+}
+/**
+ * Decorator that adds a custom HTTP headers to the response.
+ *
+ * @param headers - Header name-value pairs or a single header name and value
+ * @param value - Header value if a single header name is provided
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/data')
+ * @Headers('Cache-Control', 'max-age=60')
+ * getData() {
+ *   // Response will include the Cache-Control header
+ *   return { data: '...' };
+ * }
+ *
+ * @Get('/data/:id')
+ * @Headers({
+ *   'Cache-Control': 'max-age=60',
+ *   'X-Custom-Header': 'custom-value',
+ *   'Content-Security-Policy': "default-src 'self'"
+ * })
+ * getData() {
+ *   // Response will include all specified headers
+ *   return { data: '...' };
+ * }
+ *
+ * ```
+ */
+export function Headers(headers, value) {
+    return (target, propertyKey) => {
+        if (typeof propertyKey === 'undefined') {
+            // Class decorator
+            const existing = Reflect.getMetadata(HEADER_KEY, target) || {};
+            const newHeaders = typeof headers === 'string' ? { [headers]: value } : headers;
+            Reflect.defineMetadata(HEADER_KEY, { ...existing, ...newHeaders }, target);
+        }
+        else {
+            // Method decorator
+            const existing = Reflect.getMetadata(HEADER_KEY, target, propertyKey) || {};
+            const newHeaders = typeof headers === 'string' ? { [headers]: value } : headers;
+            Reflect.defineMetadata(HEADER_KEY, { ...existing, ...newHeaders }, target, propertyKey);
+        }
     };
 }
 /**
@@ -410,8 +508,8 @@ export function Header(name, value) {
  * ```
  */
 export function Before(fn) {
-    return function (target, propertyKey, _descriptor) {
-        var hooks = Reflect.getMetadata(BEFORE_KEY, target, propertyKey) || [];
+    return (target, propertyKey, _descriptor) => {
+        const hooks = Reflect.getMetadata(BEFORE_KEY, target, propertyKey) || [];
         hooks.push(fn);
         Reflect.defineMetadata(BEFORE_KEY, hooks, target, propertyKey);
     };
@@ -434,8 +532,8 @@ export function Before(fn) {
  * ```
  */
 export function After(fn) {
-    return function (target, propertyKey, _descriptor) {
-        var hooks = Reflect.getMetadata(AFTER_KEY, target, propertyKey) || [];
+    return (target, propertyKey, _descriptor) => {
+        const hooks = Reflect.getMetadata(AFTER_KEY, target, propertyKey) || [];
         hooks.push(fn);
         Reflect.defineMetadata(AFTER_KEY, hooks, target, propertyKey);
     };
@@ -444,6 +542,8 @@ export function After(fn) {
  * Decorator that requires specific roles for accessing a route.
  * Must be used with authentication middleware.
  *
+ * Check req.user.roles for user roles[].
+ *
  * @param roles - List of roles that can access this route
  * @returns Method decorator
  *
@@ -457,13 +557,16 @@ export function After(fn) {
  * }
  * ```
  */
-export function Roles() {
-    var roles = [];
-    for (var _i = 0; _i < arguments.length; _i++) {
-        roles[_i] = arguments[_i];
-    }
-    return function (target, propertyKey, _descriptor) {
-        Reflect.defineMetadata(ROLES_KEY, roles, target, propertyKey);
+export function Roles(...roles) {
+    return (target, propertyKey, _descriptor) => {
+        if (typeof propertyKey === 'undefined') {
+            // Class decorator
+            Reflect.defineMetadata(ROLES_KEY, roles, target);
+        }
+        else {
+            // Method decorator
+            Reflect.defineMetadata(ROLES_KEY, roles, target, propertyKey);
+        }
     };
 }
 /**
@@ -489,14 +592,220 @@ export function Roles() {
  * }
  * ```
  */
-export function Redirect(url, statusCode) {
-    if (statusCode === void 0) { statusCode = 302; }
-    return function (target, propertyKey, descriptor) {
+export function Redirect(url, statusCode = 302) {
+    return (target, propertyKey, descriptor) => {
         // Store the redirect information in metadata
-        Reflect.defineMetadata(REDIRECT_KEY, { url: url, statusCode: statusCode }, target, propertyKey);
+        Reflect.defineMetadata(REDIRECT_KEY, { url, statusCode }, target, propertyKey);
         return descriptor;
     };
 }
+/**
+ * Decorator that adds caching to a route response.
+ *
+ * @param ttlSeconds - Time to live in seconds for the cache
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/data')
+ * @Cache(300) // Cache for 5 minutes
+ * getData() {
+ *   return { data: 'expensive operation result' };
+ * }
+ * ```
+ */
+export function Cache(ttlSeconds) {
+    return (target, propertyKey, _descriptor) => {
+        if (typeof propertyKey === 'undefined') {
+            // Class decorator
+            Reflect.defineMetadata(CACHE_KEY, { ttlSeconds }, target);
+        }
+        else {
+            // Method decorator
+            Reflect.defineMetadata(CACHE_KEY, { ttlSeconds }, target, propertyKey);
+        }
+    };
+}
+/**
+ * Decorator that applies rate limiting to a route.
+ * Note: Requires 'express-rate-limit' package to be installed.
+ *
+ * @param limit - Maximum number of requests allowed in the window
+ * @param windowMs - Time window in milliseconds
+ * @returns Method decorator
+ *
+ * Default Options:
+ *  - standardHeaders: true
+ *  - legacyHeaders: false
+ *
+ * @example
+ * ```ts
+ * @Post('/login')
+ * @RateLimit({ max: 5, windowMs: 60000, standardHeaders: true, legacyHeaders: false }) // 5 requests per minute
+ * login(@Body() credentials: LoginDto) {
+ *   return this.authService.login(credentials);
+ * }
+ * ```
+ */
+export function RateLimit(options) {
+    const opts = {
+        standardHeaders: true,
+        legacyHeaders: false,
+        ...options
+    };
+    return (target, propertyKey, _descriptor) => {
+        if (typeof propertyKey === 'undefined') {
+            // Class decorator
+            Reflect.defineMetadata(RATE_LIMIT_KEY, opts, target);
+        }
+        else {
+            // Method decorator
+            Reflect.defineMetadata(RATE_LIMIT_KEY, opts, target, propertyKey);
+        }
+    };
+}
+/**
+ * Decorator that sets the content type for the response.
+ *
+ * @param type - MIME type for the response
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/download')
+ * @ContentType('application/pdf')
+ * downloadPdf() {
+ *   return this.fileService.generatePdf();
+ * }
+ * ```
+ */
+export function ContentType(type) {
+    return (target, propertyKey, _descriptor) => {
+        Reflect.defineMetadata(CONTENT_TYPE_KEY, { type }, target, propertyKey);
+    };
+}
+/**
+ * Decorator that adds API versioning to a route.
+ *
+ * @param version - Version string for the API endpoint
+ * @param options - Versioning options
+ * @returns Method decorator
+ *
+ * Default Options:
+ *  - addPrefix: true
+ *  - addHeader: true
+ *  - headerName: 'X-API-Version'
+ *
+ * @example
+ * ```ts
+ *
+ * @Get('/users')
+ * @Version('v2')
+ * getUsersV2() {
+ *   return this.userService.findAllV2();
+ * }
+ *
+ * @Get('/users')
+ * @Version('v2', { addPrefix: true, addHeader: true, headerName: 'X-API-Version' })
+ * getUsersV2() {
+ *   // Route becomes /v2/users
+ *   return this.userService.findAllV2();
+ * }
+ * ```
+ */
+export function Version(version, options) {
+    const opts = {
+        addPrefix: true,
+        addHeader: true,
+        headerName: 'X-API-Version',
+        ...options
+    };
+    return (target, propertyKey, _descriptor) => {
+        if (typeof propertyKey === 'undefined') {
+            // Class decorator
+            Reflect.defineMetadata(VERSION_KEY, { version, options: opts }, target);
+        }
+        else {
+            // Method decorator
+            Reflect.defineMetadata(VERSION_KEY, { version, options: opts }, target, propertyKey);
+        }
+    };
+}
+/**
+ * Decorator that sets a timeout for route execution.
+ *
+ * @param ms - Timeout in milliseconds
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/slow-operation')
+ * @Timeout(30000) // 30 second timeout
+ * slowOperation() {
+ *   return this.heavyService.processData();
+ * }
+ * ```
+ */
+export function Timeout(ms) {
+    return (target, propertyKey, _descriptor) => {
+        if (typeof propertyKey === 'undefined') {
+            // Class decorator
+            Reflect.defineMetadata(TIMEOUT_KEY, { ms }, target);
+        }
+        else {
+            // Method decorator
+            Reflect.defineMetadata(TIMEOUT_KEY, { ms }, target, propertyKey);
+        }
+    };
+}
+/**
+ * Decorator that adds comprehensive logging to a route.
+ *
+ * @param options - Logging configuration options
+ * @returns Method decorator
+ *
+ * Default Options:
+ *  - logEntry: true
+ *  - logExit: true
+ *  - logBody: false
+ *  - logParams: false
+ *  - logResponse: false
+ *
+ * @example
+ * ```ts
+ * @Post('/users')
+ * @Log({
+ *   logEntry: true,
+ *   logExit: true,
+ *   logBody: true,
+ *   logParams: true,
+ *   logResponse: false
+ * })
+ * createUser(@Body() userData: any) {
+ *   return this.userService.create(userData);
+ * }
+ * ```
+ */
+export function Log(options) {
+    return (target, propertyKey, _descriptor) => {
+        const config = {
+            logEntry: true,
+            logExit: true,
+            logBody: false,
+            logParams: false,
+            logResponse: false,
+            ...options
+        };
+        if (typeof propertyKey === 'undefined') {
+            // Class decorator
+            Reflect.defineMetadata(LOG_KEY, config, target);
+        }
+        else {
+            // Method decorator
+            Reflect.defineMetadata(LOG_KEY, config, target, propertyKey);
+        }
+    };
+}
 /**
  * Registers all controller classes with the provided router.
  * This function processes all decorators and sets up the Express routes.
@@ -505,162 +814,200 @@ export function Redirect(url, statusCode) {
  * @param controllers - Array of controller classes
  */
 export function registerControllers(router, controllers) {
-    var _this = this;
-    controllers.forEach(function (ControllerClass) {
-        var instance = new ControllerClass();
-        var basePath = Reflect.getMetadata('basePath', ControllerClass) || '';
-        var routes = Reflect.getMetadata(ROUTES_KEY, ControllerClass) || [];
-        routes.forEach(function (_a) {
-            var _b;
-            var path = _a.path, method = _a.method, handlerName = _a.handlerName;
-            var middlewares = Reflect.getMetadata(MIDDLEWARE_KEY, instance, handlerName) || [];
-            var params = Reflect.getMetadata(PARAMS_KEY, instance, handlerName) || [];
-            var httpCode = Reflect.getMetadata(HTTP_CODE_KEY, instance, handlerName);
-            var headers = Reflect.getMetadata(HEADER_KEY, instance, handlerName) || {};
-            var beforeHooks = Reflect.getMetadata(BEFORE_KEY, instance, handlerName) || [];
-            var afterHooks = Reflect.getMetadata(AFTER_KEY, instance, handlerName) || [];
-            var roles = Reflect.getMetadata(ROLES_KEY, instance, handlerName) || [];
-            var redirect = Reflect.getMetadata(REDIRECT_KEY, instance, handlerName);
-            var handler = function (req, res, next) { return __awaiter(_this, void 0, void 0, function () {
-                var beforeHooks_1, beforeHooks_1_1, fn, e_1_1, args_1, result, awaited, _a, redirectUrl, redirectStatus, _b, _c, _d, k, v, afterHooks_1, afterHooks_1_1, fn, e_2_1, err_1;
-                var e_1, _e, _f, e_3, _g, e_2, _h;
-                var _j, _k, _l, _m;
-                return __generator(this, function (_o) {
-                    switch (_o.label) {
-                        case 0:
-                            _o.trys.push([0, 20, , 21]);
-                            // Handle roles-based access control
-                            if (roles.length && !((_k = (_j = req === null || req === void 0 ? void 0 : req.user) === null || _j === void 0 ? void 0 : _j.roles) === null || _k === void 0 ? void 0 : _k.some(function (role) { return roles.includes(role); }))) {
-                                res.status(HttpStatusCodes.FORBIDDEN).json(new ForbiddenException('Forbidden Insufficient Roles'));
-                                return [2 /*return*/];
-                            }
-                            // Process static redirect if configured
-                            if (redirect && redirect.url) {
-                                return [2 /*return*/, res.redirect(redirect.statusCode, redirect.url)];
-                            }
-                            _o.label = 1;
-                        case 1:
-                            _o.trys.push([1, 6, 7, 8]);
-                            beforeHooks_1 = __values(beforeHooks), beforeHooks_1_1 = beforeHooks_1.next();
-                            _o.label = 2;
-                        case 2:
-                            if (!!beforeHooks_1_1.done) return [3 /*break*/, 5];
-                            fn = beforeHooks_1_1.value;
-                            return [4 /*yield*/, fn(req, res)];
-                        case 3:
-                            _o.sent();
-                            _o.label = 4;
-                        case 4:
-                            beforeHooks_1_1 = beforeHooks_1.next();
-                            return [3 /*break*/, 2];
-                        case 5: return [3 /*break*/, 8];
-                        case 6:
-                            e_1_1 = _o.sent();
-                            e_1 = { error: e_1_1 };
-                            return [3 /*break*/, 8];
-                        case 7:
-                            try {
-                                if (beforeHooks_1_1 && !beforeHooks_1_1.done && (_e = beforeHooks_1.return)) _e.call(beforeHooks_1);
-                            }
-                            finally { if (e_1) throw e_1.error; }
-                            return [7 /*endfinally*/];
-                        case 8:
-                            args_1 = [];
-                            if (params.length) {
-                                params.forEach(function (_a) {
-                                    var _b;
-                                    var index = _a.index, type = _a.type, key = _a.key;
-                                    switch (type) {
-                                        case 'query':
-                                            args_1[index] = key ? req.query[key] : req.query;
-                                            break;
-                                        case 'param':
-                                            args_1[index] = key ? req.params[key] : req.params;
-                                            break;
-                                        case 'body':
-                                            args_1[index] = key ? (_b = req.body) === null || _b === void 0 ? void 0 : _b[key] : req.body;
-                                            break;
-                                        case 'req':
-                                            args_1[index] = req;
-                                            break;
-                                        case 'res':
-                                            args_1[index] = res;
-                                            break;
-                                    }
-                                });
-                            }
-                            result = (_f = instance)[handlerName].apply(_f, __spreadArray([], __read(args_1), false));
-                            if (!(result instanceof Promise)) return [3 /*break*/, 10];
-                            return [4 /*yield*/, result];
-                        case 9:
-                            _a = _o.sent();
-                            return [3 /*break*/, 11];
-                        case 10:
-                            _a = result;
-                            _o.label = 11;
-                        case 11:
-                            awaited = _a;
-                            // Handle dynamic redirects
-                            if (redirect && awaited && typeof awaited === 'object' && 'url' in awaited) {
-                                redirectUrl = awaited.url;
-                                redirectStatus = awaited.statusCode || redirect.statusCode;
-                                return [2 /*return*/, res.redirect(redirectStatus, redirectUrl)];
+    controllers.forEach(ControllerClass => {
+        // Use DI container to resolve controller (constructor injection + property injection)
+        const instance = diContainer.get(ControllerClass);
+        const basePath = Reflect.getMetadata('basePath', ControllerClass) || '';
+        const routes = Reflect.getMetadata(ROUTES_KEY, ControllerClass) || [];
+        // Get controller-level decorators (fallback values)
+        const controllerRateLimit = Reflect.getMetadata(RATE_LIMIT_KEY, ControllerClass);
+        const controllerCache = Reflect.getMetadata(CACHE_KEY, ControllerClass);
+        const controllerTimeout = Reflect.getMetadata(TIMEOUT_KEY, ControllerClass);
+        const controllerVersion = Reflect.getMetadata(VERSION_KEY, ControllerClass);
+        const controllerRoles = Reflect.getMetadata(ROLES_KEY, ControllerClass);
+        const controllerLogConfig = Reflect.getMetadata(LOG_KEY, ControllerClass);
+        const controllerHeaders = Reflect.getMetadata(HEADER_KEY, ControllerClass) || {};
+        routes.forEach(({ path, method, handlerName }) => {
+            const middlewares = Reflect.getMetadata(MIDDLEWARE_KEY, instance, handlerName) || [];
+            const params = Reflect.getMetadata(PARAMS_KEY, instance, handlerName) || [];
+            const httpCode = Reflect.getMetadata(HTTP_CODE_KEY, instance, handlerName);
+            // Merge controller-level and method-level headers
+            const methodHeaders = Reflect.getMetadata(HEADER_KEY, instance, handlerName) || {};
+            const headers = { ...controllerHeaders, ...methodHeaders };
+            const beforeHooks = Reflect.getMetadata(BEFORE_KEY, instance, handlerName) || [];
+            const afterHooks = Reflect.getMetadata(AFTER_KEY, instance, handlerName) || [];
+            const redirect = Reflect.getMetadata(REDIRECT_KEY, instance, handlerName);
+            const contentType = Reflect.getMetadata(CONTENT_TYPE_KEY, instance, handlerName);
+            // Use method-level decorators if present, otherwise fall back to controller-level
+            const roles = Reflect.getMetadata(ROLES_KEY, instance, handlerName) || controllerRoles || [];
+            const cache = Reflect.getMetadata(CACHE_KEY, instance, handlerName) || controllerCache;
+            const rateLimitOptions = Reflect.getMetadata(RATE_LIMIT_KEY, instance, handlerName) || controllerRateLimit;
+            const version = Reflect.getMetadata(VERSION_KEY, instance, handlerName) || controllerVersion;
+            const timeout = Reflect.getMetadata(TIMEOUT_KEY, instance, handlerName) || controllerTimeout;
+            const logConfig = Reflect.getMetadata(LOG_KEY, instance, handlerName) || controllerLogConfig;
+            // Create rate limiter for this specific route if needed
+            let rateLimiter = null;
+            if (rateLimitOptions) {
+                try {
+                    rateLimiter = rateLimiterCache.get(rateLimitOptions);
+                }
+                catch (err) {
+                    getLogger().warn({ err }, 'express-rate-limit not available, skipping rate limiting for this route');
+                }
+            }
+            let finalPath = path;
+            if (version?.options?.addPrefix) {
+                finalPath = `/${version.version}${path}`;
+            }
+            const handler = async (req, res, next) => {
+                // Set start time for duration tracking
+                req['startTime'] = Date.now();
+                let timeoutId;
+                let timedOut = false;
+                try {
+                    // Handle timeout setup
+                    if (timeout) {
+                        timeoutId = setTimeout(() => {
+                            if (!res.headersSent && !timedOut) {
+                                timedOut = true;
+                                const errorResponse = createFinalErrorResponse(req, HttpStatusCodes.REQUEST_TIMEOUT, 'Request timed out');
+                                res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(errorResponse);
                             }
-                            if (!res.headersSent && typeof awaited !== 'undefined') {
-                                if (httpCode)
-                                    (_l = res.status) === null || _l === void 0 ? void 0 : _l.call(res, httpCode);
-                                try {
-                                    for (_b = __values(Object.entries(headers)), _c = _b.next(); !_c.done; _c = _b.next()) {
-                                        _d = __read(_c.value, 2), k = _d[0], v = _d[1];
-                                        (_m = res.set) === null || _m === void 0 ? void 0 : _m.call(res, k, v);
-                                    }
-                                }
-                                catch (e_3_1) { e_3 = { error: e_3_1 }; }
-                                finally {
-                                    try {
-                                        if (_c && !_c.done && (_g = _b.return)) _g.call(_b);
-                                    }
-                                    finally { if (e_3) throw e_3.error; }
-                                }
-                                res.json(awaited);
+                        }, timeout.ms);
+                    }
+                    if (timedOut)
+                        return;
+                    // Handle rate limiting
+                    if (rateLimiter) {
+                        await new Promise((resolve, reject) => {
+                            rateLimiter(req, res, (err) => {
+                                if (err)
+                                    reject(err);
+                                else
+                                    resolve();
+                            });
+                        });
+                    }
+                    // Handle content type
+                    if (!res.headersSent && contentType) {
+                        res.setHeader('Content-Type', contentType.type);
+                    }
+                    // Handle versioning header
+                    if (version?.options?.addHeader && version?.options?.headerName && version?.version) {
+                        if (!res.headersSent) {
+                            res.setHeader(version.options.headerName, version.version);
+                        }
+                    }
+                    // Handle caching
+                    if (cache && !res.headersSent) {
+                        res.setHeader('Cache-Control', `public, max-age=${cache.ttlSeconds}`);
+                    }
+                    // Handle logging - entry
+                    if (logConfig?.logEntry) {
+                        const logger = getLogger();
+                        const logData = {
+                            method: req.method,
+                            url: req.originalUrl || req.url,
+                            userAgent: req.get('User-Agent')
+                        };
+                        if (logConfig.logParams) {
+                            logData.params = req.params;
+                            logData.query = req.query;
+                        }
+                        if (logConfig.logBody)
+                            logData.body = req.body;
+                        logger.info({ entry: logData }, 'Route Entry:');
+                    }
+                    // Handle roles-based access control
+                    if (roles.length && !req?.user?.roles?.some((role) => roles.includes(role))) {
+                        const errorResponse = createFinalErrorResponse(req, HttpStatusCodes.FORBIDDEN, 'Forbidden Insufficient Roles');
+                        res.status(HttpStatusCodes.FORBIDDEN).json(errorResponse);
+                        if (timeoutId) {
+                            clearTimeout(timeoutId);
+                        }
+                        return;
+                    }
+                    // Process static redirect if configured
+                    if (redirect && redirect.url) {
+                        if (timeoutId) {
+                            clearTimeout(timeoutId);
+                        }
+                        return res.redirect(redirect.statusCode, redirect.url);
+                    }
+                    for (const fn of beforeHooks)
+                        await fn(req, res);
+                    const args = [];
+                    if (params.length) {
+                        params.forEach(({ index, type, key }) => {
+                            switch (type) {
+                                case 'query':
+                                    args[index] = key ? req.query[key] : req.query;
+                                    break;
+                                case 'param':
+                                    args[index] = key ? req.params[key] : req.params;
+                                    break;
+                                case 'body':
+                                    args[index] = key ? req.body?.[key] : req.body;
+                                    break;
+                                case 'req':
+                                    args[index] = req;
+                                    break;
+                                case 'res':
+                                    args[index] = res;
+                                    break;
                             }
-                            _o.label = 12;
-                        case 12:
-                            _o.trys.push([12, 17, 18, 19]);
-                            afterHooks_1 = __values(afterHooks), afterHooks_1_1 = afterHooks_1.next();
-                            _o.label = 13;
-                        case 13:
-                            if (!!afterHooks_1_1.done) return [3 /*break*/, 16];
-                            fn = afterHooks_1_1.value;
-                            return [4 /*yield*/, fn(req, res, awaited)];
-                        case 14:
-                            _o.sent();
-                            _o.label = 15;
-                        case 15:
-                            afterHooks_1_1 = afterHooks_1.next();
-                            return [3 /*break*/, 13];
-                        case 16: return [3 /*break*/, 19];
-                        case 17:
-                            e_2_1 = _o.sent();
-                            e_2 = { error: e_2_1 };
-                            return [3 /*break*/, 19];
-                        case 18:
-                            try {
-                                if (afterHooks_1_1 && !afterHooks_1_1.done && (_h = afterHooks_1.return)) _h.call(afterHooks_1);
+                        });
+                    }
+                    const result = instance[handlerName](...args);
+                    // Support both sync and async handlers
+                    const awaited = result instanceof Promise ? await result : result;
+                    // Clear timeout if operation completed
+                    if (timeoutId) {
+                        clearTimeout(timeoutId);
+                    }
+                    if (timedOut)
+                        return;
+                    // Handle dynamic redirects
+                    if (redirect && awaited && typeof awaited === 'object' && 'url' in awaited) {
+                        const redirectUrl = awaited.url;
+                        const redirectStatus = awaited.statusCode || redirect.statusCode;
+                        return res.redirect(redirectStatus, redirectUrl);
+                    }
+                    if (!res.headersSent && typeof awaited !== 'undefined') {
+                        if (httpCode)
+                            res.status(httpCode);
+                        for (const [k, v] of Object.entries(headers)) {
+                            const normalized = normalizeHeaderValue(v);
+                            if (typeof normalized !== 'undefined') {
+                                res.set(k, normalized);
                             }
-                            finally { if (e_2) throw e_2.error; }
-                            return [7 /*endfinally*/];
-                        case 19: return [3 /*break*/, 21];
-                        case 20:
-                            err_1 = _o.sent();
-                            next(err_1);
-                            return [3 /*break*/, 21];
-                        case 21: return [2 /*return*/];
+                        }
+                        res.json(awaited);
+                    }
+                    // Handle logging - exit
+                    if (logConfig?.logExit) {
+                        const logger = getLogger();
+                        const logData = {
+                            method: req.method,
+                            url: req.originalUrl || req.url,
+                            statusCode: res.statusCode,
+                            duration: `${Date.now() - req.startTime}ms`
+                        };
+                        if (logConfig.logResponse)
+                            logData.response = awaited;
+                        logger.info({ exit: logData }, 'Route Exit:');
+                    }
+                    for (const fn of afterHooks)
+                        await fn(req, res, awaited);
+                }
+                catch (err) {
+                    if (timeoutId) {
+                        clearTimeout(timeoutId);
                     }
-                });
-            }); };
-            (_b = router)[method].apply(_b, __spreadArray(__spreadArray([basePath + path], __read(middlewares), false), [handler], false));
+                    next(err);
+                }
+            };
+            router[method](basePath + finalPath, ...middlewares, handler);
         });
     });
 }
-//# sourceMappingURL=decorators.utils.js.map