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

package/build/esnext/utils/logger.utils.js

@@ -0,0 +1,300 @@
+/*
+ * 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 pino, { stdTimeFunctions } from 'pino';
+import { config } from '../config';
+import { ContextStore, StoreKeys } from './context-store.utils';
+import { Env } from './env.utils';
+/**
+ * Symbol used to store the root logger in the Node.js global object.
+ */
+const GLOBAL_LOGGER_KEY = Symbol.for('logger');
+// Default sensitive fields
+export const defaultSensitiveFields = [
+    'password',
+    'secret',
+    'token',
+    'apiKey',
+    'api_key',
+    'auth',
+    'jwt',
+    'access_token',
+    'client_secret',
+    'session_token',
+    'refresh_token'
+];
+/**
+ * The global censor function used by the logger.
+ */
+let globalRedactCensor = (value, path, sensitiveFields = defaultSensitiveFields) => {
+    if (typeof value !== 'string')
+        return '***';
+    const lowerPath = path.map(p => p.toLowerCase());
+    const lowerSensitiveFields = sensitiveFields.map(f => f.toLowerCase());
+    if (lowerPath.some(p => lowerSensitiveFields.includes(p)))
+        return '***';
+    // Redact URLs
+    if (lowerPath[0] === 'url') {
+        return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join('|')})=)[^&#]*`, 'gi'), '$1***');
+    }
+    if (lowerPath.some(p => p.includes('authorization') || p.includes('auth'))) {
+        return value.replace(/^(\S+)\s+.+$/, '$1 ***') || '***';
+    }
+    // Redact sensitive fields - check each path segment against each sensitive field
+    if (lowerPath.some(pathPart => lowerSensitiveFields.some(field => pathPart.includes(field)))) {
+        return '***';
+    }
+    if (path.length > 0 && !['req', 'res', 'headers'].includes(lowerPath[0])) {
+        return value;
+    }
+    return value;
+};
+/**
+ * Sets the global redaction censor function used throughout the application for log redaction.
+ *
+ * Use this function to customize how sensitive data is redacted in logs. The provided function
+ * will replace the default censor implementation.
+ *
+ * @example
+ * ```typescript
+ * // Custom censor that redacts only specific values
+ * setRedactCensor((value, path, sensitiveFields) => {
+ *   if (path.includes('password')) return '***';
+ *   return value;
+ * });
+ * ```
+ *
+ * @param fn - The redaction censor function to use globally. This function receives:
+ *   - value: The data value to potentially redact
+ *   - path: Array of strings representing the path to the value in the object
+ *   - sensitiveFields: Optional array of field names to consider sensitive
+ * @returns void
+ */
+export function setRedactCensor(fn) {
+    globalRedactCensor = fn;
+}
+/**
+ * Gets the current global redaction censor function used for log redaction.
+ *
+ * This function is called internally by the logger when determining how to redact
+ * sensitive information. It can also be used to access the current censor implementation
+ * for composition or extension.
+ *
+ * @example
+ * ```typescript
+ * const currentCensor = getRedactCensor();
+ * // Create an enhanced censor that extends the current one
+ * setRedactCensor((value, path, fields) => {
+ *   // Add custom logic before delegating to current censor
+ *   if (someCondition) return customHandling();
+ *   return currentCensor(value, path, fields);
+ * });
+ * ```
+ *
+ * @returns The current redaction censor function
+ */
+export function getRedactCensor() {
+    return globalRedactCensor;
+}
+/**
+ * Convenience function to redact sensitive data using the current global redact censor.
+ *
+ * This is a direct wrapper around the global censor function that simplifies usage
+ * in application code without needing to access the censor function directly.
+ *
+ * @example
+ * ```typescript
+ * // Redact a potential sensitive value
+ * const safeValue = redact(value, ['user', 'apiKey']);
+ * ```
+ *
+ * @param value - The value to potentially redact
+ * @param path - Array of strings representing the path to the value in the object
+ * @param sensitiveFields - Optional array of field names to consider sensitive
+ * @returns The redacted string value or "***" for redacted content
+ */
+export function redact(value, path, sensitiveFields) {
+    return globalRedactCensor(value, path, sensitiveFields);
+}
+/**
+ * Extends the current redaction function with additional fields to redact.
+ *
+ * This function wraps the existing censor while adding more fields to be considered
+ * sensitive without replacing the entire redaction logic.
+ *
+ * @example
+ * ```typescript
+ * // Add custom fields to be redacted in all future redaction operations
+ * addRedactFields(['customerId', 'accountNumber']);
+ * ```
+ *
+ * @param fields - Array of additional field names to redact
+ */
+export function addRedactFields(fields) {
+    const prev = globalRedactCensor;
+    globalRedactCensor = (value, path, sensitiveFields = defaultSensitiveFields) => prev(value, path, [...(sensitiveFields || []), ...fields]);
+}
+/**
+ * Replaces the default list of sensitive fields with a new list.
+ *
+ * This is useful when you want complete control over what fields are considered
+ * sensitive by default, rather than using the library's built-in list.
+ *
+ * @example
+ * ```typescript
+ * // Replace default sensitive fields with a custom list
+ * setSensitiveFields(['password', 'ssn', 'creditCard']);
+ * ```
+ *
+ * @param fields - Array of field names to set as the new default sensitive fields
+ */
+export function setSensitiveFields(fields) {
+    defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);
+}
+/**
+ * Adds additional field names to the default sensitive fields list.
+ *
+ * This preserves the existing sensitive fields while adding new ones for
+ * application-specific sensitive data.
+ *
+ * @example
+ * ```typescript
+ * // Add domain-specific sensitive fields to the default list
+ * addSensitiveFields(['socialSecurityNumber', 'medicalRecordNumber']);
+ * ```
+ *
+ * @param fields - Array of additional field names to add to the sensitive fields list
+ */
+export function addSensitiveFields(fields) {
+    defaultSensitiveFields.push(...fields);
+}
+/**
+ * Use an object compatible with either modern or legacy global scopes.
+ */
+export const _globalThis = typeof globalThis === 'object' ? globalThis : global;
+const _global = _globalThis;
+/**
+ * Initializes the global root logger according to app configuration.
+ *
+ * - Sets log name, level, timestamp, and redaction for sensitive fields.
+ * - Uses singleton in global symbol registry.
+ */
+function setupLogger() {
+    var _a;
+    const logParams = {
+        name: config.logger.name || '@catbee/utils',
+        level: config.logger.level || 'info',
+        redact: {
+            paths: ['req.authorization', 'res.authorization', 'url', 'headers.authorization', 'headers.cookies'],
+            censor: (value, path) => redact(value, path)
+        },
+        // serializers: {
+        //   req: pino.stdSerializers.req,
+        //   request: pino.stdSerializers.req,
+        //   res: pino.stdSerializers.res,
+        //   response: pino.stdSerializers.res,
+        //   err: pino.stdSerializers.err,
+        //   error: pino.stdSerializers.err
+        // },
+        timestamp: stdTimeFunctions.isoTime
+    };
+    const logger = config.logger.pretty && Env.isDev()
+        ? pino(logParams, pino.transport({
+            target: 'pino-pretty',
+            options: {
+                colorize: true,
+                translateTime: 'SYS:standard',
+                ignore: 'pid,hostname',
+                singleLine: config.logger.singleLine,
+                levelFirst: true
+            }
+        }))
+        : pino(logParams);
+    _global[GLOBAL_LOGGER_KEY] = logger;
+    (_a = _global[GLOBAL_LOGGER_KEY]) === null || _a === void 0 ? void 0 : _a.debug('Logger initialized');
+}
+/**
+ * Retrieves the current logger instance:
+ * - Returns a request-scoped logger from AsyncLocalStorage if available
+ * - Falls back to the global (singleton) logger
+ * - Initializes the global logger if not created yet
+ *
+ * @returns {Logger} The logger instance (request-bound or global root logger)
+ */
+export function getLogger() {
+    const logger = ContextStore.get(StoreKeys.LOGGER);
+    if (logger)
+        return logger;
+    if (!_global[GLOBAL_LOGGER_KEY]) {
+        setupLogger();
+    }
+    return _global[GLOBAL_LOGGER_KEY];
+}
+/**
+ * Logger instance for the global context.
+ * This logger is used for logging messages that are not tied to a specific request.
+ */
+export const logger = getLogger();
+/**
+ * Creates a child logger with additional context.
+ *
+ * @param {Record<string, any>} bindings - Properties to attach to all log records
+ * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)
+ * @returns {Logger} Child logger with merged context
+ */
+export function createChildLogger(bindings, parentLogger) {
+    const logger = parentLogger || getLogger();
+    return logger.child(bindings);
+}
+/**
+ * Creates a request-scoped logger with request ID and stores it in context
+ *
+ * @param {string} requestId - Unique request identifier
+ * @param {object} [additionalContext] - Additional context to include in logs
+ * @returns {Logger} Request-scoped logger instance
+ */
+export function createRequestLogger(requestId, additionalContext = {}) {
+    const logger = createChildLogger(Object.assign({ requestId }, additionalContext));
+    try {
+        ContextStore.set(StoreKeys.LOGGER, logger);
+    }
+    catch (_a) {
+        // Context not initialized, can't store logger
+        logger.debug('Failed to store logger in context - AsyncLocalStorage not initialized');
+    }
+    return logger;
+}
+/**
+ * Utility to safely log errors with proper stack trace extraction
+ *
+ * @param {Error|unknown} error - Error object to log
+ * @param {string} [message] - Optional message to include
+ * @param {Record<string, any>} [context] - Additional context properties
+ */
+export function logError(error, message, context) {
+    const logger = getLogger();
+    const errObj = error instanceof Error ? error : new Error(String(error));
+    const logContext = Object.assign(Object.assign({}, context), { error: errObj });
+    logger.error(logContext, message || errObj.message);
+}
+//# sourceMappingURL=logger.utils.js.map

