@catbee/utils 0.0.1 → 0.0.3

package/build/src/utils/id.utils.js

@@ -1,13 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.uuid = uuid;
-exports.ulidString = ulidString;
 exports.nanoId = nanoId;
 exports.randomHex = randomHex;
 exports.randomInt = randomInt;
+exports.randomBase64 = randomBase64;
 const crypto_1 = require("crypto");
-const ulid_1 = require("ulid");
-const nanoid_1 = require("nanoid");
 /**
  * Generates a UUID v4 string (RFC 4122).
  *
@@ -17,21 +15,21 @@ function uuid() {
     return (0, crypto_1.randomUUID)();
 }
 /**
- * Generates a ULID (Universally Unique Lexicographically Sortable Identifier).
+ * Generates a nanoid-style random ID (URL-safe, customizable length).
  *
- * @returns {string} ULID string (26 chars, Crockford Base32, e.g., '01H7ZXS9FJKPX06P1AYZKCGHQF').
+ * @param {number} length - Length of the ID (default: 21).
+ * @returns {string} Nanoid-style random string.
  */
-function ulidString() {
-    return (0, ulid_1.ulid)();
-}
-/**
- * Generates a nanoid string (URL-friendly, collision-resistant, customizable size).
- *
- * @param {number} [size=21] - Number of characters for the ID (default: 21).
- * @returns {string} nanoid string.
- */
-function nanoId(size = 21) {
-    return (0, nanoid_1.nanoid)(size);
+function nanoId(length = 21) {
+    if (length <= 0)
+        return '';
+    let id = '';
+    while (id.length < length) {
+        id += (0, crypto_1.randomBytes)(Math.ceil((length * 3) / 4))
+            .toString('base64url')
+            .replace(/[+/=]/g, '');
+    }
+    return id.slice(0, length);
 }
 /**
  * Generates a cryptographically strong random hex string.
@@ -40,10 +38,11 @@ function nanoId(size = 21) {
  * @returns {string} Random hex string.
  */
 function randomHex(byteLength = 16) {
-    // Node: crypto.getRandomValues is not available; use randomBytes if needed.
-    // If using browser target, replace this impl accordingly.
-    return Buffer.from(crypto.getRandomValues(new Uint8Array(byteLength)))
-        .toString("hex")
+    // Use Node.js crypto for both Node and browser compatibility
+    // Prefer randomBytes if available (Node), fallback to getRandomValues for browser (not used here)
+    return (0, crypto_1.randomBytes)(byteLength)
+        .toString('hex')
+        .padStart(byteLength * 2, '0')
         .slice(0, byteLength * 2);
 }
 /**
@@ -57,4 +56,13 @@ function randomInt(min, max) {
     const range = max - min + 1;
     return Math.floor(Math.random() * range) + min;
 }
+/**
+ * Generates a cryptographically strong random base64 string.
+ *
+ * @param {number} byteLength - Number of random bytes (default: 16).
+ * @returns {string} Random base64 string (URL-safe, no padding).
+ */
+function randomBase64(byteLength = 16) {
+    return (0, crypto_1.randomBytes)(byteLength).toString('base64url');
+}
 //# sourceMappingURL=id.utils.js.map

package/build/src/utils/id.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"id.utils.js","sourceRoot":"","sources":["../../../src/utils/id.utils.ts"],"names":[],"mappings":";;AASA,oBAEC;AAOD,gCAEC;AAQD,wBAEC;AAQD,8BAMC;AASD,8BAGC;AAxDD,mCAAoC;AACpC,+BAA4B;AAC5B,mCAAgC;AAEhC;;;;GAIG;AACH,SAAgB,IAAI;IAClB,OAAO,IAAA,mBAAU,GAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,SAAgB,UAAU;IACxB,OAAO,IAAA,WAAI,GAAE,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,MAAM,CAAC,OAAe,EAAE;IACtC,OAAO,IAAA,eAAM,EAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,SAAS,CAAC,aAAqB,EAAE;IAC/C,4EAA4E;IAC5E,0DAA0D;IAC1D,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;SACnE,QAAQ,CAAC,KAAK,CAAC;SACf,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,GAAW,EAAE,GAAW;IAChD,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;AACjD,CAAC","sourcesContent":["import { randomUUID } from \"crypto\";\nimport { ulid } from \"ulid\";\nimport { nanoid } from \"nanoid\";\n\n/**\n * Generates a UUID v4 string (RFC 4122).\n *\n * @returns {string} UUID v4 (e.g., 'c0de1234-5678-9abc-def0-123456789abc')\n */\nexport function uuid(): string {\n  return randomUUID();\n}\n\n/**\n * Generates a ULID (Universally Unique Lexicographically Sortable Identifier).\n *\n * @returns {string} ULID string (26 chars, Crockford Base32, e.g., '01H7ZXS9FJKPX06P1AYZKCGHQF').\n */\nexport function ulidString(): string {\n  return ulid();\n}\n\n/**\n * Generates a nanoid string (URL-friendly, collision-resistant, customizable size).\n *\n * @param {number} [size=21] - Number of characters for the ID (default: 21).\n * @returns {string} nanoid string.\n */\nexport function nanoId(size: number = 21): string {\n  return nanoid(size);\n}\n\n/**\n * Generates a cryptographically strong random hex string.\n *\n * @param {number} byteLength - Number of random bytes (default: 16 → 32 hex chars).\n * @returns {string} Random hex string.\n */\nexport function randomHex(byteLength: number = 16): string {\n  // Node: crypto.getRandomValues is not available; use randomBytes if needed.\n  // If using browser target, replace this impl accordingly.\n  return Buffer.from(crypto.getRandomValues(new Uint8Array(byteLength)))\n    .toString(\"hex\")\n    .slice(0, byteLength * 2);\n}\n\n/**\n * Generates a random integer between min (inclusive) and max (inclusive).\n *\n * @param {number} min - Minimum value.\n * @param {number} max - Maximum value.\n * @returns {number} Random integer in range.\n */\nexport function randomInt(min: number, max: number): number {\n  const range = max - min + 1;\n  return Math.floor(Math.random() * range) + min;\n}\n"]}
+{"version":3,"file":"id.utils.js","sourceRoot":"","sources":["../../../src/utils/id.utils.ts"],"names":[],"mappings":";;AAOA,oBAEC;AAQD,wBASC;AAQD,8BAOC;AASD,8BAGC;AAQD,oCAEC;AA/DD,mCAAiD;AAEjD;;;;GAIG;AACH,SAAgB,IAAI;IAClB,OAAO,IAAA,mBAAU,GAAE,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,MAAM,CAAC,SAAiB,EAAE;IACxC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3B,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;QAC1B,EAAE,IAAI,IAAA,oBAAW,EAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;aAC3C,QAAQ,CAAC,WAAW,CAAC;aACrB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,SAAS,CAAC,aAAqB,EAAE;IAC/C,6DAA6D;IAC7D,kGAAkG;IAClG,OAAO,IAAA,oBAAW,EAAC,UAAU,CAAC;SAC3B,QAAQ,CAAC,KAAK,CAAC;SACf,QAAQ,CAAC,UAAU,GAAG,CAAC,EAAE,GAAG,CAAC;SAC7B,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,GAAW,EAAE,GAAW;IAChD,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,aAAqB,EAAE;IAClD,OAAO,IAAA,oBAAW,EAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC","sourcesContent":["import { randomUUID, randomBytes } from 'crypto';\n\n/**\n * Generates a UUID v4 string (RFC 4122).\n *\n * @returns {string} UUID v4 (e.g., 'c0de1234-5678-9abc-def0-123456789abc')\n */\nexport function uuid(): string {\n  return randomUUID();\n}\n\n/**\n * Generates a nanoid-style random ID (URL-safe, customizable length).\n *\n * @param {number} length - Length of the ID (default: 21).\n * @returns {string} Nanoid-style random string.\n */\nexport function nanoId(length: number = 21): string {\n  if (length <= 0) return '';\n  let id = '';\n  while (id.length < length) {\n    id += randomBytes(Math.ceil((length * 3) / 4))\n      .toString('base64url')\n      .replace(/[+/=]/g, '');\n  }\n  return id.slice(0, length);\n}\n\n/**\n * Generates a cryptographically strong random hex string.\n *\n * @param {number} byteLength - Number of random bytes (default: 16 → 32 hex chars).\n * @returns {string} Random hex string.\n */\nexport function randomHex(byteLength: number = 16): string {\n  // Use Node.js crypto for both Node and browser compatibility\n  // Prefer randomBytes if available (Node), fallback to getRandomValues for browser (not used here)\n  return randomBytes(byteLength)\n    .toString('hex')\n    .padStart(byteLength * 2, '0')\n    .slice(0, byteLength * 2);\n}\n\n/**\n * Generates a random integer between min (inclusive) and max (inclusive).\n *\n * @param {number} min - Minimum value.\n * @param {number} max - Maximum value.\n * @returns {number} Random integer in range.\n */\nexport function randomInt(min: number, max: number): number {\n  const range = max - min + 1;\n  return Math.floor(Math.random() * range) + min;\n}\n\n/**\n * Generates a cryptographically strong random base64 string.\n *\n * @param {number} byteLength - Number of random bytes (default: 16).\n * @returns {string} Random base64 string (URL-safe, no padding).\n */\nexport function randomBase64(byteLength: number = 16): string {\n  return randomBytes(byteLength).toString('base64url');\n}\n"]}

