@catbee/utils 2.0.5 → 2.2.0

package/index.cjs

@@ -39,6 +39,7 @@ var env = require("./env/index.cjs");
 var error = require("./error/index.cjs");
 var exception = require("./exception/index.cjs");
 var fs = require("./fs/index.cjs");
+var healthzServer = require("./healthz-server/index.cjs");
 var httpStatusCodes = require("./http-status-codes/index.cjs");
 var id = require("./id/index.cjs");
 var logger = require("./logger/index.cjs");
@@ -145,6 +146,12 @@ Object.keys(fs).forEach(function (k) {
 		get: function () { return fs[k]; }
 	});
 });
+Object.keys(healthzServer).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return healthzServer[k]; }
+	});
+});
 Object.keys(httpStatusCodes).forEach(function (k) {
 	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/index.d.ts

@@ -37,6 +37,7 @@ export * from './env';
 export * from './error';
 export * from './exception';
 export * from './fs';
+export * from './healthz-server';
 export * from './http-status-codes';
 export * from './id';
 export * from './logger';

package/index.mjs

@@ -37,6 +37,7 @@ export * from "./env/index.mjs";
 export * from "./error/index.mjs";
 export * from "./exception/index.mjs";
 export * from "./fs/index.mjs";
+export * from "./healthz-server/index.mjs";
 export * from "./http-status-codes/index.mjs";
 export * from "./id/index.mjs";
 export * from "./logger/index.mjs";

package/logger/index.cjs

@@ -57,57 +57,140 @@ var defaultSensitiveFields = [
   "passphrase",
   "otp",
   "api_secret",
-  "token_secret"
+  "token_secret",
+  "cookie",
+  "cookies",
+  "set-cookie",
+  "session_id",
+  "credit_card",
+  "card_number",
+  "cvv",
+  "cvc",
+  "ssn",
+  "pin"
 ];
-var defaultRedactPaths = [
-  "req.authorization",
-  "req.headers.authorization",
-  "req.headers.cookie",
-  'req.headers["x-api-key"]',
-  'req.headers["x-auth-token"]',
-  'req.headers["x-access-token"]',
-  "req.body.password",
-  "req.body.token",
-  "req.body.secret",
-  "req.query.token",
-  "req.query.api_key",
-  "req.query.apiKey",
-  "res.authorization",
-  "res.headers.authorization",
-  'res.headers["set-cookie"]',
+var requestSubPaths = [
+  "authorization",
   "headers.authorization",
+  "headers.cookie",
   "headers.cookies",
   'headers["set-cookie"]',
   'headers["x-api-key"]',
   'headers["x-auth-token"]',
   'headers["x-access-token"]',
+  "body.password",
+  "body.token",
+  "body.secret",
+  "query.token",
+  "query.api_key",
+  "query.apiKey",
+  "url",
+  "originalUrl"
+];
+var responseSubPaths = [
+  "authorization",
+  "headers.authorization",
+  'headers["set-cookie"]'
+];
+var commonHeaderPaths = [
+  "headers.authorization",
+  "headers.cookie",
+  "headers.cookies",
+  'headers["set-cookie"]',
+  'headers["x-api-key"]',
+  'headers["x-auth-token"]',
+  'headers["x-access-token"]'
+];
+var defaultRedactPaths = [
+  ...[
+    "req",
+    "request"
+  ].flatMap((p) => requestSubPaths.map((sp) => `${p}.${sp}`)),
+  ...[
+    "res",
+    "response"
+  ].flatMap((p) => responseSubPaths.map((sp) => `${p}.${sp}`)),
+  ...commonHeaderPaths,
   "url",
   "uri",
   "href",
   "redirect_uri",
   "redirectUri"
 ];
-var globalRedactCensor = /* @__PURE__ */ __name((value, path, sensitiveFields = getExpandedSensitiveFields()) => {
+var escapeRegExp = /* @__PURE__ */ __name((value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "escapeRegExp");
+function buildUrlRedactRegex(lowerSensitiveFields) {
+  if (lowerSensitiveFields.length === 0) return null;
+  const pattern = lowerSensitiveFields.map(escapeRegExp).join("|");
+  return new RegExp(`([?&](${pattern})=)[^&#]*`, "gi");
+}
+__name(buildUrlRedactRegex, "buildUrlRedactRegex");
+var URL_PATH_KEYS = /* @__PURE__ */ new Set([
+  "url",
+  "uri",
+  "href",
+  "originalurl",
+  "redirect_uri",
+  "redirecturi"
+]);
+var cachedExpandedFields = null;
+var cachedLowerSensitiveFields = null;
+var cachedLowerSensitiveSet = null;
+var cachedNormalizedMultiWordFields = null;
+var cachedUrlRegex = null;
+function invalidateSensitiveFieldsCache() {
+  cachedExpandedFields = null;
+  cachedLowerSensitiveFields = null;
+  cachedLowerSensitiveSet = null;
+  cachedNormalizedMultiWordFields = null;
+  cachedUrlRegex = null;
+}
+__name(invalidateSensitiveFieldsCache, "invalidateSensitiveFieldsCache");
+function extractNormalizedMultiWordFields(fields) {
+  return Array.from(new Set(fields.map((f) => f.replace(/[-]/g, "_")).filter((f) => f.includes("_")).map((f) => `_${f}_`)));
+}
+__name(extractNormalizedMultiWordFields, "extractNormalizedMultiWordFields");
+function isSensitivePathSegment(segment, lowerFieldsSet, multiWordNormalizedList) {
+  if (!segment || typeof segment !== "string") return false;
+  const lower = segment.toLowerCase();
+  if (lowerFieldsSet.has(lower)) return true;
+  const tokens = segment.split(/[_-]+|(?<=[a-z0-9])(?=[A-Z])/g).filter(Boolean);
+  if (tokens.some((t) => lowerFieldsSet.has(t.toLowerCase()))) return true;
+  if (multiWordNormalizedList.length === 0) return false;
+  const normalized = `_${segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().replace(/[-]/g, "_")}_`;
+  return multiWordNormalizedList.some((fNorm) => normalized.includes(fNorm));
+}
+__name(isSensitivePathSegment, "isSensitivePathSegment");
+function getExpandedSensitiveFields() {
+  if (!cachedExpandedFields) {
+    cachedExpandedFields = expandSensitiveFields(defaultSensitiveFields);
+    cachedLowerSensitiveFields = cachedExpandedFields.map((f) => f.toLowerCase());
+    cachedLowerSensitiveSet = new Set(cachedLowerSensitiveFields);
+    cachedNormalizedMultiWordFields = extractNormalizedMultiWordFields(cachedLowerSensitiveFields);
+    cachedUrlRegex = buildUrlRedactRegex(cachedLowerSensitiveFields);
+  }
+  return cachedExpandedFields;
+}
+__name(getExpandedSensitiveFields, "getExpandedSensitiveFields");
+var globalRedactCensor = /* @__PURE__ */ __name((value, path, sensitiveFields) => {
   if (typeof value !== "string") return "***";
-  const lowerPath = path.filter((p) => typeof p === "string").map((p) => p.toLowerCase());
-  const lowerSensitiveFields = sensitiveFields.map((f) => f.toLowerCase());
-  if (lowerPath.some((p) => lowerSensitiveFields.includes(p))) return "***";
-  if (lowerPath[0] === "url" || lowerPath[0] === "uri" || lowerPath[0] === "href" || lowerPath.includes("redirect_uri") || lowerPath.includes("redirecturi")) {
-    return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join("|")})=)[^&#]*`, "gi"), "$1***");
+  const stringPath = path.filter((p) => typeof p === "string");
+  const lowerPath = stringPath.map((p) => p.toLowerCase());
+  const isCustomFields = sensitiveFields !== void 0;
+  if (!isCustomFields) {
+    getExpandedSensitiveFields();
   }
-  if (lowerPath.some((p) => p.includes("authorization") || p.includes("auth"))) {
-    return value.replace(/^(\S+)\s+.+$/, "$1 ***") || "***";
+  const lowerFieldsList = isCustomFields ? sensitiveFields.map((f) => f.toLowerCase()) : cachedLowerSensitiveFields;
+  const lowerFieldsSet = isCustomFields ? new Set(lowerFieldsList) : cachedLowerSensitiveSet;
+  const multiWordList = isCustomFields ? extractNormalizedMultiWordFields(lowerFieldsList) : cachedNormalizedMultiWordFields;
+  if (lowerPath.some((p) => lowerFieldsSet.has(p))) return "***";
+  if (lowerPath.some((p) => URL_PATH_KEYS.has(p) || p.includes("redirect_uri") || p.includes("redirecturi"))) {
+    if (lowerFieldsList.length === 0) return value;
+    const urlRegex = isCustomFields ? buildUrlRedactRegex(lowerFieldsList) : cachedUrlRegex;
+    return urlRegex ? value.replace(urlRegex, "$1***") : value;
   }
-  if (lowerPath.some((p) => lowerSensitiveFields.some((f) => p.includes(f)))) {
+  if (stringPath.some((p) => isSensitivePathSegment(p, lowerFieldsSet, multiWordList))) {
     return "***";
   }
-  if (path.length > 0 && ![
-    "req",
-    "res",
-    "headers"
-  ].includes(lowerPath[0])) {
-    return value;
-  }
   return value;
 }, "globalRedactCensor");
 function setRedactCensor(fn) {
@@ -123,38 +206,36 @@ function redact(value, path, sensitiveFields) {
 }
 __name(redact, "redact");
 function addRedactFields(fields) {
+  addSensitiveFields(fields);
   const prev = globalRedactCensor;
   globalRedactCensor = /* @__PURE__ */ __name((value, path, sensitiveFields = getExpandedSensitiveFields()) => prev(value, path, [
     ...sensitiveFields || [],
     ...fields
   ]), "globalRedactCensor");
-  cachedExpandedFields = null;
 }
 __name(addRedactFields, "addRedactFields");
-var cachedExpandedFields = null;
-function getExpandedSensitiveFields() {
-  cachedExpandedFields ??= expandSensitiveFields(defaultSensitiveFields);
-  return cachedExpandedFields;
-}
-__name(getExpandedSensitiveFields, "getExpandedSensitiveFields");
 function setSensitiveFields(fields) {
   defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);
-  cachedExpandedFields = null;
+  invalidateSensitiveFieldsCache();
 }
 __name(setSensitiveFields, "setSensitiveFields");
 function addSensitiveFields(fields) {
   defaultSensitiveFields.push(...fields);
-  cachedExpandedFields = null;
+  invalidateSensitiveFieldsCache();
 }
 __name(addSensitiveFields, "addSensitiveFields");
 var _globalThis = typeof globalThis === "object" ? globalThis : global;
 var _global = _globalThis;
+function resetLogger() {
+  delete _global[GLOBAL_LOGGER_KEY];
+}
+__name(resetLogger, "resetLogger");
 function setupLogger(isGlobal = true) {
   const sensitiveFields = getExpandedSensitiveFields();
   const { logger: loggerConfig } = config.getCatbeeGlobalConfig();
   const paths = /* @__PURE__ */ new Set([
     ...defaultRedactPaths,
-    ...sensitiveFields.flatMap((field) => generateDeepPaths(field, 2))
+    ...sensitiveFields.flatMap((field) => generateDeepPaths(field, 5))
   ]);
   const logParams = {
     name: loggerConfig?.name ?? "@catbee/utils",
@@ -176,56 +257,50 @@ function setupLogger(isGlobal = true) {
   let logger;
   const logDir = loggerConfig?.dir?.trim();
   const hasFileLogging = Boolean(logDir);
+  const destination = logDir ? `${logDir.replace(/[/\\]+$/, "")}/app.log` : "app.log";
+  const prettyOptions = {
+    colorize: loggerConfig?.colorize,
+    translateTime: "SYS:standard",
+    ignore: "pid,hostname",
+    singleLine: loggerConfig?.singleLine,
+    levelFirst: true
+  };
+  const fileOptions = {
+    destination,
+    mkdir: true
+  };
   if (hasFileLogging && loggerConfig?.pretty) {
     logger = pino__default.default(logParams, pino__default.default.transport({
       targets: [
         {
           target: "pino-pretty",
           level: loggerConfig?.level ?? "info",
-          options: {
-            colorize: loggerConfig?.colorize,
-            translateTime: "SYS:standard",
-            ignore: "pid,hostname",
-            singleLine: loggerConfig?.singleLine,
-            levelFirst: true
-          }
+          options: prettyOptions
         },
         {
           target: "pino/file",
           level: loggerConfig?.level ?? "info",
-          options: {
-            destination: `${logDir}/app.log`,
-            mkdir: true
-          }
+          options: fileOptions
         }
       ]
     }));
   } else if (hasFileLogging) {
     logger = pino__default.default(logParams, pino__default.default.transport({
       target: "pino/file",
-      options: {
-        destination: `${logDir}/app.log`,
-        mkdir: true
-      }
+      options: fileOptions
     }));
   } else if (loggerConfig?.pretty) {
     logger = pino__default.default(logParams, pino__default.default.transport({
       target: "pino-pretty",
-      options: {
-        colorize: loggerConfig?.colorize,
-        translateTime: "SYS:standard",
-        ignore: "pid,hostname",
-        singleLine: loggerConfig?.singleLine,
-        levelFirst: true
-      }
+      options: prettyOptions
     }));
   } else {
     logger = pino__default.default(logParams);
   }
   if (isGlobal) {
     _global[GLOBAL_LOGGER_KEY] = logger;
-    _global[GLOBAL_LOGGER_KEY]?.debug({
-      logDir
+    logger.debug({
+      logDir: logDir || "none"
     }, "Global Logger Initialized");
   }
   return logger;
@@ -253,9 +328,15 @@ function createRequestLogger(requestId, additionalContext = {}) {
     requestId,
     ...additionalContext
   });
+  let stored = false;
   try {
-    contextStore.ContextStore.set(contextStore.StoreKeys.LOGGER, logger);
+    if (typeof contextStore.ContextStore.getAll !== "function" || contextStore.ContextStore.getAll() !== void 0) {
+      contextStore.ContextStore.set(contextStore.StoreKeys.LOGGER, logger);
+      stored = true;
+    }
   } catch {
+  }
+  if (!stored) {
     logger.debug("Failed to store logger in context - AsyncLocalStorage not initialized");
   }
   return logger;
@@ -282,13 +363,29 @@ function expandSensitiveFields(fields) {
 }
 __name(expandSensitiveFields, "expandSensitiveFields");
 function expandSensitiveField(field) {
-  const parts = field.split(/[_-]/g).filter(Boolean);
-  const camel = parts[0].toLowerCase() + parts.slice(1).map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join("");
-  const mergedLower = parts.join("").toLowerCase();
-  const mergedUpper = parts.join("").toUpperCase();
-  const kebab = parts.map((p) => p.toLowerCase()).join("-");
-  const snakeLower = parts.map((p) => p.toLowerCase()).join("_");
-  const snakeUpper = parts.map((p) => p.toUpperCase()).join("_");
+  if (!field || typeof field !== "string") {
+    return [];
+  }
+  const trimmed = field.trim();
+  if (!trimmed) {
+    return [
+      field
+    ];
+  }
+  const parts = trimmed.split(/[_-]+|(?<=[a-z0-9])(?=[A-Z])/g).filter(Boolean);
+  if (parts.length === 0) {
+    return [
+      field
+    ];
+  }
+  const lowerParts = parts.map((p) => p.toLowerCase());
+  const upperParts = parts.map((p) => p.toUpperCase());
+  const camel = lowerParts[0] + lowerParts.slice(1).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+  const mergedLower = lowerParts.join("");
+  const mergedUpper = upperParts.join("");
+  const kebab = lowerParts.join("-");
+  const snakeLower = lowerParts.join("_");
+  const snakeUpper = upperParts.join("_");
   return Array.from(/* @__PURE__ */ new Set([
     field,
     camel,
@@ -300,7 +397,7 @@ function expandSensitiveField(field) {
   ]));
 }
 __name(expandSensitiveField, "expandSensitiveField");
-function generateDeepPaths(field, depth) {
+function generateDeepPaths(field, depth = 5) {
   const set = /* @__PURE__ */ new Set([
     field
   ]);
@@ -329,5 +426,6 @@ exports.getLogger = getLogger;
 exports.getRedactCensor = getRedactCensor;
 exports.logError = logError;
 exports.redact = redact;
+exports.resetLogger = resetLogger;
 exports.setRedactCensor = setRedactCensor;
 exports.setSensitiveFields = setSensitiveFields;

package/logger/index.d.ts

@@ -28,11 +28,26 @@ import pino, { Logger as Logger$1 } from 'pino';
  * Logger type for application-wide logging.
  */
 type Logger = Logger$1;
+/**
+ * Logger level for application-wide logging.
+ */
+type LoggerLevel = pino.Level;
 /**
  * Logger levels for application-wide logging.
+ *
+ * @deprecated Use `LoggerLevel` instead.
  */
-type LoggerLevels = pino.Level;
+type LoggerLevels = LoggerLevel;
 declare const defaultSensitiveFields: string[];
+/**
+ * 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[];
 /**
  * Sets the global redaction censor function used throughout the application for log redaction.
  *
@@ -75,7 +90,7 @@ declare function setRedactCensor(fn: (value: unknown, path: string[], sensitiveF
  *
  * @returns The current redaction censor function
  */
-declare function getRedactCensor(): (value: unknown, path: string[], sensitiveFields?: string[]) => string;
+declare function getRedactCensor(): (value: unknown, path: string[], sensitiveFields?: string[]) => unknown;
 /**
  * Convenience function to redact sensitive data using the current global redact censor.
  *
@@ -93,7 +108,7 @@ declare function getRedactCensor(): (value: unknown, path: string[], sensitiveFi
  * @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;
+declare function redact(value: unknown, path: string[], sensitiveFields?: string[]): unknown;
 /**
  * @deprecated Use addSensitiveFields instead.
  *
@@ -111,15 +126,6 @@ declare function redact(value: unknown, path: string[], sensitiveFields?: string
  * @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.
  *
@@ -154,6 +160,11 @@ declare function addSensitiveFields(fields: string[]): void;
  * Use an object compatible with either modern or legacy global scopes.
  */
 declare const _globalThis: typeof globalThis;
+/**
+ * Resets the cached root logger instance.
+ * Useful for tests or dynamic reconfiguration.
+ */
+declare function resetLogger(): void;
 /**
  * Retrieves the current logger instance:
  * - Returns a request-scoped logger from AsyncLocalStorage if available
@@ -168,7 +179,7 @@ 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 {Record<string, unknown>} 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
  */
@@ -184,11 +195,11 @@ declare function createRequestLogger(requestId: string, additionalContext?: Reco
 /**
  * Utility to safely log errors with proper stack trace extraction
  *
- * @param {Error|unknown} error - Error object to log
+ * @param {unknown} error - Error object to log
  * @param {string} [message] - Optional message to include
  * @param {Record<string, unknown>} [context] - Additional context properties
  */
-declare function logError(error: Error | string, message?: string, context?: Record<string, unknown>): void;
+declare function logError(error: unknown, message?: string, context?: Record<string, unknown>): void;
 /**
  * Expands multiple sensitive field names into their variants.
  * Useful to match fields like `api_key`, `apiKey`, `apikey`, `APIKEY`, etc.
@@ -207,7 +218,7 @@ declare function expandSensitiveField(field: string): string[];
  *  *.password
  *  *.*.password
  */
-declare function generateDeepPaths(field: string, depth: number): string[];
+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 };
+export { _globalThis, addRedactFields, addSensitiveFields, createChildLogger, createRequestLogger, defaultSensitiveFields, expandSensitiveField, expandSensitiveFields, generateDeepPaths, getExpandedSensitiveFields, getLogger, getRedactCensor, logError, redact, resetLogger, setRedactCensor, setSensitiveFields };
+export type { Logger, LoggerLevel, LoggerLevels };