@catbee/utils 2.0.0-next.0 → 2.0.0

package/logger/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/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
@@ -22,4 +22,192 @@
  * SOFTWARE.
  */
 
-export * from './logger.utils';
+import pino, { Logger as Logger$1 } from 'pino';
+
+/**
+ * Logger type for application-wide logging.
+ */
+type Logger = Logger$1;
+/**
+ * Logger levels for application-wide logging.
+ */
+type LoggerLevels = pino.Level;
+declare const defaultSensitiveFields: string[];
+/**
+ * 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
+ */
+declare function setRedactCensor(fn: (value: unknown, path: string[], sensitiveFields?: string[]) => string): void;
+/**
+ * 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
+ */
+declare function getRedactCensor(): (value: unknown, path: string[], sensitiveFields?: string[]) => string;
+/**
+ * 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
+ */
+declare function redact(value: unknown, path: string[], sensitiveFields?: string[]): string;
+/**
+ * @deprecated Use addSensitiveFields instead.
+ *
+ * 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
+ */
+declare function addRedactFields(fields: string[]): void;
+/**
+ * Retrieves the expanded list of sensitive fields.
+ *
+ * This function expands the default sensitive fields into their various naming
+ * conventions (e.g., camelCase, snake_case) and caches the result for efficiency.
+ *
+ * @returns Array of expanded sensitive field names
+ */
+declare function getExpandedSensitiveFields(): string[];
+/**
+ * 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
+ */
+declare function setSensitiveFields(fields: string[]): void;
+/**
+ * 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
+ */
+declare function addSensitiveFields(fields: string[]): void;
+/**
+ * Use an object compatible with either modern or legacy global scopes.
+ */
+declare const _globalThis: typeof globalThis;
+/**
+ * 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
+ * - If newInstance is true, returns a fresh logger without any context
+ *
+ * @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(newInstance?: boolean): Logger$1;
+/**
+ * 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
+ */
+declare function createChildLogger(bindings: Record<string, any>, parentLogger?: Logger$1): Logger$1;
+/**
+ * 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
+ */
+declare function createRequestLogger(requestId: string, additionalContext?: Record<string, any>): Logger$1;
+/**
+ * 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
+ */
+declare function logError(error: Error | string, message?: string, context?: Record<string, any>): void;
+/**
+ * Expands multiple sensitive field names into their variants.
+ * Useful to match fields like `api_key`, `apiKey`, `apikey`, `APIKEY`, etc.
+ */
+declare function expandSensitiveFields(fields: string[]): string[];
+/**
+ * Generates multiple variants of a sensitive field name.
+ * Useful to match fields like `api_key`, `apiKey`, `apikey`, `APIKEY`, etc.
+ */
+declare function expandSensitiveField(field: string): string[];
+/**
+ * Generates wildcard paths up to the given depth.
+ *
+ * depth = 2 ->
+ *  password
+ *  *.password
+ *  *.*.password
+ */
+declare function generateDeepPaths(field: string, depth: number): string[];
+
+export { _globalThis, addRedactFields, addSensitiveFields, createChildLogger, createRequestLogger, defaultSensitiveFields, expandSensitiveField, expandSensitiveFields, generateDeepPaths, getExpandedSensitiveFields, getLogger, getRedactCensor, logError, redact, setRedactCensor, setSensitiveFields };
+export type { Logger, LoggerLevels };

package/logger/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/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
@@ -23,7 +23,7 @@
  */
 
 import pino, { stdTimeFunctions } from 'pino';
-import { defaultCatbeeConfig } from '@catbee/utils/config';
+import { getCatbeeGlobalConfig } from '@catbee/utils/config';
 import { ContextStore, StoreKeys } from '@catbee/utils/context-store';
 
 var __defProp = Object.defineProperty;
