feat: add decorators utils

Co-authored-by: Bavithra bavithrarajagopal@gmail.com

Author: cyber-hari

README.md

@@ -54,6 +54,7 @@ console.log(isEmail("user@example.com")); // true
 - [**String Utilities**](#-string-utilities)
 - [**URL Utilities**](#-url-utilities)
 - [**Validate Utilities**](#-validate-utilities)
+- [**Decorators Utilities**](#decorators-utilities)
 
 ---
 
@@ -408,6 +409,75 @@ A comprehensive suite of string/format validators for safe input and API checks.
 
 ---
 
+# 📧 Decorators Utilities
+
+## Available Decorators
+
+- `@Controller(basePath: string)` – Class decorator to set the base route.
+- `@Get(path)`, `@Post(path)`, `@Put(path)`, `@Patch(path)`, `@Delete(path)`, `@Options(path)`, `@Head(path)`, `@Trace(path)`, `@Connect(path)` – Method decorators for HTTP verbs.
+- `@Use(...middlewares)` – Attach Express-style middleware to a route handler.
+- `@Query(key?)`, `@Param(key?)`, `@Body(key?)`, `@Req()`, `@Res()` – Parameter decorators for extracting request data.
+- `@HttpCode(status)` – Set custom HTTP status code for the response.
+- `@Header(name, value)` – Set custom response headers.
+- `@Before(fn)`, `@After(fn)` – Register before/after hooks for a route handler.
+
+## Example Usage
+
+```typescript
+import {
+  Controller, Get, Post, Use, Query, Param, Body, Req, Res,
+  HttpCode, Header, Before, After, registerControllers, Request, Response, NextFunction
+} from './src/utils/decorators.utils';
+
+// Example middleware
+function logMiddleware(req: Request, res: Response, next: NextFunction) {
+  console.log('Request:', req.method, req.url);
+  next();
+}
+
+// Example before/after hooks
+function beforeHook(req: Request, res: Response) {
+  console.log('Before handler');
+}
+function afterHook(req: Request, res: Response, result: any) {
+  console.log('After handler', result);
+}
+
+@Controller('/api')
+class ExampleController {
+  @Get('/items/:id')
+  @Use(logMiddleware)
+  @HttpCode(200)
+  @Header('X-Example', 'yes')
+  @Before(beforeHook)
+  @After(afterHook)
+  getItem(
+    @Query('q') q: string,
+    @Param('id') id: string,
+    @Body('name') name: string,
+    @Req() req: Request,
+    @Res() res: Response
+  ) {
+    return { q, id, name };
+  }
+
+  @Post('/items')
+  createItem(@Body() body: any) {
+    return { created: true, ...body };
+  }
+}
+
+// Register controllers with your router (Express-like)
+const router = /* your router instance */;
+registerControllers(router, [ExampleController]);
+```
+
+## Notes
+
+- Decorated methods **must** use standard method syntax, not arrow functions or property initializers.
+- All parameter decorators (`@Query`, `@Param`, etc.) are optional and can be used in any order.
+- `registerControllers(router, controllers)` will register all routes and apply middlewares, hooks, status codes, and headers as defined.
+
 ## 🏁 Usage
 
 Import only what you need:

package-lock.json

@@ -47,7 +47,8 @@
   ],
   "dependencies": {
     "abort-controller": "^3.0.0",
-    "pino": "^9.7.0"
+    "pino": "^9.7.0",
+    "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",

package.json

@@ -0,0 +1,235 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import "reflect-metadata";
+
+// --- Sample Express interfaces for type safety ---
+export interface Request {
+  query: any;
+  params: any;
+  body?: any;
+  [key: string]: any;
+}
+export interface Response {
+  json: (body: any) => void;
+  headersSent: boolean;
+  [key: string]: any;
+}
+export type NextFunction = (err?: any) => void;
+export type RequestHandler = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => any;
+export interface Router {
+  [method: string]: (path: string, ...handlers: RequestHandler[]) => void;
+}
+// --- End sample Express interfaces ---
+
+const ROUTES_KEY = Symbol("routes");
+const MIDDLEWARE_KEY = Symbol("middlewares");
+const PARAMS_KEY = Symbol("params");
+
+export type HttpMethod =
+  | "get"
+  | "post"
+  | "put"
+  | "patch"
+  | "delete"
+  | "options"
+  | "head"
+  | "trace"
+  | "connect";
+
+interface RouteDefinition {
+  path: string;
+  method: HttpMethod;
+  handlerName: string;
+}
+
+interface ParamDefinition {
+  index: number;
+  type: "query" | "param" | "body" | "req" | "res";
+  key?: string;
+}
+
+// ---- Route Decorators ----
+function createRouteDecorator(method: HttpMethod) {
+  return (path: string): MethodDecorator => {
+    return (target, propertyKey, descriptor) => {
+      const routes: RouteDefinition[] =
+        Reflect.getMetadata(ROUTES_KEY, target.constructor) || [];
+      routes.push({
+        path,
+        method,
+        handlerName: propertyKey as string,
+      });
+      Reflect.defineMetadata(ROUTES_KEY, routes, target.constructor);
+    };
+  };
+}
+
+export const Get = createRouteDecorator("get");
+export const Post = createRouteDecorator("post");
+export const Put = createRouteDecorator("put");
+export const Patch = createRouteDecorator("patch");
+export const Delete = createRouteDecorator("delete");
+export const Options = createRouteDecorator("options");
+export const Head = createRouteDecorator("head");
+export const Trace = createRouteDecorator("trace");
+export const Connect = createRouteDecorator("connect");
+
+// ---- Controller Decorator ----
+export function Controller(basePath: string): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata("basePath", basePath, target);
+  };
+}
+
+// ---- Middleware Decorator ----
+export function Use(...middlewares: RequestHandler[]): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    const existing: RequestHandler[] =
+      Reflect.getMetadata(MIDDLEWARE_KEY, target, propertyKey as string) || [];
+    Reflect.defineMetadata(
+      MIDDLEWARE_KEY,
+      [...existing, ...middlewares],
+      target,
+      propertyKey as string,
+    );
+  };
+}
+
+// ---- Parameter Decorators ----
+function createParamDecorator(type: ParamDefinition["type"], key?: string) {
+  return (paramKey?: string): ParameterDecorator => {
+    return (target, propertyKey, parameterIndex) => {
+      const params: ParamDefinition[] =
+        Reflect.getMetadata(PARAMS_KEY, target, propertyKey as string) || [];
+      // 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 as string);
+    };
+  };
+}
+
+export const Query = createParamDecorator("query");
+export const Param = createParamDecorator("param");
+export const Body = createParamDecorator("body");
+export const Req = createParamDecorator("req");
+export const Res = createParamDecorator("res");
+
+// Custom HTTP status code decorator
+const HTTP_CODE_KEY = Symbol("httpCode");
+export function HttpCode(status: number): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    Reflect.defineMetadata(
+      HTTP_CODE_KEY,
+      status,
+      target,
+      propertyKey as string,
+    );
+  };
+}
+
+// Custom header decorator
+const HEADER_KEY = Symbol("headers");
+export function Header(name: string, value: string): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    const headers: Record<string, string> =
+      Reflect.getMetadata(HEADER_KEY, target, propertyKey as string) || {};
+    headers[name] = value;
+    Reflect.defineMetadata(HEADER_KEY, headers, target, propertyKey as string);
+  };
+}
+
+// Before/After hooks (not Express middleware, but can be used for logging, etc.)
+const BEFORE_KEY = Symbol("before");
+const AFTER_KEY = Symbol("after");
+export function Before(fn: Function): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    const hooks: Function[] =
+      Reflect.getMetadata(BEFORE_KEY, target, propertyKey as string) || [];
+    hooks.push(fn);
+    Reflect.defineMetadata(BEFORE_KEY, hooks, target, propertyKey as string);
+  };
+}
+export function After(fn: Function): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    const hooks: Function[] =
+      Reflect.getMetadata(AFTER_KEY, target, propertyKey as string) || [];
+    hooks.push(fn);
+    Reflect.defineMetadata(AFTER_KEY, hooks, target, propertyKey as string);
+  };
+}
+
+// ---- Register Controllers ----
+export function registerControllers(router: Router, controllers: any[]) {
+  controllers.forEach((ControllerClass) => {
+    const instance = new ControllerClass();
+    const basePath: string =
+      Reflect.getMetadata("basePath", ControllerClass) || "";
+    const routes: RouteDefinition[] =
+      Reflect.getMetadata(ROUTES_KEY, ControllerClass) || [];
+
+    routes.forEach(({ path, method, handlerName }) => {
+      const middlewares: RequestHandler[] =
+        Reflect.getMetadata(MIDDLEWARE_KEY, instance, handlerName) || [];
+      const params: ParamDefinition[] =
+        Reflect.getMetadata(PARAMS_KEY, instance, handlerName) || [];
+
+      const httpCode: number | undefined = Reflect.getMetadata(
+        HTTP_CODE_KEY,
+        instance,
+        handlerName,
+      );
+      const headers: Record<string, string> =
+        Reflect.getMetadata(HEADER_KEY, instance, handlerName) || {};
+      const beforeHooks: Function[] =
+        Reflect.getMetadata(BEFORE_KEY, instance, handlerName) || [];
+      const afterHooks: Function[] =
+        Reflect.getMetadata(AFTER_KEY, instance, handlerName) || [];
+
+      const handler: RequestHandler = async (req, res, next) => {
+        try {
+          for (const fn of beforeHooks) await fn(req, res);
+          const args: any[] = [];
+          if (params.length) {
+            params.forEach(({ index, type, key }) => {
+              switch (type) {
+                case "query":
+                  args[index] = key ? req.query[key] : req.query;
+                  break;
+                case "param":
+                  args[index] = key ? req.params[key] : req.params;
+                  break;
+                case "body":
+                  args[index] = key ? req.body?.[key] : req.body;
+                  break;
+                case "req":
+                  args[index] = req;
+                  break;
+                case "res":
+                  args[index] = res;
+                  break;
+              }
+            });
+          }
+          const result = (instance as any)[handlerName](...args);
+          // Support both sync and async handlers
+          const awaited = result instanceof Promise ? await result : result;
+          if (!res.headersSent && typeof awaited !== "undefined") {
+            if (httpCode) res.status?.(httpCode);
+            for (const [k, v] of Object.entries(headers)) res.set?.(k, v);
+            res.json(awaited);
+          }
+          for (const fn of afterHooks) await fn(req, res, awaited);
+        } catch (err) {
+          next(err);
+        }
+      };
+
+      (router as any)[method](basePath + path, ...middlewares, handler);
+    });
+  });
+}