@catbee/utils 0.0.1 → 0.0.2

package/build/esnext/utils/id.utils.js

@@ -1,6 +1,4 @@
-import { randomUUID } from "crypto";
-import { ulid } from "ulid";
-import { nanoid } from "nanoid";
+import { randomUUID, randomBytes } from "crypto";
 /**
  * Generates a UUID v4 string (RFC 4122).
  *
@@ -10,21 +8,21 @@ export function uuid() {
     return 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.
  */
-export function ulidString() {
-    return 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.
- */
-export function nanoId(size = 21) {
-    return nanoid(size);
+export function nanoId(length = 21) {
+    if (length <= 0)
+        return "";
+    let id = "";
+    while (id.length < length) {
+        id += randomBytes(Math.ceil((length * 3) / 4))
+            .toString("base64url")
+            .replace(/[+/=]/g, "");
+    }
+    return id.slice(0, length);
 }
 /**
  * Generates a cryptographically strong random hex string.
@@ -33,10 +31,11 @@ export function nanoId(size = 21) {
  * @returns {string} Random hex string.
  */
 export 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)))
+    // Use Node.js crypto for both Node and browser compatibility
+    // Prefer randomBytes if available (Node), fallback to getRandomValues for browser (not used here)
+    return randomBytes(byteLength)
         .toString("hex")
+        .padStart(byteLength * 2, "0")
         .slice(0, byteLength * 2);
 }
 /**
@@ -50,4 +49,13 @@ export 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).
+ */
+export function randomBase64(byteLength = 16) {
+    return randomBytes(byteLength).toString("base64url");
+}
 //# sourceMappingURL=id.utils.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"id.utils.js","sourceRoot":"","sources":["../../../src/utils/id.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;GAIG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,EAAE,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE;IACtC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,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,MAAM,UAAU,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":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,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,WAAW,CAAC,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,MAAM,UAAU,SAAS,CAAC,aAAqB,EAAE;IAC/C,6DAA6D;IAC7D,kGAAkG;IAClG,OAAO,WAAW,CAAC,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,MAAM,UAAU,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,MAAM,UAAU,YAAY,CAAC,aAAqB,EAAE;IAClD,OAAO,WAAW,CAAC,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/esnext/utils/logger.utils.d.ts

@@ -12,4 +12,28 @@ export declare const _globalThis: typeof globalThis;
  * @returns {Logger} The logger instance (request-bound or global root logger)
  */
 export declare function getLogger(): Logger;
+/**
+ * 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?: Logger): Logger;
+/**
+ * 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>): 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
+ */
+export declare function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void;
 //# sourceMappingURL=logger.utils.d.ts.map

package/build/esnext/utils/logger.utils.js

@@ -56,4 +56,46 @@ export 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
+ */
+export 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
+ */
+export function createRequestLogger(requestId, additionalContext = {}) {
+    const logger = createChildLogger(Object.assign({ requestId }, additionalContext));
+    try {
+        ContextStore.set(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
+ */
+export 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/esnext/utils/logger.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAiB,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;GAEG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC;AAChF,MAAM,OAAO,GAAG,WAAyD,CAAC;AAE1E;;;;;GAKG;AACH,SAAS,WAAW;IAClB,MAAM,SAAS,GAAkB;QAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI;QACxB,KAAK,EAAE,MAAM,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,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QAC/B,SAAS,CAAC,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC;IACjD,CAAC;IAED,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7C,OAAO,CAAC,iBAAiB,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAS,SAAS,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 } 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\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(\n  bindings: Record<string, any>,\n  parentLogger?: Logger,\n): Logger {\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(\n  requestId: string,\n  additionalContext: Record<string, any> = {},\n): Logger {\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(\n      \"Failed to store logger in context - AsyncLocalStorage not initialized\",\n    );\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(\n  error: Error | unknown,\n  message?: string,\n  context?: Record<string, any>,\n): 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/esnext/utils/middleware.utils.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Type definitions for Express-compatible middleware
+ */
+export 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;
+};
+export 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;
+};
+export type NextFunction = (err?: Error | any) => void;
+export 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;
+//# sourceMappingURL=middleware.utils.d.ts.map

package/build/esnext/utils/middleware.utils.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "crypto";
+import { Config } from "../config";
+import { uuid } from "./id.utils";
+import { HttpStatusCodes } from "./http-status-codes";
+import { ErrorResponse } from "./response.utils";
+import { Env } from "./env.utils";
+import { getLogger } from "./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
+ */
+export 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 || 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
+ */
+export 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;
+                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
+ */
+export function timeout(timeoutMs = 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.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 || 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
+ */
+export 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) || 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) || 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 ErrorResponse) {
+            return res.status(status).json({
+                error: err.error,
+                message: err.message,
+                timestamp: err.timestamp,
+                requestId: err.requestId || req.id || 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/esnext/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 */\nexport type 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\nexport type 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\nexport type NextFunction = (err?: Error | any) => void;\n\nexport type Middleware = (\n  req: Request,\n  res: Response,\n  next: NextFunction,\n) => 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?: {\n  headerName?: string;\n  exposeHeader?: boolean;\n}): 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?: {\n  addHeader?: boolean;\n  logOnComplete?: boolean;\n}): 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 = (\n  message: string,\n  req: Request,\n  error: any,\n  options?: { includeDetails?: boolean },\n) => {\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 =\n      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/esnext/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