@catbee/utils 1.0.5 → 2.0.0-next.0

package/decorators/index.mjs

@@ -0,0 +1,872 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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 '@catbee/utils/logger';
+import { createFinalErrorResponse } from '@catbee/utils/response';
+import { HttpStatusCodes } from '@catbee/utils/http-status-codes';
+import { TTLCache } from '@catbee/utils/cache';
+import { BadRequestException } from '@catbee/utils/exception';
+import { optionalRequire } from '@catbee/utils/async';
+import { DependencyErrors } from '@catbee/utils/server';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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");
+var RateLimiterCache = class RateLimiterCache2 {
+  static {
+    __name(this, "RateLimiterCache");
+  }
+  rateLimit;
+  cache;
+  constructor(maxSize = 100, ttlMs = 5 * 60 * 1e3) {
+    this.cache = new TTLCache({
+      maxSize,
+      ttlMs
+    });
+    const rateLimitModule = optionalRequire("express-rate-limit");
+    if (rateLimitModule) this.rateLimit = rateLimitModule.rateLimit;
+  }
+  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;
+    }
+    if (!this.rateLimit) {
+      throw new Error(DependencyErrors["express-rate-limit"]);
+    }
+    const limiter = this.rateLimit({
+      ...options,
+      handler: /* @__PURE__ */ __name((req, res) => {
+        const errorResponse = createFinalErrorResponse(req, HttpStatusCodes.TOO_MANY_REQUESTS, "Too Many Requests");
+        res.status(HttpStatusCodes.TOO_MANY_REQUESTS).json(errorResponse);
+      }, "handler")
+    });
+    this.cache.set(key, {
+      limiter,
+      config: key
+    });
+    return limiter;
+  }
+  clear() {
+    this.cache.clear();
+  }
+  size() {
+    return this.cache.size();
+  }
+  destroy() {
+    this.cache.destroy();
+  }
+};
+var rateLimiterCache = new RateLimiterCache();
+var DIContainer = class {
+  static {
+    __name(this, "DIContainer");
+  }
+  instances = /* @__PURE__ */ new Map();
+  constructing = /* @__PURE__ */ new Map();
+  propertyInjections = /* @__PURE__ */ new Map();
+  register(target) {
+    if (!this.instances.has(target) && !this.constructing.has(target)) ;
+  }
+  /**
+  * Register a property injection to be resolved when the target class is instantiated
+  */
+  registerPropertyInjection(target, propertyKey, injectClass) {
+    const targetClass = target.constructor;
+    if (!this.propertyInjections.has(targetClass)) {
+      this.propertyInjections.set(targetClass, []);
+    }
+    this.propertyInjections.get(targetClass).push({
+      targetClass: injectClass,
+      propertyKey
+    });
+  }
+  get(target) {
+    if (this.instances.has(target)) {
+      return this.instances.get(target);
+    }
+    if (this.constructing.has(target)) {
+      return this.constructing.get(target);
+    }
+    let proxy = {};
+    this.constructing.set(target, proxy);
+    const paramTypes = Reflect.getMetadata("design:paramtypes", target) || [];
+    const dependencies = paramTypes.map((dep) => this.get(dep));
+    const instance = new target(...dependencies);
+    this.applyPropertyInjections(target, instance);
+    Object.assign(proxy, instance);
+    this.instances.set(target, proxy);
+    this.constructing.delete(target);
+    Object.setPrototypeOf(proxy, target.prototype);
+    return proxy;
+  }
+  applyPropertyInjections(targetClass, instance) {
+    const injections = this.propertyInjections.get(targetClass) || [];
+    for (const injection of injections) {
+      const dependency = this.get(injection.targetClass);
+      instance[injection.propertyKey] = dependency;
+    }
+  }
+  clear() {
+    this.instances.clear();
+    this.constructing.clear();
+    this.propertyInjections.clear();
+  }
+};
+var diContainer = new DIContainer();
+function normalizeHeaderValue(value) {
+  if (typeof value === "undefined") return void 0;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  return String(value);
+}
+__name(normalizeHeaderValue, "normalizeHeaderValue");
+function Injectable() {
+  return (target) => {
+    Reflect.defineMetadata("injectable", true, target);
+    diContainer.register(target);
+  };
+}
+__name(Injectable, "Injectable");
+function Inject(targetClass) {
+  return (target, propertyKey) => {
+    diContainer.registerPropertyInjection(target, propertyKey, targetClass);
+    Object.defineProperty(target, propertyKey, {
+      configurable: true,
+      get: /* @__PURE__ */ __name(function() {
+        const value = Object.getOwnPropertyDescriptor(this, propertyKey)?.value;
+        if (value !== void 0) return value;
+        const injectedValue = diContainer.get(targetClass);
+        Object.defineProperty(this, propertyKey, {
+          value: injectedValue,
+          writable: true,
+          configurable: true
+        });
+        return injectedValue;
+      }, "get"),
+      set: /* @__PURE__ */ __name(function(value) {
+        Object.defineProperty(this, propertyKey, {
+          value,
+          writable: true,
+          configurable: true
+        });
+      }, "set")
+    });
+  };
+}
+__name(Inject, "Inject");
+function inject(targetClass) {
+  return diContainer.get(targetClass);
+}
+__name(inject, "inject");
+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);
+    };
+  };
+}
+__name(createRouteDecorator, "createRouteDecorator");
+var Get = createRouteDecorator("get");
+var Post = createRouteDecorator("post");
+var Put = createRouteDecorator("put");
+var Patch = createRouteDecorator("patch");
+var Delete = createRouteDecorator("delete");
+var Options = createRouteDecorator("options");
+var Head = createRouteDecorator("head");
+var Trace = createRouteDecorator("trace");
+var Connect = createRouteDecorator("connect");
+function Controller(basePath) {
+  return (target) => {
+    Reflect.defineMetadata("basePath", basePath, target);
+  };
+}
+__name(Controller, "Controller");
+function Use(...middlewares) {
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      const existing = Reflect.getMetadata(MIDDLEWARE_KEY, target) || [];
+      Reflect.defineMetadata(MIDDLEWARE_KEY, [
+        ...existing,
+        ...middlewares
+      ], target);
+    } else {
+      const existing = Reflect.getMetadata(MIDDLEWARE_KEY, target, propertyKey) || [];
+      Reflect.defineMetadata(MIDDLEWARE_KEY, [
+        ...existing,
+        ...middlewares
+      ], target, propertyKey);
+    }
+  };
+}
+__name(Use, "Use");
+function defineParamMetadata(target, propertyKey, parameterIndex, type, key) {
+  const params = Reflect.getMetadata(PARAMS_KEY, target, propertyKey) || [];
+  params.push({
+    index: parameterIndex,
+    type,
+    key
+  });
+  params.sort((a, b) => a.index - b.index);
+  Reflect.defineMetadata(PARAMS_KEY, params, target, propertyKey);
+}
+__name(defineParamMetadata, "defineParamMetadata");
+function createParamDecorator(type, key) {
+  return (paramKey) => {
+    return (target, propertyKey, parameterIndex) => {
+      defineParamMetadata(target, propertyKey, parameterIndex, type, paramKey ?? key);
+    };
+  };
+}
+__name(createParamDecorator, "createParamDecorator");
+function createParamDecoratorWithoutParam(type) {
+  return () => {
+    return (target, propertyKey, parameterIndex) => {
+      defineParamMetadata(target, propertyKey, parameterIndex, type, void 0);
+    };
+  };
+}
+__name(createParamDecoratorWithoutParam, "createParamDecoratorWithoutParam");
+function createApiUrlParamDecorator(type, key) {
+  return (paramKey, options) => {
+    return (target, propertyKey, parameterIndex) => {
+      const params = Reflect.getMetadata(PARAMS_KEY, target, propertyKey) || [];
+      let paramOptions = void 0;
+      if (typeof options === "object") {
+        paramOptions = {};
+        paramOptions.type = "string";
+        paramOptions.dataType = "single";
+        paramOptions.delimiter = ",";
+        paramOptions.required = false;
+        paramOptions.throwError = true;
+        paramOptions = {
+          ...paramOptions,
+          ...options
+        };
+      }
+      params.push({
+        index: parameterIndex,
+        type,
+        key: paramKey || key,
+        options: paramOptions
+      });
+      params.sort((a, b) => a.index - b.index);
+      Reflect.defineMetadata(PARAMS_KEY, params, target, propertyKey);
+    };
+  };
+}
+__name(createApiUrlParamDecorator, "createApiUrlParamDecorator");
+var Query = createApiUrlParamDecorator("query");
+var Param = createApiUrlParamDecorator("param");
+var Body = createParamDecorator("body");
+var ReqLogger = createParamDecoratorWithoutParam("logger");
+var ReqId = createParamDecoratorWithoutParam("reqId");
+var ReqHeader = createParamDecorator("reqHeader");
+var ReqCookie = createParamDecorator("cookie");
+var Req = createParamDecoratorWithoutParam("req");
+var Res = createParamDecoratorWithoutParam("res");
+function HttpCode(status) {
+  return (target, propertyKey, _descriptor) => {
+    Reflect.defineMetadata(HTTP_CODE_KEY, status, target, propertyKey);
+  };
+}
+__name(HttpCode, "HttpCode");
+function Header(name, value) {
+  return Headers(name, value);
+}
+__name(Header, "Header");
+function Headers(headers, value) {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === "undefined") {
+      const existing = Reflect.getMetadata(HEADER_KEY, target) || {};
+      const newHeaders = typeof headers === "string" ? {
+        [headers]: value
+      } : headers;
+      Reflect.defineMetadata(HEADER_KEY, {
+        ...existing,
+        ...newHeaders
+      }, target);
+    } else {
+      const existing = Reflect.getMetadata(HEADER_KEY, target, propertyKey) || {};
+      const newHeaders = typeof headers === "string" ? {
+        [headers]: value
+      } : headers;
+      Reflect.defineMetadata(HEADER_KEY, {
+        ...existing,
+        ...newHeaders
+      }, target, propertyKey);
+    }
+  };
+}
+__name(Headers, "Headers");
+function Before(fn) {
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      const hooks = Reflect.getMetadata(BEFORE_KEY, target) || [];
+      hooks.push(fn);
+      Reflect.defineMetadata(BEFORE_KEY, hooks, target);
+    } else {
+      const hooks = Reflect.getMetadata(BEFORE_KEY, target, propertyKey) || [];
+      hooks.push(fn);
+      Reflect.defineMetadata(BEFORE_KEY, hooks, target, propertyKey);
+    }
+  };
+}
+__name(Before, "Before");
+function After(fn) {
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      const hooks = Reflect.getMetadata(AFTER_KEY, target) || [];
+      hooks.push(fn);
+      Reflect.defineMetadata(AFTER_KEY, hooks, target);
+    } else {
+      const hooks = Reflect.getMetadata(AFTER_KEY, target, propertyKey) || [];
+      hooks.push(fn);
+      Reflect.defineMetadata(AFTER_KEY, hooks, target, propertyKey);
+    }
+  };
+}
+__name(After, "After");
+function Roles(...roles) {
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      Reflect.defineMetadata(ROLES_KEY, roles, target);
+    } else {
+      Reflect.defineMetadata(ROLES_KEY, roles, target, propertyKey);
+    }
+  };
+}
+__name(Roles, "Roles");
+function Redirect(url, statusCode = 302) {
+  return (target, propertyKey, descriptor) => {
+    Reflect.defineMetadata(REDIRECT_KEY, {
+      url,
+      statusCode
+    }, target, propertyKey);
+    return descriptor;
+  };
+}
+__name(Redirect, "Redirect");
+function Cache(ttlSeconds) {
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      Reflect.defineMetadata(CACHE_KEY, {
+        ttlSeconds
+      }, target);
+    } else {
+      Reflect.defineMetadata(CACHE_KEY, {
+        ttlSeconds
+      }, target, propertyKey);
+    }
+  };
+}
+__name(Cache, "Cache");
+function RateLimit(options) {
+  const opts = {
+    standardHeaders: true,
+    legacyHeaders: false,
+    ...options
+  };
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      Reflect.defineMetadata(RATE_LIMIT_KEY, opts, target);
+    } else {
+      Reflect.defineMetadata(RATE_LIMIT_KEY, opts, target, propertyKey);
+    }
+  };
+}
+__name(RateLimit, "RateLimit");
+function ContentType(type) {
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      Reflect.defineMetadata(CONTENT_TYPE_KEY, {
+        type
+      }, target);
+    } else {
+      Reflect.defineMetadata(CONTENT_TYPE_KEY, {
+        type
+      }, target, propertyKey);
+    }
+  };
+}
+__name(ContentType, "ContentType");
+function Version(version, options) {
+  const opts = {
+    addPrefix: true,
+    addHeader: true,
+    headerName: "X-API-Version",
+    ...options
+  };
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      Reflect.defineMetadata(VERSION_KEY, {
+        version,
+        options: opts
+      }, target);
+    } else {
+      Reflect.defineMetadata(VERSION_KEY, {
+        version,
+        options: opts
+      }, target, propertyKey);
+    }
+  };
+}
+__name(Version, "Version");
+function Timeout(ms) {
+  return (target, propertyKey, _descriptor) => {
+    if (typeof propertyKey === "undefined") {
+      Reflect.defineMetadata(TIMEOUT_KEY, {
+        ms
+      }, target);
+    } else {
+      Reflect.defineMetadata(TIMEOUT_KEY, {
+        ms
+      }, target, propertyKey);
+    }
+  };
+}
+__name(Timeout, "Timeout");
+function Log(options) {
+  return (target, propertyKey, _descriptor) => {
+    const config = {
+      logEntry: true,
+      logExit: true,
+      logBody: false,
+      logParams: false,
+      logResponse: false,
+      ...options
+    };
+    if (typeof propertyKey === "undefined") {
+      Reflect.defineMetadata(LOG_KEY, config, target);
+    } else {
+      Reflect.defineMetadata(LOG_KEY, config, target, propertyKey);
+    }
+  };
+}
+__name(Log, "Log");
+function registerControllers(router, controllers) {
+  controllers.forEach((ControllerClass) => {
+    if (!Reflect.getMetadata("injectable", ControllerClass)) {
+      Reflect.defineMetadata("injectable", true, ControllerClass);
+      diContainer.register(ControllerClass);
+    }
+    const instance = diContainer.get(ControllerClass);
+    let basePath = Reflect.getMetadata("basePath", ControllerClass) || "";
+    const routes = Reflect.getMetadata(ROUTES_KEY, ControllerClass) || [];
+    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) || {};
+    const controllerMiddlewares = Reflect.getMetadata(MIDDLEWARE_KEY, ControllerClass) || [];
+    const controllerBeforeHooks = Reflect.getMetadata(BEFORE_KEY, ControllerClass) || [];
+    const controllerAfterHooks = Reflect.getMetadata(AFTER_KEY, ControllerClass) || [];
+    const controllerContentType = Reflect.getMetadata(CONTENT_TYPE_KEY, ControllerClass);
+    if (controllerVersion?.options?.addPrefix) {
+      basePath = `/${controllerVersion.version}${basePath || ""}`;
+    }
+    routes.forEach(({ path, method, handlerName }) => {
+      const methodMiddlewares = Reflect.getMetadata(MIDDLEWARE_KEY, instance, handlerName) || [];
+      const params = Reflect.getMetadata(PARAMS_KEY, instance, handlerName) || [];
+      const httpCode = Reflect.getMetadata(HTTP_CODE_KEY, instance, handlerName);
+      const methodHeaders = Reflect.getMetadata(HEADER_KEY, instance, handlerName) || {};
+      const headers = {
+        ...controllerHeaders,
+        ...methodHeaders
+      };
+      const middlewares = [
+        ...controllerMiddlewares,
+        ...methodMiddlewares
+      ];
+      const methodBeforeHooks = Reflect.getMetadata(BEFORE_KEY, instance, handlerName) || [];
+      const methodAfterHooks = Reflect.getMetadata(AFTER_KEY, instance, handlerName) || [];
+      const beforeHooks = [
+        ...controllerBeforeHooks,
+        ...methodBeforeHooks
+      ];
+      const afterHooks = [
+        ...methodAfterHooks,
+        ...controllerAfterHooks
+      ];
+      const redirect = Reflect.getMetadata(REDIRECT_KEY, instance, handlerName);
+      const methodContentType = Reflect.getMetadata(CONTENT_TYPE_KEY, instance, handlerName);
+      const contentType = methodContentType || controllerContentType;
+      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 methodVersion = Reflect.getMetadata(VERSION_KEY, instance, handlerName);
+      const version = methodVersion || controllerVersion;
+      const timeout = Reflect.getMetadata(TIMEOUT_KEY, instance, handlerName) || controllerTimeout;
+      const logConfig = Reflect.getMetadata(LOG_KEY, instance, handlerName) || controllerLogConfig;
+      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 (methodVersion?.options?.addPrefix && methodVersion.version !== controllerVersion?.version) {
+        finalPath = `/${methodVersion.version}${path}`;
+      }
+      const handler = /* @__PURE__ */ __name(async (req, res, next) => {
+        req["startTime"] = Date.now();
+        let timeoutId;
+        let timedOut = false;
+        try {
+          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;
+          if (rateLimiter) {
+            await new Promise((resolve, reject) => {
+              rateLimiter(req, res, (err) => {
+                if (err) reject(err);
+                else resolve();
+              });
+            });
+          }
+          if (!res.headersSent && contentType) {
+            res.setHeader("Content-Type", contentType.type);
+          }
+          if (version?.options?.addHeader && version?.options?.headerName && version?.version) {
+            if (!res.headersSent) {
+              res.setHeader(version.options.headerName, version.version);
+            }
+          }
+          if (cache && !res.headersSent) {
+            res.setHeader("Cache-Control", `public, max-age=${cache.ttlSeconds}`);
+          }
+          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:");
+          }
+          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;
+          }
+          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, options }) => {
+              let rawValue;
+              switch (type) {
+                case "query":
+                  rawValue = key ? req.query[key] : req.query;
+                  args[index] = options ? applyParamOptions(rawValue, options, key) : rawValue;
+                  break;
+                case "param":
+                  rawValue = key ? req.params[key] : req.params;
+                  args[index] = options ? applyParamOptions(rawValue, options, key) : rawValue;
+                  break;
+                case "body":
+                  args[index] = key ? req.body?.[key] : req.body;
+                  break;
+                case "req":
+                  args[index] = req;
+                  break;
+                case "res":
+                  args[index] = res;
+                  break;
+                case "logger":
+                  args[index] = getLogger();
+                  break;
+                case "reqHeader":
+                  args[index] = key ? req.headers[key.toLowerCase()] : req.headers;
+                  break;
+                case "reqId":
+                  args[index] = req.headers["x-request-id"] || req?.id || void 0;
+                  break;
+                case "cookie":
+                  args[index] = key ? req.cookies?.[key] : req.cookies;
+                  break;
+              }
+            });
+          }
+          const result = instance[handlerName](...args);
+          const awaited = result instanceof Promise ? await result : result;
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+          }
+          if (timedOut) return;
+          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);
+          }
+          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);
+          }
+          next(err);
+        }
+      }, "handler");
+      router[method](basePath + finalPath, ...middlewares, handler);
+    });
+  });
+}
+__name(registerControllers, "registerControllers");
+function applyParamOptions(rawValue, options, key) {
+  if (!options) return rawValue;
+  let value = rawValue;
+  const paramName = key ? `: ${key}` : "";
+  if (value === void 0 || value === null || value === "") {
+    if ("default" in options) {
+      value = options.default;
+    }
+  }
+  if (options.required && (value === void 0 || value === null || value === "")) {
+    throw new BadRequestException(`Required parameter missing${paramName}`);
+  }
+  if (value !== void 0 && value !== null) {
+    if (options.dataType === "array") {
+      const delimiter = options.delimiter || ",";
+      if (typeof value === "string") {
+        value = value.split(delimiter).map((v) => v.trim());
+      } else if (!Array.isArray(value)) {
+        value = [
+          value
+        ];
+      }
+      if (options.type === "string" && options.pattern) {
+        const hasInvalidPattern = value.some((v) => !options.pattern.test(v));
+        if (hasInvalidPattern) {
+          throw new BadRequestException(`Parameter '${key}' array contains values that do not match pattern: ${options.patternName || options.pattern}`);
+        }
+      }
+      if (options.type === "number" && options.pattern) {
+        const hasInvalidPattern = value.some((v) => !options.pattern.test(String(v)));
+        if (hasInvalidPattern) {
+          throw new BadRequestException(`Parameter '${key}' array contains values that do not match pattern: ${options.patternName || options.pattern}`);
+        }
+      }
+      if (options.type === "number" && options.throwError !== false) {
+        const hasInvalidNumber = value.some((v) => isNaN(Number(v)));
+        if (hasInvalidNumber) {
+          throw new BadRequestException(`Type error: expected number array${paramName}`);
+        }
+        if (options.min !== void 0) {
+          const hasBelowMin = value.some((v) => Number(v) < options.min);
+          if (hasBelowMin) {
+            throw new BadRequestException(`Validation error: number array values must be >= ${options.min}${paramName}`);
+          }
+        }
+        if (options.max !== void 0) {
+          const hasAboveMax = value.some((v) => Number(v) > options.max);
+          if (hasAboveMax) {
+            throw new BadRequestException(`Validation error: number array values must be <= ${options.max}${paramName}`);
+          }
+        }
+      }
+      if (options.type === "boolean" && options.throwError !== false) {
+        const hasInvalidBoolean = value.some((v) => !isValidBooleanInput(v));
+        if (hasInvalidBoolean) {
+          throw new BadRequestException(`Type error: expected boolean array${paramName}`);
+        }
+      }
+      if (options.type) {
+        value = value.map((v) => convertType(v, options.type || "string"));
+      }
+    } else if (options.dataType === "object") {
+      if (typeof value === "string") {
+        try {
+          value = JSON.parse(value);
+        } catch (_e) {
+          if (options.throwError !== false) {
+            throw new BadRequestException(`Invalid JSON object${paramName}`);
+          }
+        }
+      }
+    } else if (options.type) {
+      const originalValue = value;
+      value = convertType(value, options.type);
+      if (options.throwError === false) {
+        if (options.type === "number" && typeof value === "number") {
+          if (options.min !== void 0 && value < options.min) {
+            value = void 0;
+          }
+          if (options.max !== void 0 && value > options.max) {
+            value = void 0;
+          }
+        }
+      }
+      if (options.type === "string" && options.pattern && typeof value === "string" && !options.pattern.test(value)) {
+        throw new BadRequestException(`Parameter '${key}' does not match pattern: ${options.patternName || options.pattern}`);
+      } else if (options.type === "number" && options.pattern && typeof value === "number" && !options.pattern.test(String(value))) {
+        throw new BadRequestException(`Parameter '${key}' does not match pattern: ${options.patternName || options.pattern}`);
+      }
+      if (options.throwError !== false) {
+        if (options.type === "number" && typeof value === "number" && isNaN(value)) {
+          throw new BadRequestException(`Type error: expected number${paramName}`);
+        }
+        if (options.type === "number" && typeof value === "number") {
+          if (options.min !== void 0 && value < options.min) {
+            throw new BadRequestException(`Validation error: number must be >= ${options.min}${paramName}`);
+          }
+          if (options.max !== void 0 && value > options.max) {
+            throw new BadRequestException(`Validation error: number must be <= ${options.max}${paramName}`);
+          }
+        }
+        if (options.type === "boolean" && !isValidBooleanInput(originalValue)) {
+          throw new BadRequestException(`Type error: expected boolean${paramName}`);
+        }
+      }
+    }
+  }
+  if (options.transform && typeof options.transform === "function") {
+    value = options.transform(value);
+  }
+  if (options.validate && typeof options.validate === "function") {
+    if (!options.validate(value)) {
+      if (options.throwError !== false) {
+        throw new BadRequestException(`Parameter validation failed${paramName}`);
+      }
+      return void 0;
+    }
+  }
+  return value;
+}
+__name(applyParamOptions, "applyParamOptions");
+function isValidBooleanInput(value) {
+  if (typeof value === "boolean") return true;
+  if (typeof value === "number") return value === 0 || value === 1;
+  if (typeof value === "string") {
+    const normalizedValue = value.toLowerCase().trim();
+    return [
+      "true",
+      "false",
+      "0",
+      "1",
+      "yes",
+      "no"
+    ].includes(normalizedValue);
+  }
+  return false;
+}
+__name(isValidBooleanInput, "isValidBooleanInput");
+function convertType(value, type) {
+  if (value === void 0 || value === null) {
+    return value;
+  }
+  switch (type) {
+    case "number":
+      return Number(value);
+    case "boolean":
+      if (typeof value === "string") {
+        const normalizedValue = value.toLowerCase().trim();
+        return normalizedValue === "true" || normalizedValue === "1" || normalizedValue === "yes";
+      }
+      return value === true || value === 1;
+    case "string":
+    default:
+      return String(value);
+  }
+}
+__name(convertType, "convertType");
+
+export { After, Before, Body, Cache, Connect, ContentType, Controller, DIContainer, Delete, Get, Head, Header, Headers, HttpCode, Inject, Injectable, Log, Options, Param, Patch, Post, Put, Query, RateLimit, Redirect, Req, ReqCookie, ReqHeader, ReqId, ReqLogger, Res, Roles, Timeout, Trace, Use, Version, createParamDecorator, createParamDecoratorWithoutParam, inject, registerControllers };