package/build/esnext/utils/logger.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport pino, { LoggerOptions, stdTimeFunctions } from 'pino';\nimport type { Logger as PinoLogger } from 'pino'; // Type-only import\nimport { config } from '../config';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { Env } from './env.utils';\n\n/**\n * Symbol used to store the root logger in the Node.js global object.\n */\nconst GLOBAL_LOGGER_KEY = Symbol.for('logger');\n\n/**\n * Logger type for application-wide logging.\n */\nexport type Logger = pino.Logger;\n\n/**\n * Logger levels for application-wide logging.\n */\nexport type LoggerLevels = pino.Level;\n\n// Default sensitive fields\nexport const defaultSensitiveFields = [\n  'password',\n  'secret',\n  'token',\n  'apiKey',\n  'api_key',\n  'auth',\n  'jwt',\n  'access_token',\n  'client_secret',\n  'session_token',\n  'refresh_token'\n];\n\n/**\n * The global censor function used by the logger.\n */\nlet globalRedactCensor: (value: unknown, path: string[], sensitiveFields?: string[]) => string = (\n  value,\n  path,\n  sensitiveFields = defaultSensitiveFields\n) => {\n  if (typeof value !== 'string') return '***';\n\n  const lowerPath = path.map(p => p.toLowerCase());\n  const lowerSensitiveFields = sensitiveFields.map(f => f.toLowerCase());\n\n  if (lowerPath.some(p => lowerSensitiveFields.includes(p))) return '***';\n\n  // Redact URLs\n  if (lowerPath[0] === 'url') {\n    return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join('|')})=)[^&#]*`, 'gi'), '$1***');\n  }\n\n  if (lowerPath.some(p => p.includes('authorization') || p.includes('auth'))) {\n    return value.replace(/^(\\S+)\\s+.+$/, '$1 ***') || '***';\n  }\n\n  // Redact sensitive fields - check each path segment against each sensitive field\n  if (lowerPath.some(pathPart => lowerSensitiveFields.some(field => pathPart.includes(field)))) {\n    return '***';\n  }\n\n  if (path.length > 0 && !['req', 'res', 'headers'].includes(lowerPath[0])) {\n    return value;\n  }\n\n  return value;\n};\n\n/**\n * Sets the global redaction censor function used throughout the application for log redaction.\n *\n * Use this function to customize how sensitive data is redacted in logs. The provided function\n * will replace the default censor implementation.\n *\n * @example\n * ```typescript\n * // Custom censor that redacts only specific values\n * setRedactCensor((value, path, sensitiveFields) => {\n *   if (path.includes('password')) return '***';\n *   return value;\n * });\n * ```\n *\n * @param fn - The redaction censor function to use globally. This function receives:\n *   - value: The data value to potentially redact\n *   - path: Array of strings representing the path to the value in the object\n *   - sensitiveFields: Optional array of field names to consider sensitive\n * @returns void\n */\nexport function setRedactCensor(fn: (value: unknown, path: string[], sensitiveFields?: string[]) => string) {\n  globalRedactCensor = fn;\n}\n\n/**\n * Gets the current global redaction censor function used for log redaction.\n *\n * This function is called internally by the logger when determining how to redact\n * sensitive information. It can also be used to access the current censor implementation\n * for composition or extension.\n *\n * @example\n * ```typescript\n * const currentCensor = getRedactCensor();\n * // Create an enhanced censor that extends the current one\n * setRedactCensor((value, path, fields) => {\n *   // Add custom logic before delegating to current censor\n *   if (someCondition) return customHandling();\n *   return currentCensor(value, path, fields);\n * });\n * ```\n *\n * @returns The current redaction censor function\n */\nexport function getRedactCensor() {\n  return globalRedactCensor;\n}\n\n/**\n * Convenience function to redact sensitive data using the current global redact censor.\n *\n * This is a direct wrapper around the global censor function that simplifies usage\n * in application code without needing to access the censor function directly.\n *\n * @example\n * ```typescript\n * // Redact a potential sensitive value\n * const safeValue = redact(value, ['user', 'apiKey']);\n * ```\n *\n * @param value - The value to potentially redact\n * @param path - Array of strings representing the path to the value in the object\n * @param sensitiveFields - Optional array of field names to consider sensitive\n * @returns The redacted string value or \"***\" for redacted content\n */\nexport function redact(value: unknown, path: string[], sensitiveFields?: string[]) {\n  return globalRedactCensor(value, path, sensitiveFields);\n}\n\n/**\n * Extends the current redaction function with additional fields to redact.\n *\n * This function wraps the existing censor while adding more fields to be considered\n * sensitive without replacing the entire redaction logic.\n *\n * @example\n * ```typescript\n * // Add custom fields to be redacted in all future redaction operations\n * addRedactFields(['customerId', 'accountNumber']);\n * ```\n *\n * @param fields - Array of additional field names to redact\n */\nexport function addRedactFields(fields: string[]) {\n  const prev = globalRedactCensor;\n  globalRedactCensor = (value, path, sensitiveFields = defaultSensitiveFields) =>\n    prev(value, path, [...(sensitiveFields || []), ...fields]);\n}\n\n/**\n * Replaces the default list of sensitive fields with a new list.\n *\n * This is useful when you want complete control over what fields are considered\n * sensitive by default, rather than using the library's built-in list.\n *\n * @example\n * ```typescript\n * // Replace default sensitive fields with a custom list\n * setSensitiveFields(['password', 'ssn', 'creditCard']);\n * ```\n *\n * @param fields - Array of field names to set as the new default sensitive fields\n */\nexport function setSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);\n}\n\n/**\n * Adds additional field names to the default sensitive fields list.\n *\n * This preserves the existing sensitive fields while adding new ones for\n * application-specific sensitive data.\n *\n * @example\n * ```typescript\n * // Add domain-specific sensitive fields to the default list\n * addSensitiveFields(['socialSecurityNumber', 'medicalRecordNumber']);\n * ```\n *\n * @param fields - Array of additional field names to add to the sensitive fields list\n */\nexport function addSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.push(...fields);\n}\n\n/**\n * Use an object compatible with either modern or legacy global scopes.\n */\nexport const _globalThis = typeof globalThis === 'object' ? globalThis : global;\nconst _global = _globalThis as unknown as { [GLOBAL_LOGGER_KEY]: PinoLogger };\n\n/**\n * Initializes the global root logger according to app configuration.\n *\n * - Sets log name, level, timestamp, and redaction for sensitive fields.\n * - Uses singleton in global symbol registry.\n */\nfunction setupLogger(): void {\n  const logParams: LoggerOptions = {\n    name: config.logger.name || '@catbee/utils',\n    level: config.logger.level || 'info',\n    redact: {\n      paths: ['req.authorization', 'res.authorization', 'url', 'headers.authorization', 'headers.cookies'],\n      censor: (value, path) => redact(value, path)\n    },\n    // serializers: {\n    //   req: pino.stdSerializers.req,\n    //   request: pino.stdSerializers.req,\n    //   res: pino.stdSerializers.res,\n    //   response: pino.stdSerializers.res,\n    //   err: pino.stdSerializers.err,\n    //   error: pino.stdSerializers.err\n    // },\n    timestamp: stdTimeFunctions.isoTime\n  };\n\n  const logger =\n    config.logger.pretty && Env.isDev()\n      ? pino(\n          logParams,\n          pino.transport({\n            target: 'pino-pretty',\n            options: {\n              colorize: true,\n              translateTime: 'SYS:standard',\n              ignore: 'pid,hostname',\n              singleLine: config.logger.singleLine,\n              levelFirst: true\n            }\n          })\n        )\n      : pino(logParams);\n\n  _global[GLOBAL_LOGGER_KEY] = logger;\n  _global[GLOBAL_LOGGER_KEY]?.debug('Logger initialized');\n}\n\n/**\n * Retrieves the current logger instance:\n * - Returns a request-scoped logger from AsyncLocalStorage if available\n * - Falls back to the global (singleton) logger\n * - Initializes the global logger if not created yet\n *\n * @returns {Logger} The logger instance (request-bound or global root logger)\n */\nexport function getLogger(): PinoLogger {\n  const logger = ContextStore.get<PinoLogger>(StoreKeys.LOGGER);\n  if (logger) return logger;\n\n  if (!_global[GLOBAL_LOGGER_KEY]) {\n    setupLogger();\n  }\n\n  return _global[GLOBAL_LOGGER_KEY];\n}\n\n/**\n * Logger instance for the global context.\n * This logger is used for logging messages that are not tied to a specific request.\n */\nexport const logger = getLogger();\n\n/**\n * Creates a child logger with additional context.\n *\n * @param {Record<string, any>} bindings - Properties to attach to all log records\n * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)\n * @returns {Logger} Child logger with merged context\n */\nexport function createChildLogger(bindings: Record<string, any>, parentLogger?: PinoLogger): PinoLogger {\n  const logger = parentLogger || getLogger();\n  return logger.child(bindings);\n}\n\n/**\n * Creates a request-scoped logger with request ID and stores it in context\n *\n * @param {string} requestId - Unique request identifier\n * @param {object} [additionalContext] - Additional context to include in logs\n * @returns {Logger} Request-scoped logger instance\n */\nexport function createRequestLogger(requestId: string, additionalContext: Record<string, any> = {}): PinoLogger {\n  const logger = createChildLogger({\n    requestId,\n    ...additionalContext\n  });\n\n  try {\n    ContextStore.set(StoreKeys.LOGGER, logger);\n  } catch {\n    // Context not initialized, can't store logger\n    logger.debug('Failed to store logger in context - AsyncLocalStorage not initialized');\n  }\n\n  return logger;\n}\n\n/**\n * Utility to safely log errors with proper stack trace extraction\n *\n * @param {Error|unknown} error - Error object to log\n * @param {string} [message] - Optional message to include\n * @param {Record<string, any>} [context] - Additional context properties\n */\nexport function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void {\n  const logger = getLogger();\n\n  const errObj = error instanceof Error ? error : new Error(String(error));\n  const logContext = {\n    ...context,\n    error: errObj\n  };\n\n  logger.error(logContext, message || errObj.message);\n}\n"]}