package/build/src/utils/logger.utils.d.ts

@@ -1,4 +1,13 @@
-import type { Logger } from "pino";
+import pino from 'pino';
+import type { Logger as PinoLogger } from 'pino';
+/**
+ * Logger type for application-wide logging.
+ */
+export type Logger = pino.Logger;
+/**
+ * Logger levels for application-wide logging.
+ */
+export type LoggerLevels = pino.Level;
 /**
  * Use an object compatible with either modern or legacy global scopes.
  */
@@ -11,5 +20,29 @@ export declare const _globalThis: typeof globalThis;
  *
  * @returns {Logger} The logger instance (request-bound or global root logger)
  */
-export declare function getLogger(): Logger;
+export declare function getLogger(): 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;
 //# sourceMappingURL=logger.utils.d.ts.map

package/build/src/utils/logger.utils.js

@@ -35,17 +35,20 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._globalThis = void 0;
 exports.getLogger = getLogger;
+exports.createChildLogger = createChildLogger;
+exports.createRequestLogger = createRequestLogger;
+exports.logError = logError;
 const pino_1 = __importStar(require("pino"));
 const config_1 = require("../config");
 const context_store_utils_1 = require("./context-store.utils");
 /**
  * Symbol used to store the root logger in the Node.js global object.
  */