@@ -127,9 +127,7 @@ function addRedactFields(fields) {
 __name(addRedactFields, "addRedactFields");
 var cachedExpandedFields = null;
 function getExpandedSensitiveFields() {
-  if (!cachedExpandedFields) {
-    cachedExpandedFields = expandSensitiveFields(defaultSensitiveFields);
-  }
+  cachedExpandedFields ??= expandSensitiveFields(defaultSensitiveFields);
   return cachedExpandedFields;
 }
 __name(getExpandedSensitiveFields, "getExpandedSensitiveFields");
@@ -152,8 +150,8 @@ function setupLogger(isGlobal = true) {
     ...sensitiveFields.flatMap((field) => generateDeepPaths(field, 2))
   ]);
   const logParams = {
-    name: defaultCatbeeConfig.logger?.name || "@catbee/utils",
-    level: defaultCatbeeConfig.logger?.level || "info",
+    name: getCatbeeGlobalConfig().logger?.name || "@catbee/utils",
+    level: getCatbeeGlobalConfig().logger?.level || "info",
     redact: {
       paths: Array.from(paths),
       censor: /* @__PURE__ */ __name((value, path) => redact(value, path), "censor")
@@ -169,25 +167,25 @@ function setupLogger(isGlobal = true) {
     timestamp: stdTimeFunctions.isoTime
   };
   let logger;
-  const logDir = defaultCatbeeConfig.logger?.dir?.trim();
+  const logDir = getCatbeeGlobalConfig().logger?.dir?.trim();
   const hasFileLogging = Boolean(logDir);
-  if (hasFileLogging && defaultCatbeeConfig.logger?.pretty) {
+  if (hasFileLogging && getCatbeeGlobalConfig().logger?.pretty) {
     logger = pino(logParams, pino.transport({
       targets: [
         {
           target: "pino-pretty",
-          level: defaultCatbeeConfig.logger?.level ?? "info",
+          level: getCatbeeGlobalConfig().logger?.level ?? "info",
           options: {
-            colorize: defaultCatbeeConfig.logger?.colorize,
+            colorize: getCatbeeGlobalConfig().logger?.colorize,
             translateTime: "SYS:standard",
             ignore: "pid,hostname",
-            singleLine: defaultCatbeeConfig.logger?.singleLine,
+            singleLine: getCatbeeGlobalConfig().logger?.singleLine,
             levelFirst: true
           }
         },
         {
           target: "pino/file",
-          level: defaultCatbeeConfig.logger?.level ?? "info",
+          level: getCatbeeGlobalConfig().logger?.level ?? "info",
           options: {
             destination: `${logDir}/app.log`,
             mkdir: true
@@ -203,14 +201,14 @@ function setupLogger(isGlobal = true) {
         mkdir: true
       }
     }));
-  } else if (defaultCatbeeConfig.logger?.pretty) {
+  } else if (getCatbeeGlobalConfig().logger?.pretty) {
     logger = pino(logParams, pino.transport({
       target: "pino-pretty",
       options: {
-        colorize: defaultCatbeeConfig.logger?.colorize,
+        colorize: getCatbeeGlobalConfig().logger?.colorize,
         translateTime: "SYS:standard",
         ignore: "pid,hostname",
-        singleLine: defaultCatbeeConfig.logger?.singleLine,
+        singleLine: getCatbeeGlobalConfig().logger?.singleLine,
         levelFirst: true
       }
     }));

package/middleware/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/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

package/middleware/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/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
@@ -22,4 +22,106 @@
  * SOFTWARE.
  */
 
-export * from './middleware.utils';
+import { Request, Response, NextFunction } from 'express';
+
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+declare function setupRequestContext(options?: {
+    headerName?: string;
+    autoLog?: boolean;
+}): Middleware;
+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');
+ * });
+ */
+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
+ */
+declare function healthCheck(options?: {
+    path?: string;
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean> | boolean;
+    }>;
+    detailed?: boolean;
+}): Middleware;
+
+export { errorHandler, healthCheck, requestId, responseTime, setupRequestContext, timeout };
+export type { ErrorHandlerOptions, Middleware };

package/middleware/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/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