@catbee/utils 2.0.3 → 2.0.4

package/error/index.cjs

@@ -0,0 +1,58 @@
+/*
+ * The MIT 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
+ * 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 __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/error/error.utils.ts
+function ensureError(err) {
+  if (err instanceof Error) {
+    return err;
+  }
+  const message = typeof err === "string" ? err : hasErrorMessage(err) ? err.message : String(err);
+  return new Error(message, {
+    cause: err
+  });
+}
+__name(ensureError, "ensureError");
+function hasErrorMessage(value) {
+  return typeof value === "object" && value !== null && "message" in value && typeof value.message === "string";
+}
+__name(hasErrorMessage, "hasErrorMessage");
+function serializeError(err) {
+  const error = ensureError(err);
+  return {
+    name: error.name,
+    message: error.message,
+    stack: error.stack,
+    cause: error.cause
+  };
+}
+__name(serializeError, "serializeError");
+
+exports.ensureError = ensureError;
+exports.hasErrorMessage = hasErrorMessage;
+exports.serializeError = serializeError;

package/error/index.d.ts

@@ -0,0 +1,62 @@
+/*
+ * The MIT 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
+ * 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.
+ */
+
+/**
+ * Ensures the provided value is returned as an {@link Error}.
+ *
+ * If the value is not already an Error, a new Error is created using the
+ * value's message (if available) or its string representation. The original
+ * value is attached as the error's `cause`.
+ *
+ * @param err - The value to convert to an Error.
+ * @returns An Error instance.
+ */
+declare function ensureError(err: unknown): Error;
+/**
+ * Returns the error message for the provided value.
+ *
+ * If the value is not already an Error, it is first converted using
+ * {@link ensureError}.
+ *
+ * @param err - The value to extract the error message from.
+ * @returns The error message.
+ */
+declare function hasErrorMessage(value: unknown): value is {
+    message: string;
+};
+interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: unknown;
+}
+/**
+ * Serializes an error into a plain object containing its name, message, stack trace, and cause.
+ * @param err - The error to serialize.
+ * @returns An object representing the serialized error.
+ */
+declare function serializeError(err: unknown): SerializedError;
+
+export { ensureError, hasErrorMessage, serializeError };
+export type { SerializedError };

package/error/index.mjs

@@ -0,0 +1,54 @@
+/*
+ * The MIT 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
+ * 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.
+ */
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/error/error.utils.ts
+function ensureError(err) {
+  if (err instanceof Error) {
+    return err;
+  }
+  const message = typeof err === "string" ? err : hasErrorMessage(err) ? err.message : String(err);
+  return new Error(message, {
+    cause: err
+  });
+}
+__name(ensureError, "ensureError");
+function hasErrorMessage(value) {
+  return typeof value === "object" && value !== null && "message" in value && typeof value.message === "string";
+}
+__name(hasErrorMessage, "hasErrorMessage");
+function serializeError(err) {
+  const error = ensureError(err);
+  return {
+    name: error.name,
+    message: error.message,
+    stack: error.stack,
+    cause: error.cause
+  };
+}
+__name(serializeError, "serializeError");
+
+export { ensureError, hasErrorMessage, serializeError };

package/index.cjs

@@ -36,6 +36,7 @@ var date = require("./date/index.cjs");
 var decorator = require("./decorator/index.cjs");
 var directory = require("./directory/index.cjs");
 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 httpStatusCodes = require("./http-status-codes/index.cjs");
@@ -126,6 +127,12 @@ Object.keys(env).forEach(function (k) {
 		get: function () { return env[k]; }
 	});
 });
