@catbee/utils 0.0.8-rc.2 → 0.0.8-rc.4

package/build/esm/utils/middleware.utils.js

@@ -1,235 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-import { uuid } from './id.utils';
-import { HttpStatusCodes } from './http-status-codes';
-import { createFinalErrorResponse, ErrorResponse } from './response.utils';
-import { getLogger } from './logger.utils';
-import { ContextStore, StoreKeys } from './context-store.utils';
-import { RequestTimeoutException } from './exception.utils';
-/**
- * Attaches a unique request ID to each request.
- * Useful for request tracing and correlation between logs.
- *
- * @param {object} [options] - Configuration options
- * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID
- * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response
- * @param {() => string} [options.generator] - Custom ID generator function
- * @returns {Middleware} Express-compatible middleware
- */
-export function requestId(options) {
-    const headerName = options?.headerName || 'X-Request-ID';
-    const exposeHeader = options?.exposeHeader !== false;
-    const generateId = options?.generator || uuid;
-    return (req, res, next) => {
-        // Use existing request ID from header or generate a new one
-        const existingId = req.headers[headerName.toLowerCase()];
-        const id = existingId || generateId();
-        // Attach ID to request object
-        req.id = id;
-        // Add ID to response headers
-        if (exposeHeader) {
-            res.setHeader(headerName, id);
-        }
-        next();
-    };
-}
-/**
- * Measures request processing time and logs or adds it to response headers.
- *
- * @param {object} [options] - Configuration options
- * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header
- * @param {boolean} [options.logOnComplete=false] - Whether to log timing info
- * @returns {Middleware} Express-compatible middleware
- */
-export function responseTime(options) {
-    const addHeader = options?.addHeader !== false;
-    const logOnComplete = options?.logOnComplete === true;
-    return (req, res, next) => {
-        const start = process.hrtime();
-        // Function to calculate duration
-        const getDuration = () => {
-            const diff = process.hrtime(start);
-            return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);
-        };
-        if (addHeader) {
-            // Ensure header is set before response is sent
-            const originalWriteHead = res.writeHead;
-            res.writeHead = function (...args) {
-                res.setHeader('X-Response-Time', `${getDuration()}ms`);
-                return originalWriteHead.apply(this, args);
-            };
-        }
-        if (logOnComplete) {
-            res.on('finish', () => {
-                getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);
-            });
-        }
-        next();
-    };
-}
-/**
- * Request timeout middleware.
- * Aborts requests that take too long to process.
- *
- * @param {number} [timeoutMs=30000] - Timeout in milliseconds
- * @returns {Middleware} Express-compatible middleware
- */
-export function timeout(timeoutMs = 30000) {
-    return (_req, res, next) => {
-        // Set timeout for the request
-        const timer = setTimeout(() => {
-            const response = new RequestTimeoutException('Request timed out');
-            res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);
-        }, timeoutMs);
-        // Clear timeout when response is sent
-        res.on('finish', () => {
-            clearTimeout(timer);
-        });
-        next();
-    };
-}
-/**
- * Creates an Express middleware that initializes a per-request context.
- *
- * @param {object} [options] - Optional configuration
- * @param {string} [options.headerName='x-request-id'] - Header to look for request ID
- * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized
- * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function
- */
-export function setupRequestContext(options = {}) {
-    const { headerName = 'x-request-id', autoLog = true } = options;
-    return (req, _res, next) => {
-        // Generate or use existing request ID
-        const requestId = req.headers[headerName] || req?.['id'] || uuid();
-        ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {
-            // Create a child logger for this request
-            const childLogger = getLogger().child({
-                requestId,
-                method: req.method,
-                url: req.originalUrl || req.url
-            });
-            req.logger = childLogger;
-            // Store logger in context
-            ContextStore.set(StoreKeys.LOGGER, childLogger);
-            if (autoLog) {
-                req.logger.info('Request context initialized');
-            }
-            next();
-        });
-    };
-}
-/**
- * Global error handling middleware with enhanced features.
- *
- * @param {ErrorHandlerOptions} options - Error handler options
- * @param {boolean} [options.logErrors=true] - Whether to log errors
- * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
- * @returns Error middleware
- *
- * @example
- * import express from 'express';
- * import { errorHandler } from '@catbee/utils';
- *
- * const app = express();
- *
- * // Your routes
- * app.get('/ping', (req, res) => {
- *   throw new Error('Something went wrong');
- * });
- *
- * // Error handler (must be last middleware)
- * app.use(errorHandler({ includeDetails: true }));
- *
- * app.listen(3000, () => {
- *   console.log('Server running on port 3000');
- * });
- */
-export function errorHandler(options) {
-    const logErrors = options?.logErrors !== false;
-    const includeDetails = options?.includeDetails === true;
-    return (err, req, res, _next) => {
-        // Determine status code
-        const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;
-        // Log error if enabled
-        if (logErrors) {
-            getLogger().error({ err }, `${err.message || 'Unknown error'}`);
-        }
-        // Handle ErrorResponse instances (our custom error class)
-        if (err instanceof ErrorResponse) {
-            const result = {
-                error: true,
-                message: err.message,
-                timestamp: err.timestamp,
-                requestId: err?.requestId || req?.id || uuid(),
-                status,
-                path: req.originalUrl || req.url
-            };
-            if (includeDetails && err?.stack) {
-                result.stack = err.stack.split('\n').map((line) => line.trim());
-            }
-            return res.status(status).json(result);
-        }
-        // Handle any other errors
-        return res
-            .status(status)
-            .json(createFinalErrorResponse(req, status, err?.message || 'Internal Server Error', err, { includeDetails }));
-    };
-}
-/**
- * Health check middleware for service status and custom checks.
- *
- * @param {object} [options] - Health check options
- * @param {string} [options.path='/healthz'] - Health check endpoint path
- * @param {Array<{name: string; check: () => Promise<boolean> | boolean}>} [options.checks] - Custom health checks
- * @param {boolean} [options.detailed=true] - Show detailed check results
- * @returns {Middleware} Express-compatible middleware
- */
-export function healthCheck(options) {
-    const path = options?.path || '/healthz';
-    const checks = options?.checks || [];
-    const detailed = options?.detailed !== false;
-    return async (req, res, next) => {
-        if (req.path !== path)
-            return next();
-        const results = {};
-        let allHealthy = true;
-        for (const check of checks) {
-            try {
-                const result = await Promise.resolve(check.check());
-                results[check.name] = !!result;
-                if (!result)
-                    allHealthy = false;
-            }
-            catch {
-                results[check.name] = false;
-                allHealthy = false;
-            }
-        }
-        const status = allHealthy ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;
-        const response = detailed
-            ? { status: allHealthy ? 'ok' : 'unhealthy', checks: results, timestamp: new Date().toISOString() }
-            : { status: allHealthy ? 'ok' : 'unhealthy' };
-        res.status(status).json(response);
-    };
-}

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