-const GLOBAL_LOGGER_KEY = Symbol.for("logger");
+const GLOBAL_LOGGER_KEY = Symbol.for('logger');
 /**
  * Use an object compatible with either modern or legacy global scopes.
  */
-exports._globalThis = typeof globalThis === "object" ? globalThis : global;
+exports._globalThis = typeof globalThis === 'object' ? globalThis : global;
 const _global = exports._globalThis;
 /**
  * Initializes the global root logger according to app configuration.
@@ -58,23 +61,23 @@ function setupLogger() {
         name: config_1.Config.Logger.name,
         level: config_1.Config.Logger.level,
         redact: {
-            paths: ["req.authorization", "url"],
+            paths: ['req.authorization', 'url'],
             censor(value, path) {
-                if (path[0] === "url") {
-                    return value.replace(/access_token=[a-zA-Z0-9_-]*/, "access_token=***");
+                if (path[0] === 'url') {
+                    return value.replace(/access_token=[a-zA-Z0-9_-]*/, 'access_token=***');
                 }
-                else if (path[1] === "authorization") {
-                    return value.replace(/\s+(\S+)$/, " ***");
+                else if (path[1] === 'authorization') {
+                    return value.replace(/\s+(\S+)$/, ' ***');
                 }
-                return "***";
-            },
-        },
+                return '***';
+            }
+        }
     };
     if (config_1.Config.Logger.isoTimestamp) {
         logParams.timestamp = pino_1.stdTimeFunctions.isoTime;
     }
     _global[GLOBAL_LOGGER_KEY] = (0, pino_1.default)(logParams);