+Object.keys(error).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return error[k]; }
+	});
+});
 Object.keys(exception).forEach(function (k) {
 	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/index.d.ts

@@ -34,6 +34,7 @@ export * from './date';
 export * from './decorator';
 export * from './directory';
 export * from './env';
+export * from './error';
 export * from './exception';
 export * from './fs';
 export * from './http-status-codes';

package/index.mjs

@@ -34,6 +34,7 @@ export * from "./date/index.mjs";
 export * from "./decorator/index.mjs";
 export * from "./directory/index.mjs";
 export * from "./env/index.mjs";
+export * from "./error/index.mjs";
 export * from "./exception/index.mjs";
 export * from "./fs/index.mjs";
 export * from "./http-status-codes/index.mjs";

package/logger/index.cjs

@@ -151,13 +151,14 @@ var _globalThis = typeof globalThis === "object" ? globalThis : global;
 var _global = _globalThis;
 function setupLogger(isGlobal = true) {
   const sensitiveFields = getExpandedSensitiveFields();
+  const { logger: loggerConfig } = config.getCatbeeGlobalConfig();
   const paths = /* @__PURE__ */ new Set([
     ...defaultRedactPaths,
     ...sensitiveFields.flatMap((field) => generateDeepPaths(field, 2))
   ]);
   const logParams = {
-    name: config.getCatbeeGlobalConfig().logger?.name || "@catbee/utils",
-    level: config.getCatbeeGlobalConfig().logger?.level || "info",
+    name: loggerConfig?.name ?? "@catbee/utils",
+    level: loggerConfig?.level ?? "info",
     redact: {
       paths: Array.from(paths),
       censor: /* @__PURE__ */ __name((value, path) => redact(value, path), "censor")
@@ -173,25 +174,25 @@ function setupLogger(isGlobal = true) {
     timestamp: pino.stdTimeFunctions.isoTime
   };
   let logger;
-  const logDir = config.getCatbeeGlobalConfig().logger?.dir?.trim();
+  const logDir = loggerConfig?.dir?.trim();
   const hasFileLogging = Boolean(logDir);
-  if (hasFileLogging && config.getCatbeeGlobalConfig().logger?.pretty) {
+  if (hasFileLogging && loggerConfig?.pretty) {
     logger = pino__default.default(logParams, pino__default.default.transport({
       targets: [
         {
           target: "pino-pretty",
-          level: config.getCatbeeGlobalConfig().logger?.level ?? "info",
+          level: loggerConfig?.level ?? "info",
           options: {
-            colorize: config.getCatbeeGlobalConfig().logger?.colorize,
+            colorize: loggerConfig?.colorize,
             translateTime: "SYS:standard",
             ignore: "pid,hostname",
-            singleLine: config.getCatbeeGlobalConfig().logger?.singleLine,
+            singleLine: loggerConfig?.singleLine,
             levelFirst: true
           }
         },
         {
           target: "pino/file",
-          level: config.getCatbeeGlobalConfig().logger?.level ?? "info",
+          level: loggerConfig?.level ?? "info",
           options: {
             destination: `${logDir}/app.log`,
             mkdir: true
@@ -207,14 +208,14 @@ function setupLogger(isGlobal = true) {
         mkdir: true
       }
     }));
-  } else if (config.getCatbeeGlobalConfig().logger?.pretty) {
+  } else if (loggerConfig?.pretty) {
     logger = pino__default.default(logParams, pino__default.default.transport({
       target: "pino-pretty",
       options: {
-        colorize: config.getCatbeeGlobalConfig().logger?.colorize,
+        colorize: loggerConfig?.colorize,
         translateTime: "SYS:standard",
         ignore: "pid,hostname",
-        singleLine: config.getCatbeeGlobalConfig().logger?.singleLine,
+        singleLine: loggerConfig?.singleLine,
         levelFirst: true
       }
     }));
@@ -243,7 +244,7 @@ function getLogger(newInstance = false) {
 }
 __name(getLogger, "getLogger");
 function createChildLogger(bindings, parentLogger) {
-  const logger = parentLogger || getLogger();
+  const logger = parentLogger ?? getLogger();
   return logger.child(bindings);
 }
 __name(createChildLogger, "createChildLogger");

package/logger/index.d.ts

@@ -172,23 +172,23 @@ declare function getLogger(newInstance?: boolean): Logger$1;
  * @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;
+declare function createChildLogger(bindings: Record<string, unknown>, 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
+ * @param {Record<string, unknown>} [additionalContext] - Additional context to include in logs
  * @returns {Logger} Request-scoped logger instance
  */
-declare function createRequestLogger(requestId: string, additionalContext?: Record<string, any>): Logger$1;
+declare function createRequestLogger(requestId: string, additionalContext?: Record<string, unknown>): 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
+ * @param {Record<string, unknown>} [context] - Additional context properties
  */
-declare function logError(error: Error | string, message?: string, context?: Record<string, any>): void;
+declare function logError(error: Error | string, 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.

package/logger/index.mjs

@@ -145,13 +145,14 @@ var _globalThis = typeof globalThis === "object" ? globalThis : global;
 var _global = _globalThis;
 function setupLogger(isGlobal = true) {
   const sensitiveFields = getExpandedSensitiveFields();
+  const { logger: loggerConfig } = getCatbeeGlobalConfig();
   const paths = /* @__PURE__ */ new Set([
     ...defaultRedactPaths,
     ...sensitiveFields.flatMap((field) => generateDeepPaths(field, 2))
   ]);
   const logParams = {
-    name: getCatbeeGlobalConfig().logger?.name || "@catbee/utils",
-    level: getCatbeeGlobalConfig().logger?.level || "info",
+    name: loggerConfig?.name ?? "@catbee/utils",
+    level: loggerConfig?.level ?? "info",
     redact: {
       paths: Array.from(paths),
       censor: /* @__PURE__ */ __name((value, path) => redact(value, path), "censor")
@@ -167,25 +168,25 @@ function setupLogger(isGlobal = true) {
     timestamp: stdTimeFunctions.isoTime
   };
   let logger;
-  const logDir = getCatbeeGlobalConfig().logger?.dir?.trim();
+  const logDir = loggerConfig?.dir?.trim();
   const hasFileLogging = Boolean(logDir);
-  if (hasFileLogging && getCatbeeGlobalConfig().logger?.pretty) {
+  if (hasFileLogging && loggerConfig?.pretty) {
     logger = pino(logParams, pino.transport({
       targets: [
         {
           target: "pino-pretty",
-          level: getCatbeeGlobalConfig().logger?.level ?? "info",
+          level: loggerConfig?.level ?? "info",
           options: {
-            colorize: getCatbeeGlobalConfig().logger?.colorize,
+            colorize: loggerConfig?.colorize,
             translateTime: "SYS:standard",
             ignore: "pid,hostname",
-            singleLine: getCatbeeGlobalConfig().logger?.singleLine,
+            singleLine: loggerConfig?.singleLine,
             levelFirst: true
           }
         },
         {
           target: "pino/file",
-          level: getCatbeeGlobalConfig().logger?.level ?? "info",
+          level: loggerConfig?.level ?? "info",
           options: {
             destination: `${logDir}/app.log`,
             mkdir: true
@@ -201,14 +202,14 @@ function setupLogger(isGlobal = true) {
         mkdir: true
       }
     }));
-  } else if (getCatbeeGlobalConfig().logger?.pretty) {
+  } else if (loggerConfig?.pretty) {
     logger = pino(logParams, pino.transport({
       target: "pino-pretty",
       options: {
-        colorize: getCatbeeGlobalConfig().logger?.colorize,
+        colorize: loggerConfig?.colorize,
         translateTime: "SYS:standard",
         ignore: "pid,hostname",
-        singleLine: getCatbeeGlobalConfig().logger?.singleLine,
+        singleLine: loggerConfig?.singleLine,
         levelFirst: true
       }
     }));
@@ -237,7 +238,7 @@ function getLogger(newInstance = false) {
 }
 __name(getLogger, "getLogger");
 function createChildLogger(bindings, parentLogger) {
-  const logger = parentLogger || getLogger();
+  const logger = parentLogger ?? getLogger();
   return logger.child(bindings);
 }
 __name(createChildLogger, "createChildLogger");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catbee/utils",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.",
   "publishConfig": {
     "access": "public"
@@ -32,7 +32,6 @@
     "express-rate-limit": "^8.3.2",
     "helmet": "^8.1.0",
     "pino-pretty": "^13.1.3",
-    "prom-client": "^15.1.3",
     "reflect-metadata": "^0.2.2"
   },
   "peerDependencies": {
@@ -131,6 +130,11 @@
       "require": "./env/index.cjs",
       "types": "./env/index.d.ts"
     },
+    "./error": {
+      "import": "./error/index.mjs",
+      "require": "./error/index.cjs",
+      "types": "./error/index.d.ts"
+    },
     "./exception": {
       "import": "./exception/index.mjs",
       "require": "./exception/index.cjs",