@@ -1,123 +0,0 @@
-/**
- * Checks whether the object has no own enumerable properties.
- *
- * @param {Record<any, any>} obj - The object to check.
- * @returns {boolean} True if the object is empty, false otherwise.
- */
-export declare function isObjEmpty(obj: Record<any, any>): boolean;
-/**
- * Returns a new object with only the specified keys picked.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to pick from the object.
- * @returns {Pick<T, K>} New object with picked keys.
- */
-export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
-/**
- * Returns a new object with the specified keys omitted.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to omit from the object.
- * @returns {Omit<T, K>} New object without omitted keys.
- */
-export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
-/**
- * Deeply merges multiple objects into the target object (mutates and returns the target object, not pure).
- *
- * @template T
- * @param {T} target - The object to merge into (will be mutated).
- * @param {...any[]} sources - The objects to merge from.
- * @returns {T} The merged object (same as target).
- */
-export declare function deepObjMerge<T extends object>(target: T, ...sources: any[]): T;
-/**
- * Checks if a value is a plain object (i.e., not an array, null, or a built-in object).
- *
- * @param value - The value to check.
- * @returns True if the value is a plain object, false otherwise.
- */
-export declare function isPlainObject(value: any): value is Record<string, any>;
-/**
- * Flattens a nested object using dot notation for keys (e.g., `{a: {b: 1}}` → `{ "a.b": 1 }`).
- *
- * @template T
- * @param {T} obj - The object to flatten.
- * @param {string} [prefix=""] - Optional prefix for nested keys (used internally).
- * @returns {Record<string, any>} A new object with flattened keys.
- */
-export declare function flattenObject<T extends Record<string, any>>(obj: T, prefix?: string): Record<string, any>;
-/**
- * Safely gets the value of a deeply nested key in an object using dot/bracket notation path.
- *
- * @template T
- * @param {T} obj - The object to extract from.
- * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
- * @returns {any} The value at the given path, or undefined if not found.
- */
-export declare function getValueByPath<T extends object>(obj: T, path: string): any;
-/**
- * Sets a value at a deeply nested key in an object using dot/bracket notation path.
- * Creates intermediate objects and arrays as needed.
- *
- * @template T
- * @param {T} obj - The object to modify.
- * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
- * @param {any} value - The value to set at the path.
- * @returns {T} The modified object.
- */
-export declare function setValueByPath<T extends object>(obj: T, path: string, value: any): T;
-/**
- * Performs a deep equality check between two objects.
- *
- * @param {any} a - First value to compare.
- * @param {any} b - Second value to compare.
- * @returns {boolean} True if values are deeply equal.
- */
-export declare function isEqual(a: any, b: any): boolean;
-/**
- * Filters object properties based on a predicate function.
- *
- * @template T
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => boolean} predicate - Filter function.
- * @returns {Partial<T>} New object with filtered properties.
- */
-export declare function filterObject<T extends object>(obj: T, predicate: (value: any, key: string, obj: T) => boolean): Partial<T>;
-/**
- * Maps object values to new values using a mapping function.
- *
- * @template T
- * @template U
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => U} mapFn - Mapping function.
- * @returns {Record<keyof T, U>} New object with mapped values.
- */
-export declare function mapObject<T extends object, U>(obj: T, mapFn: (value: any, key: string, obj: T) => U): Record<keyof T, U>;
-/**
- * Recursively freezes an object and all its properties.
- * Makes an object immutable.
- *
- * @template T
- * @param {T} obj - The object to freeze.
- * @returns {Readonly<T>} The frozen object.
- */
-export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
-/**
- * Safely checks if a value is an object (not null, not array).
- *
- * @param {unknown} value - Value to check.
- * @returns {boolean} True if value is a non-null, non-array object.
- */
-export declare function isObject(value: unknown): value is Record<string, any>;
-/**
- * Gets all paths in an object using dot notation.
- *
- * @param {Record<string, any>} obj - Object to analyze.
- * @param {string} [parentPath=""] - Internal param for recursion.
- * @returns {string[]} Array of all paths in dot notation.
- */
-export declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];