@catbee/utils 0.0.1 → 0.0.2

package/build/esm/utils/validate.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.utils.js","sourceRoot":"","sources":["../../../src/utils/validate.utils.ts"],"names":[],"mappings":"AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAE1D,oBAAoB;IACd,IAAA,KAAA,OAAkB,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAA,EAA/B,KAAK,QAAA,EAAE,MAAM,QAAkB,CAAC;IACvC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAEpC,oDAAoD;IACpD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAEhE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,GAAW;IAChC,OAAO,4EAA4E,CAAC,IAAI,CACtF,GAAG,CACJ,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE1C,mDAAmD;IACnD,IAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IAElE,6DAA6D;IAC7D,OAAO,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAsB;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACnE,IAAM,GAAG,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9D,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,+BAA+B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAM,QAAQ,GACZ,sEAAsE,CAAC;IAEzE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAEtC,IAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO,CACL,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAC1E,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Collection of common validation helpers for strings, numbers, email, UUID, etc.\n */\n\n/**\n * Checks if a string is a valid email address.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid email, else false.\n */\nexport function isEmail(str: string): boolean {\n  if (!/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(str)) return false;\n\n  // Additional checks\n  const [local, domain] = str.split(\"@\");\n  if (!local || !domain) return false;\n\n  // Disallow consecutive dots in local or domain part\n  if (local.includes(\"..\") || domain.includes(\"..\")) return false;\n\n  return true;\n}\n\n/**\n * Checks if a string is a valid UUID (versions 1-5).\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid UUID, else false.\n */\nexport function isUUID(str: string): boolean {\n  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(\n    str,\n  );\n}\n\n/**\n * Checks if a string is a valid URL.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid URL, else false.\n */\nexport function isURL(str: string): boolean {\n  try {\n    new URL(str);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Checks if a string is a valid international phone number (E.164 or common patterns).\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if looks like a phone number.\n */\nexport function isPhone(str: string): boolean {\n  if (typeof str !== \"string\") return false;\n\n  // Strip non-digit characters to count total digits\n  const digitsOnly = str.replace(/\\D/g, \"\");\n  if (digitsOnly.length < 6 || digitsOnly.length > 15) return false;\n\n  // Accept typical phone characters: +, digits, space, -, (, )\n  return /^[+]?[\\d\\s().-]+$/.test(str);\n}\n\n/**\n * Checks if a string is strictly alphanumeric (letters/numbers only).\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if alphanumeric.\n */\nexport function isAlphanumeric(str: string): boolean {\n  return /^[a-z0-9]+$/i.test(str);\n}\n\n/**\n * Checks if a string or number can be safely parsed to a number.\n *\n * @param {string | number} value - The value to check.\n * @returns {boolean} True if the value is numeric.\n */\nexport function isNumeric(value: string | number): boolean {\n  if (typeof value === \"string\" && value.trim() === \"\") return false;\n  const num = typeof value === \"number\" ? value : Number(value);\n  return typeof num === \"number\" && isFinite(num);\n}\n\n/**\n * Checks if a string is a valid hex color code (e.g. #FFF or #FFFFFF).\n *\n * @param {string} str - Input string.\n * @returns {boolean}\n */\nexport function isHexColor(str: string): boolean {\n  return /^#([a-f0-9]{6}|[a-f0-9]{3})$/i.test(str);\n}\n\n/**\n * Checks if a string is a valid date string.\n *\n * @param {string} str - Input string.\n * @returns {boolean}\n */\nexport function isISODate(str: string): boolean {\n  const isoRegex =\n    /^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})?)?$/;\n\n  if (!isoRegex.test(str)) return false;\n\n  const date = new Date(str);\n  return (\n    !isNaN(date.getTime()) && date.toISOString().startsWith(str.slice(0, 10))\n  );\n}\n"]}
+{"version":3,"file":"validate.utils.js","sourceRoot":"","sources":["../../../src/utils/validate.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Collection of common validation helpers for strings, numbers, email, UUID, etc.\n */\n\n/**\n * Checks if a string is a valid email address.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid email, else false.\n */\nexport function isEmail(str: string): boolean {\n  if (!/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(str)) return false;\n\n  // Additional checks\n  const [local, domain] = str.split(\"@\");\n  if (!local || !domain) return false;\n\n  // Disallow consecutive dots in local or domain part\n  if (local.includes(\"..\") || domain.includes(\"..\")) return false;\n\n  return true;\n}\n\n/**\n * Checks if a string is a valid UUID (versions 1-5).\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid UUID, else false.\n */\nexport function isUUID(str: string): boolean {\n  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(\n    str,\n  );\n}\n\n/**\n * Checks if a string is a valid URL.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid URL, else false.\n */\nexport function isURL(str: string): boolean {\n  try {\n    new URL(str);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Checks if a string is a valid international phone number (E.164 or common patterns).\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if looks like a phone number.\n */\nexport function isPhone(str: string): boolean {\n  if (typeof str !== \"string\") return false;\n\n  // Strip non-digit characters to count total digits\n  const digitsOnly = str.replace(/\\D/g, \"\");\n  if (digitsOnly.length < 6 || digitsOnly.length > 15) return false;\n\n  // Accept typical phone characters: +, digits, space, -, (, )\n  return /^[+]?[\\d\\s().-]+$/.test(str);\n}\n\n/**\n * Checks if a string is strictly alphanumeric (letters/numbers only).\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if alphanumeric.\n */\nexport function isAlphanumeric(str: string): boolean {\n  return /^[a-z0-9]+$/i.test(str);\n}\n\n/**\n * Checks if a string or number can be safely parsed to a number.\n *\n * @param {string | number} value - The value to check.\n * @returns {boolean} True if the value is numeric.\n */\nexport function isNumeric(value: string | number): boolean {\n  if (typeof value === \"string\" && value.trim() === \"\") return false;\n  const num = typeof value === \"number\" ? value : Number(value);\n  return typeof num === \"number\" && isFinite(num);\n}\n\n/**\n * Checks if a string is a valid hex color code (e.g. #FFF or #FFFFFF).\n *\n * @param {string} str - Input string.\n * @returns {boolean}\n */\nexport function isHexColor(str: string): boolean {\n  return /^#([a-f0-9]{6}|[a-f0-9]{3})$/i.test(str);\n}\n\n/**\n * Checks if a string is a valid date string.\n *\n * @param {string} str - Input string.\n * @returns {boolean}\n */\nexport function isISODate(str: string): boolean {\n  const isoRegex =\n    /^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})?)?$/;\n\n  if (!isoRegex.test(str)) return false;\n\n  const date = new Date(str);\n  return (\n    !isNaN(date.getTime()) && date.toISOString().startsWith(str.slice(0, 10))\n  );\n}\n\n/**\n * Checks if a string matches a specified length range.\n *\n * @param {string} str - The input string.\n * @param {number} min - Minimum length (inclusive).\n * @param {number} max - Maximum length (inclusive).\n * @returns {boolean} True if string length is within range.\n */\nexport function isLengthBetween(\n  str: string,\n  min: number,\n  max: number,\n): boolean {\n  return str.length >= min && str.length <= max;\n}\n\n/**\n * Validates that a number is between specified min and max values (inclusive).\n *\n * @param {number} value - The number to validate.\n * @param {number} min - Minimum value.\n * @param {number} max - Maximum value.\n * @returns {boolean} True if number is within range.\n */\nexport function isNumberBetween(\n  value: number,\n  min: number,\n  max: number,\n): boolean {\n  return value >= min && value <= max;\n}\n\n/**\n * Checks if a string contains only alphabetic characters.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if alphabetic only.\n */\nexport function isAlpha(str: string): boolean {\n  return /^[a-zA-Z]+$/.test(str);\n}\n\n/**\n * Validates that a string contains at least one uppercase letter,\n * one lowercase letter, one number, and one special character.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if string meets password complexity requirements.\n */\nexport function isStrongPassword(str: string): boolean {\n  if (str.length < 8) return false;\n  const hasUpperCase = /[A-Z]/.test(str);\n  const hasLowerCase = /[a-z]/.test(str);\n  const hasNumbers = /[0-9]/.test(str);\n  const hasSpecialChar = /[!@#$%^&*()_+\\-=[\\]{};':\"\\\\|,.<>?]/.test(str);\n  return hasUpperCase && hasLowerCase && hasNumbers && hasSpecialChar;\n}\n\n/**\n * Checks if a string is a valid IPv4 address.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid IPv4 address.\n */\nexport function isIPv4(str: string): boolean {\n  const parts = str.split(\".\");\n  if (parts.length !== 4) return false;\n\n  return parts.every((part) => {\n    const num = parseInt(part, 10);\n    return part === num.toString() && num >= 0 && num <= 255;\n  });\n}\n\n/**\n * Checks if a string is a valid IPv6 address.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid IPv6 address.\n */\nexport function isIPv6(str: string): boolean {\n  // Simple but effective check for common IPv6 formats\n  return /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]+|::(ffff(:0{1,4})?:)?((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9]))$/.test(\n    str,\n  );\n}\n\n/**\n * Validates a credit card number using the Luhn algorithm.\n *\n * @param {string} str - The credit card number string.\n * @returns {boolean} True if valid credit card number.\n */\nexport function isCreditCard(str: string): boolean {\n  // Remove non-digit characters\n  const cardNumber = str.replace(/\\D/g, \"\");\n  if (cardNumber.length < 13 || cardNumber.length > 19) return false;\n\n  // Luhn algorithm implementation\n  let sum = 0;\n  let shouldDouble = false;\n\n  for (let i = cardNumber.length - 1; i >= 0; i--) {\n    let digit = parseInt(cardNumber.charAt(i), 10);\n\n    if (shouldDouble) {\n      digit *= 2;\n      if (digit > 9) digit -= 9;\n    }\n\n    sum += digit;\n    shouldDouble = !shouldDouble;\n  }\n\n  return sum % 10 === 0;\n}\n\n/**\n * Checks if a string is a valid JSON.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid JSON.\n */\nexport function isValidJSON(str: string): boolean {\n  try {\n    JSON.parse(str);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Type guard that checks if a value is an array.\n *\n * @template T Optional expected element type\n * @param {unknown} value - The value to check.\n * @param {(item: unknown) => boolean} [itemGuard] - Optional function to validate each item.\n * @returns {boolean} True if value is an array (with optional item validation).\n */\nexport function isArray<T = unknown>(\n  value: unknown,\n  itemGuard?: (item: unknown) => item is T,\n): value is T[] {\n  if (!Array.isArray(value)) return false;\n  return !itemGuard || value.every((item) => itemGuard(item));\n}\n\n/**\n * Checks if a string is a valid base64 encoded string.\n *\n * @param {string} str - The input string.\n * @returns {boolean} True if valid base64.\n */\nexport function isBase64(str: string): boolean {\n  return /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(\n    str,\n  );\n}\n\n/**\n * Validates that an object has all required properties.\n *\n * @param {object} obj - The object to validate.\n * @param {string[]} requiredProps - Array of required property names.\n * @returns {boolean} True if all required properties exist.\n */\nexport function hasRequiredProps(\n  obj: Record<string, unknown>,\n  requiredProps: string[],\n): boolean {\n  return requiredProps.every(\n    (prop) =>\n      Object.prototype.hasOwnProperty.call(obj, prop) &&\n      obj[prop] !== undefined &&\n      obj[prop] !== null,\n  );\n}\n\n/**\n * Validates a date is within a specified range.\n *\n * @param {Date} date - The date to validate.\n * @param {Date} [minDate] - Optional minimum date (inclusive).\n * @param {Date} [maxDate] - Optional maximum date (inclusive).\n * @returns {boolean} True if date is within range.\n */\nexport function isDateInRange(\n  date: Date,\n  minDate?: Date,\n  maxDate?: Date,\n): boolean {\n  if (!(date instanceof Date) || isNaN(date.getTime())) return false;\n\n  if (minDate && date < minDate) return false;\n  if (maxDate && date > maxDate) return false;\n\n  return true;\n}\n\n/**\n * Validates a string matches a specific regular expression pattern.\n *\n * @param {string} str - The input string.\n * @param {RegExp} pattern - Regular expression to test against.\n * @returns {boolean} True if string matches pattern.\n */\nexport function matchesPattern(str: string, pattern: RegExp): boolean {\n  return pattern.test(str);\n}\n\n/**\n * Validates data against multiple constraints.\n *\n * @param {unknown} value - The value to validate.\n * @param {Array<(value: unknown) => boolean>} validators - Array of validation functions.\n * @returns {boolean} True if value passes all validations.\n */\nexport function validateAll(\n  value: unknown,\n  validators: Array<(value: unknown) => boolean>,\n): boolean {\n  return validators.every((validator) => validator(value));\n}\n"]}

package/build/esnext/config.d.ts

@@ -17,6 +17,18 @@ export declare const Config: {
          */
         isoTimestamp: boolean;
     };
+    Http: {
+        /**
+         * Timeout for HTTP requests in milliseconds
+         */
+        timeout: number;
+    };
+    Cache: {
+        /**
+         * Default TTL (time to live) for cache entries in seconds
+         */
+        defaultTtl: number;
+    };
 };
 export {};
 //# sourceMappingURL=config.d.ts.map