-    _global[GLOBAL_LOGGER_KEY].debug("Logger initialized");
+    _global[GLOBAL_LOGGER_KEY].debug('Logger initialized');
 }
 /**
  * Retrieves the current logger instance:
@@ -93,4 +96,46 @@ function getLogger() {
     }
     return _global[GLOBAL_LOGGER_KEY];
 }
+/**
+ * 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
+ */
+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
+ */
+function createRequestLogger(requestId, additionalContext = {}) {
+    const logger = createChildLogger(Object.assign({ requestId }, additionalContext));
+    try {
+        context_store_utils_1.ContextStore.set(context_store_utils_1.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
+ */
+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), { err: errObj });
+    logger.error(logContext, message || errObj.message);
+}
 //# sourceMappingURL=logger.utils.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,8BASC;AAnED,6CAA6D;AAE7D,sCAAmC;AACnC,+DAAgE;AAEhE;;GAEG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAE/C;;GAEG;AACU,QAAA,WAAW,GAAG,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC;AAChF,MAAM,OAAO,GAAG,mBAAyD,CAAC;AAE1E;;;;;GAKG;AACH,SAAS,WAAW;IAClB,MAAM,SAAS,GAAkB;QAC/B,IAAI,EAAE,eAAM,CAAC,MAAM,CAAC,IAAI;QACxB,KAAK,EAAE,eAAM,CAAC,MAAM,CAAC,KAAK;QAC1B,MAAM,EAAE;YACN,KAAK,EAAE,CAAC,mBAAmB,EAAE,KAAK,CAAC;YACnC,MAAM,CAAC,KAAK,EAAE,IAAI;gBAChB,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;oBACtB,OAAO,KAAK,CAAC,OAAO,CAClB,6BAA6B,EAC7B,kBAAkB,CACnB,CAAC;gBACJ,CAAC;qBAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,eAAe,EAAE,CAAC;oBACvC,OAAO,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;gBAC5C,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SACF;KACF,CAAC;IAEF,IAAI,eAAM,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QAC/B,SAAS,CAAC,SAAS,GAAG,uBAAgB,CAAC,OAAO,CAAC;IACjD,CAAC;IAED,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAA,cAAI,EAAC,SAAS,CAAC,CAAC;IAC7C,OAAO,CAAC,iBAAiB,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,SAAS;IACvB,MAAM,MAAM,GAAG,kCAAY,CAAC,GAAG,CAAS,+BAAS,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAChC,WAAW,EAAE,CAAC;IAChB,CAAC;IAED,OAAO,OAAO,CAAC,iBAAiB,CAAC,CAAC;AACpC,CAAC","sourcesContent":["import pino, { LoggerOptions, stdTimeFunctions } from \"pino\";\nimport type { Logger } from \"pino\"; // Type-only import\nimport { Config } from \"../config\";\nimport { ContextStore, StoreKeys } from \"./context-store.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 * 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]: Logger };\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,\n    level: Config.Logger.level,\n    redact: {\n      paths: [\"req.authorization\", \"url\"],\n      censor(value, path) {\n        if (path[0] === \"url\") {\n          return value.replace(\n            /access_token=[a-zA-Z0-9_-]*/,\n            \"access_token=***\",\n          );\n        } else if (path[1] === \"authorization\") {\n          return value.replace(/\\s+(\\S+)$/, \" ***\");\n        }\n        return \"***\";\n      },\n    },\n  };\n\n  if (Config.Logger.isoTimestamp) {\n    logParams.timestamp = stdTimeFunctions.isoTime;\n  }\n\n  _global[GLOBAL_LOGGER_KEY] = pino(logParams);\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(): Logger {\n  const logger = ContextStore.get<Logger>(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"]}
