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

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

@@ -0,0 +1,508 @@
+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.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users')
+ * getUsers() {
+ *   return this.userService.findAll();
+ * }
+ * ```
+ */
+export declare const Get: (path: string) => MethodDecorator;
+/**
+ * Decorator for POST HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Post('/users')
+ * createUser(@Body() userData: any) {
+ *   return this.userService.create(userData);
+ * }
+ * ```
+ */
+export declare const Post: (path: string) => MethodDecorator;
+/**
+ * Decorator for PUT HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export declare const Put: (path: string) => MethodDecorator;
+/**
+ * Decorator for PATCH HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export declare const Patch: (path: string) => MethodDecorator;
+/**
+ * Decorator for DELETE HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export declare const Delete: (path: string) => MethodDecorator;
+/**
+ * Decorator for OPTIONS HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export declare const Options: (path: string) => MethodDecorator;
+/**
+ * Decorator for HEAD HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export declare const Head: (path: string) => MethodDecorator;
+/**
+ * Decorator for TRACE HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export declare const Trace: (path: string) => MethodDecorator;
+/**
+ * Decorator for CONNECT HTTP method routes.
+ *
+ * @param path - URL path for the route
+ * @returns Method decorator
+ */
+export declare const Connect: (path: string) => MethodDecorator;
+/**
+ * Decorator that marks a class as a controller with a base path.
+ * Used as the entry point for routing configuration.
+ *
+ * @param basePath - Base URL path for all routes in this controller
+ * @returns Class decorator
+ *
+ * @example
+ * ```ts
+ * @Controller('/api/users')
+ * class UserController {
+ *   // Controller methods...
+ * }
+ * ```
+ */
+export declare function Controller(basePath: string): ClassDecorator;
+/**
+ * Decorator that applies middleware to a controller method.
+ * Multiple middlewares can be applied and will execute in order.
+ *
+ * @param middlewares - Express middleware functions to apply
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/protected')
+ * @Use(authMiddleware, loggingMiddleware)
+ * getProtectedResource() {
+ *   // This route is protected by auth middleware
+ * }
+ * ```
+ */
+export declare function Use(...middlewares: RequestHandler[]): MethodDecorator;
+/**
+ * Decorator that extracts query parameters from request.
+ *
+ * @param paramKey - Optional key to extract specific query parameter
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/search')
+ * search(@Query('term') searchTerm: string) {
+ *   // searchTerm will contain the value of req.query.term
+ * }
+ * ```
+ */
+export declare const Query: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that extracts route parameters from request.
+ *
+ * @param paramKey - Optional key to extract specific route parameter
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users/:id')
+ * getUser(@Param('id') userId: string) {
+ *   // userId will contain the value of req.params.id
+ * }
+ * ```
+ */
+export declare const Param: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that extracts body or body property from request.
+ *
+ * @param paramKey - Optional key to extract specific body property
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Post('/users')
+ * createUser(@Body() userData: any) {
+ *   // userData will contain the entire req.body
+ * }
+ *
+ * @Post('/update')
+ * updateName(@Body('name') name: string) {
+ *   // name will contain the value of req.body.name
+ * }
+ * ```
+ */
+export declare const Body: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that injects the entire request object.
+ *
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/complex')
+ * complex(@Req() req: Request) {
+ *   // Access the full request object
+ *   console.log(req.headers);
+ * }
+ * ```
+ */
+export declare const Req: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that injects the response object.
+ *
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/custom')
+ * custom(@Res() res: Response) {
+ *   // Direct access to response object
+ *   return res.status(201).send('Created');
+ * }
+ * ```
+ */
+export declare const Res: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that sets a custom HTTP status code for a response.
+ *
+ * @param status - HTTP status code to use
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Post('/users')
+ * @HttpCode(201)
+ * createUser(@Body() userData: any) {
+ *   // Response will have 201 Created status code
+ *   return { id: '123', ...userData };
+ * }
+ * ```
+ */
+export declare function HttpCode(status: number): MethodDecorator;
+/**
+ * Decorator that adds a custom HTTP header to the response.
+ *
+ * @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
+ * ```ts
+ * @Get('/data')
+ * @Header('Cache-Control', 'max-age=60')
+ * getData() {
+ *   // 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.
+ *
+ * @param fn - Function to execute before the handler
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users/:id')
+ * @Before((req, res) => console.log(`Accessing user ${req.params.id}`))
+ * getUser(@Param('id') id: string) {
+ *   // Function will log before this handler runs
+ * }
+ * ```
+ */
+export declare function Before(fn: Function): MethodDecorator;
+/**
+ * Decorator that registers a function to run after route handler execution.
+ * Can access the handler's result.
+ *
+ * @param fn - Function to execute after the handler
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/users/:id')
+ * @After((req, res, result) => console.log(`User data sent: ${JSON.stringify(result)}`))
+ * getUser(@Param('id') id: string) {
+ *   // After this handler, the function will log the returned data
+ *   return { id, name: 'Example' };
+ * }
+ * ```
+ */
+export declare function After(fn: Function): MethodDecorator;
+/**
+ * Decorator that requires specific roles for accessing a route.
+ * Must be used with authentication middleware.
+ *
+ * @param roles - List of roles that can access this route
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/admin/settings')
+ * @Roles('admin', 'superuser')
+ * getSettings() {
+ *   // Only admins and superusers can access
+ *   return { settings: [...] };
+ * }
+ * ```
+ */
+export declare function Roles(...roles: string[]): MethodDecorator;
+/**
+ * Decorator that redirects to another URL.
+ *
+ * @param url - URL to redirect to (can be absolute or relative)
+ * @param statusCode - HTTP status code for redirect (default: 302)
+ * @returns Method decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/old-path')
+ * @Redirect('/new-path', 301)
+ * redirectToNewPath() {
+ *   // This method won't be executed; automatic redirect happens
+ * }
+ *
+ * @Get('/dynamic-redirect')
+ * @Redirect()
+ * getDynamicRedirect() {
+ *   // Return an object with url and optionally statusCode
+ *   return { url: '/calculated-path', statusCode: 307 };
+ * }
+ * ```
+ */
+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.
+ *
+ * @param router - Express router instance
+ * @param controllers - Array of controller classes
+ */
+export declare function registerControllers(router: Router, controllers: any[]): void;
+export { rateLimiterCache };
+//# sourceMappingURL=decorators.utils.d.ts.map