package/build/esnext/config.js

@@ -17,5 +17,17 @@ export const Config = {
          */
         isoTimestamp: Env.getBoolean("LOGGER_ISO_TIMESTAMP", false),
     },
+    Http: {
+        /**
+         * Timeout for HTTP requests in milliseconds
+         */
+        timeout: Env.getNumber("HTTP_TIMEOUT", 30000),
+    },
+    Cache: {
+        /**
+         * Default TTL (time to live) for cache entries in seconds
+         */
+        defaultTtl: Env.getNumber("CACHE_DEFAULT_TTL", 300),
+    },
 };
 //# sourceMappingURL=config.js.map

package/build/esnext/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAWxC;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,MAAM,EAAE;QACN;;WAEG;QACH,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAa;QAElD;;WAEG;QACH,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;QAE1E;;WAEG;QACH,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC,sBAAsB,EAAE,KAAK,CAAC;KAC5D;CACF,CAAC","sourcesContent":["import { Env } from \"./utils/env.utils\";\n\ntype LogLevel =\n  | \"fatal\"\n  | \"error\"\n  | \"warn\"\n  | \"info\"\n  | \"debug\"\n  | \"trace\"\n  | \"silent\";\n\n/**\n * Application runtime configuration loaded from environment variables.\n */\nexport const Config = {\n  Logger: {\n    /**\n     * Logging level (e.g., 'info', 'debug', 'warn', 'error').\n     */\n    level: Env.get(\"LOGGER_LEVEL\", \"info\") as LogLevel,\n\n    /**\n     * Name of the logger instance (defaults to npm package name).\n     */\n    name: Env.get(\"LOGGER_NAME\", Env.get(\"npm_package_name\", \"@catbee/utils\")),\n\n    /**\n     * Whether to use ISO 8601 timestamps in logs.\n     */\n    isoTimestamp: Env.getBoolean(\"LOGGER_ISO_TIMESTAMP\", false),\n  },\n};\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAWxC;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,MAAM,EAAE;QACN;;WAEG;QACH,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAa;QAElD;;WAEG;QACH,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;QAE1E;;WAEG;QACH,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC,sBAAsB,EAAE,KAAK,CAAC;KAC5D;IAED,IAAI,EAAE;QACJ;;WAEG;QACH,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,KAAK,CAAC;KAC9C;IAED,KAAK,EAAE;QACL;;WAEG;QACH,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,GAAG,CAAC;KACpD;CACF,CAAC","sourcesContent":["import { Env } from \"./utils/env.utils\";\n\ntype LogLevel =\n  | \"fatal\"\n  | \"error\"\n  | \"warn\"\n  | \"info\"\n  | \"debug\"\n  | \"trace\"\n  | \"silent\";\n\n/**\n * Application runtime configuration loaded from environment variables.\n */\nexport const Config = {\n  Logger: {\n    /**\n     * Logging level (e.g., 'info', 'debug', 'warn', 'error').\n     */\n    level: Env.get(\"LOGGER_LEVEL\", \"info\") as LogLevel,\n\n    /**\n     * Name of the logger instance (defaults to npm package name).\n     */\n    name: Env.get(\"LOGGER_NAME\", Env.get(\"npm_package_name\", \"@catbee/utils\")),\n\n    /**\n     * Whether to use ISO 8601 timestamps in logs.\n     */\n    isoTimestamp: Env.getBoolean(\"LOGGER_ISO_TIMESTAMP\", false),\n  },\n\n  Http: {\n    /**\n     * Timeout for HTTP requests in milliseconds\n     */\n    timeout: Env.getNumber(\"HTTP_TIMEOUT\", 30000),\n  },\n\n  Cache: {\n    /**\n     * Default TTL (time to live) for cache entries in seconds\n     */\n    defaultTtl: Env.getNumber(\"CACHE_DEFAULT_TTL\", 300),\n  },\n};\n"]}