+{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import 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';\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/**\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,\n    level: Config.Logger.level,\n    redact: {\n      paths: ['req.authorization', 'url'],\n      censor(value, path) {\n        if (path[0] === 'url') {\n          return value.replace(/access_token=[a-zA-Z0-9_-]*/, 'access_token=***');\n        } else if (path[1] === 'authorization') {\n          return value.replace(/\\s+(\\S+)$/, ' ***');\n        }\n        return '***';\n      }\n    }\n  };\n\n  if (Config.Logger.isoTimestamp) {\n    logParams.timestamp = stdTimeFunctions.isoTime;\n  }\n\n  _global[GLOBAL_LOGGER_KEY] = pino(logParams);\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 * 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    err: errObj\n  };\n\n  logger.error(logContext, message || errObj.message);\n}\n"]}

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

@@ -0,0 +1,73 @@
+/**
+ * Type definitions for Express-compatible middleware
+ */
+type Request = {
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    url: string;
+    ip?: string;
+    body?: any;
+    query?: Record<string, any>;
+    params?: Record<string, any>;
+    [key: string]: any;
+};
+type Response = {
+    status: (code: number) => Response;
+    json: (data: any) => void;
+    send: (data: any) => void;
+    setHeader: (name: string, value: string | string[]) => void;
+    end: (data?: any) => void;
+    on: (event: string, callback: (...args: any[]) => void) => void;
+    [key: string]: any;
+};
+type NextFunction = (err?: Error | any) => void;
+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
+ * @returns {Middleware} Express-compatible middleware
+ */
+export declare function requestId(options?: {
+    headerName?: string;
+    exposeHeader?: boolean;
+}): 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;
+}): Middleware;
+/**
+ * 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;
+/**
+ * Global error handling middleware with enhanced features.
+ *
+ * @param {object} [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
+ * @param {Function} [options.logger=getLogger().error] - Custom logging function
+ * @returns {(err: any, req: Request, res: Response, next: NextFunction) => void} Error middleware
+ */
+export declare function errorHandler(options?: {
+    logErrors?: boolean;
+    includeDetails?: boolean;
+    logger?: (message: string, error: any) => void;
+}): (err: any, req: Request, res: Response, _next: NextFunction) => void;
+export {};
+//# sourceMappingURL=middleware.utils.d.ts.map

