@catbee/utils 0.0.8-next.0 → 0.0.8-rc.1

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

@@ -0,0 +1,1057 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+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 };
+    }
+};
+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);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    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];
+        }
+    }
+    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 };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+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
+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');
+var CACHE_KEY = Symbol('cache');
+var RATE_LIMIT_KEY = Symbol('rateLimit');
+var CONTENT_TYPE_KEY = Symbol('contentType');
+var VERSION_KEY = Symbol('version');
+var TIMEOUT_KEY = Symbol('timeout');
+var LOG_KEY = Symbol('log');
+/**
+ * RateLimiter cache that uses TTLCache for automatic TTL and LRU handling.
+ */
+var RateLimiterCache = /** @class */ (function () {
+    function RateLimiterCache(maxSize, ttlMs) {
+        if (maxSize === void 0) { maxSize = 100; }
+        if (ttlMs === void 0) { ttlMs = 5 * 60 * 1000; }
+        this.cache = new TTLCache({
+            maxSize: maxSize,
+            ttlMs: ttlMs
+        });
+    }
+    RateLimiterCache.prototype.generateKey = function (options) {
+        return "".concat(options.max, ":").concat(options.windowMs, ":").concat(options.standardHeaders, ":").concat(options.legacyHeaders);
+    };
+    RateLimiterCache.prototype.get = function (options) {
+        var key = this.generateKey(options);
+        var cached = this.cache.get(key);
+        if (cached) {
+            return cached.limiter;
+        }
+        // Create new limiter
+        var limiter = rateLimit(__assign(__assign({}, options), { handler: function (req, res) {
+                var 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: limiter,
+            config: key
+        });
+        return limiter;
+    };
+    RateLimiterCache.prototype.clear = function () {
+        this.cache.clear();
+    };
+    RateLimiterCache.prototype.size = function () {
+        return this.cache.size();
+    };
+    RateLimiterCache.prototype.destroy = function () {
+        this.cache.destroy();
+    };
+    return RateLimiterCache;
+}());
+export { RateLimiterCache };
+// Global cache instance
+var rateLimiterCache = new RateLimiterCache();
+function normalizeHeaderValue(value) {
+    if (typeof value === 'undefined')
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && value.every(function (item) { return typeof item === 'string'; })) {
+        return value;
+    }
+    return String(value);
+}
+/**
+ * Factory function that creates HTTP method decorators.
+ *
+ * @param method - HTTP method to create decorator for
+ * @returns A method decorator function
+ */
+function createRouteDecorator(method) {
+    return function (path) {
+        return function (target, propertyKey, descriptor) {
+            var routes = Reflect.getMetadata(ROUTES_KEY, target.constructor) || [];
+            routes.push({
+                path: path,
+                method: method,
+                handlerName: propertyKey
+            });
+            Reflect.defineMetadata(ROUTES_KEY, routes, target.constructor);
+        };
+    };
+}
+/**
+ * Decorator for GET HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users')
+ * getUsers() {
+ *   return this.userService.findAll();
+ * }
+ * ```
+ */
+export var Get = createRouteDecorator('get');
+/**
+ * Decorator for POST HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Post('/users')
+ * createUser(@Body() userData: any) {
+ *   return this.userService.create(userData);
+ * }
+ * ```
+ */
+export var Post = createRouteDecorator('post');
+/**
+ * Decorator for PUT HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export var Put = createRouteDecorator('put');
+/**
+ * Decorator for PATCH HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export var Patch = createRouteDecorator('patch');
+/**
+ * Decorator for DELETE HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export var Delete = createRouteDecorator('delete');
+/**
+ * Decorator for OPTIONS HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export var Options = createRouteDecorator('options');
+/**
+ * Decorator for HEAD HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export var Head = createRouteDecorator('head');
+/**
+ * Decorator for TRACE HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export var Trace = createRouteDecorator('trace');
+/**
+ * Decorator for CONNECT HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export var Connect = createRouteDecorator('connect');
+/**
+ * Decorator that marks a class as a controller with a base path.
+ * Used as the entry point for routing configuration.
+ *
+ * @param basePath - Base URL path for all routes in this controller
+ * @returns Class decorator
+ *
+ * @example
+ * ```ts
+ * @Controller('/api/users')
+ * class UserController {
+ *   // Controller methods...
+ * }
+ * ```
+ */
+export function Controller(basePath) {
+    return function (target) {
+        Reflect.defineMetadata('basePath', basePath, target);
+    };
+}
+/**
+ * Decorator that applies middleware to a controller method.
+ * Multiple middlewares can be applied and will execute in order.
+ *
+ * @param middlewares - Express middleware functions to apply
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/protected')
+ * @Use(authMiddleware, loggingMiddleware)
+ * getProtectedResource() {
+ *   // This route is protected by auth middleware
+ * }
+ * ```
+ */
+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);
+    };
+}
+/**
+ * Factory function that creates parameter decorators.
+ *
+ * @param type - Parameter type to extract from request
+ * @param key - Optional fixed key for extraction
+ * @returns Parameter decorator function
+ */
+function createParamDecorator(type, key) {
+    return function (paramKey) {
+        return function (target, propertyKey, parameterIndex) {
+            var 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; });
+            Reflect.defineMetadata(PARAMS_KEY, params, target, propertyKey);
+        };
+    };
+}
+/**
+ * Decorator that extracts query parameters from request.
+ *
+ * @param paramKey - Optional key to extract specific query parameter
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/search')
+ * search(@Query('term') searchTerm: string) {
+ *   // searchTerm will contain the value of req.query.term
+ * }
+ * ```
+ */
+export var Query = createParamDecorator('query');
+/**
+ * Decorator that extracts route parameters from request.
+ *
+ * @param paramKey - Optional key to extract specific route parameter
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users/:id')
+ * getUser(@Param('id') userId: string) {
+ *   // userId will contain the value of req.params.id
+ * }
+ * ```
+ */
+export var Param = createParamDecorator('param');
+/**
+ * Decorator that extracts body or body property from request.
+ *
+ * @param paramKey - Optional key to extract specific body property
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Post('/users')
+ * createUser(@Body() userData: any) {
+ *   // userData will contain the entire req.body
+ * }
+ *
+ * @Post('/update')
+ * updateName(@Body('name') name: string) {
+ *   // name will contain the value of req.body.name
+ * }
+ * ```
+ */
+export var Body = createParamDecorator('body');
+/**
+ * Decorator that injects the entire request object.
+ *
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/complex')
+ * complex(@Req() req: Request) {
+ *   // Access the full request object
+ *   console.log(req.headers);
+ * }
+ * ```
+ */
+export var Req = createParamDecorator('req');
+/**
+ * Decorator that injects the response object.
+ *
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/custom')
+ * custom(@Res() res: Response) {
+ *   // Direct access to response object
+ *   return res.status(201).send('Created');
+ * }
+ * ```
+ */
+export var Res = createParamDecorator('res');
+/**
+ * Decorator that sets a custom HTTP status code for a response.
+ *
+ * @param status - HTTP status code to use
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Post('/users')
+ * @HttpCode(201)
+ * createUser(@Body() userData: any) {
+ *   // Response will have 201 Created status code
+ *   return { id: '123', ...userData };
+ * }
+ * ```
+ */
+export function HttpCode(status) {
+    return function (target, propertyKey, _descriptor) {
+        Reflect.defineMetadata(HTTP_CODE_KEY, status, target, propertyKey);
+    };
+}
+/**
+ * Decorator that adds a custom HTTP header to the response.
+ *
+ * @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
+ * ```ts
+ * @Get('/data')
+ * @Header('Cache-Control', 'max-age=60')
+ * getData() {
+ *   // Response will include the Cache-Control header
+ *   return { data: '...' };
+ * }
+ */
+export function Header(name, value) {
+    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 function (target, propertyKey) {
+        var _a;
+        var existing = Reflect.getMetadata(HEADER_KEY, target, propertyKey) || {};
+        var newHeaders = typeof headers === 'string' ? (_a = {}, _a[headers] = value, _a) : headers;
+        Reflect.defineMetadata(HEADER_KEY, __assign(__assign({}, existing), newHeaders), target, propertyKey);
+    };
+}
+/**
+ * Decorator that registers a function to run before route handler execution.
+ * Useful for pre-processing or logging.
+ *
+ * @param fn - Function to execute before the handler
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users/:id')
+ * @Before((req, res) => console.log(`Accessing user ${req.params.id}`))
+ * getUser(@Param('id') id: string) {
+ *   // Function will log before this handler runs
+ * }
+ * ```
+ */
+export function Before(fn) {
+    return function (target, propertyKey, _descriptor) {
+        var hooks = Reflect.getMetadata(BEFORE_KEY, target, propertyKey) || [];
+        hooks.push(fn);
+        Reflect.defineMetadata(BEFORE_KEY, hooks, target, propertyKey);
+    };
+}
+/**
+ * Decorator that registers a function to run after route handler execution.
+ * Can access the handler's result.
+ *
+ * @param fn - Function to execute after the handler
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users/:id')
+ * @After((req, res, result) => console.log(`User data sent: ${JSON.stringify(result)}`))
+ * getUser(@Param('id') id: string) {
+ *   // After this handler, the function will log the returned data
+ *   return { id, name: 'Example' };
+ * }
+ * ```
+ */
+export function After(fn) {
+    return function (target, propertyKey, _descriptor) {
+        var hooks = Reflect.getMetadata(AFTER_KEY, target, propertyKey) || [];
+        hooks.push(fn);
+        Reflect.defineMetadata(AFTER_KEY, hooks, target, propertyKey);
+    };
+}
+/**
+ * Decorator that requires specific roles for accessing a route.
+ * Must be used with authentication middleware.
+ *
+ * @param roles - List of roles that can access this route
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/admin/settings')
+ * @Roles('admin', 'superuser')
+ * getSettings() {
+ *   // Only admins and superusers can access
+ *   return { settings: [...] };
+ * }
+ * ```
+ */
+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);
+    };
+}
+/**
+ * Decorator that redirects to another URL.
+ *
+ * @param url - URL to redirect to (can be absolute or relative)
+ * @param statusCode - HTTP status code for redirect (default: 302)
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/old-path')
+ * @Redirect('/new-path', 301)
+ * redirectToNewPath() {
+ *   // This method won't be executed; automatic redirect happens
+ * }
+ *
+ * @Get('/dynamic-redirect')
+ * @Redirect()
+ * getDynamicRedirect() {
+ *   // Return an object with url and optionally statusCode
+ *   return { url: '/calculated-path', statusCode: 307 };
+ * }
+ * ```
+ */
+export function Redirect(url, statusCode) {
+    if (statusCode === void 0) { statusCode = 302; }
+    return function (target, propertyKey, descriptor) {
+        // Store the redirect information in metadata
+        Reflect.defineMetadata(REDIRECT_KEY, { url: url, statusCode: 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 function (target, propertyKey, _descriptor) {
+        Reflect.defineMetadata(CACHE_KEY, { ttlSeconds: 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) {
+    var opts = __assign({ standardHeaders: true, legacyHeaders: false }, options);
+    return function (target, propertyKey, _descriptor) {
+        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 function (target, propertyKey, _descriptor) {
+        Reflect.defineMetadata(CONTENT_TYPE_KEY, { type: 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) {
+    var opts = __assign({ addPrefix: true, addHeader: true, headerName: 'X-API-Version' }, options);
+    return function (target, propertyKey, _descriptor) {
+        Reflect.defineMetadata(VERSION_KEY, { version: 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 function (target, propertyKey, _descriptor) {
+        Reflect.defineMetadata(TIMEOUT_KEY, { ms: 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 function (target, propertyKey, _descriptor) {
+        var config = __assign({ logEntry: true, logExit: true, logBody: false, logParams: false, logResponse: false }, options);
+        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.
+ *
+ * @param router - Express router instance
+ * @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) || [];
+        // Get controller-level decorators (fallback values)
+        var controllerRateLimit = Reflect.getMetadata(RATE_LIMIT_KEY, ControllerClass);
+        var controllerCache = Reflect.getMetadata(CACHE_KEY, ControllerClass);
+        var controllerTimeout = Reflect.getMetadata(TIMEOUT_KEY, ControllerClass);
+        var controllerVersion = Reflect.getMetadata(VERSION_KEY, ControllerClass);
+        var controllerRoles = Reflect.getMetadata(ROLES_KEY, ControllerClass);
+        var controllerLogConfig = Reflect.getMetadata(LOG_KEY, ControllerClass);
+        var controllerHeaders = Reflect.getMetadata(HEADER_KEY, ControllerClass) || {};
+        routes.forEach(function (_a) {
+            var _b;
+            var _c;
+            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);
+            // Merge controller-level and method-level headers
+            var methodHeaders = Reflect.getMetadata(HEADER_KEY, instance, handlerName) || {};
+            var headers = __assign(__assign({}, controllerHeaders), methodHeaders);
+            var beforeHooks = Reflect.getMetadata(BEFORE_KEY, instance, handlerName) || [];
+            var afterHooks = Reflect.getMetadata(AFTER_KEY, instance, handlerName) || [];
+            var redirect = Reflect.getMetadata(REDIRECT_KEY, instance, handlerName);
+            var contentType = Reflect.getMetadata(CONTENT_TYPE_KEY, instance, handlerName);
+            // Use method-level decorators if present, otherwise fall back to controller-level
+            var roles = Reflect.getMetadata(ROLES_KEY, instance, handlerName) || controllerRoles || [];
+            var cache = Reflect.getMetadata(CACHE_KEY, instance, handlerName) || controllerCache;
+            var rateLimitOptions = Reflect.getMetadata(RATE_LIMIT_KEY, instance, handlerName) || controllerRateLimit;
+            var version = Reflect.getMetadata(VERSION_KEY, instance, handlerName) || controllerVersion;
+            var timeout = Reflect.getMetadata(TIMEOUT_KEY, instance, handlerName) || controllerTimeout;
+            var logConfig = Reflect.getMetadata(LOG_KEY, instance, handlerName) || controllerLogConfig;
+            // Create rate limiter for this specific route if needed
+            var rateLimiter = null;
+            if (rateLimitOptions) {
+                try {
+                    rateLimiter = rateLimiterCache.get(rateLimitOptions);
+                }
+                catch (err) {
+                    getLogger().warn({ err: err }, 'express-rate-limit not available, skipping rate limiting for this route');
+                }
+            }
+            var finalPath = path;
+            if ((_c = version === null || version === void 0 ? void 0 : version.options) === null || _c === void 0 ? void 0 : _c.addPrefix) {
+                finalPath = "/".concat(version.version).concat(path);
+            }
+            var handler = function (req, res, next) { return __awaiter(_this, void 0, void 0, function () {
+                var timeoutId, timedOut, logger, logData, errorResponse, beforeHooks_1, beforeHooks_1_1, fn, e_1_1, args_1, result, awaited, _a, redirectUrl, redirectStatus, _b, _c, _d, k, v, normalized, logger, logData, 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:
+                            // Set start time for duration tracking
+                            req['startTime'] = Date.now();
+                            timedOut = false;
+                            _o.label = 1;
+                        case 1:
+                            _o.trys.push([1, 23, , 24]);
+                            // Handle timeout setup
+                            if (timeout) {
+                                timeoutId = setTimeout(function () {
+                                    if (!res.headersSent && !timedOut) {
+                                        timedOut = true;
+                                        var errorResponse = createFinalErrorResponse(req, HttpStatusCodes.REQUEST_TIMEOUT, 'Request timed out');
+                                        res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(errorResponse);
+                                    }
+                                }, timeout.ms);
+                            }
+                            if (timedOut)
+                                return [2 /*return*/];
+                            if (!rateLimiter) return [3 /*break*/, 3];
+                            return [4 /*yield*/, new Promise(function (resolve, reject) {
+                                    rateLimiter(req, res, function (err) {
+                                        if (err)
+                                            reject(err);
+                                        else
+                                            resolve();
+                                    });
+                                })];
+                        case 2:
+                            _o.sent();
+                            _o.label = 3;
+                        case 3:
+                            // Handle content type
+                            if (!res.headersSent && contentType) {
+                                res.setHeader('Content-Type', contentType.type);
+                            }
+                            // Handle versioning header
+                            if (((_j = version === null || version === void 0 ? void 0 : version.options) === null || _j === void 0 ? void 0 : _j.addHeader) && ((_k = version === null || version === void 0 ? void 0 : version.options) === null || _k === void 0 ? void 0 : _k.headerName) && (version === null || version === void 0 ? void 0 : 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=".concat(cache.ttlSeconds));
+                            }
+                            // Handle logging - entry
+                            if (logConfig === null || logConfig === void 0 ? void 0 : logConfig.logEntry) {
+                                logger = getLogger();
+                                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 && !((_m = (_l = req === null || req === void 0 ? void 0 : req.user) === null || _l === void 0 ? void 0 : _l.roles) === null || _m === void 0 ? void 0 : _m.some(function (role) { return roles.includes(role); }))) {
+                                errorResponse = createFinalErrorResponse(req, HttpStatusCodes.FORBIDDEN, 'Forbidden Insufficient Roles');
+                                res.status(HttpStatusCodes.FORBIDDEN).json(errorResponse);
+                                if (timeoutId) {
+                                    clearTimeout(timeoutId);
+                                }
+                                return [2 /*return*/];
+                            }
+                            // Process static redirect if configured
+                            if (redirect && redirect.url) {
+                                if (timeoutId) {
+                                    clearTimeout(timeoutId);
+                                }
+                                return [2 /*return*/, res.redirect(redirect.statusCode, redirect.url)];
+                            }
+                            _o.label = 4;
+                        case 4:
+                            _o.trys.push([4, 9, 10, 11]);
+                            beforeHooks_1 = __values(beforeHooks), beforeHooks_1_1 = beforeHooks_1.next();
+                            _o.label = 5;
+                        case 5:
+                            if (!!beforeHooks_1_1.done) return [3 /*break*/, 8];
+                            fn = beforeHooks_1_1.value;
+                            return [4 /*yield*/, fn(req, res)];
+                        case 6:
+                            _o.sent();
+                            _o.label = 7;
+                        case 7:
+                            beforeHooks_1_1 = beforeHooks_1.next();
+                            return [3 /*break*/, 5];
+                        case 8: return [3 /*break*/, 11];
+                        case 9:
+                            e_1_1 = _o.sent();
+                            e_1 = { error: e_1_1 };
+                            return [3 /*break*/, 11];
+                        case 10:
+                            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 11:
+                            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*/, 13];
+                            return [4 /*yield*/, result];
+                        case 12:
+                            _a = _o.sent();
+                            return [3 /*break*/, 14];
+                        case 13:
+                            _a = result;
+                            _o.label = 14;
+                        case 14:
+                            awaited = _a;
+                            // Clear timeout if operation completed
+                            if (timeoutId) {
+                                clearTimeout(timeoutId);
+                            }
+                            if (timedOut)
+                                return [2 /*return*/];
+                            // 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)];
+                            }
+                            if (!res.headersSent && typeof awaited !== 'undefined') {
+                                if (httpCode)
+                                    res.status(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];
+                                        normalized = normalizeHeaderValue(v);
+                                        if (typeof normalized !== 'undefined') {
+                                            res.set(k, normalized);
+                                        }
+                                    }
+                                }
+                                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);
+                            }
+                            // Handle logging - exit
+                            if (logConfig === null || logConfig === void 0 ? void 0 : logConfig.logExit) {
+                                logger = getLogger();
+                                logData = {
+                                    method: req.method,
+                                    url: req.originalUrl || req.url,
+                                    statusCode: res.statusCode,
+                                    duration: "".concat(Date.now() - req.startTime, "ms")
+                                };
+                                if (logConfig.logResponse)
+                                    logData.response = awaited;
+                                logger.info({ exit: logData }, 'Route Exit:');
+                            }
+                            _o.label = 15;
+                        case 15:
+                            _o.trys.push([15, 20, 21, 22]);
+                            afterHooks_1 = __values(afterHooks), afterHooks_1_1 = afterHooks_1.next();
+                            _o.label = 16;
+                        case 16:
+                            if (!!afterHooks_1_1.done) return [3 /*break*/, 19];
+                            fn = afterHooks_1_1.value;
+                            return [4 /*yield*/, fn(req, res, awaited)];
+                        case 17:
+                            _o.sent();
+                            _o.label = 18;
+                        case 18:
+                            afterHooks_1_1 = afterHooks_1.next();
+                            return [3 /*break*/, 16];
+                        case 19: return [3 /*break*/, 22];
+                        case 20:
+                            e_2_1 = _o.sent();
+                            e_2 = { error: e_2_1 };
+                            return [3 /*break*/, 22];
+                        case 21:
+                            try {
+                                if (afterHooks_1_1 && !afterHooks_1_1.done && (_h = afterHooks_1.return)) _h.call(afterHooks_1);
+                            }
+                            finally { if (e_2) throw e_2.error; }
+                            return [7 /*endfinally*/];
+                        case 22: return [3 /*break*/, 24];
+                        case 23:
+                            err_1 = _o.sent();
+                            if (timeoutId) {
+                                clearTimeout(timeoutId);
+                            }
+                            next(err_1);
+                            return [3 /*break*/, 24];
+                        case 24: return [2 /*return*/];
+                    }
+                });
+            }); };
+            (_b = router)[method].apply(_b, __spreadArray(__spreadArray([basePath + finalPath], __read(middlewares), false), [handler], false));
+        });
+    });
+}
+// Export for testing purposes
+export { rateLimiterCache };
+//# sourceMappingURL=decorators.utils.js.map