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.
@@ -83,7 +85,7 @@ interface ParamDefinition {
 
 // Parameter options for advanced extraction
 interface ParamOptions<T = any> {
-  type: 'string' | 'number' | 'boolean';
+  type?: 'string' | 'number' | 'boolean';
   dataType?: 'single' | 'array' | 'object';
   delimiter?: string;
   default?: T;
@@ -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 */
@@ -504,7 +504,7 @@ export function Use(...middlewares: RequestHandler[]): MethodDecorator & ClassDe
  */
 export interface ParamOptions<T = any> {
   /** Base type of the parameter (default: 'string') */
-  type: 'string' | 'number' | 'boolean';
+  type?: 'string' | 'number' | 'boolean';
 
   /** Data structure type (default: 'single') */
   dataType?: 'single' | 'array' | 'object';
@@ -540,14 +540,36 @@ export interface ParamOptions<T = any> {
   transform?: (value: any) => any;
 }
 
-function createParamDecorator(type: ParamDefinition['type'], key?: string) {
+function defineParamMetadata(
+  target: any,
+  propertyKey: string | symbol,
+  parameterIndex: number,
+  type: ParamDefinition['type'],
+  key: string | undefined
+) {
+  const params: ParamDefinition[] = 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);
+}
+
+export function createParamDecorator(
+  type: ParamDefinition['type'],
+  key?: string
+): (paramKey?: string) => ParameterDecorator {
   return (paramKey?: string): 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: paramKey || key });
-      params.sort((a, b) => a.index - b.index);
-      Reflect.defineMetadata(PARAMS_KEY, params, target as object, propertyKey as string);
+      defineParamMetadata(target, propertyKey as string, parameterIndex, type, paramKey ?? key);
+    };
+  };
+}
+
+export function createParamDecoratorWithoutParam(type: ParamDefinition['type']): () => ParameterDecorator {
+  return (): ParameterDecorator => {
+    return (target, propertyKey, parameterIndex) => {
+      defineParamMetadata(target, propertyKey as string, parameterIndex, type, undefined);
     };
   };
 }
@@ -652,7 +674,21 @@ 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 +705,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 +734,7 @@ export const ReqHeader = createParamDecorator('reqHeader');
  * }
  * ```
  */
-export const Req = createParamDecorator('req');
+export const Req = createParamDecoratorWithoutParam('req');
 
 /**
  * Decorator that injects the response object.
@@ -699,7 +750,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 +1438,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;
               }
             });
           }
@@ -1529,7 +1586,7 @@ function applyParamOptions(rawValue: any, options: ParamOptions, key?: string) {
 
       // Apply type conversion to each array element
       if (options.type) {
-        value = value.map((v: any) => convertType(v, options.type));
+        value = value.map((v: any) => convertType(v, options.type || 'string'));
       }
     } else if (options.dataType === 'object') {
       // Handle object data type

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 {

tests/utils/exception.utils.test.ts

@@ -263,10 +263,21 @@ describe('ExceptionUtils', () => {
     it('returns correct error class for known status', () => {
       expect(createHttpError(HttpStatusCodes.BAD_REQUEST)).toBeInstanceOf(BadRequestException);
       expect(createHttpError(HttpStatusCodes.UNAUTHORIZED)).toBeInstanceOf(UnauthorizedException);
+      expect(createHttpError(HttpStatusCodes.FORBIDDEN)).toBeInstanceOf(ForbiddenException);
       expect(createHttpError(HttpStatusCodes.NOT_FOUND)).toBeInstanceOf(NotFoundException);
       expect(createHttpError(HttpStatusCodes.METHOD_NOT_ALLOWED)).toBeInstanceOf(MethodNotAllowedException);
+      expect(createHttpError(HttpStatusCodes.NOT_ACCEPTABLE)).toBeInstanceOf(NotAcceptableException);
+      expect(createHttpError(HttpStatusCodes.REQUEST_TIMEOUT)).toBeInstanceOf(RequestTimeoutException);
+      expect(createHttpError(HttpStatusCodes.CONFLICT)).toBeInstanceOf(ConflictException);
+      expect(createHttpError(HttpStatusCodes.PAYLOAD_TOO_LARGE)).toBeInstanceOf(PayloadTooLargeException);
+      expect(createHttpError(HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE)).toBeInstanceOf(UnsupportedMediaTypeException);
       expect(createHttpError(HttpStatusCodes.UNPROCESSABLE_ENTITY)).toBeInstanceOf(UnprocessableEntityException);
-      expect(createHttpError(499, 'Custom')).toBeInstanceOf(HttpError);
+      expect(createHttpError(HttpStatusCodes.INTERNAL_SERVER_ERROR)).toBeInstanceOf(InternalServerErrorException);
+      expect(createHttpError(HttpStatusCodes.BAD_GATEWAY)).toBeInstanceOf(BadGatewayException);
+      expect(createHttpError(HttpStatusCodes.TOO_MANY_REQUESTS)).toBeInstanceOf(TooManyRequestsException);
+      expect(createHttpError(HttpStatusCodes.SERVICE_UNAVAILABLE)).toBeInstanceOf(ServiceUnavailableException);
+      expect(createHttpError(HttpStatusCodes.GATEWAY_TIMEOUT)).toBeInstanceOf(GatewayTimeoutException);
+      expect(createHttpError(HttpStatusCodes.INSUFFICIENT_STORAGE)).toBeInstanceOf(InsufficientStorageException);
     });
     it('sets message if provided', () => {
       const e = createHttpError(HttpStatusCodes.BAD_REQUEST, 'bad!');