package/build/src/utils/middleware.utils.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestId = requestId;
+exports.responseTime = responseTime;
+exports.timeout = timeout;
+exports.errorHandler = errorHandler;
+const crypto_1 = require("crypto");
+const config_1 = require("../config");
+const id_utils_1 = require("./id.utils");
+const http_status_codes_1 = require("./http-status-codes");
+const response_utils_1 = require("./response.utils");
+const env_utils_1 = require("./env.utils");
+const logger_utils_1 = require("./logger.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
+ * @returns {Middleware} Express-compatible middleware
+ */
+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;
+    return (req, res, next) => {
+        // Use existing request ID from header or generate a new one
+        const existingId = req.headers[headerName.toLowerCase()];
+        const id = existingId || (0, crypto_1.randomUUID)();
+        // 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
+ */
+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 elapsed time
+        const calculateDuration = () => {
+            const diff = process.hrtime(start);
+            return diff[0] * 1e3 + diff[1] * 1e-6; // Convert to ms
+        };
+        // Handle response completion
+        res.on('finish', () => {
+            const duration = calculateDuration();
+            if (addHeader) {
+                res.setHeader('X-Response-Time', `${duration.toFixed(2)}ms`);
+            }
+            if (logOnComplete) {
+                const { method, url } = req;
+                (0, logger_utils_1.getLogger)().info(`${method} ${url} - ${duration.toFixed(2)}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
+ */
+function timeout(timeoutMs = config_1.Config.Http.timeout) {
+    return (req, res, next) => {
+        // Set timeout for the request
+        const timer = setTimeout(() => {
+            res.status(408).json({
+                error: true,
+                message: 'Request timeout',
+                status: 408,
+                timestamp: new Date().toISOString()
+            });
+        }, timeoutMs);
+        // Clear timeout when response is sent
+        res.on('finish', () => {
+            clearTimeout(timer);
+        });
+        next();
+    };
+}
+/**
+ * Creates a standardized error response object for API errors.
+ *
+ * @param {string} message - Error message
+ * @param {Request} req - Express request object
+ * @param {any} error - Original error object
+ * @param {object} [options] - Additional options
+ * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
+ * @returns {object} Formatted error response
+ */
+const createErrorResponse = (message, req, error, options) => {
+    const isDev = env_utils_1.Env.isDev();
+    const includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) && isDev;
+    const response = {
+        error: true,
+        message,
+        timestamp: new Date().toISOString(),
+        requestId: (error === null || error === void 0 ? void 0 : error.requestId) || req.id || (0, id_utils_1.uuid)(),
+        path: req.originalUrl || req.url
+    };
+    // Include error code if present
+    if (error === null || error === void 0 ? void 0 : error.code) {
+        response.code = error.code;
+    }
+    // Include stack trace in development mode if requested
+    if (includeDetails && (error === null || error === void 0 ? void 0 : error.stack)) {
+        response.stack = error.stack.split('\n').map((line) => line.trim());
+    }
+    return response;
+};
+/**
+ * Global error handling middleware with enhanced features.
+ *
+ * @param {object} [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
+ * @param {Function} [options.logger=getLogger().error] - Custom logging function
+ * @returns {(err: any, req: Request, res: Response, next: NextFunction) => void} Error middleware
+ */
+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;
+    const logger = (options === null || options === void 0 ? void 0 : options.logger) || (0, logger_utils_1.getLogger)().error;
+    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) || http_status_codes_1.HttpStatusCodes.INTERNAL_SERVER_ERROR;
+        // Log error if enabled
+        if (logErrors) {
+            const logMessage = `[ERROR] ${req.method} ${req.originalUrl || req.url}: ${err.message || 'Unknown error'}`;
+            logger(logMessage, err);
+        }
+        // Handle ErrorResponse instances (our custom error class)
+        if (err instanceof response_utils_1.ErrorResponse) {
+            return res.status(status).json({
+                error: err.error,
+                message: err.message,
+                timestamp: err.timestamp,
+                requestId: err.requestId || req.id || (0, id_utils_1.uuid)(),
+                path: req.originalUrl || req.url
+            });
+        }
+        // Handle any other errors
+        return res.status(status).json(createErrorResponse((err === null || err === void 0 ? void 0 : err.message) || 'Internal Server Error', req, err, {
+            includeDetails
+        }));
+    };
+}
+//# sourceMappingURL=middleware.utils.js.map

package/build/src/utils/middleware.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from 'crypto';\nimport { Config } from '../config';\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { ErrorResponse } from './response.utils';\nimport { Env } from './env.utils';\nimport { getLogger } from './logger.utils';\n\n/**\n * Type definitions for Express-compatible middleware\n */\ntype Request = {\n  headers: Record<string, string | string[] | undefined>;\n  method: string;\n  url: string;\n  ip?: string;\n  body?: any;\n  query?: Record<string, any>;\n  params?: Record<string, any>;\n  [key: string]: any;\n};\n\ntype Response = {\n  status: (code: number) => Response;\n  json: (data: any) => void;\n  send: (data: any) => void;\n  setHeader: (name: string, value: string | string[]) => void;\n  end: (data?: any) => void;\n  on: (event: string, callback: (...args: any[]) => void) => void;\n  [key: string]: any;\n};\n\ntype NextFunction = (err?: Error | any) => void;\n\ntype Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;\n\n/**\n * Attaches a unique request ID to each request.\n * Useful for request tracing and correlation between logs.\n *\n * @param {object} [options] - Configuration options\n * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID\n * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response\n * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: { headerName?: string; exposeHeader?: boolean }): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\n\n  return (req, res, next) => {\n    // Use existing request ID from header or generate a new one\n    const existingId = req.headers[headerName.toLowerCase()];\n    const id = (existingId as string) || randomUUID();\n\n    // Attach ID to request object\n    req.id = id;\n\n    // Add ID to response headers\n    if (exposeHeader) {\n      res.setHeader(headerName, id);\n    }\n\n    next();\n  };\n}\n\n/**\n * Measures request processing time and logs or adds it to response headers.\n *\n * @param {object} [options] - Configuration options\n * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header\n * @param {boolean} [options.logOnComplete=false] - Whether to log timing info\n * @returns {Middleware} Express-compatible middleware\n */\nexport function responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }): Middleware {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req, res, next) => {\n    const start = process.hrtime();\n\n    // Function to calculate elapsed time\n    const calculateDuration = (): number => {\n      const diff = process.hrtime(start);\n      return diff[0] * 1e3 + diff[1] * 1e-6; // Convert to ms\n    };\n\n    // Handle response completion\n    res.on('finish', () => {\n      const duration = calculateDuration();\n\n      if (addHeader) {\n        res.setHeader('X-Response-Time', `${duration.toFixed(2)}ms`);\n      }\n\n      if (logOnComplete) {\n        const { method, url } = req;\n        getLogger().info(`${method} ${url} - ${duration.toFixed(2)}ms`);\n      }\n    });\n\n    next();\n  };\n}\n\n/**\n * Request timeout middleware.\n * Aborts requests that take too long to process.\n *\n * @param {number} [timeoutMs=30000] - Timeout in milliseconds\n * @returns {Middleware} Express-compatible middleware\n */\nexport function timeout(timeoutMs: number = Config.Http.timeout): Middleware {\n  return (req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      res.status(408).json({\n        error: true,\n        message: 'Request timeout',\n        status: 408,\n        timestamp: new Date().toISOString()\n      });\n    }, timeoutMs);\n\n    // Clear timeout when response is sent\n    res.on('finish', () => {\n      clearTimeout(timer);\n    });\n\n    next();\n  };\n}\n\n/**\n * Creates a standardized error response object for API errors.\n *\n * @param {string} message - Error message\n * @param {Request} req - Express request object\n * @param {any} error - Original error object\n * @param {object} [options] - Additional options\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns {object} Formatted error response\n */\nconst createErrorResponse = (message: string, req: Request, error: any, options?: { includeDetails?: boolean }) => {\n  const isDev = Env.isDev();\n  const includeDetails = options?.includeDetails && isDev;\n\n  const response: Record<string, any> = {\n    error: true,\n    message,\n    timestamp: new Date().toISOString(),\n    requestId: error?.requestId || req.id || uuid(),\n    path: req.originalUrl || req.url\n  };\n\n  // Include error code if present\n  if (error?.code) {\n    response.code = error.code;\n  }\n\n  // Include stack trace in development mode if requested\n  if (includeDetails && error?.stack) {\n    response.stack = error.stack.split('\\n').map((line: string) => line.trim());\n  }\n\n  return response;\n};\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {object} [options] - Error handler options\n * @param {boolean} [options.logErrors=true] - Whether to log errors\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @param {Function} [options.logger=getLogger().error] - Custom logging function\n * @returns {(err: any, req: Request, res: Response, next: NextFunction) => void} Error middleware\n */\nexport function errorHandler(options?: {\n  logErrors?: boolean;\n  includeDetails?: boolean;\n  logger?: (message: string, error: any) => void;\n}) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n  const logger = options?.logger || getLogger().error;\n\n  return (err: any, req: Request, res: Response, _next: NextFunction) => {\n    // Determine status code\n    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;\n\n    // Log error if enabled\n    if (logErrors) {\n      const logMessage = `[ERROR] ${req.method} ${req.originalUrl || req.url}: ${err.message || 'Unknown error'}`;\n      logger(logMessage, err);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      return res.status(status).json({\n        error: err.error,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err.requestId || req.id || uuid(),\n        path: req.originalUrl || req.url\n      });\n    }\n\n    // Handle any other errors\n    return res.status(status).json(\n      createErrorResponse(err?.message || 'Internal Server Error', req, err, {\n        includeDetails\n      })\n    );\n  };\n}\n"]}

package/build/src/utils/obj.utils.d.ts

@@ -4,7 +4,7 @@
  * @param {Record<any, any>} obj - The object to check.
  * @returns {boolean} True if the object is empty, false otherwise.
  */
-export declare const isObjEmpty: (obj: Record<any, any>) => boolean;
+export declare function isObjEmpty(obj: Record<any, any>): boolean;
 /**
  * Returns a new object with only the specified keys picked.
  *
@@ -14,7 +14,7 @@ export declare const isObjEmpty: (obj: Record<any, any>) => boolean;
  * @param {K[]} keys - Keys to pick from the object.
  * @returns {Pick<T, K>} New object with picked keys.
  */
-export declare const pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
 /**
  * Returns a new object with the specified keys omitted.
  *
@@ -24,7 +24,7 @@ export declare const pick: <T extends object, K extends keyof T>(obj: T, keys: K
  * @param {K[]} keys - Keys to omit from the object.
  * @returns {Omit<T, K>} New object without omitted keys.
  */
-export declare const omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
 /**
  * Deeply merges two objects (mutates and returns the target object, not pure).
  *
@@ -52,4 +52,66 @@ export declare function flattenObject<T extends Record<string, any>>(obj: T, pre
  * @returns {any} The value at the given path, or undefined if not found.
  */
 export declare function getValueByPath<T extends object>(obj: T, path: string): any;
+/**
+ * Sets a value at a deeply nested key in an object using dot/bracket notation path.
+ * Creates intermediate objects and arrays as needed.
+ *
+ * @template T
+ * @param {T} obj - The object to modify.
+ * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
+ * @param {any} value - The value to set at the path.
+ * @returns {T} The modified object.
+ */
+export declare function setValueByPath<T extends object>(obj: T, path: string, value: any): T;
+/**
+ * Performs a deep equality check between two objects.
+ *
+ * @param {any} a - First value to compare.
+ * @param {any} b - Second value to compare.
+ * @returns {boolean} True if values are deeply equal.
+ */
+export declare function isEqual(a: any, b: any): boolean;
+/**
+ * Filters object properties based on a predicate function.
+ *
+ * @template T
+ * @param {T} obj - The source object.
+ * @param {(value: any, key: string, obj: T) => boolean} predicate - Filter function.
+ * @returns {Partial<T>} New object with filtered properties.
+ */
+export declare function filterObject<T extends object>(obj: T, predicate: (value: any, key: string, obj: T) => boolean): Partial<T>;
+/**
+ * Maps object values to new values using a mapping function.
+ *
+ * @template T
+ * @template U
+ * @param {T} obj - The source object.
+ * @param {(value: any, key: string, obj: T) => U} mapFn - Mapping function.
+ * @returns {Record<keyof T, U>} New object with mapped values.
+ */
+export declare function mapObject<T extends object, U>(obj: T, mapFn: (value: any, key: string, obj: T) => U): Record<keyof T, U>;
+/**
+ * Recursively freezes an object and all its properties.
+ * Makes an object immutable.
+ *
+ * @template T
+ * @param {T} obj - The object to freeze.
+ * @returns {Readonly<T>} The frozen object.
+ */
+export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
+/**
+ * Safely checks if a value is an object (not null, not array).
+ *
+ * @param {unknown} value - Value to check.
+ * @returns {boolean} True if value is a non-null, non-array object.
+ */
+export declare function isObject(value: unknown): value is Record<string, any>;
+/**
+ * Gets all paths in an object using dot notation.
+ *
+ * @param {Record<string, any>} obj - Object to analyze.
+ * @param {string} [parentPath=""] - Internal param for recursion.
+ * @returns {string[]} Array of all paths in dot notation.
+ */
+export declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];
 //# sourceMappingURL=obj.utils.d.ts.map