@catbee/utils 0.0.1 → 0.0.2

package/README.md

@@ -4,7 +4,7 @@
 
 A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.
 
-![CI](https://github.com/catbee-technologies/catbee-utils/actions/workflows/node-build.yml/badge.svg) ![Coverage](https://codecov.io/gh/catbee-technologies/catbee-utils/branch/main/graph/badge.svg) ![Audit](https://github.com/catbee-technologies/catbee-utils/actions/workflows/audit.yml/badge.svg) ![Publish](https://github.com/catbee-technologies/catbee-utils/actions/workflows/npm-publish.yml/badge.svg)
+[build](https://github.com/catbee-technologies/catbee-utils/actions/workflows/node-build.yml/badge.svg) ![test](https://github.com/catbee-technologies/catbee-utils/actions/workflows/code-coverage.yml/badge.svg) ![coverage](https://codecov.io/gh/catbee-technologies/catbee-utils/branch/main/graph/badge.svg) ![dependencies](https://img.shields.io/librariesio/release/npm/@catbee%2Futils)
 
 ## 📦 Installation
 
@@ -31,7 +31,6 @@ console.log(uuid()); // e.g. 2a563ec1-caf6-4fe2-b60c-9cf7fb1bdb7f
 
 // Basic validation
 console.log(isEmail("user@example.com")); // true
-
 ```
 
 ## 📦 Modules Overview
@@ -39,6 +38,7 @@ console.log(isEmail("user@example.com")); // true
 - [**Array Utilities**](#-array-utilities)
 - [**Async Utilities**](#-async-utilities)
 - [**Cache Utilities**](#-cache-utilities)
+- [**Config**](#-config)
 - [**Context Store**](#-context-store)
 - [**Crypto Utilities**](#-crypto-utilities)
 - [**Directory Utilities**](#-directory-utilities)
@@ -47,76 +47,104 @@ console.log(isEmail("user@example.com")); // true
 - [**File System Utilities**](#-file-system-utilities)
 - [**HTTP Status Codes**](#-http-status-codes)
 - [**ID Utilities**](#-id-utilities)
-- [**Logger Utilities**](#-logger-utility)
+- [**Logger Utilities**](#-logger-utilities)
+- [**Middleware Utilities**](#-middleware-utilities)
 - [**Object Utilities**](#-object-utilities)
 - [**Response Utilities**](#-response-utilities)
 - [**String Utilities**](#-string-utilities)
 - [**URL Utilities**](#-url-utilities)
 - [**Validate Utilities**](#-validate-utilities)
+- [**Decorators Utilities**](#decorators-utilities)
+
+---
 
 ## 📦 Array Utilities
 
-- `chunk<T>(arr: T[], size: number): T[][]` – Split array into chunks.
-- `unique<T>(array: T[]): T[]` – Remove duplicates.
+- `chunk<T>(array: T[], size: number): T[][]` – Split array into chunks.
+- `unique<T>(array: T[], keyFn?: (item: T) => unknown): T[]` – Remove duplicates.
 - `flattenDeep<T>(array: any[]): T[]` – Deep flatten nested arrays.
 - `random<T>(array: T[]): T | undefined` – Random element.
-- `groupBy<T, K>(array: T[], keyFn: (item: T) => K): Record<K, T[]>` – Group by key.
+- `groupBy<T>(array: T[], keyOrFn: keyof T | ((item: T) => string | number | symbol)): Record<string | number | symbol, T[]>` – Group by key.
 - `shuffle<T>(array: T[]): T[]` – Fisher-Yates shuffle.
+- `pluck<T, K extends keyof T>(array: T[], key: K): T[K][]` – Pluck values by key.
 - `difference<T>(a: T[], b: T[]): T[]` – Elements in `a` not in `b`.
 - `intersect<T>(a: T[], b: T[]): T[]` – Intersection.
-- `mergeSort<T extends object>(array: T[], key: string, direction = 'asc'): T[]` – Merge sort by nested key.
+- `mergeSort<T>(array: T[], key: string | ((item: T) => any), direction?: "asc" | "desc"): T[]` – Merge sort by nested key.
+- `zip<T>(...arrays: T[][]): T[][]` – Zip arrays together.
+- `partition<T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): [T[], T[]]` – Partition array by predicate.
+- `range(start: number, end: number, step?: number): number[]` – Generate a range of numbers.
+- `take<T>(array: T[], n?: number): T[]` – Take first `n` elements.
+- `takeWhile<T>(array: T[], predicate: (item: T, index: number) => boolean): T[]` – Take elements while predicate is true.
+- `compact<T>(array: T[]): NonNullable<T>[]` – Remove falsy values.
+- `countBy<T>(array: T[], keyFn: (item: T) => string | number | symbol): Record<string, number>` – Count occurrences by key.
+- `sample<T>(array: T[], n?: number): T[]` – Sample `n` elements.
 
 ## ⏳ Async Utilities
 
 - `sleep(ms: number): Promise<void>`
-- `debounce<T>(fn: T, wait: number): T & { cancel(): void; flush(): void }`
-- `throttle<T>(fn: T, wait: number, options?): T`
-- `retry<T>(fn: () => Promise<T>, retries?: number): Promise<T>`
-- `withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>`
-- `runInBatches<T>(tasks: (() => Promise<T>)[], batchSize: number): Promise<T[]>`
-- `singletonAsync<TArgs, TResult>(fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>`
-- `settleAll<T>(tasks: (() => Promise<T>)[]): Promise<SettledResult<T>[]>`
-- `createTaskQueue(limit: number)`
+- `debounce<T>(fn: T, delay: number): T & { cancel(): void; flush(): void }`
+- `throttle<T>(fn: T, limit: number, opts?): (...args: Parameters<T>) => void`
+- `retry<T>(fn: () => Promise<T>, retries?: number, delay?: number, backoff?: boolean, onRetry?): Promise<T>`
+- `withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>`
+- `runInBatches<T>(tasks: (() => Promise<T>)[], limit: number): Promise<T[]>`
+- `singletonAsync<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, drop?: boolean): (...args: TArgs) => Promise<TResult>`
+- `settleAll<T>(tasks: (() => Promise<T>)[]): Promise<PromiseSettledResult<T>[]>`
+- `createTaskQueue(limit: number): TaskQueue`
 - `runInSeries<T>(tasks: (() => Promise<T>)[]): Promise<T[]>`
+- `memoizeAsync<T, Args extends any[]>(fn: (...args: Args) => Promise<T>, options?): (...args: Args) => Promise<T>`
+- `abortable<T>(promise: Promise<T>, signal: AbortSignal, abortValue?: any): Promise<T>`
+- `createDeferred<T>(): [Promise<T>, (value: T | PromiseLike<T>) => void, (reason?: any) => void]`
+- `waterfall<T>(fns: Array<(input: any) => Promise<any>>): (initialValue: any) => Promise<T>`
+- `rateLimit<T>(fn: (...args: any[]) => Promise<T>, maxCalls: number, interval: number): (...args: any[]) => Promise<T>`
 
 ## 🗃️ Cache Utilities
 
-- `TTLCache<K, V>(ttl: number)` – In-memory TTL cache with `.set`, `.get`, `.has`, `.delete`, `.clear`.
-
-You can use it like:
+- `TTLCache<K, V>(options?: TTLCacheOptions)` – In-memory TTL cache with `.set`, `.get`, `.has`, `.delete`, `.clear`, `.cleanup`, `.entries`, `.keys`, `.values`, `.refresh`, `.stats`, `.destroy`, `.setMany`, `.getMany`, `.getOrCompute`.
 
+**Example:**
 ```ts
-const cache = new TTLCache<string, number>(3600_000);
+const cache = new TTLCache<string, number>({ ttlMs: 3600_000 });
 cache.set("foo", 42);
 cache.get("foo"); // 42
 cache.has("foo"); // true
 cache.cleanup();  // cleans expired
 ```
 
+## ⚙️ Config
+
+- `Config.Logger.level` – Logging level (e.g., 'info', 'debug')
+- `Config.Logger.name` – Logger name
+- `Config.Logger.isoTimestamp` – Use ISO timestamps in logs
+- `Config.Http.timeout` – HTTP request timeout (ms)
+- `Config.Cache.defaultTtl` – Default cache TTL (seconds)
+
 ## 🧩 Context Store
 
 - `ContextStore` – Per-request context using AsyncLocalStorage.
 
   **Static Methods:**
-  - `getInstance(): AsyncLocalStorage<Store>` – Get the AsyncLocalStorage instance.
+  - `getInstance(): AsyncLocalStorage<Store>`
   - `getAll(): Store | undefined` – Get the current context store.
-  - `run(store: Store, callback: () => void): void` – Run a callback within a context.
-  - `set<K extends keyof Store>(key: K, value: Store[K]): void` – Set a value in the context.
-  - `get<K extends keyof Store>(key: K): Store[K] | undefined` – Get a value from the context.
+  - `run(store: Store, callback: () => void): void`
+  - `set(key: symbol, value: unknown): void`
+  - `get<T>(key: symbol): T | undefined`
+  - `has(key: symbol): boolean`
+  - `delete(key: symbol): boolean`
+  - `patch(values: Partial<Record<symbol, unknown>>): void`
+  - `withValue(key: symbol, value: unknown, callback: () => T): T`
+  - `extend(newValues: Partial<Record<symbol, unknown>>, callback: () => T): T`
+  - `createExpressMiddleware(initialValuesFactory?): Middleware`
 
 - `StoreKeys` – Common context keys.
 - `getRequestId(): string | undefined` – Get the current request ID from context.
 
-### Example (Express middleware usage):
-
+**Example (Express middleware usage):**
 ```ts
-// ✅ Recommended: Unified middleware to initialize context and logger
 import { ContextStore, StoreKeys, getLogger } from "@catbee/utils";
 import crypto from "crypto";
 
-export function setupRequestContext(req: Request, res: Response, next: NextFunction): void {
+export function setupRequestContext(req, res, next) {
   const requestId = req.headers["x-request-id"]?.toString() || crypto.randomUUID();
-
   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {
     const logger = getLogger().child({ reqId: requestId });
     ContextStore.set(StoreKeys.LOGGER, logger);
@@ -124,52 +152,48 @@ export function setupRequestContext(req: Request, res: Response, next: NextFunct
     next();
   });
 }
-
-// In your app entry point
 app.use(setupRequestContext);
 ```
 
-👇 Alternatively, split it into two separate middlewares:
-
-```ts
-// First: Initialize context with request ID
-app.use((req, res, next) => {
-  const requestId = req.headers["x-request-id"] || crypto.randomUUID();
-  ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => next());
-});
-
-// Second: Inject logger into the context
-app.use((req, res, next) => {
-  const logger = getLogger().child({ reqId: req.headers["x-request-id"] });
-  ContextStore.set(StoreKeys.LOGGER, logger);
-  logger.info("Request started");
-  next();
-});
-```
-
 ## 🔐 Crypto Utilities
 
-- `hmac(algorithm: string, input: string, secret: string): string`
-- `hash(algorithm: string, input: string): string`
+- `hmac(algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding): string`
+- `hash(algorithm: string, input: string, encoding?: BinaryToTextEncoding): string`
 - `sha256Hmac(input: string, secret: string): string`
-- `sha1(input: string): string`
-- `sha256(input: string): string`
+- `sha1(input: string, encoding?: BinaryToTextEncoding): string`
+- `sha256(input: string, encoding?: BinaryToTextEncoding): string`
 - `md5(input: string): string`
 - `randomString(): string`
-
+- `generateRandomBytes(byteLength?: number): Buffer`
+- `generateRandomBytesAsString(byteLength?: number, encoding?: BinaryToTextEncoding): string`
+- `generateApiKey(prefix?: string, byteLength?: number): string`
+- `safeCompare(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean`
+- `encrypt(data: string | Buffer, key: string | Buffer, options?): Promise<EncryptionResult>`
+- `decrypt(encryptedData: EncryptionResult, key: string | Buffer, options?): Promise<string | Buffer>`
+- `createSignedToken(payload: object, secret: string, expiresInSeconds?: number): string`
+- `verifySignedToken(token: string, secret: string): object | null`
 
 ## 📂 Directory Utilities
 
 - `ensureDir(dirPath: string): Promise<void>`
-- `listFiles(dirPath: string, options?): Promise<string[]>`
+- `listFiles(dirPath: string, recursive?: boolean): Promise<string[]>`
 - `deleteDirRecursive(dirPath: string): Promise<void>`
-- `isDirectory(path: string): Promise<boolean>`
+- `isDirectory(pathStr: string): Promise<boolean>`
 - `copyDir(src: string, dest: string): Promise<void>`
 - `moveDir(src: string, dest: string): Promise<void>`
 - `emptyDir(dirPath: string): Promise<void>`
 - `getDirSize(dirPath: string): Promise<number>`
-- `watchDir(dirPath: string, cb: (event, filename) => void)`
-
+- `watchDir(dirPath: string, callback): () => void`
+- `findFilesByPattern(pattern: string, options?): Promise<string[]>`
+- `getSubdirectories(dirPath: string, recursive?: boolean): Promise<string[]>`
+- `ensureEmptyDir(dirPath: string): Promise<void>`
+- `createTempDir(options?): Promise<{ path: string, cleanup: () => Promise<void> }>`
+- `findNewestFile(dirPath: string, recursive?: boolean): Promise<string | null>`
+- `findOldestFile(dirPath: string, recursive?: boolean): Promise<string | null>`
+- `findInDir(dirPath: string, predicate, recursive?: boolean): Promise<string[]>`
+- `watchDirRecursive(dirPath: string, callback, includeSubdirs?: boolean): Promise<() => void>`
+- `getDirStats(dirPath: string): Promise<{ fileCount: number, dirCount: number, totalSize: number }>`
+- `walkDir(dirPath: string, options): Promise<void>`
 
 ## 🌱 Environment Utilities
 
@@ -177,83 +201,141 @@ app.use((req, res, next) => {
 - `Env` class – Environment variable helpers.
 
   **Static Methods:**
-  - `isDev(): boolean` – Is NODE_ENV development?
-  - `set(key: string, value: string): void` – Set an environment variable.
-  - `getAll(): object` – Get all environment variables.
-  - `get(key: string, defaultValue?: string): string | undefined` – Get an environment variable.
-  - `getRequired(key: string): string` – Get a required environment variable.
-  - `getNumber(key: string, defaultValue: number): number` – Get a number environment variable.
-  - `getNumberRequired(key: string): number` – Get a required number environment variable.
-  - `getBoolean(key: string, defaultValue = false): boolean` – Get a boolean environment variable.
-  - `getBooleanRequired(key: string): boolean` – Get a required boolean environment variable.
-  - `getJSON<T extends object = object>(key: string, defaultValue: T): T` – Parse a JSON object from an environment variable.
-  - `getArray<T = string>(key: string, defaultValue: T[] = [], splitter = ','): string[] | T[]` – Parse a comma-separated string as an array.
-  - `getEnum<T extends string>(key: string, allowedValues: T[], defaultValue?: T): T` – Get and validate an enum-like environment variable.
-  - `has(key: string): boolean` – Check if an environment variable exists.
-  - `delete(key: string): void` – Delete an environment variable (useful in tests). 
-
+  - `isDev(): boolean`
+  - `isProd(): boolean`
+  - `isTest(): boolean`
+  - `isStaging(): boolean`
+  - `set(key: string, value: string): void`
+  - `getAll(): object`
+  - `get(key: string, defaultValue?: string): string | undefined`
+  - `getRequired(key: string): string`
+  - `getNumber(key: string, defaultValue: number): number`
+  - `getNumberRequired(key: string): number`
+  - `getBoolean(key: string, defaultValue?: boolean): boolean`
+  - `getBooleanRequired(key: string): boolean`
+  - `getJSON<T>(key: string, defaultValue: T): T`
+  - `getArray<T = string>(key: string, defaultValue?: T[], splitter?: string): string[] | T[]`
+  - `getEnum<T extends string>(key: string, allowedValues: T[], defaultValue?: T): T`
+  - `getUrl(key: string, defaultValue?: string, options?): string`
+  - `getEmail(key: string, defaultValue?: string): string`
+  - `getPath(key: string, defaultValue?: string, options?): string`
+  - `getPort(key: string, defaultValue?: number): number`
+  - `getDuration(key: string, defaultValue?: string | number): number`
+  - `getSafeEnv(sensitiveKeys?: string[]): Record<string, string>`
+  - `getWithDefault(key: string, defaultFn: () => string): string`
+  - `has(key: string): boolean`
+  - `delete(key: string): void`
 
 ## 🚨 Exception Utilities
 
-- `HttpError`, `InternalServerErrorException`, `UnauthorizedException`, `BadRequestException`, `NotFoundException`, `ForbiddenException`, `ConflictException`, `BadGatewayException`, `TooManyRequestsException`, `ServiceUnavailableException`, `GatewayTimeoutException` – All extend `ErrorResponse`.
-
+- `HttpError`, `InternalServerErrorException`, `UnauthorizedException`, `BadRequestException`, `NotFoundException`, `ForbiddenException`, `ConflictException`, `BadGatewayException`, `TooManyRequestsException`, `ServiceUnavailableException`, `GatewayTimeoutException`, `UnprocessableEntityException`, `MethodNotAllowedException`, `NotAcceptableException`, `RequestTimeoutException`, `UnsupportedMediaTypeException`, `PayloadTooLargeException`, `InsufficientStorageException`
+- `isHttpError(error: unknown): error is ErrorResponse`
+- `createHttpError(status: number, message?: string): ErrorResponse`
+- `hasErrorShape(error: unknown): error is { message: string; status?: number; code?: string }`
+- `getErrorMessage(error: unknown): string`
+- `withErrorHandling<T extends (...args: any[]) => Promise<any>>(handler: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>`
 
 ## 📁 File System Utilities
 
 - `fileExists(path: string): Promise<boolean>`
 - `readJsonFile<T>(path: string): Promise<T | null>`
-- `writeJsonFile(path: string, data: any): Promise<void>`
+- `writeJsonFile(path: string, data: any, space?: number): Promise<void>`
 - `deleteFileIfExists(path: string): Promise<boolean>`
-
+- `readTextFile(path: string, encoding?: BufferEncoding): Promise<string | null>`
+- `writeTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>`
+- `appendTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>`
+- `copyFile(source: string, destination: string, overwrite?: boolean): Promise<boolean>`
+- `moveFile(oldPath: string, newPath: string): Promise<boolean>`
+- `getFileStats(path: string): Promise<fs.Stats | null>`
+- `createTempFile(options?): Promise<string>`
+- `streamFile(source: string, destination: string): Promise<void>`
+- `readDirectory(dirPath: string, options?): Promise<string[]>`
+- `createDirectory(dirPath: string, recursive?: boolean): Promise<boolean>`
+- `safeReadJsonFile<T>(path: string): Promise<{ data: T | null; error: Error | null }>`
+- `isFile(path: string): Promise<boolean>`
+- `getFileSize(path: string): Promise<number>`
+- `readFileBuffer(path: string): Promise<Buffer | null>`
 
 ## 📊 HTTP Status Codes
 
-A typed object with all HTTP status codes and their standard messages.
+A typed enum with all HTTP status codes and their standard messages.
 
 - `HttpStatusCodes.OK === 200`
 - `HttpStatusCodes.NOT_FOUND === 404`
 - ...and so on.
 
-You can use it like:
-
+**Example:**
 ```ts
 import { HttpStatusCodes } from "@catbee/utils";
-
 res.status(HttpStatusCodes.BAD_REQUEST).send("Invalid payload");
 ```
 
 ## 🆔 ID Utilities
 
-Helpers for generating unique and random identifiers, covering popular formats for distributed systems and secure tokens.
-
-- `uuid(): string` — Generate a UUID v4 string (RFC 4122).
-- `ulidString(): string` — Generate a ULID (Universally Unique Lexicographically Sortable Identifier).
-- `nanoId(size?: number): string` — Generate a nanoid string.
-- `randomHex(byteLength?: number): string` — Generate a cryptographically strong random hex string of given length in bytes.
-- `randomInt(min: number, max: number): number` — Generate a secure random integer between min and max, inclusive.
-
+- `uuid(): string`
+- `nanoId(size?: number): string`
+- `randomHex(byteLength?: number): string`
+- `randomInt(min: number, max: number): number`
+- `randomBase64(byteLength?: number): number`
 
 ## 📄 Logger Utilities
 
-- `getLogger(): Logger` – Context-aware logger (uses `pino`).
-
+- `getLogger(): Logger`
+- `createChildLogger(bindings: Record<string, any>, parentLogger?: Logger): Logger`
+- `createRequestLogger(requestId: string, additionalContext?: Record<string, any>): Logger`
+- `logError(error: Error | unknown, message?: string, context?: Record<string, any>): void`
+- `resetLogger(): void`
+
+## 🧩 Middleware Utilities
+
+- `requestId(options?): Middleware`
+- `responseTime(options?): Middleware`
+- `timeout(timeoutMs?: number): Middleware`
+- `errorHandler(options?): Middleware`
+- `cors(options?): Middleware`
+- `validateRequest(schema, location?): Middleware`
+- `rateLimit(options?): Middleware`
+- `securityHeaders(options?): Middleware`
+- `basicAuth(validator, realm?): Middleware`
+
+**Example:**
+```ts
+import { requestId, responseTime, errorHandler } from "@catbee/utils";
+app.use(requestId());
+app.use(responseTime());
+app.use(errorHandler());
+```
 
 ## 🧩 Object Utilities
 
 - `isObjEmpty(obj: Record<any, any>): boolean`
 - `pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>`
 - `omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>`
-- `deepObjMerge<T>(a: T, b: Partial<T>): T`
-- `flattenObject<T>(obj: T): Record<string, any>`
-- `getValueByPath<T>(obj: T, path: string)`
-
+- `deepObjMerge<T>(target: T, source: Partial<T>): T`
+- `flattenObject<T>(obj: T, prefix?: string): Record<string, any>`
+- `getValueByPath<T>(obj: T, path: string): any`
+- `setValueByPath<T>(obj: T, path: string, value: any): T`
+- `deepClone<T>(obj: T): T`
+- `unflattenObject(obj: Record<string, any>): Record<string, any>`
+- `isEqual(a: any, b: any): boolean`
+- `filterObject<T>(obj: T, predicate): Partial<T>`
+- `mapObject<T, U>(obj: T, mapFn): Record<keyof T, U>`
+- `deepFreeze<T>(obj: T): Readonly<T>`
+- `isObject(value: unknown): value is Record<string, any>`
+- `getAllPaths(obj: Record<string, any>, parentPath?: string): string[]`
 
 ## 📝 Response Utilities
 
 - `SuccessResponse<T>` – Standard API success wrapper.
 - `ErrorResponse` – Standard API error wrapper.
-- Types: `ApiResponse<T>`, `Pagination<T>`, `PaginationResponse<T>`
-
+- `PaginatedResponse<T>` – Paginated API response.
+- `NoContentResponse` – 204 No Content response.
+- `RedirectResponse` – Redirect response.
+- `createSuccessResponse<T>(data: T, message?: string): SuccessResponse<T>`
+- `createErrorResponse(message: string, statusCode?: number): ErrorResponse`
+- `createPaginatedResponse<T>(allItems: T[], page: number, pageSize: number, message?: string): PaginatedResponse<T>`
+- `sendResponse(res, apiResponse): void`
+- `isApiResponse(value: any): value is ApiResponse<any>`
 
 ## 🧵 String Utilities
 
@@ -262,25 +344,139 @@ Helpers for generating unique and random identifiers, covering popular formats f
 - `toCamelCase(str: string): string`
 - `slugify(str: string): string`
 - `truncate(str: string, len: number): string`
-
+- `toPascalCase(str: string): string`
+- `toSnakeCase(str: string): string`
+- `format(template: string, values: Record<string, any> | any[]): string`
+- `isValidEmail(str: string): boolean`
+- `isValidUrl(str: string, requireProtocol?: boolean): boolean`
+- `mask(str: string, visibleStart?: number, visibleEnd?: number, maskChar?: string): string`
+- `stripHtml(str: string): string`
+- `equalsIgnoreCase(a: string, b: string): boolean`
+- `reverse(str: string): string`
+- `countOccurrences(str: string, substring: string, caseSensitive?: boolean): number`
+- `randomString(length?: number, charset?: string): string`
+- `pluralize(singular: string, count: number, plural?: string): string`
+- `toTitleCase(str: string): string`
+- `pad(str: string, length: number, padChar?: string, padEnd?: boolean): string`
 
 ## 🌐 URL Utilities
 
-- `appendQueryParams(url: string, params: object): string`
+- `appendQueryParams(url: string, params: Record<string, string | number>): string`
 - `parseQueryString(query: string): Record<string, string>`
-
+- `isValidUrl(url: string, requireHttps?: boolean): boolean`
+- `getDomain(url: string, removeSubdomains?: boolean): string`
+- `joinPaths(...segments: string[]): string`
+- `normalizeUrl(url: string, base?: string): string`
+- `createUrlBuilder(baseUrl: string): { path(path: string, params?: Record<string, any>): string; query(params: Record<string, any>): string }`
+- `extractQueryParams(url: string, paramNames: string[]): Record<string, string>`
+- `removeQueryParams(url: string, paramsToRemove: string[]): string`
+- `getExtension(url: string): string`
+- `parseTypedQueryParams<T>(url: string, converters?: Record<keyof T, (val: string) => any>): Partial<T>`
+
+**Example:**
+```ts
+const url = appendQueryParams('https://example.com', { page: 1, limit: 10 });
+// → 'https://example.com/?page=1&limit=10'
+```
 
 ## ✅ Validate Utilities
+
 A comprehensive suite of string/format validators for safe input and API checks.
 
-- `isEmail(str: string): boolean` — Validate basic email address.
-- `isUUID(str: string): boolean` — Validate string as UUID (v1–v5).
-- `isURL(str: string): boolean` — Check if string is a valid URL.
-- `isPhone(str: string): boolean` — Validate (international/E164/local) phone number.
-- `isAlphanumeric(str: string): boolean` — Check for letters/numbers only.
-- `isNumeric(strOrNum: string | number)`: boolean — Check safely parsable numeric value.
-- `isHexColor(str: string): boolean` — Validate hex color (#RGB or #RRGGBB).
-- `isISODate(str: string): boolean` — Validate ISO 8601 date string.
+- `isEmail(str: string): boolean`
+- `isUUID(str: string): boolean`
+- `isURL(str: string): boolean`
+- `isPhone(str: string): boolean`
+- `isAlphanumeric(str: string): boolean`
+- `isNumeric(value: string | number): boolean`
+- `isHexColor(str: string): boolean`
+- `isISODate(str: string): boolean`
+- `isLengthBetween(str: string, min: number, max: number): boolean`
+- `isNumberBetween(value: number, min: number, max: number): boolean`
+- `isAlpha(str: string): boolean`
+- `isStrongPassword(str: string): boolean`
+- `isIPv4(str: string): boolean`
+- `isIPv6(str: string): boolean`
+- `isCreditCard(str: string): boolean`
+- `isValidJSON(str: string): boolean`
+- `isObject(value: unknown): value is Record<string, unknown>`
+- `isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[]`
+- `isBase64(str: string): boolean`
+- `hasRequiredProps(obj: Record<string, unknown>, requiredProps: string[]): boolean`
+- `isDateInRange(date: Date, minDate?: Date, maxDate?: Date): boolean`
+- `matchesPattern(str: string, pattern: RegExp): boolean`
+- `validateAll(value: unknown, validators: Array<(value: unknown) => boolean>): boolean`
+
+---
+
+# 📧 Decorators Utilities
+
+## Available Decorators
+
+- `@Controller(basePath: string)` – Class decorator to set the base route.
+- `@Get(path)`, `@Post(path)`, `@Put(path)`, `@Patch(path)`, `@Delete(path)`, `@Options(path)`, `@Head(path)`, `@Trace(path)`, `@Connect(path)` – Method decorators for HTTP verbs.
+- `@Use(...middlewares)` – Attach Express-style middleware to a route handler.
+- `@Query(key?)`, `@Param(key?)`, `@Body(key?)`, `@Req()`, `@Res()` – Parameter decorators for extracting request data.
+- `@HttpCode(status)` – Set custom HTTP status code for the response.
+- `@Header(name, value)` – Set custom response headers.
+- `@Before(fn)`, `@After(fn)` – Register before/after hooks for a route handler.
+
+## Example Usage
+
+```typescript
+import {
+  Controller, Get, Post, Use, Query, Param, Body, Req, Res,
+  HttpCode, Header, Before, After, registerControllers, Request, Response, NextFunction
+} from './src/utils/decorators.utils';
+
+// Example middleware
+function logMiddleware(req: Request, res: Response, next: NextFunction) {
+  console.log('Request:', req.method, req.url);
+  next();
+}
+
+// Example before/after hooks
+function beforeHook(req: Request, res: Response) {
+  console.log('Before handler');
+}
+function afterHook(req: Request, res: Response, result: any) {
+  console.log('After handler', result);
+}
+
+@Controller('/api')
+class ExampleController {
+  @Get('/items/:id')
+  @Use(logMiddleware)
+  @HttpCode(200)
+  @Header('X-Example', 'yes')
+  @Before(beforeHook)
+  @After(afterHook)
+  getItem(
+    @Query('q') q: string,
+    @Param('id') id: string,
+    @Body('name') name: string,
+    @Req() req: Request,
+    @Res() res: Response
+  ) {
+    return { q, id, name };
+  }
+
+  @Post('/items')
+  createItem(@Body() body: any) {
+    return { created: true, ...body };
+  }
+}
+
+// Register controllers with your router (Express-like)
+const router = /* your router instance */;
+registerControllers(router, [ExampleController]);
+```
+
+## Notes
+
+- Decorated methods **must** use standard method syntax, not arrow functions or property initializers.
+- All parameter decorators (`@Query`, `@Param`, etc.) are optional and can be used in any order.
+- `registerControllers(router, controllers)` will register all routes and apply middlewares, hooks, status codes, and headers as defined.
 
 ## 🏁 Usage
 

package/build/esm/config.d.ts

@@ -17,6 +17,18 @@ export declare const Config: {
          */
         isoTimestamp: boolean;
     };
+    Http: {
+        /**
+         * Timeout for HTTP requests in milliseconds
+         */
+        timeout: number;
+    };
+    Cache: {
+        /**
+         * Default TTL (time to live) for cache entries in seconds
+         */
+        defaultTtl: number;
+    };
 };
 export {};
 //# sourceMappingURL=config.d.ts.map

package/build/esm/config.js

@@ -17,5 +17,17 @@ export var Config = {
          */
         isoTimestamp: Env.getBoolean("LOGGER_ISO_TIMESTAMP", false),
     },
+    Http: {
+        /**
+         * Timeout for HTTP requests in milliseconds
+         */
+        timeout: Env.getNumber("HTTP_TIMEOUT", 30000),
+    },
+    Cache: {
+        /**
+         * Default TTL (time to live) for cache entries in seconds
+         */
+        defaultTtl: Env.getNumber("CACHE_DEFAULT_TTL", 300),
+    },
 };
 //# sourceMappingURL=config.js.map

package/build/esm/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAWxC;;GAEG;AACH,MAAM,CAAC,IAAM,MAAM,GAAG;IACpB,MAAM,EAAE;QACN;;WAEG;QACH,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAa;QAElD;;WAEG;QACH,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;QAE1E;;WAEG;QACH,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC,sBAAsB,EAAE,KAAK,CAAC;KAC5D;CACF,CAAC","sourcesContent":["import { Env } from \"./utils/env.utils\";\n\ntype LogLevel =\n  | \"fatal\"\n  | \"error\"\n  | \"warn\"\n  | \"info\"\n  | \"debug\"\n  | \"trace\"\n  | \"silent\";\n\n/**\n * Application runtime configuration loaded from environment variables.\n */\nexport const Config = {\n  Logger: {\n    /**\n     * Logging level (e.g., 'info', 'debug', 'warn', 'error').\n     */\n    level: Env.get(\"LOGGER_LEVEL\", \"info\") as LogLevel,\n\n    /**\n     * Name of the logger instance (defaults to npm package name).\n     */\n    name: Env.get(\"LOGGER_NAME\", Env.get(\"npm_package_name\", \"@catbee/utils\")),\n\n    /**\n     * Whether to use ISO 8601 timestamps in logs.\n     */\n    isoTimestamp: Env.getBoolean(\"LOGGER_ISO_TIMESTAMP\", false),\n  },\n};\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAWxC;;GAEG;AACH,MAAM,CAAC,IAAM,MAAM,GAAG;IACpB,MAAM,EAAE;QACN;;WAEG;QACH,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAa;QAElD;;WAEG;QACH,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;QAE1E;;WAEG;QACH,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC,sBAAsB,EAAE,KAAK,CAAC;KAC5D;IAED,IAAI,EAAE;QACJ;;WAEG;QACH,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,KAAK,CAAC;KAC9C;IAED,KAAK,EAAE;QACL;;WAEG;QACH,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,GAAG,CAAC;KACpD;CACF,CAAC","sourcesContent":["import { Env } from \"./utils/env.utils\";\n\ntype LogLevel =\n  | \"fatal\"\n  | \"error\"\n  | \"warn\"\n  | \"info\"\n  | \"debug\"\n  | \"trace\"\n  | \"silent\";\n\n/**\n * Application runtime configuration loaded from environment variables.\n */\nexport const Config = {\n  Logger: {\n    /**\n     * Logging level (e.g., 'info', 'debug', 'warn', 'error').\n     */\n    level: Env.get(\"LOGGER_LEVEL\", \"info\") as LogLevel,\n\n    /**\n     * Name of the logger instance (defaults to npm package name).\n     */\n    name: Env.get(\"LOGGER_NAME\", Env.get(\"npm_package_name\", \"@catbee/utils\")),\n\n    /**\n     * Whether to use ISO 8601 timestamps in logs.\n     */\n    isoTimestamp: Env.getBoolean(\"LOGGER_ISO_TIMESTAMP\", false),\n  },\n\n  Http: {\n    /**\n     * Timeout for HTTP requests in milliseconds\n     */\n    timeout: Env.getNumber(\"HTTP_TIMEOUT\", 30000),\n  },\n\n  Cache: {\n    /**\n     * Default TTL (time to live) for cache entries in seconds\n     */\n    defaultTtl: Env.getNumber(\"CACHE_DEFAULT_TTL\", 300),\n  },\n};\n"]}

package/build/esm/index.d.ts

@@ -10,6 +10,7 @@ export * from "./utils/fs.utils";
 export * from "./utils/http-status-codes";
 export * from "./utils/id.utils";
 export * from "./utils/logger.utils";
+export * from "./utils/middleware.utils";
 export * from "./utils/obj.utils";
 export * from "./utils/response.utils";
 export * from "./utils/string.utils";

package/build/esm/index.js

@@ -10,6 +10,7 @@ export * from "./utils/fs.utils";
 export * from "./utils/http-status-codes";
 export * from "./utils/id.utils";
 export * from "./utils/logger.utils";
+export * from "./utils/middleware.utils";
 export * from "./utils/obj.utils";
 export * from "./utils/response.utils";
 export * from "./utils/string.utils";

package/build/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./utils/array.utils\";\nexport * from \"./utils/async.utils\";\nexport * from \"./utils/cache.utils\";\nexport * from \"./utils/context-store.utils\";\nexport * from \"./utils/crypto.utils\";\nexport * from \"./utils/dir.utils\";\nexport * from \"./utils/env.utils\";\nexport * from \"./utils/exception.utils\";\nexport * from \"./utils/fs.utils\";\nexport * from \"./utils/http-status-codes\";\nexport * from \"./utils/id.utils\";\nexport * from \"./utils/logger.utils\";\nexport * from \"./utils/obj.utils\";\nexport * from \"./utils/response.utils\";\nexport * from \"./utils/string.utils\";\nexport * from \"./utils/url.utils\";\nexport * from \"./utils/validate.utils\";\n\nexport * from \"./types/api-response\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./utils/array.utils\";\nexport * from \"./utils/async.utils\";\nexport * from \"./utils/cache.utils\";\nexport * from \"./utils/context-store.utils\";\nexport * from \"./utils/crypto.utils\";\nexport * from \"./utils/dir.utils\";\nexport * from \"./utils/env.utils\";\nexport * from \"./utils/exception.utils\";\nexport * from \"./utils/fs.utils\";\nexport * from \"./utils/http-status-codes\";\nexport * from \"./utils/id.utils\";\nexport * from \"./utils/logger.utils\";\nexport * from \"./utils/middleware.utils\";\nexport * from \"./utils/obj.utils\";\nexport * from \"./utils/response.utils\";\nexport * from \"./utils/string.utils\";\nexport * from \"./utils/url.utils\";\nexport * from \"./utils/validate.utils\";\n\nexport * from \"./types/api-response\";\n"]}