package/build/esnext/utils/middleware.utils.d.ts

@@ -0,0 +1,100 @@
+import type { Request, Response, NextFunction } from 'express';
+export type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+/**
+ * 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 declare function requestId(options?: {
+    headerName?: string;
+    exposeHeader?: boolean;
+    generator?: () => string;
+}): Middleware;
+/**
+ * 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 declare function responseTime(options?: {
+    addHeader?: boolean;
+    logOnComplete?: boolean;
+}): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Request timeout middleware.
+ * Aborts requests that take too long to process.
+ *
+ * @param {number} [timeoutMs=30000] - Timeout in milliseconds
+ * @returns {Middleware} Express-compatible middleware
+ */
+export declare function timeout(timeoutMs?: number): Middleware;
+/**
+ * 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 declare function setupRequestContext(options?: {
+    headerName?: string;
+    autoLog?: boolean;
+}): Middleware;
+export interface ErrorHandlerOptions {
+    /** Whether to log errors (default: true) */
+    logErrors?: boolean;
+    /** Whether to include error details in non-production (default: false) */
+    includeDetails?: boolean;
+}
+/**
+ * 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 declare function errorHandler(options?: ErrorHandlerOptions): (err: any, req: Request, res: Response, _next: NextFunction) => Response<any, Record<string, any>>;
+/**
+ * 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 declare function healthCheck(options?: {
+    path?: string;
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean> | boolean;
+    }>;
+    detailed?: boolean;
+}): Middleware;
+//# sourceMappingURL=middleware.utils.d.ts.map

package/build/esnext/utils/middleware.utils.js

@@ -0,0 +1,236 @@
+/*
+ * 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 === null || options === void 0 ? void 0 : options.headerName) || 'X-Request-ID';
+    const exposeHeader = (options === null || options === void 0 ? void 0 : options.exposeHeader) !== false;
+    const generateId = (options === null || options === void 0 ? void 0 : 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 === null || options === void 0 ? void 0 : options.addHeader) !== false;
+    const logOnComplete = (options === null || options === void 0 ? void 0 : 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 === null || req === void 0 ? void 0 : 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 === null || options === void 0 ? void 0 : options.logErrors) !== false;
+    const includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) === true;
+    return (err, req, res, _next) => {
+        // Determine status code
+        const status = (err === null || err === void 0 ? void 0 : err.status) || (err === null || err === void 0 ? void 0 : 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 === null || err === void 0 ? void 0 : err.requestId) || (req === null || req === void 0 ? void 0 : req.id) || uuid(),
+                status,
+                path: req.originalUrl || req.url
+            };
+            if (includeDetails && (err === null || err === void 0 ? void 0 : 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 === null || err === void 0 ? void 0 : 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 === null || options === void 0 ? void 0 : options.path) || '/healthz';
+    const checks = (options === null || options === void 0 ? void 0 : options.checks) || [];
+    const detailed = (options === null || options === void 0 ? void 0 : 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 (_a) {
+                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);
+    };
+}
+//# sourceMappingURL=middleware.utils.js.map