package/build/esnext/index.d.ts

@@ -10,6 +10,7 @@ export * from "./utils/fs.utils";
 export * from "./utils/http-status-codes";
 export * from "./utils/id.utils";
 export * from "./utils/logger.utils";
+export * from "./utils/middleware.utils";
 export * from "./utils/obj.utils";
 export * from "./utils/response.utils";
 export * from "./utils/string.utils";

package/build/esnext/index.js

@@ -10,6 +10,7 @@ export * from "./utils/fs.utils";
 export * from "./utils/http-status-codes";
 export * from "./utils/id.utils";
 export * from "./utils/logger.utils";
+export * from "./utils/middleware.utils";
 export * from "./utils/obj.utils";
 export * from "./utils/response.utils";
 export * from "./utils/string.utils";

package/build/esnext/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./utils/array.utils\";\nexport * from \"./utils/async.utils\";\nexport * from \"./utils/cache.utils\";\nexport * from \"./utils/context-store.utils\";\nexport * from \"./utils/crypto.utils\";\nexport * from \"./utils/dir.utils\";\nexport * from \"./utils/env.utils\";\nexport * from \"./utils/exception.utils\";\nexport * from \"./utils/fs.utils\";\nexport * from \"./utils/http-status-codes\";\nexport * from \"./utils/id.utils\";\nexport * from \"./utils/logger.utils\";\nexport * from \"./utils/obj.utils\";\nexport * from \"./utils/response.utils\";\nexport * from \"./utils/string.utils\";\nexport * from \"./utils/url.utils\";\nexport * from \"./utils/validate.utils\";\n\nexport * from \"./types/api-response\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./utils/array.utils\";\nexport * from \"./utils/async.utils\";\nexport * from \"./utils/cache.utils\";\nexport * from \"./utils/context-store.utils\";\nexport * from \"./utils/crypto.utils\";\nexport * from \"./utils/dir.utils\";\nexport * from \"./utils/env.utils\";\nexport * from \"./utils/exception.utils\";\nexport * from \"./utils/fs.utils\";\nexport * from \"./utils/http-status-codes\";\nexport * from \"./utils/id.utils\";\nexport * from \"./utils/logger.utils\";\nexport * from \"./utils/middleware.utils\";\nexport * from \"./utils/obj.utils\";\nexport * from \"./utils/response.utils\";\nexport * from \"./utils/string.utils\";\nexport * from \"./utils/url.utils\";\nexport * from \"./utils/validate.utils\";\n\nexport * from \"./types/api-response\";\n"]}

package/build/esnext/types/api-response.d.ts

