feat(decorators): add @ReqCookie and @ReqId decorators for extracting cookies and request IDs

Author: cyber-hari

docs/docs/utils/decorators.md

@@ -23,7 +23,9 @@ These utilities provide a declarative way to define Express routes, middleware,
 - [**`@Req(): ParameterDecorator`**](#req) - Extract the request object.
 - [**`@Res(): ParameterDecorator`**](#res) - Extract the response object.
 - [**`@ReqHeader(key?: string): ParameterDecorator`**](#reqheader) - Extract request headers.
+- [**`@ReqCookie(name?: string): ParameterDecorator`**](#reqcookie) - Extract cookies from the request.
 - [**`@ReqLogger(): ParameterDecorator`**](#reqlogger) - Inject a logger instance.
+- [**`@ReqId(): ParameterDecorator`**](#reqid) - Extract the request ID from headers or request object.
 - [**`@HttpCode(status: number): MethodDecorator`**](#httpcode) - Set a custom HTTP status code for the response.
 - [**`@Header(name: string, value: string): MethodDecorator & ClassDecorator`**](#header) - Add a custom HTTP header to the response.
 - [**`@Headers(headers: Record<string, string> | string, value?: string): MethodDecorator & ClassDecorator`**](#headers) - Add multiple custom HTTP headers to the response.
@@ -689,6 +691,32 @@ getData(
 
 ---
 
+### `@ReqCookie()`
+Extracts cookies from the request.
+
+**Method Signature:**
+```ts
+@ReqCookie(name: string): ParameterDecorator
+```
+
+**Parameters:**
+- `name`: The name of the cookie to extract.
+
+**Returns:** 
+- A parameter decorator.
+
+**Examples:**
+```ts
+import { Get, ReqCookie } from '@catbee/utils';
+
+@Get('/data')
+getData(@ReqCookie('session_id') sessionId: string) {
+  return { sessionId };
+}
+```
+
+---
+
 ### `@ReqLogger()`
 Injects a logger instance.
 
@@ -719,6 +747,29 @@ createItem(@Body() data: any, @ReqLogger() logger: any) {
 
 ---
 
+### `@ReqId()`
+Extracts the request ID from the request headers or the request object.
+
+**Method Signature:**
+```ts
+@ReqId(): ParameterDecorator
+```
+
+**Returns:** 
+- A parameter decorator.
+
+**Examples:**
+```ts
+import { Get, ReqId } from '@catbee/utils';
+
+@Get('/data')
+getData(@ReqId() reqId: string) {
+  return { reqId };
+}
+```
+
+---
+
 ### `@HttpCode()`
 Sets a custom HTTP status code for the response.
 

src/utils/decorators.utils.ts

@@ -72,7 +72,7 @@ interface ParamDefinition {
   /** Parameter position in method signature */
   index: number;
   /** Type of parameter (query, body, etc.) */
-  type: 'query' | 'param' | 'body' | 'req' | 'res' | 'logger' | 'reqHeader';
+  type: 'query' | 'param' | 'body' | 'req' | 'res' | 'logger' | 'reqHeader' | 'reqId' | 'cookie';
   /** Optional key for extracting specific property */
   key?: string;
   /** Optional ParamOptions for advanced extraction */
@@ -552,6 +552,18 @@ function createParamDecorator(type: ParamDefinition['type'], key?: string) {
   };
 }
 
+function createParamDecoratorWithoutParam(type: ParamDefinition['type']) {
+  return (): ParameterDecorator => {
+    return (target, propertyKey, parameterIndex) => {
+      const params: ParamDefinition[] = Reflect.getMetadata(PARAMS_KEY, target as object, propertyKey as string) || [];
+      // Ensure parameters are ordered by index
+      params.push({ index: parameterIndex, type, key: undefined });
+      params.sort((a, b) => a.index - b.index);
+      Reflect.defineMetadata(PARAMS_KEY, params, target as object, propertyKey as string);
+    };
+  };
+}
+
 /**
  * Factory function that creates parameter decorators.
  *
@@ -652,7 +664,20 @@ export const Body = createParamDecorator('body');
  * }
  * ```
  */
-export const ReqLogger = createParamDecorator('logger');
+export const ReqLogger = createParamDecoratorWithoutParam('logger');
+
+/**
+ * Decorator that extracts request ID from headers.
+ * @returns Parameter decorator
+ * @example
+ * ```ts
+ * @Get('/data')
+ * getData(@ReqId() reqId: string) {
+ *  // reqId will contain the value of req.headers['x-request-id'] or req.id
+ * }
+ * ```
+ */
+export const ReqId = createParamDecoratorWithoutParam('reqId');
 
 /**
  * Decorator that extracts request headers.
@@ -669,6 +694,21 @@ export const ReqLogger = createParamDecorator('logger');
  */
 export const ReqHeader = createParamDecorator('reqHeader');
 
+/**
+ * Decorator that extracts cookies from request.
+ * @param key - Optional key to extract specific cookie
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/data')
+ * getData(@ReqCookie('session_id') sessionId: string) {
+ *   // sessionId will contain the value of req.cookies['session_id']
+ * }
+ * ```
+ */
+export const ReqCookie = createParamDecorator('cookie');
+
 /**
  * Decorator that injects the entire request object.
  *
@@ -683,7 +723,7 @@ export const ReqHeader = createParamDecorator('reqHeader');
  * }
  * ```
  */
-export const Req = createParamDecorator('req');
+export const Req = createParamDecoratorWithoutParam('req');
 
 /**
  * Decorator that injects the response object.
@@ -699,7 +739,7 @@ export const Req = createParamDecorator('req');
  * }
  * ```
  */
-export const Res = createParamDecorator('res');
+export const Res = createParamDecoratorWithoutParam('res');
 
 /**
  * Decorator that sets a custom HTTP status code for a response.
@@ -1387,6 +1427,12 @@ export function registerControllers(router: Router, controllers: any[]) {
                 case 'reqHeader':
                   args[index] = key ? req.headers[key.toLowerCase()] : req.headers;
                   break;
+                case 'reqId':
+                  args[index] = req.headers['x-request-id'] || req?.id || undefined;
+                  break;
+                case 'cookie':
+                  args[index] = key ? req.cookies?.[key] : req.cookies;
+                  break;
               }
             });
           }

tests/utils/decorator.utils.test.ts

@@ -27,7 +27,9 @@ import {
   registerControllers,
   Injectable,
   Inject,
-  ReqHeader
+  ReqHeader,
+  ReqCookie,
+  ReqId
 } from '../../src/utils/decorators.utils';
 import { jest } from '@jest/globals';
 import { HttpStatusCodes } from '../../src/utils/http-status-codes';
@@ -153,6 +155,79 @@ describe('Decorators and registerControllers', () => {
     });
   });
 
+  it('should extract request ID with @ReqId and respect options', async () => {
+    mockReq.headers['x-request-id'] = 'test-id-123';
+
+    @Controller('/reqid-options')
+    class ReqIdOptionsController {
+      @Get('/test')
+      testReqId(@ReqId() plainReqId: string) {
+        return { plainReqId };
+      }
+    }
+
+    registerControllers(mockRouter, [ReqIdOptionsController]);
+    const [, ...handlers] = mockRouter.get.mock.calls[0];
+    const routeHandler = handlers[handlers.length - 1];
+
+    await routeHandler(mockReq, mockRes, mockNext);
+    expect(mockRes.json).toHaveBeenCalledWith({
+      plainReqId: 'test-id-123'
+    });
+
+    // Test with request ID from req.id property
+    mockReq.headers['x-request-id'] = undefined;
+    mockReq.id = 'test-id-456';
+
+    await routeHandler(mockReq, mockRes, mockNext);
+    expect(mockRes.json).toHaveBeenCalledWith({
+      plainReqId: 'test-id-456'
+    });
+
+    // Test with missing request ID
+    mockReq.headers['x-request-id'] = undefined;
+    mockReq.id = undefined;
+    mockRes.json = jest.fn();
+
+    await routeHandler(mockReq, mockRes, mockNext);
+
+    expect(mockRes.json).toHaveBeenCalledWith({ plainReqId: undefined });
+  });
+
+  it('should extract cookies with @ReqCookie and respect options', async () => {
+    mockReq.cookies = {
+      JSESSION: 'header.payload.signature'
+    };
+
+    @Controller('/cookie-options')
+    class CookieOptionsController {
+      @Get('/test')
+      testCookieOptions(
+        @ReqCookie('JSESSION') sessionToken: string,
+        @ReqCookie('missing') missingCookie: string,
+        @ReqCookie() allCookies: Record<string, string>
+      ) {
+        return {
+          sessionToken,
+          missingCookie,
+          allCookies
+        };
+      }
+    }
+
+    registerControllers(mockRouter, [CookieOptionsController]);
+    const [, ...handlers] = mockRouter.get.mock.calls[0];
+    const routeHandler = handlers[handlers.length - 1];
+
+    await routeHandler(mockReq, mockRes, mockNext);
+
+    expect(mockRes.json).toHaveBeenCalledWith({
+      sessionToken: 'header.payload.signature',
+      missingCookie: undefined,
+      allCookies: { JSESSION: 'header.payload.signature' }
+    });
+  });
+
   it('should handle async route handlers', async () => {
     @Controller('/async')
     class AsyncController {