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

package/build/esnext/utils/decorators.utils.js

@@ -0,0 +1,877 @@
+/*
+ * 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.
+ */
+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.
+ */
+export class RateLimiterCache {
+    constructor(maxSize = 100, ttlMs = 5 * 60 * 1000) {
+        this.cache = new TTLCache({
+            maxSize,
+            ttlMs
+        });
+    }
+    generateKey(options) {
+        return `${options.max}:${options.windowMs}:${options.standardHeaders}:${options.legacyHeaders}`;
+    }
+    get(options) {
+        const key = this.generateKey(options);
+        const cached = this.cache.get(key);
+        if (cached) {
+            return cached.limiter;
+        }
+        // Create new limiter
+        const limiter = rateLimit(Object.assign(Object.assign({}, 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;
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size();
+    }
+    destroy() {
+        this.cache.destroy();
+    }
+}
+// Global cache instance
+const rateLimiterCache = new RateLimiterCache();
+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);
+}
+/**
+ * Factory function that creates HTTP method decorators.
+ *
+ * @param method - HTTP method to create decorator for
+ * @returns A method decorator function
+ */
+function createRouteDecorator(method) {
+    return (path) => {
+        return (target, propertyKey, descriptor) => {
+            const routes = Reflect.getMetadata(ROUTES_KEY, target.constructor) || [];
+            routes.push({
+                path,
+                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 const 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 const Post = createRouteDecorator('post');
+/**
+ * Decorator for PUT HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export const Put = createRouteDecorator('put');
+/**
+ * Decorator for PATCH HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export const Patch = createRouteDecorator('patch');
+/**
+ * Decorator for DELETE HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export const Delete = createRouteDecorator('delete');
+/**
+ * Decorator for OPTIONS HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export const Options = createRouteDecorator('options');
+/**
+ * Decorator for HEAD HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export const Head = createRouteDecorator('head');
+/**
+ * Decorator for TRACE HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export const Trace = createRouteDecorator('trace');
+/**
+ * Decorator for CONNECT HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+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.
+ *
+ * @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 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(...middlewares) {
+    return (target, propertyKey, _descriptor) => {
+        const existing = Reflect.getMetadata(MIDDLEWARE_KEY, target, propertyKey) || [];
+        Reflect.defineMetadata(MIDDLEWARE_KEY, [...existing, ...middlewares], 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 (paramKey) => {
+        return (target, propertyKey, parameterIndex) => {
+            const params = Reflect.getMetadata(PARAMS_KEY, target, propertyKey) || [];
+            // Ensure parameters are ordered by index
+            params.push({ index: parameterIndex, type, key: paramKey || key });
+            params.sort((a, b) => 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 const 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 const 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 const 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 const 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 const 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 (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 (target, propertyKey) => {
+        const existing = Reflect.getMetadata(HEADER_KEY, target, propertyKey) || {};
+        const newHeaders = typeof headers === 'string' ? { [headers]: value } : headers;
+        Reflect.defineMetadata(HEADER_KEY, Object.assign(Object.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 (target, propertyKey, _descriptor) => {
+        const 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 (target, propertyKey, _descriptor) => {
+        const 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(...roles) {
+    return (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 = 302) {
+    return (target, propertyKey, descriptor) => {
+        // Store the redirect information in metadata
+        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) => {
+        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 = Object.assign({ standardHeaders: true, legacyHeaders: false }, options);
+    return (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 (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 = Object.assign({ addPrefix: true, addHeader: true, headerName: 'X-API-Version' }, options);
+    return (target, propertyKey, _descriptor) => {
+        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) => {
+        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 = Object.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) {
+    controllers.forEach(ControllerClass => {
+        const instance = new 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 }) => {
+            var _a;
+            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 = Object.assign(Object.assign({}, 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 ((_a = version === null || version === void 0 ? void 0 : version.options) === null || _a === void 0 ? void 0 : _a.addPrefix) {
+                finalPath = `/${version.version}${path}`;
+            }
+            const handler = async (req, res, next) => {
+                var _a, _b, _c, _d;
+                // 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);
+                            }
+                        }, 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 (((_a = version === null || version === void 0 ? void 0 : version.options) === null || _a === void 0 ? void 0 : _a.addHeader) && ((_b = version === null || version === void 0 ? void 0 : version.options) === null || _b === void 0 ? void 0 : _b.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=${cache.ttlSeconds}`);
+                    }
+                    // Handle logging - entry
+                    if (logConfig === null || logConfig === void 0 ? void 0 : 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 && !((_d = (_c = req === null || req === void 0 ? void 0 : req.user) === null || _c === void 0 ? void 0 : _c.roles) === null || _d === void 0 ? void 0 : _d.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 }) => {
+                            var _a;
+                            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 ? (_a = req.body) === null || _a === void 0 ? void 0 : _a[key] : req.body;
+                                    break;
+                                case 'req':
+                                    args[index] = req;
+                                    break;
+                                case 'res':
+                                    args[index] = res;
+                                    break;
+                            }
+                        });
+                    }
+                    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);
+                            }
+                        }
+                        res.json(awaited);
+                    }
+                    // Handle logging - exit
+                    if (logConfig === null || logConfig === void 0 ? void 0 : 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);
+                    }
+                    next(err);
+                }
+            };
+            router[method](basePath + finalPath, ...middlewares, handler);
+        });
+    });
+}
+// Export for testing purposes
+export { rateLimiterCache };
+//# sourceMappingURL=decorators.utils.js.map