@@ -41,4 +41,86 @@ export interface Pagination<T = any> {
  * Allows semantic naming like `PaginationResponse<User>` or `PaginationResponse<Post>`.
  */
 export type PaginationResponse<T = any> = Pagination<T>;
+/**
+ * Error response structure with additional metadata.
+ * Used for providing richer error information to clients.
+ */
+export interface ApiErrorResponse extends Omit<ApiResponse<never>, "data"> {
+    /** Error always true for error responses */
+    error: true;
+    /** HTTP status code */
+    status: number;
+    /** Error code for client-side error handling */
+    code?: string;
+    /** Optional detailed validation errors */
+    details?: Record<string, string[]>;
+    /** Link to error documentation */
+    docUrl?: string;
+}
+/**
+ * Success response structure with strongly typed data.
+ * Used for providing successful responses to clients.
+ */
+export interface ApiSuccessResponse<T = any> extends ApiResponse<T> {
+    /** Error always false for success responses */
+    error: false;
+    /** HTTP status code (usually 200) */
+    status?: number;
+}
+/**
+ * Response structure for batch operations.
+ * Used when multiple operations are performed in a single request.
+ */
+export interface BatchResponse<T = any> {
+    /** Overall success/failure indicator */
+    success: boolean;
+    /** Total number of operations */
+    total: number;
+    /** Number of successful operations */
+    successful: number;
+    /** Number of failed operations */
+    failed: number;
+    /** Results of individual operations */
+    results: Array<{
+        /** Identifier for this operation */
+        id: string | number;
+        /** Success/failure indicator for this operation */
+        success: boolean;
+        /** Response data for this operation */
+        data?: T;
+        /** Error information if this operation failed */
+        error?: {
+            message: string;
+            code?: string;
+        };
+    }>;
+}
+/**
+ * Response structure for asynchronous operations.
+ * Used when the operation will complete in the future.
+ */
+export interface AsyncOperationResponse {
+    /** Always true for async operations */
+    async: true;
+    /** Job or task ID to check status later */
+    jobId: string;
+    /** Estimated completion time in seconds (if known) */
+    estimatedTime?: number;
+    /** URL to check status */
+    statusUrl: string;
+}
+/**
+ * Response structure for streaming operations.
+ * Used when data is returned as a stream rather than all at once.
+ */
+export interface StreamResponse {
+    /** Stream identifier */
+    streamId: string;
+    /** Stream type (e.g., 'json', 'binary') */
+    streamType: string;
+    /** Total size in bytes (if known) */
+    totalSize?: number;
+    /** Chunk size in bytes */
+    chunkSize: number;
+}
 //# sourceMappingURL=api-response.d.ts.map

package/build/esnext/types/api-response.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-response.js","sourceRoot":"","sources":["../../../src/types/api-response.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Generic API response format.\n * Used to wrap any successful or failed response from the server.\n */\nexport interface ApiResponse<T = any> {\n  /** Payload returned from the API. Can be any shape depending on the endpoint. */\n  data: T | null;\n\n  /** Indicates whether an error occurred (true = error, false = success). */\n  error: boolean;\n\n  /** Human-readable message to describe the result or error. */\n  message: string;\n\n  /** Unique request ID for traceability in logs (e.g., from a middleware). */\n  requestId: string;\n\n  /** ISO timestamp when the response was generated. */\n  timestamp: string;\n}\n\n/**\n * Generic pagination structure used for paged lists (e.g., /users?page=1).\n */\nexport interface Pagination<T = any> {\n  /** List of records for the current page. */\n  content: T[];\n\n  /** Metadata about the pagination state. */\n  pagination: {\n    /** Total number of records across all pages. */\n    totalRecords: number;\n\n    /** Total number of pages available. */\n    totalPages: number;\n\n    /** Current page number (1-based index). */\n    page: number;\n\n    /** Number of records per page. */\n    limit: number;\n\n    /** Field by which the data is sorted. */\n    sortBy: string;\n\n    /** Sort order: ascending or descending. */\n    sortOrder: \"asc\" | \"desc\";\n  };\n}\n\n/**\n * Alias for paginated API response.\n * Allows semantic naming like `PaginationResponse<User>` or `PaginationResponse<Post>`.\n */\nexport type PaginationResponse<T = any> = Pagination<T>;\n"]}
+{"version":3,"file":"api-response.js","sourceRoot":"","sources":["../../../src/types/api-response.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Generic API response format.\n * Used to wrap any successful or failed response from the server.\n */\nexport interface ApiResponse<T = any> {\n  /** Payload returned from the API. Can be any shape depending on the endpoint. */\n  data: T | null;\n\n  /** Indicates whether an error occurred (true = error, false = success). */\n  error: boolean;\n\n  /** Human-readable message to describe the result or error. */\n  message: string;\n\n  /** Unique request ID for traceability in logs (e.g., from a middleware). */\n  requestId: string;\n\n  /** ISO timestamp when the response was generated. */\n  timestamp: string;\n}\n\n/**\n * Generic pagination structure used for paged lists (e.g., /users?page=1).\n */\nexport interface Pagination<T = any> {\n  /** List of records for the current page. */\n  content: T[];\n\n  /** Metadata about the pagination state. */\n  pagination: {\n    /** Total number of records across all pages. */\n    totalRecords: number;\n\n    /** Total number of pages available. */\n    totalPages: number;\n\n    /** Current page number (1-based index). */\n    page: number;\n\n    /** Number of records per page. */\n    limit: number;\n\n    /** Field by which the data is sorted. */\n    sortBy: string;\n\n    /** Sort order: ascending or descending. */\n    sortOrder: \"asc\" | \"desc\";\n  };\n}\n\n/**\n * Alias for paginated API response.\n * Allows semantic naming like `PaginationResponse<User>` or `PaginationResponse<Post>`.\n */\nexport type PaginationResponse<T = any> = Pagination<T>;\n\n/**\n * Error response structure with additional metadata.\n * Used for providing richer error information to clients.\n */\nexport interface ApiErrorResponse extends Omit<ApiResponse<never>, \"data\"> {\n  /** Error always true for error responses */\n  error: true;\n\n  /** HTTP status code */\n  status: number;\n\n  /** Error code for client-side error handling */\n  code?: string;\n\n  /** Optional detailed validation errors */\n  details?: Record<string, string[]>;\n\n  /** Link to error documentation */\n  docUrl?: string;\n}\n\n/**\n * Success response structure with strongly typed data.\n * Used for providing successful responses to clients.\n */\nexport interface ApiSuccessResponse<T = any> extends ApiResponse<T> {\n  /** Error always false for success responses */\n  error: false;\n\n  /** HTTP status code (usually 200) */\n  status?: number;\n}\n\n/**\n * Response structure for batch operations.\n * Used when multiple operations are performed in a single request.\n */\nexport interface BatchResponse<T = any> {\n  /** Overall success/failure indicator */\n  success: boolean;\n\n  /** Total number of operations */\n  total: number;\n\n  /** Number of successful operations */\n  successful: number;\n\n  /** Number of failed operations */\n  failed: number;\n\n  /** Results of individual operations */\n  results: Array<{\n    /** Identifier for this operation */\n    id: string | number;\n\n    /** Success/failure indicator for this operation */\n    success: boolean;\n\n    /** Response data for this operation */\n    data?: T;\n\n    /** Error information if this operation failed */\n    error?: {\n      message: string;\n      code?: string;\n    };\n  }>;\n}\n\n/**\n * Response structure for asynchronous operations.\n * Used when the operation will complete in the future.\n */\nexport interface AsyncOperationResponse {\n  /** Always true for async operations */\n  async: true;\n\n  /** Job or task ID to check status later */\n  jobId: string;\n\n  /** Estimated completion time in seconds (if known) */\n  estimatedTime?: number;\n\n  /** URL to check status */\n  statusUrl: string;\n}\n\n/**\n * Response structure for streaming operations.\n * Used when data is returned as a stream rather than all at once.\n */\nexport interface StreamResponse {\n  /** Stream identifier */\n  streamId: string;\n\n  /** Stream type (e.g., 'json', 'binary') */\n  streamType: string;\n\n  /** Total size in bytes (if known) */\n  totalSize?: number;\n\n  /** Chunk size in bytes */\n  chunkSize: number;\n}\n"]}

package/build/esnext/utils/array.utils.d.ts

@@ -8,7 +8,7 @@
  * @throws {TypeError} If array is not an array.
  * @throws {Error} If chunk size is not a positive integer.
  */
-export declare const chunk: <T>(array: T[], size: number) => T[][];
+export declare function chunk<T>(array: T[], size: number): T[][];
 /**
  * Removes duplicate values from an array.
  * Optionally enforces uniqueness by a key function.
@@ -102,4 +102,67 @@ export declare function intersect<T>(a: T[], b: T[]): T[];
  * @throws {TypeError} If array is not an array.
  */
 export declare function mergeSort<T>(array: T[], key: string | ((item: T) => any), direction?: "asc" | "desc"): T[];
+/**
+ * Combines multiple arrays into a single array of grouped elements.
+ * Output array length equals the length of the shortest input array.
+ *
+ * @example zip([1, 2], ['a', 'b']) => [[1, 'a'], [2, 'b']]
+ * @param {...Array<T>[]} arrays - Two or more arrays to zip together.
+ * @returns {Array<T[]>} Array of grouped elements.
+ */
+export declare function zip<T>(...arrays: T[][]): T[][];
+/**
+ * Splits an array into two arrays based on a predicate function.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T, index: number, array: T[]) => boolean} predicate - Function to test each element.
+ * @returns {[T[], T[]]} A tuple of two arrays: [matched, unmatched].
+ */
+export declare function partition<T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): [T[], T[]];
+/**
+ * Generates an array of numbers within a specified range.
+ *
+ * @param {number} start - Start of range (inclusive).
+ * @param {number} end - End of range (exclusive).
+ * @param {number} [step=1] - Step between numbers.
+ * @returns {number[]} Array of numbers in range.
+ */
+export declare function range(start: number, end: number, step?: number): number[];
+/**
+ * Returns the first n elements of an array.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {number} [n=1] - Number of elements to take.
+ * @returns {T[]} New array with first n elements.
+ */
+export declare function take<T>(array: T[], n?: number): T[];
+/**
+ * Takes elements from the array while predicate returns true.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T, index: number) => boolean} predicate - Function to test each element.
+ * @returns {T[]} New array with taken elements.
+ */
+export declare function takeWhile<T>(array: T[], predicate: (item: T, index: number) => boolean): T[];
+/**
+ * Removes all falsy values from an array.
+ * False, null, 0, "", undefined, and NaN are falsy.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @returns {NonNullable<T>[]} New array with falsy values removed.
+ */
+export declare function compact<T>(array: T[]): NonNullable<T>[];
+/**
+ * Counts array elements by a key function.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T) => string | number | symbol} keyFn - Function to generate count key.
+ * @returns {Record<string, number>} Object with counts by key.
+ */
+export declare function countBy<T>(array: T[], keyFn: (item: T) => string | number | symbol): Record<string, number>;
 //# sourceMappingURL=array.utils.d.ts.map

