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

package/README.md

@@ -1,10 +1,34 @@
 # @catbee/utils
 
+<!-- <div style="width: 100%; display: flex; align-items: center; justify-content: space-between;">
+  <b style="font-size: 24px; text-decoration: none;">@catbee/utils</b>
+  <a href="https://sonarcloud.io/summary/new_code?id=catbee-technologies_catbee-utils">
+    <img src="https://sonarcloud.io/images/project_badges/sonarcloud-dark.svg" alt="SonarQube Cloud" width="200"/>
+  </a>
+</div> -->
+
 ## 🧰 Utility Modules for Node.js
 
 A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications. All utilities are tree-shakable and can be imported independently.
 
-![build](https://img.shields.io/badge/build-passing-brightgreen) ![coverage](https://codecov.io/gh/catbee-technologies/catbee-utils/graph/badge.svg?token=XAJHK6R1OQ) ![node](https://img.shields.io/node/v/@catbee/utils) ![npm](https://img.shields.io/npm/v/@catbee/utils) ![downloads](https://img.shields.io/npm/dm/@catbee/utils) ![dependencies](https://img.shields.io/librariesio/release/npm/@catbee%2Futils) ![license](https://img.shields.io/npm/l/@catbee/utils)
+<div style="display: flex; flex-wrap: wrap; gap: 0.5rem; margin: 1rem 0;">
+  <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status" />
+  <img src="https://codecov.io/gh/catbee-technologies/catbee-utils/graph/badge.svg?token=XAJHK6R1OQ" alt="Coverage" />
+  <img src="https://img.shields.io/node/v/@catbee/utils" alt="Node Version" />
+  <img src="https://img.shields.io/npm/v/@catbee/utils" alt="NPM Version" />
+  <img src="https://img.shields.io/npm/v/@catbee/utils/rc" alt="NPM RC Version" />
+  <img src="https://img.shields.io/npm/dt/@catbee/utils" alt="NPM Downloads" />
+  <img src="https://img.shields.io/npm/types/@catbee/utils" alt="TypeScript Types" />
+  <img src="https://img.shields.io/librariesio/release/npm/@catbee%2Futils" alt="Dependencies" />
+  <img src="https://img.shields.io/maintenance/yes/2025" alt="Maintenance" />
+  <img src="https://snyk.io/test/github/<owner>/<repo>/badge.svg" alt="Snyk Vulnerabilities" />
+  <!-- <img src="https://sonarcloud.io/api/project_badges/measure?project=catbee-technologies_catbee-utils&metric=alert_status&token=93da835f2d48d37b41fa628cc7fc764c873bd700" alt="Quality Gate Status" /> -->
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=catbee-technologies_catbee-utils&metric=ncloc&token=93da835f2d48d37b41fa628cc7fc764c873bd700" alt="Lines of Code" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=catbee-technologies_catbee-utils&metric=security_rating&token=93da835f2d48d37b41fa628cc7fc764c873bd700" alt="Security Rating" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=catbee-technologies_catbee-utils&metric=sqale_rating&token=93da835f2d48d37b41fa628cc7fc764c873bd700" alt="Maintainability Rating" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=catbee-technologies_catbee-utils&metric=vulnerabilities&token=93da835f2d48d37b41fa628cc7fc764c873bd700" alt="Vulnerabilities" />
+  <img src="https://img.shields.io/npm/l/@catbee/utils" alt="License" />
+</div>
 
 ---
 

package/build/esm/utils/decorators.utils.d.ts

@@ -1,5 +1,24 @@
 import type { RequestHandler, Router } from 'express';
 import 'reflect-metadata';
+import { rateLimit } from 'express-rate-limit';
+/**
+ * RateLimiter cache that uses TTLCache for automatic TTL and LRU handling.
+ */
+export declare class RateLimiterCache {
+    private cache;
+    constructor(maxSize?: number, ttlMs?: number);
+    private generateKey;
+    get(options: {
+        max: number;
+        windowMs: number;
+        standardHeaders: boolean;
+        legacyHeaders: boolean;
+    }): ReturnType<typeof rateLimit>;
+    clear(): void;
+    size(): number;
+    destroy(): void;
+}
+declare const rateLimiterCache: RateLimiterCache;
 /**
  * Decorator for GET HTTP method routes.
  *
@@ -212,8 +231,8 @@ export declare function HttpCode(status: number): MethodDecorator;
 /**
  * Decorator that adds a custom HTTP header to the response.
  *
- * @param name - Header name
- * @param value - Header value
+ * @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
@@ -224,9 +243,38 @@ export declare function HttpCode(status: number): MethodDecorator;
  *   // Response will include the Cache-Control header
  *   return { data: '...' };
  * }
- * ```
  */
 export declare function Header(name: string, value: string): MethodDecorator;
+/**
+ * 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 declare function Headers(headers: Record<string, string> | string, value?: string): MethodDecorator;
 /**
  * Decorator that registers a function to run before route handler execution.
  * Useful for pre-processing or logging.
@@ -304,6 +352,150 @@ export declare function Roles(...roles: string[]): MethodDecorator;
  * ```
  */
 export declare function Redirect(url?: string, statusCode?: number): MethodDecorator;
+/**
+ * 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 declare function Cache(ttlSeconds: number): MethodDecorator;
+/**
+ * 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 declare function RateLimit(options: {
+    max: number;
+    windowMs: number;
+    standardHeaders?: boolean;
+    legacyHeaders?: boolean;
+}): MethodDecorator;
+/**
+ * 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 declare function ContentType(type: string): MethodDecorator;
+/**
+ * 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 declare function Version(version: string, options?: {
+    addPrefix?: boolean;
+    addHeader?: boolean;
+    headerName?: string;
+}): MethodDecorator;
+/**
+ * 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 declare function Timeout(ms: number): MethodDecorator;
+/**
+ * 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 declare function Log(options?: {
+    logEntry?: boolean;
+    logExit?: boolean;
+    logBody?: boolean;
+    logParams?: boolean;
+    logResponse?: boolean;
+}): MethodDecorator;
 /**
  * Registers all controller classes with the provided router.
  * This function processes all decorators and sets up the Express routes.
@@ -312,4 +504,5 @@ export declare function Redirect(url?: string, statusCode?: number): MethodDecor
  * @param controllers - Array of controller classes
  */
 export declare function registerControllers(router: Router, controllers: any[]): void;
+export { rateLimiterCache };
 //# sourceMappingURL=decorators.utils.d.ts.map