@catbee/utils 0.0.8-rc.4 → 1.0.1

package/build/index.d.ts

@@ -37,7 +37,7 @@ import { CorsOptions } from 'cors';
 /**
  * Logger type for application-wide logging.
  */
-type Logger = pino.Logger;
+type Logger = Logger$1;
 /**
  * Logger levels for application-wide logging.
  */
@@ -158,12 +158,14 @@ declare const _globalThis: typeof globalThis;
  * - Returns a request-scoped logger from AsyncLocalStorage if available
  * - Falls back to the global (singleton) logger
  * - Initializes the global logger if not created yet
+ * - If newInstance is true, returns a fresh logger without any context
  *
- * @returns {Logger} The logger instance (request-bound or global root logger)
+ * @param {boolean} newInstance - If true, returns a fresh logger without any context
+ * @returns {Logger} The logger instance (request-bound or global root logger or fresh instance)
  */
-declare function getLogger(): Logger$1;
+declare function getLogger(newInstance?: boolean): Logger$1;
 /**
- * Logger instance for the global context.
+ * Returns a fresh logger instance without any request context.
  * This logger is used for logging messages that are not tied to a specific request.
  */
 declare const logger: pino.Logger;
@@ -1182,12 +1184,31 @@ declare function createSignedToken(payload: Record<string, any>, secret: string,
  */
 declare function verifySignedToken(token: string, secret: string): Record<string, any> | null;
 
+/**
+ * Parameter decoration definition for method parameters
+ */
+interface ParamDefinition {
+    /** Parameter position in method signature */
+    index: number;
+    /** Type of parameter (query, body, etc.) */
+    type: 'query' | 'param' | 'body' | 'req' | 'res' | 'logger' | 'reqHeader' | 'reqId' | 'cookie';
+    /** Optional key for extracting specific property */
+    key?: string;
+    /** Optional ParamOptions for advanced extraction */
+    options?: ParamOptions;
+}
 type Constructor<T = any> = new (...args: any[]) => T;
 declare class DIContainer {
     private instances;
     private constructing;
+    private propertyInjections;
     register<T>(target: Constructor<T>): void;
+    /**
+     * Register a property injection to be resolved when the target class is instantiated
+     */
+    registerPropertyInjection(target: object, propertyKey: string | symbol, injectClass: Constructor): void;
     get<T>(target: Constructor<T>): T;
+    private applyPropertyInjections;
     clear(): void;
 }
 /**
@@ -1203,6 +1224,16 @@ declare function Injectable(): ClassDecorator;
  * @returns Property decorator that injects the specified class into the property
  */
 declare function Inject<T>(targetClass: new (...args: any[]) => T): PropertyDecorator;
+/**
+ * Inject function for retrieving instances from the DI container.
+ * @param targetClass - The class to inject
+ *
+ * @returns The instance of the requested class
+ *
+ * @example
+ * const a = inject(TestClass);
+ */
+declare function inject<T>(targetClass: new (...args: any[]) => T): T;
 /**
  * Decorator for GET HTTP method routes.
  *
@@ -1299,11 +1330,11 @@ declare const Connect: (path: string) => MethodDecorator;
  */
 declare function Controller(basePath: string): ClassDecorator;
 /**
- * Decorator that applies middleware to a controller method.
+ * Decorator that applies middleware to a controller method or an entire controller.
  * Multiple middlewares can be applied and will execute in order.
  *
  * @param middlewares - Express middleware functions to apply
- * @returns Method decorator
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1312,39 +1343,89 @@ declare function Controller(basePath: string): ClassDecorator;
  * getProtectedResource() {
  *   // This route is protected by auth middleware
  * }
+ *
+ * @Controller('/api')
+ * @Use(commonMiddleware)
+ * class ApiController {
+ *   // All routes in this controller use the middleware
+ * }
  * ```
  */
-declare function Use(...middlewares: RequestHandler[]): MethodDecorator;
+declare function Use(...middlewares: RequestHandler[]): MethodDecorator & ClassDecorator;
+/**
+ * Options for parameter decorators
+ * @template T - Type of the parameter value after transformation
+ *
+ * @property type - Base type of the parameter (default: 'string')'
+ * @property dataType - Data structure type (single, array, object)
+ * @property delimiter - Delimiter for array types
+ * @property default - Default value if parameter is missing
+ * @property required - Whether the parameter is required
+ * @property throwError - Throw error on validation failure
+ * @property validate - Custom validation function
+ * @property transform - Custom transformation function
+ */
+interface ParamOptions<T = any> {
+    /** Base type of the parameter (default: 'string') */
+    type?: 'string' | 'number' | 'boolean';
+    /** Data structure type (default: 'single') */
+    dataType?: 'single' | 'array' | 'object';
+    /** Delimiter for array types (default: ',') */
+    delimiter?: string;
+    /** Default value if parameter is missing */
+    default?: T;
+    /** Whether the parameter is required (default: false) */
+    required?: boolean;
+    /** Throw error on validation failure (default: true) */
+    throwError?: boolean;
+    /** Minimum value for number type */
+    min?: number;
+    /** Maximum value for number type */
+    max?: number;
+    /** Regex pattern the value must match */
+    pattern?: RegExp;
+    /** Name of the pattern for error messages */
+    patternName?: string;
+    /** Custom validation function */
+    validate?: (value: any) => boolean;
+    /** Custom transformation function */
+    transform?: (value: any) => any;
+}
+declare function createParamDecorator(type: ParamDefinition['type'], key?: string): (paramKey?: string) => ParameterDecorator;
+declare function createParamDecoratorWithoutParam(type: ParamDefinition['type']): () => ParameterDecorator;
 /**
  * Decorator that extracts query parameters from request.
  *
  * @param paramKey - Optional key to extract specific query parameter
+ * @param options - Optional ParamOptions
  * @returns Parameter decorator
  *
  * @example
  * ```ts
  * @Get('/search')
- * search(@Query('term') searchTerm: string) {
- *   // searchTerm will contain the value of req.query.term
+ * search(@Query('term') term: string, @Query('page', { type: 'number', default: 1 }) page: number) {
+ *   // term will contain the value of req.query.term
+ *   // page will contain the numeric value of req.query.page or default to 1
  * }
  * ```
  */
-declare const Query: (paramKey?: string) => ParameterDecorator;
+declare const Query: (paramKey?: string, options?: ParamOptions) => ParameterDecorator;
 /**
  * Decorator that extracts route parameters from request.
  *
  * @param paramKey - Optional key to extract specific route parameter
+ * @param options - Optional ParamOptions
  * @returns Parameter decorator
  *
- * @example
+ *  @example
  * ```ts
  * @Get('/users/:id')
- * getUser(@Param('id') userId: string) {
- *   // userId will contain the value of req.params.id
+ * getUser(@Param('id') id: string) {
+ *   // id will contain the value of req.params.id
  * }
  * ```
  */
-declare const Param: (paramKey?: string) => ParameterDecorator;
+declare const Param: (paramKey?: string, options?: ParamOptions) => ParameterDecorator;
 /**
  * Decorator that extracts body or body property from request.
  *
@@ -1365,6 +1446,60 @@ declare const Param: (paramKey?: string) => ParameterDecorator;
  * ```
  */
 declare const Body: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that injects a logger instance.
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/log')
+ * log(@ReqLogger() logger: Logger) {
+ *   logger.info('Logging request...');
+ * }
+ * ```
+ */
+declare const ReqLogger: () => ParameterDecorator;
+/**
+ * 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
+ * }
+ * ```
+ */
+declare const ReqId: () => ParameterDecorator;
+/**
+ * Decorator that extracts request headers.
+ * @param key - Optional key to extract specific header
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/data')
+ * getData(@ReqHeader('Authorization') authHeader: string) {
+ *   // authHeader will contain the value of req.headers['authorization']
+ * }
+ * ```
+ */
+declare const ReqHeader: (paramKey?: string) => ParameterDecorator;
+/**
+ * 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']
+ * }
+ * ```
+ */
+declare const ReqCookie: (paramKey?: string) => ParameterDecorator;
 /**
  * Decorator that injects the entire request object.
  *
@@ -1379,7 +1514,7 @@ declare const Body: (paramKey?: string) => ParameterDecorator;
  * }
  * ```
  */
-declare const Req: (paramKey?: string) => ParameterDecorator;
+declare const Req: () => ParameterDecorator;
 /**
  * Decorator that injects the response object.
  *
@@ -1394,7 +1529,7 @@ declare const Req: (paramKey?: string) => ParameterDecorator;
  * }
  * ```
  */
-declare const Res: (paramKey?: string) => ParameterDecorator;
+declare const Res: () => ParameterDecorator;
 /**
  * Decorator that sets a custom HTTP status code for a response.
  *
@@ -1464,7 +1599,7 @@ declare function Headers(headers: Record<string, string> | string, value?: strin
  * Useful for pre-processing or logging.
  *
  * @param fn - Function to execute before the handler
- * @returns Method decorator
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1473,15 +1608,21 @@ declare function Headers(headers: Record<string, string> | string, value?: strin
  * getUser(@Param('id') id: string) {
  *   // Function will log before this handler runs
  * }
+ *
+ * @Controller('/api')
+ * @Before((req, res) => console.log(`API access: ${req.path}`))
+ * class ApiController {
+ *   // Hook runs before all routes in this controller
+ * }
  * ```
  */
-declare function Before(fn: Function): MethodDecorator;
+declare function Before(fn: Function): MethodDecorator & ClassDecorator;
 /**
  * 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
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1491,9 +1632,15 @@ declare function Before(fn: Function): MethodDecorator;
  *   // After this handler, the function will log the returned data
  *   return { id, name: 'Example' };
  * }
+ *
+ * @Controller('/api')
+ * @After((req, res, result) => console.log(`API response: ${JSON.stringify(result)}`))
+ * class ApiController {
+ *   // Hook runs after all routes in this controller
+ * }
  * ```
  */
-declare function After(fn: Function): MethodDecorator;
+declare function After(fn: Function): MethodDecorator & ClassDecorator;
 /**
  * Decorator that requires specific roles for accessing a route.
  * Must be used with authentication middleware.
@@ -1585,7 +1732,7 @@ declare function RateLimit(options: {
  * Decorator that sets the content type for the response.
  *
  * @param type - MIME type for the response
- * @returns Method decorator
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1594,9 +1741,15 @@ declare function RateLimit(options: {
  * downloadPdf() {
  *   return this.fileService.generatePdf();
  * }
+ *
+ * @Controller('/api/json')
+ * @ContentType('application/json')
+ * class JsonApiController {
+ *   // All routes in this controller use this content type
+ * }
  * ```
  */
-declare function ContentType(type: string): MethodDecorator;
+declare function ContentType(type: string): MethodDecorator & ClassDecorator;
 /**
  * Decorator that adds API versioning to a route.
  *
@@ -5128,4 +5281,4 @@ declare class ServerConfigBuilder {
     private setEnabled;
 }
 
-export { After, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AsyncOperationResponse, type Awaited$1 as Awaited, BUILD_MARKER, BadGatewayException, BadRequestException, type BatchResponse, Before, Body, type BufferEncoding, Cache, CircuitBreakerOpenError, type CircuitBreakerOptions, CircuitBreakerState, ConflictException, Connect, ContentType, ContextStore, Controller, DIContainer, type DecryptionOptions, type DeepPartial, type DeepReadonly, type DeepRequired, type DeepStringifyOrNull, Delete, type EncryptionOptions, type EncryptionResult, Env, Environment, type ErrorHandlerOptions, ErrorResponse, ExpressServer, ForbiddenException, type Func, GatewayTimeoutException, Get, Head, Header, Headers, HttpCode, HttpError, HttpStatusCodes, Inject, Injectable, InsufficientStorageException, InternalServerErrorException, type IsEqual, type KeysOfType, Log, type Logger, type LoggerLevels, type MaybePromise, MethodNotAllowedException, type Middleware, type Mutable, NoContentResponse, type NonEmptyArray, NotAcceptableException, NotFoundException, type Nullable, type Optional, type Optional2, Options, PaginatedResponse, type Pagination, type PaginationParams, type PaginationResponse, Param, type PartialPick, Patch, type PathOptions, PayloadTooLargeException, type PickByType, Post, type Primitive, Put, Query, RateLimit, type RecordOptional, Redirect, RedirectResponse, Req, RequestTimeoutException, type RequireAtLeastOne, Res, Roles, type ServerConfig, ServerConfigBuilder, type ServerHooks, ServiceUnavailableException, SortDirection, type Store, StoreKeys, type StreamResponse, type StringKeyedRecord, SuccessResponse, TTLCache, type TTLCacheOptions, type TaskQueue, Timeout, type ToggleConfig, TooManyRequestsException, Trace, TypedContextKey, UnauthorizedException, type UnionToIntersection, UnprocessableEntityException, UnsupportedMediaTypeException, type UrlOptions, Use, type ValidationOptions, type ValidationResult, type ValueOf, Version, type WithPagination, type Without, type Writable, _globalThis, abortable, addRedactFields, addSensitiveFields, appendQueryParams, appendTextFile, capitalize, chunk, circuitBreaker, compact, copyDir, copyFile, countBy, countOccurrences, createChildLogger, createDeferred, createDirectory, createErrorResponse, createFinalErrorResponse, createHttpError, createPaginatedResponse, createRequestLogger, createSignedToken, createSuccessResponse, createTaskQueue, createTempDir, createTempFile, createUrlBuilder, debounce, decrypt, deepFreeze, deepObjMerge, defaultSensitiveFields, deleteDirRecursive, deleteFileIfExists, difference, emptyDir, encrypt, ensureDir, ensureEmptyDir, equalsIgnoreCase, errorHandler, extractFilterParams, extractPaginationParams, extractQueryParams, extractSortParams, fileExists, filterObject, findFilesByPattern, findInDir, findNewestFile, findOldestFile, flattenDeep, flattenObject, generateApiKey, generateRandomBytes, generateRandomBytesAsString, getAllPaths, getConfig, getDirSize, getDirStats, getDomain, getErrorMessage, getExtension, getFileSize, getFileStats, getFromContext, getLogger, getPaginationParams, getRedactCensor, getRequestId, getSubdirectories, getValueByPath, groupBy, hasErrorShape, hasRequiredProps, hash, healthCheck, hmac, intersect, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isDirectory, isEmail, isEqual, isFile, isHexColor, isHttpError, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isObjEmpty, isObject, isPhone, isPlainObject, isPort, isStrongPassword, isURL, isUUID, isValidJSON, isValidUrl, joinPaths, listFiles, logError, logger, mapObject, mask, matchesPattern, md5, memoizeAsync, mergeSort, moveDir, moveFile, nanoId, normalizeUrl, omit, parseBooleanParam, parseNumberParam, parseQueryString, parseTypedQueryParams, partition, pick, pluck, random, randomBase64, randomHex, randomInt, randomString, range, rateLimit, readDirectory, readFileBuffer, readJsonFile, readTextFile, redact, registerControllers, removeQueryParams, requestId, responseTime, retry, reverse, runInBatches, runInSeries, runWithConcurrency, safeCompare, safeReadJsonFile, sendResponse, setConfig, setRedactCensor, setSensitiveFields, setValueByPath, settleAll, setupRequestContext, sha1, sha256, sha256Hmac, shuffle, singletonAsync, sleep, slugify, streamFile, stripHtml, take, takeWhile, throttle, timeout, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, truncate, unique, uuid, validateAll, verifySignedToken, walkDir, watchDir, watchDirRecursive, waterfall, withErrorHandling, withTimeout, writeJsonFile, writeTextFile, zip };
+export { After, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AsyncOperationResponse, type Awaited$1 as Awaited, BUILD_MARKER, BadGatewayException, BadRequestException, type BatchResponse, Before, Body, type BufferEncoding, Cache, CircuitBreakerOpenError, type CircuitBreakerOptions, CircuitBreakerState, ConflictException, Connect, ContentType, ContextStore, Controller, DIContainer, type DecryptionOptions, type DeepPartial, type DeepReadonly, type DeepRequired, type DeepStringifyOrNull, Delete, type EncryptionOptions, type EncryptionResult, Env, Environment, type ErrorHandlerOptions, ErrorResponse, ExpressServer, ForbiddenException, type Func, GatewayTimeoutException, Get, Head, Header, Headers, HttpCode, HttpError, HttpStatusCodes, Inject, Injectable, InsufficientStorageException, InternalServerErrorException, type IsEqual, type KeysOfType, Log, type Logger, type LoggerLevels, type MaybePromise, MethodNotAllowedException, type Middleware, type Mutable, NoContentResponse, type NonEmptyArray, NotAcceptableException, NotFoundException, type Nullable, type Optional, type Optional2, Options, PaginatedResponse, type Pagination, type PaginationParams, type PaginationResponse, Param, type ParamOptions, type PartialPick, Patch, type PathOptions, PayloadTooLargeException, type PickByType, Post, type Primitive, Put, Query, RateLimit, type RecordOptional, Redirect, RedirectResponse, Req, ReqCookie, ReqHeader, ReqId, ReqLogger, RequestTimeoutException, type RequireAtLeastOne, Res, Roles, type ServerConfig, ServerConfigBuilder, type ServerHooks, ServiceUnavailableException, SortDirection, type Store, StoreKeys, type StreamResponse, type StringKeyedRecord, SuccessResponse, TTLCache, type TTLCacheOptions, type TaskQueue, Timeout, type ToggleConfig, TooManyRequestsException, Trace, TypedContextKey, UnauthorizedException, type UnionToIntersection, UnprocessableEntityException, UnsupportedMediaTypeException, type UrlOptions, Use, type ValidationOptions, type ValidationResult, type ValueOf, Version, type WithPagination, type Without, type Writable, _globalThis, abortable, addRedactFields, addSensitiveFields, appendQueryParams, appendTextFile, capitalize, chunk, circuitBreaker, compact, copyDir, copyFile, countBy, countOccurrences, createChildLogger, createDeferred, createDirectory, createErrorResponse, createFinalErrorResponse, createHttpError, createPaginatedResponse, createParamDecorator, createParamDecoratorWithoutParam, createRequestLogger, createSignedToken, createSuccessResponse, createTaskQueue, createTempDir, createTempFile, createUrlBuilder, debounce, decrypt, deepFreeze, deepObjMerge, defaultSensitiveFields, deleteDirRecursive, deleteFileIfExists, difference, emptyDir, encrypt, ensureDir, ensureEmptyDir, equalsIgnoreCase, errorHandler, extractFilterParams, extractPaginationParams, extractQueryParams, extractSortParams, fileExists, filterObject, findFilesByPattern, findInDir, findNewestFile, findOldestFile, flattenDeep, flattenObject, generateApiKey, generateRandomBytes, generateRandomBytesAsString, getAllPaths, getConfig, getDirSize, getDirStats, getDomain, getErrorMessage, getExtension, getFileSize, getFileStats, getFromContext, getLogger, getPaginationParams, getRedactCensor, getRequestId, getSubdirectories, getValueByPath, groupBy, hasErrorShape, hasRequiredProps, hash, healthCheck, hmac, inject, intersect, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isDirectory, isEmail, isEqual, isFile, isHexColor, isHttpError, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isObjEmpty, isObject, isPhone, isPlainObject, isPort, isStrongPassword, isURL, isUUID, isValidJSON, isValidUrl, joinPaths, listFiles, logError, logger, mapObject, mask, matchesPattern, md5, memoizeAsync, mergeSort, moveDir, moveFile, nanoId, normalizeUrl, omit, parseBooleanParam, parseNumberParam, parseQueryString, parseTypedQueryParams, partition, pick, pluck, random, randomBase64, randomHex, randomInt, randomString, range, rateLimit, readDirectory, readFileBuffer, readJsonFile, readTextFile, redact, registerControllers, removeQueryParams, requestId, responseTime, retry, reverse, runInBatches, runInSeries, runWithConcurrency, safeCompare, safeReadJsonFile, sendResponse, setConfig, setRedactCensor, setSensitiveFields, setValueByPath, settleAll, setupRequestContext, sha1, sha256, sha256Hmac, shuffle, singletonAsync, sleep, slugify, streamFile, stripHtml, take, takeWhile, throttle, timeout, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, truncate, unique, uuid, validateAll, verifySignedToken, walkDir, watchDir, watchDirRecursive, waterfall, withErrorHandling, withTimeout, writeJsonFile, writeTextFile, zip };