@catbee/utils 1.0.5 → 2.0.0-next.0

package/logger/logger.utils.d.ts

@@ -0,0 +1,210 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 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
+ * 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 from 'pino';
+import type { Logger as PinoLogger } from 'pino';
+/**
+ * Logger type for application-wide logging.
+ */
+export type Logger = PinoLogger;
+/**
+ * Logger levels for application-wide logging.
+ */
+export type LoggerLevels = pino.Level;
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export declare function addSensitiveFields(fields: string[]): void;
+/**
+ * Use an object compatible with either modern or legacy global scopes.
+ */
+export 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)
+ */
+export declare function getLogger(newInstance?: boolean): PinoLogger;
+/**
+ * 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 declare function createChildLogger(bindings: Record<string, any>, parentLogger?: PinoLogger): PinoLogger;
+/**
+ * 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 declare function createRequestLogger(requestId: string, additionalContext?: Record<string, any>): PinoLogger;
+/**
+ * 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 declare function logError(error: Error | unknown, 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.
+ */
+export 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.
+ */
+export declare function expandSensitiveField(field: string): string[];
+/**
+ * Generates wildcard paths up to the given depth.
+ *
+ * depth = 2 →
+ *  password
+ *  *.password
+ *  *.*.password
+ */
+export declare function generateDeepPaths(field: string, depth: number): string[];

package/middleware/index.cjs

@@ -0,0 +1,177 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 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
+ * 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.
+ */
+
+'use strict';
+
+var id = require('@catbee/utils/id');
+var httpStatusCodes = require('@catbee/utils/http-status-codes');
+var response = require('@catbee/utils/response');
+var logger = require('@catbee/utils/logger');
+var contextStore = require('@catbee/utils/context-store');
+var exception = require('@catbee/utils/exception');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function requestId(options) {
+  const headerName = options?.headerName || "X-Request-ID";
+  const exposeHeader = options?.exposeHeader !== false;
+  const generateId = options?.generator || id.uuid;
+  return (req, res, next) => {
+    const existingId = req.headers[headerName.toLowerCase()];
+    const id = existingId || generateId();
+    req.id = id;
+    if (exposeHeader) {
+      res.setHeader(headerName, id);
+    }
+    next();
+  };
+}
+__name(requestId, "requestId");
+function responseTime(options) {
+  const addHeader = options?.addHeader !== false;
+  const logOnComplete = options?.logOnComplete === true;
+  return (req, res, next) => {
+    const start = process.hrtime();
+    const getDuration = /* @__PURE__ */ __name(() => {
+      const diff = process.hrtime(start);
+      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);
+    }, "getDuration");
+    if (addHeader) {
+      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", () => {
+        logger.getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);
+      });
+    }
+    next();
+  };
+}
+__name(responseTime, "responseTime");
+function timeout(timeoutMs = 3e4) {
+  return (_req, res, next) => {
+    const timer = setTimeout(() => {
+      const response = new exception.RequestTimeoutException("Request timed out");
+      res.status(httpStatusCodes.HttpStatusCodes.REQUEST_TIMEOUT).json(response);
+    }, timeoutMs);
+    res.on("finish", () => {
+      clearTimeout(timer);
+    });
+    next();
+  };
+}
+__name(timeout, "timeout");
+function setupRequestContext(options = {}) {
+  const { headerName = "x-request-id", autoLog = true } = options;
+  return (req, _res, next) => {
+    const requestId2 = req.headers[headerName] || req?.["id"] || id.uuid();
+    contextStore.ContextStore.run({
+      [contextStore.StoreKeys.REQUEST_ID]: requestId2
+    }, () => {
+      const childLogger = logger.getLogger().child({
+        requestId: requestId2,
+        method: req.method,
+        url: req.originalUrl || req.url
+      });
+      req.logger = childLogger;
+      contextStore.ContextStore.set(contextStore.StoreKeys.LOGGER, childLogger);
+      if (autoLog) {
+        req.logger.info("Request context initialized");
+      }
+      next();
+    });
+  };
+}
+__name(setupRequestContext, "setupRequestContext");
+function errorHandler(options) {
+  const logErrors = options?.logErrors !== false;
+  const includeDetails = options?.includeDetails === true;
+  return (err, req, res, _next) => {
+    const status = err?.status || err?.statusCode || httpStatusCodes.HttpStatusCodes.INTERNAL_SERVER_ERROR;
+    if (logErrors) {
+      logger.getLogger().error({
+        err
+      }, `${err.message || "Unknown error"}`);
+    }
+    if (err instanceof response.ErrorResponse) {
+      const result = {
+        error: true,
+        message: err.message,
+        timestamp: err.timestamp,
+        requestId: err?.requestId || req?.id || 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);
+    }
+    return res.status(status).json(response.createFinalErrorResponse(req, status, err?.message || "Internal Server Error", err, {
+      includeDetails
+    }));
+  };
+}
+__name(errorHandler, "errorHandler");
+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.HttpStatusCodes.OK : httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE;
+    const response = detailed ? {
+      status: allHealthy ? "ok" : "unhealthy",
+      checks: results,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    } : {
+      status: allHealthy ? "ok" : "unhealthy"
+    };
+    res.status(status).json(response);
+  };
+}
+__name(healthCheck, "healthCheck");
+
+exports.errorHandler = errorHandler;
+exports.healthCheck = healthCheck;
+exports.requestId = requestId;
+exports.responseTime = responseTime;
+exports.setupRequestContext = setupRequestContext;
+exports.timeout = timeout;