package/build/esnext/utils/array.utils.js

@@ -9,7 +9,7 @@ import { getValueByPath } from "./obj.utils";
  * @throws {TypeError} If array is not an array.
  * @throws {Error} If chunk size is not a positive integer.
  */
-export const chunk = (array, size) => {
+export function chunk(array, size) {
     if (!Array.isArray(array))
         throw new TypeError("Expected an array");
     if (!array.length)
@@ -17,7 +17,7 @@ export const chunk = (array, size) => {
     if (!Number.isInteger(size) || size <= 0)
         throw new Error("Chunk size must be a positive integer");
     return Array.from({ length: Math.ceil(array.length / size) }, (_, i) => array.slice(i * size, i * size + size));
-};
+}
 /**
  * Removes duplicate values from an array.
  * Optionally enforces uniqueness by a key function.
@@ -200,4 +200,131 @@ export function mergeSort(array, key, direction = "asc") {
     };
     return sort(array);
 }
+/**
+ * Combines multiple arrays into a single array of grouped elements.
+ * Output array length equals the length of the shortest input array.
+ *
+ * @example zip([1, 2], ['a', 'b']) => [[1, 'a'], [2, 'b']]
+ * @param {...Array<T>[]} arrays - Two or more arrays to zip together.
+ * @returns {Array<T[]>} Array of grouped elements.
+ */
+export function zip(...arrays) {
+    if (arrays.length === 0)
+        return [];
+    if (arrays.some((arr) => !Array.isArray(arr))) {
+        throw new TypeError("All arguments must be arrays");
+    }
+    const minLength = Math.min(...arrays.map((arr) => arr.length));
+    const result = [];
+    for (let i = 0; i < minLength; i++) {
+        result.push(arrays.map((arr) => arr[i]));
+    }
+    return result;
+}
+/**
+ * Splits an array into two arrays based on a predicate function.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T, index: number, array: T[]) => boolean} predicate - Function to test each element.
+ * @returns {[T[], T[]]} A tuple of two arrays: [matched, unmatched].
+ */
+export function partition(array, predicate) {
+    if (!Array.isArray(array))
+        return [[], []];
+    return array.reduce(([pass, fail], item, index) => {
+        return predicate(item, index, array)
+            ? [[...pass, item], fail]
+            : [pass, [...fail, item]];
+    }, [[], []]);
+}
+/**
+ * Generates an array of numbers within a specified range.
+ *
+ * @param {number} start - Start of range (inclusive).
+ * @param {number} end - End of range (exclusive).
+ * @param {number} [step=1] - Step between numbers.
+ * @returns {number[]} Array of numbers in range.
+ */
+export function range(start, end, step = 1) {
+    if (!Number.isFinite(start) ||
+        !Number.isFinite(end) ||
+        !Number.isFinite(step)) {
+        throw new TypeError("Arguments must be finite numbers");
+    }
+    if (step === 0)
+        throw new Error("Step cannot be zero");
+    const isAscending = step > 0;
+    if ((isAscending && start >= end) || (!isAscending && start <= end)) {
+        return [];
+    }
+    const length = Math.max(Math.ceil((end - start) / step), 0);
+    const result = new Array(length);
+    for (let i = 0, value = start; i < length; i++, value += step) {
+        result[i] = value;
+    }
+    return result;
+}
+/**
+ * Returns the first n elements of an array.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {number} [n=1] - Number of elements to take.
+ * @returns {T[]} New array with first n elements.
+ */
+export function take(array, n = 1) {
+    if (!Array.isArray(array) || n <= 0)
+        return [];
+    return array.slice(0, n);
+}
+/**
+ * Takes elements from the array while predicate returns true.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T, index: number) => boolean} predicate - Function to test each element.
+ * @returns {T[]} New array with taken elements.
+ */
+export function takeWhile(array, predicate) {
+    if (!Array.isArray(array))
+        return [];
+    const result = [];
+    for (let i = 0; i < array.length; i++) {
+        if (!predicate(array[i], i))
+            break;
+        result.push(array[i]);
+    }
+    return result;
+}
+/**
+ * Removes all falsy values from an array.
+ * False, null, 0, "", undefined, and NaN are falsy.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @returns {NonNullable<T>[]} New array with falsy values removed.
+ */
+export function compact(array) {
+    if (!Array.isArray(array))
+        return [];
+    return array.filter(Boolean);
+}
+/**
+ * Counts array elements by a key function.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T) => string | number | symbol} keyFn - Function to generate count key.
+ * @returns {Record<string, number>} Object with counts by key.
+ */
+export function countBy(array, keyFn) {
+    if (!Array.isArray(array))
+        return {};
+    return array.reduce((acc, item) => {
+        const key = String(keyFn(item));
+        acc[key] = (acc[key] || 0) + 1;
+        return acc;
+    }, {});
+}
 //# sourceMappingURL=array.utils.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"array.utils.js","sourceRoot":"","sources":["../../../src/utils/array.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { getValueByPath } from \"./obj.utils\";\n\n/**\n * Splits an array into chunks of the specified size.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The array to split into chunks.\n * @param {number} size - The number of elements per chunk.\n * @returns {T[][]} A new array containing chunked arrays.\n * @throws {TypeError} If array is not an array.\n * @throws {Error} If chunk size is not a positive integer.\n */\nexport const chunk = <T>(array: T[], size: number): T[][] => {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected an array\");\n  if (!array.length) return [];\n  if (!Number.isInteger(size) || size <= 0)\n    throw new Error(\"Chunk size must be a positive integer\");\n  return Array.from({ length: Math.ceil(array.length / size) }, (_, i) =>\n    array.slice(i * size, i * size + size),\n  );\n};\n\n/**\n * Removes duplicate values from an array.\n * Optionally enforces uniqueness by a key function.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @param {(item: T) => unknown} [keyFn] - Optional function to determine uniqueness by key.\n * @returns {T[]} A new array with unique values.\n */\nexport function unique<T>(array: T[], keyFn?: (item: T) => unknown): T[] {\n  if (!Array.isArray(array) || array.length === 0) return [];\n  if (!keyFn) return Array.from(new Set(array));\n  const seen = new Set<unknown>();\n  return array.filter((item) => {\n    const key = keyFn(item);\n    if (seen.has(key)) return false;\n    seen.add(key);\n    return true;\n  });\n}\n\n/**\n * Deeply flattens a nested array to a single-level array.\n *\n * @template T The leaf type of array elements.\n * @param {any[]} array - The (possibly deeply nested) input array.\n * @returns {T[]} A deeply flattened array.\n */\nexport function flattenDeep<T>(array: any[]): T[] {\n  if (!Array.isArray(array)) return [];\n  return array.reduce<T[]>((acc, val) => {\n    if (Array.isArray(val)) {\n      acc.push(...flattenDeep<T>(val));\n    } else {\n      acc.push(val);\n    }\n    return acc;\n  }, []);\n}\n\n/**\n * Returns a random element from an array, or undefined if empty.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @returns {T | undefined} A randomly selected item, or undefined if array is empty or not an array.\n */\nexport function random<T>(array: T[]): T | undefined {\n  if (!Array.isArray(array) || array.length === 0) return undefined;\n  return array[Math.floor(Math.random() * array.length)];\n}\n\n/* eslint-disable no-redeclare */\n/**\n * Groups items in an array by a key or key function.\n *\n * @template T The type of array elements.\n * @overload\n * @param {T[]} array - The array to group.\n * @param {keyof T} key - Property key to group by.\n * @returns {Record<string, T[]>}\n * @overload\n * @param {T[]} array - The array to group.\n * @param {(item: T) => string | number | symbol} keyFn - Function to generate group key from item.\n * @returns {Record<K, T[]>}\n * @param {T[]} array - The array to group.\n * @param {keyof T | ((item: T) => string | number | symbol)} keyOrFn - Property key or key-generating function.\n * @returns {Record<string | number | symbol, T[]>} An object mapping group keys to item arrays.\n */\nexport function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;\nexport function groupBy<T, K extends string | number | symbol>(\n  array: T[],\n  keyFn: (item: T) => K,\n): Record<K, T[]>;\nexport function groupBy<T>(\n  array: T[],\n  keyOrFn: keyof T | ((item: T) => string | number | symbol),\n): Record<string | number | symbol, T[]> {\n  if (!Array.isArray(array) || array.length === 0) return {};\n  const keyFn =\n    typeof keyOrFn === \"function\"\n      ? keyOrFn\n      : (item: T) => item[keyOrFn as keyof T];\n  return array.reduce(\n    (acc, item) => {\n      const key = keyFn(item) as string | number | symbol;\n      if (!acc[key]) acc[key] = [];\n      acc[key].push(item);\n      return acc;\n    },\n    {} as Record<string | number | symbol, T[]>,\n  );\n}\n/* eslint-enable no-redeclare */\n\n/**\n * Shuffles an array using the Fisher-Yates algorithm.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @returns {T[]} A new shuffled array.\n * @throws {TypeError} If array is not an array.\n */\nexport function shuffle<T>(array: T[]): T[] {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected an array\");\n  const copy = array.slice();\n  for (let i = copy.length - 1; i > 0; i--) {\n    const j = Math.floor(Math.random() * (i + 1));\n    [copy[i], copy[j]] = [copy[j], copy[i]];\n  }\n  return copy;\n}\n\n/**\n * Returns an array of property values from an array of objects.\n *\n * @template T The type of array elements.\n * @template K The object property to pluck.\n * @param {T[]} array - The input array.\n * @param {K} key - The property name to pluck.\n * @returns {T[K][]} Array of property values.\n */\nexport function pluck<T, K extends keyof T>(array: T[], key: K): T[K][] {\n  if (!Array.isArray(array)) return [];\n  return array.map((item) => item[key]);\n}\n\n/**\n * Returns values in array A that are not in array B.\n *\n * @template T The type of array elements.\n * @param {T[]} a - First array.\n * @param {T[]} b - Second array.\n * @returns {T[]} Elements in A that are not in B.\n */\nexport function difference<T>(a: T[], b: T[]): T[] {\n  if (!Array.isArray(a) || !Array.isArray(b)) return [];\n  const setB = new Set(b);\n  return a.filter((item) => !setB.has(item));\n}\n\n/**\n * Returns common values between arrays A and B.\n *\n * @template T The type of array elements.\n * @param {T[]} a - First array.\n * @param {T[]} b - Second array.\n * @returns {T[]} Elements that exist in both arrays.\n */\nexport function intersect<T>(a: T[], b: T[]): T[] {\n  if (!Array.isArray(a) || !Array.isArray(b)) return [];\n  const setB = new Set(b);\n  return a.filter((item) => setB.has(item));\n}\n\n/**\n * Sorts an array of objects by a nested key using Merge Sort (O(n log n)).\n * Missing/undefined keys are sorted to the \"end\" (asc) or \"start\" (desc).\n *\n * @template T The type of array elements (objects).\n * @param {T[]} array - Array of objects to sort.\n * @param {string | ((item: T) => any)} key - Dot-notated key (e.g., \"profile.age\") or function.\n * @param {\"asc\" | \"desc\"} [direction=\"asc\"] - Sort direction: 'asc' or 'desc'.\n * @returns {T[]} A new sorted array.\n * @throws {TypeError} If array is not an array.\n */\nexport function mergeSort<T>(\n  array: T[],\n  key: string | ((item: T) => any),\n  direction: \"asc\" | \"desc\" = \"asc\",\n): T[] {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected array\");\n  if (array.length <= 1) return array.slice();\n\n  const keyFn =\n    typeof key === \"function\"\n      ? key\n      : (item: T) => getValueByPath(item as object, key);\n\n  const compare = (a: T, b: T) => {\n    const aVal = keyFn(a);\n    const bVal = keyFn(b);\n    // Sorts undefined/null last for \"asc\", first for \"desc\"\n    if (aVal === bVal) return 0;\n    if (aVal == null) return direction === \"asc\" ? 1 : -1;\n    if (bVal == null) return direction === \"asc\" ? -1 : 1;\n    return direction === \"asc\" ? (aVal < bVal ? -1 : 1) : aVal > bVal ? -1 : 1;\n  };\n\n  const merge = (left: T[], right: T[]): T[] => {\n    const result: T[] = [];\n    let i = 0,\n      j = 0;\n    while (i < left.length && j < right.length) {\n      if (compare(left[i], right[j]) <= 0) result.push(left[i++]);\n      else result.push(right[j++]);\n    }\n    return result.concat(left.slice(i)).concat(right.slice(j));\n  };\n\n  const sort = (arr: T[]): T[] => {\n    if (arr.length <= 1) return arr;\n    const mid = Math.floor(arr.length / 2);\n    const left = sort(arr.slice(0, mid));\n    const right = sort(arr.slice(mid));\n    return merge(left, right);\n  };\n  return sort(array);\n}\n"]}
+{"version":3,"file":"array.utils.js","sourceRoot":"","sources":["../../../src/utils/array.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { getValueByPath } from \"./obj.utils\";\n\n/**\n * Splits an array into chunks of the specified size.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The array to split into chunks.\n * @param {number} size - The number of elements per chunk.\n * @returns {T[][]} A new array containing chunked arrays.\n * @throws {TypeError} If array is not an array.\n * @throws {Error} If chunk size is not a positive integer.\n */\nexport function chunk<T>(array: T[], size: number): T[][] {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected an array\");\n  if (!array.length) return [];\n  if (!Number.isInteger(size) || size <= 0)\n    throw new Error(\"Chunk size must be a positive integer\");\n  return Array.from({ length: Math.ceil(array.length / size) }, (_, i) =>\n    array.slice(i * size, i * size + size),\n  );\n}\n\n/**\n * Removes duplicate values from an array.\n * Optionally enforces uniqueness by a key function.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @param {(item: T) => unknown} [keyFn] - Optional function to determine uniqueness by key.\n * @returns {T[]} A new array with unique values.\n */\nexport function unique<T>(array: T[], keyFn?: (item: T) => unknown): T[] {\n  if (!Array.isArray(array) || array.length === 0) return [];\n  if (!keyFn) return Array.from(new Set(array));\n  const seen = new Set<unknown>();\n  return array.filter((item) => {\n    const key = keyFn(item);\n    if (seen.has(key)) return false;\n    seen.add(key);\n    return true;\n  });\n}\n\n/**\n * Deeply flattens a nested array to a single-level array.\n *\n * @template T The leaf type of array elements.\n * @param {any[]} array - The (possibly deeply nested) input array.\n * @returns {T[]} A deeply flattened array.\n */\nexport function flattenDeep<T>(array: any[]): T[] {\n  if (!Array.isArray(array)) return [];\n  return array.reduce<T[]>((acc, val) => {\n    if (Array.isArray(val)) {\n      acc.push(...flattenDeep<T>(val));\n    } else {\n      acc.push(val);\n    }\n    return acc;\n  }, []);\n}\n\n/**\n * Returns a random element from an array, or undefined if empty.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @returns {T | undefined} A randomly selected item, or undefined if array is empty or not an array.\n */\nexport function random<T>(array: T[]): T | undefined {\n  if (!Array.isArray(array) || array.length === 0) return undefined;\n  return array[Math.floor(Math.random() * array.length)];\n}\n\n/* eslint-disable no-redeclare */\n/**\n * Groups items in an array by a key or key function.\n *\n * @template T The type of array elements.\n * @overload\n * @param {T[]} array - The array to group.\n * @param {keyof T} key - Property key to group by.\n * @returns {Record<string, T[]>}\n * @overload\n * @param {T[]} array - The array to group.\n * @param {(item: T) => string | number | symbol} keyFn - Function to generate group key from item.\n * @returns {Record<K, T[]>}\n * @param {T[]} array - The array to group.\n * @param {keyof T | ((item: T) => string | number | symbol)} keyOrFn - Property key or key-generating function.\n * @returns {Record<string | number | symbol, T[]>} An object mapping group keys to item arrays.\n */\nexport function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;\nexport function groupBy<T, K extends string | number | symbol>(\n  array: T[],\n  keyFn: (item: T) => K,\n): Record<K, T[]>;\nexport function groupBy<T>(\n  array: T[],\n  keyOrFn: keyof T | ((item: T) => string | number | symbol),\n): Record<string | number | symbol, T[]> {\n  if (!Array.isArray(array) || array.length === 0) return {};\n  const keyFn =\n    typeof keyOrFn === \"function\"\n      ? keyOrFn\n      : (item: T) => item[keyOrFn as keyof T];\n  return array.reduce(\n    (acc, item) => {\n      const key = keyFn(item) as string | number | symbol;\n      if (!acc[key]) acc[key] = [];\n      acc[key].push(item);\n      return acc;\n    },\n    {} as Record<string | number | symbol, T[]>,\n  );\n}\n/* eslint-enable no-redeclare */\n\n/**\n * Shuffles an array using the Fisher-Yates algorithm.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @returns {T[]} A new shuffled array.\n * @throws {TypeError} If array is not an array.\n */\nexport function shuffle<T>(array: T[]): T[] {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected an array\");\n  const copy = array.slice();\n  for (let i = copy.length - 1; i > 0; i--) {\n    const j = Math.floor(Math.random() * (i + 1));\n    [copy[i], copy[j]] = [copy[j], copy[i]];\n  }\n  return copy;\n}\n\n/**\n * Returns an array of property values from an array of objects.\n *\n * @template T The type of array elements.\n * @template K The object property to pluck.\n * @param {T[]} array - The input array.\n * @param {K} key - The property name to pluck.\n * @returns {T[K][]} Array of property values.\n */\nexport function pluck<T, K extends keyof T>(array: T[], key: K): T[K][] {\n  if (!Array.isArray(array)) return [];\n  return array.map((item) => item[key]);\n}\n\n/**\n * Returns values in array A that are not in array B.\n *\n * @template T The type of array elements.\n * @param {T[]} a - First array.\n * @param {T[]} b - Second array.\n * @returns {T[]} Elements in A that are not in B.\n */\nexport function difference<T>(a: T[], b: T[]): T[] {\n  if (!Array.isArray(a) || !Array.isArray(b)) return [];\n  const setB = new Set(b);\n  return a.filter((item) => !setB.has(item));\n}\n\n/**\n * Returns common values between arrays A and B.\n *\n * @template T The type of array elements.\n * @param {T[]} a - First array.\n * @param {T[]} b - Second array.\n * @returns {T[]} Elements that exist in both arrays.\n */\nexport function intersect<T>(a: T[], b: T[]): T[] {\n  if (!Array.isArray(a) || !Array.isArray(b)) return [];\n  const setB = new Set(b);\n  return a.filter((item) => setB.has(item));\n}\n\n/**\n * Sorts an array of objects by a nested key using Merge Sort (O(n log n)).\n * Missing/undefined keys are sorted to the \"end\" (asc) or \"start\" (desc).\n *\n * @template T The type of array elements (objects).\n * @param {T[]} array - Array of objects to sort.\n * @param {string | ((item: T) => any)} key - Dot-notated key (e.g., \"profile.age\") or function.\n * @param {\"asc\" | \"desc\"} [direction=\"asc\"] - Sort direction: 'asc' or 'desc'.\n * @returns {T[]} A new sorted array.\n * @throws {TypeError} If array is not an array.\n */\nexport function mergeSort<T>(\n  array: T[],\n  key: string | ((item: T) => any),\n  direction: \"asc\" | \"desc\" = \"asc\",\n): T[] {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected array\");\n  if (array.length <= 1) return array.slice();\n\n  const keyFn =\n    typeof key === \"function\"\n      ? key\n      : (item: T) => getValueByPath(item as object, key);\n\n  const compare = (a: T, b: T) => {\n    const aVal = keyFn(a);\n    const bVal = keyFn(b);\n    // Sorts undefined/null last for \"asc\", first for \"desc\"\n    if (aVal === bVal) return 0;\n    if (aVal == null) return direction === \"asc\" ? 1 : -1;\n    if (bVal == null) return direction === \"asc\" ? -1 : 1;\n    return direction === \"asc\" ? (aVal < bVal ? -1 : 1) : aVal > bVal ? -1 : 1;\n  };\n\n  const merge = (left: T[], right: T[]): T[] => {\n    const result: T[] = [];\n    let i = 0,\n      j = 0;\n    while (i < left.length && j < right.length) {\n      if (compare(left[i], right[j]) <= 0) result.push(left[i++]);\n      else result.push(right[j++]);\n    }\n    return result.concat(left.slice(i)).concat(right.slice(j));\n  };\n\n  const sort = (arr: T[]): T[] => {\n    if (arr.length <= 1) return arr;\n    const mid = Math.floor(arr.length / 2);\n    const left = sort(arr.slice(0, mid));\n    const right = sort(arr.slice(mid));\n    return merge(left, right);\n  };\n  return sort(array);\n}\n\n/**\n * Combines multiple arrays into a single array of grouped elements.\n * Output array length equals the length of the shortest input array.\n *\n * @example zip([1, 2], ['a', 'b']) => [[1, 'a'], [2, 'b']]\n * @param {...Array<T>[]} arrays - Two or more arrays to zip together.\n * @returns {Array<T[]>} Array of grouped elements.\n */\nexport function zip<T>(...arrays: T[][]): T[][] {\n  if (arrays.length === 0) return [];\n  if (arrays.some((arr) => !Array.isArray(arr))) {\n    throw new TypeError(\"All arguments must be arrays\");\n  }\n\n  const minLength = Math.min(...arrays.map((arr) => arr.length));\n  const result: T[][] = [];\n\n  for (let i = 0; i < minLength; i++) {\n    result.push(arrays.map((arr) => arr[i]));\n  }\n\n  return result;\n}\n\n/**\n * Splits an array into two arrays based on a predicate function.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @param {(item: T, index: number, array: T[]) => boolean} predicate - Function to test each element.\n * @returns {[T[], T[]]} A tuple of two arrays: [matched, unmatched].\n */\nexport function partition<T>(\n  array: T[],\n  predicate: (item: T, index: number, array: T[]) => boolean,\n): [T[], T[]] {\n  if (!Array.isArray(array)) return [[], []];\n\n  return array.reduce(\n    ([pass, fail], item, index) => {\n      return predicate(item, index, array)\n        ? [[...pass, item], fail]\n        : [pass, [...fail, item]];\n    },\n    [[] as T[], [] as T[]],\n  );\n}\n\n/**\n * Generates an array of numbers within a specified range.\n *\n * @param {number} start - Start of range (inclusive).\n * @param {number} end - End of range (exclusive).\n * @param {number} [step=1] - Step between numbers.\n * @returns {number[]} Array of numbers in range.\n */\nexport function range(start: number, end: number, step: number = 1): number[] {\n  if (\n    !Number.isFinite(start) ||\n    !Number.isFinite(end) ||\n    !Number.isFinite(step)\n  ) {\n    throw new TypeError(\"Arguments must be finite numbers\");\n  }\n  if (step === 0) throw new Error(\"Step cannot be zero\");\n\n  const isAscending = step > 0;\n  if ((isAscending && start >= end) || (!isAscending && start <= end)) {\n    return [];\n  }\n\n  const length = Math.max(Math.ceil((end - start) / step), 0);\n  const result = new Array(length);\n\n  for (let i = 0, value = start; i < length; i++, value += step) {\n    result[i] = value;\n  }\n\n  return result;\n}\n\n/**\n * Returns the first n elements of an array.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @param {number} [n=1] - Number of elements to take.\n * @returns {T[]} New array with first n elements.\n */\nexport function take<T>(array: T[], n: number = 1): T[] {\n  if (!Array.isArray(array) || n <= 0) return [];\n  return array.slice(0, n);\n}\n\n/**\n * Takes elements from the array while predicate returns true.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @param {(item: T, index: number) => boolean} predicate - Function to test each element.\n * @returns {T[]} New array with taken elements.\n */\nexport function takeWhile<T>(\n  array: T[],\n  predicate: (item: T, index: number) => boolean,\n): T[] {\n  if (!Array.isArray(array)) return [];\n\n  const result: T[] = [];\n  for (let i = 0; i < array.length; i++) {\n    if (!predicate(array[i], i)) break;\n    result.push(array[i]);\n  }\n\n  return result;\n}\n\n/**\n * Removes all falsy values from an array.\n * False, null, 0, \"\", undefined, and NaN are falsy.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @returns {NonNullable<T>[]} New array with falsy values removed.\n */\nexport function compact<T>(array: T[]): NonNullable<T>[] {\n  if (!Array.isArray(array)) return [];\n  return array.filter(Boolean) as NonNullable<T>[];\n}\n\n/**\n * Counts array elements by a key function.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @param {(item: T) => string | number | symbol} keyFn - Function to generate count key.\n * @returns {Record<string, number>} Object with counts by key.\n */\nexport function countBy<T>(\n  array: T[],\n  keyFn: (item: T) => string | number | symbol,\n): Record<string, number> {\n  if (!Array.isArray(array)) return {};\n\n  return array.reduce(\n    (acc, item) => {\n      const key = String(keyFn(item));\n      acc[key] = (acc[key] || 0) + 1;\n      return acc;\n    },\n    {} as Record<string, number>,\n  );\n}\n"]}

package/build/esnext/utils/async.utils.d.ts

@@ -4,7 +4,7 @@
  * @param {number} ms - The number of milliseconds to sleep.
  * @returns {Promise<void>} A Promise that resolves after the given time.
  */
-export declare const sleep: (ms: number) => Promise<void>;
+export declare function sleep(ms: number): Promise<void>;
 /**
  * Creates a debounced version of a function that delays its execution.
  * Provides `.cancel()` and `.flush()` methods.
@@ -116,4 +116,63 @@ export declare function createTaskQueue(limit: number): TaskQueue;
  * @returns {Promise<T[]>} Array of resolved values.
  */
 export declare function runInSeries<T>(tasks: (() => Promise<T>)[]): Promise<T[]>;
+/**
+ * Memoizes an async function, caching results for repeated calls with identical arguments.
+ * Optional TTL (time-to-live) for cached entries.
+ *
+ * @template T Function return type
+ * @template Args Function arguments types
+ * @param {(...args: Args) => Promise<T>} fn - The async function to memoize
+ * @param {object} [options] - Memoization options
+ * @param {number} [options.ttl] - Cache TTL in milliseconds (optional)
+ * @param {(args: Args) => string} [options.keyFn] - Custom key generator function
+ * @returns {(...args: Args) => Promise<T>} Memoized function
+ */
+export declare function memoizeAsync<T, Args extends any[]>(fn: (...args: Args) => Promise<T>, options?: {
+    ttl?: number;
+    keyFn?: (args: Args) => string;
+}): (...args: Args) => Promise<T>;
+/**
+ * Creates an abortable version of a promise that can be cancelled using an AbortController.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The promise to make abortable
+ * @param {AbortSignal} signal - AbortSignal from AbortController
+ * @param {any} [abortValue] - Value to use when rejecting on abort
+ * @returns {Promise<T>} Promise that rejects if the signal is aborted
+ */
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal, abortValue?: any): Promise<T>;
+/**
+ * Creates a promise with external resolve/reject functions.
+ * Useful for creating promises that can be resolved or rejected from outside.
+ *
+ * @template T
+ * @returns {[Promise<T>, (value: T | PromiseLike<T>) => void, (reason?: any) => void]}
+ *   Tuple of [promise, resolve, reject]
+ */
+export declare function createDeferred<T>(): [
+    Promise<T>,
+    (value: T | PromiseLike<T>) => void,
+    (reason?: any) => void
+];
+/**
+ * Chains a series of async functions, passing the result of each to the next.
+ * Similar to function composition but for async functions.
+ *
+ * @template T
+ * @param {Array<(input: any) => Promise<any>>} fns - Array of async functions to compose
+ * @returns {(input: any) => Promise<T>} Composed function
+ */
+export declare function waterfall<T>(fns: Array<(input: any) => Promise<any>>): (initialValue: any) => Promise<T>;
+/**
+ * Creates a rate limiter that ensures functions aren't called more than
+ * a specified number of times per interval.
+ *
+ * @template T
+ * @param {(...args: any[]) => Promise<T>} fn - Function to rate limit
+ * @param {number} maxCalls - Maximum calls allowed per interval
+ * @param {number} interval - Time interval in milliseconds
+ * @returns {(...args: any[]) => Promise<T>} Rate limited function
+ */
+export declare function rateLimit<T>(fn: (...args: any[]) => Promise<T>, maxCalls: number, interval: number): (...args: any[]) => Promise<T>;
 //# sourceMappingURL=async.utils.d.ts.map