package/middleware/index.d.ts

@@ -0,0 +1,25 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 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
+ * 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.
+ */
+
+export * from './middleware.utils';

package/middleware/index.mjs

@@ -0,0 +1,170 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 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
+ * 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 '@catbee/utils/id';
+import { HttpStatusCodes } from '@catbee/utils/http-status-codes';
+import { ErrorResponse, createFinalErrorResponse } from '@catbee/utils/response';
+import { getLogger } from '@catbee/utils/logger';
+import { ContextStore, StoreKeys } from '@catbee/utils/context-store';
+import { RequestTimeoutException } from '@catbee/utils/exception';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function requestId(options) {
+  const headerName = options?.headerName || "X-Request-ID";
+  const exposeHeader = options?.exposeHeader !== false;
+  const generateId = options?.generator || uuid;
+  return (req, res, next) => {
+    const existingId = req.headers[headerName.toLowerCase()];
+    const id = existingId || generateId();
+    req.id = id;
+    if (exposeHeader) {
+      res.setHeader(headerName, id);
+    }
+    next();
+  };
+}
+__name(requestId, "requestId");
+function responseTime(options) {
+  const addHeader = options?.addHeader !== false;
+  const logOnComplete = options?.logOnComplete === true;
+  return (req, res, next) => {
+    const start = process.hrtime();
+    const getDuration = /* @__PURE__ */ __name(() => {
+      const diff = process.hrtime(start);
+      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);
+    }, "getDuration");
+    if (addHeader) {
+      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();
+  };
+}
+__name(responseTime, "responseTime");
+function timeout(timeoutMs = 3e4) {
+  return (_req, res, next) => {
+    const timer = setTimeout(() => {
+      const response = new RequestTimeoutException("Request timed out");
+      res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);
+    }, timeoutMs);
+    res.on("finish", () => {
+      clearTimeout(timer);
+    });
+    next();
+  };
+}
+__name(timeout, "timeout");
+function setupRequestContext(options = {}) {
+  const { headerName = "x-request-id", autoLog = true } = options;
+  return (req, _res, next) => {
+    const requestId2 = req.headers[headerName] || req?.["id"] || uuid();
+    ContextStore.run({
+      [StoreKeys.REQUEST_ID]: requestId2
+    }, () => {
+      const childLogger = getLogger().child({
+        requestId: requestId2,
+        method: req.method,
+        url: req.originalUrl || req.url
+      });
+      req.logger = childLogger;
+      ContextStore.set(StoreKeys.LOGGER, childLogger);
+      if (autoLog) {
+        req.logger.info("Request context initialized");
+      }
+      next();
+    });
+  };
+}
+__name(setupRequestContext, "setupRequestContext");
+function errorHandler(options) {
+  const logErrors = options?.logErrors !== false;
+  const includeDetails = options?.includeDetails === true;
+  return (err, req, res, _next) => {
+    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;
+    if (logErrors) {
+      getLogger().error({
+        err
+      }, `${err.message || "Unknown error"}`);
+    }
+    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);
+    }
+    return res.status(status).json(createFinalErrorResponse(req, status, err?.message || "Internal Server Error", err, {
+      includeDetails
+    }));
+  };
+}
+__name(errorHandler, "errorHandler");
+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: (/* @__PURE__ */ new Date()).toISOString()
+    } : {
+      status: allHealthy ? "ok" : "unhealthy"
+    };
+    res.status(status).json(response);
+  };
+}
+__name(healthCheck, "healthCheck");
+
+export { errorHandler, healthCheck, requestId, responseTime, setupRequestContext, timeout };