@rzl-zone/utils-js 3.13.1 → 3.14.0-beta.0

package/dist/generators/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["isNonEmptyArray","isInteger","getPreciseType","safeStableStringify","isNumber","isPlainObject","isInteger","getPreciseType","safeStableStringify","isPlainObject","isInteger","getPreciseType","safeStableStringify","isNaN","isPlainObject","getPreciseType","safeStableStringify","isNonEmptyString","isBoolean"],"sources":["../../src/generators/random/array/getRandomItem.ts","../../src/generators/random/integer/randomInt.ts","../../src/generators/random/integer/randomIntByLength.ts","../../src/generators/random/string/randomStr.ts","../../src/generators/random/uuid/randomUUID.ts"],"sourcesContent":["import type {\n  Extends,\n  FixNeverArrayRecursive,\n  IfNonEmptyArray,\n  NullToUndefined\n} from \"@rzl-zone/ts-types-plus\";\n\nimport { isNonEmptyArray } from \"@/predicates/is/isNonEmptyArray\";\n\n/** ---------------------------------\n * * ***Utility: `getRandomItem`.***\n * ---------------------------------\n * **Function to get a random element from a given array.**\n * @template T - The type of the input array.\n * @param {*} array - The input array, can be `null`, `undefined`, or an empty array.\n * @returns\n * - If `array` is a non-empty tuple, returns one of its elements.\n * - If `array` is empty, `null`, or `undefined`, returns `undefined`.\n * @example\n * getRandomItem([]);\n * // ➔ undefined\n * getRandomItem(null);\n * // ➔ undefined\n * getRandomItem(undefined);\n * // ➔ undefined\n * getRandomItem([1, 2, 3, 4]);\n * // ➔ number\n * getRandomItem([\"apple\", \"banana\", \"cherry\"]);\n * // ➔ string\n * getRandomItem([\"apple\", 123, true]);\n * // ➔ string | number | boolean\n * getRandomItem([\"apple\", 123, true, null]);\n * // ➔ string | number | boolean | undefined\n * getRandomItem([\"apple\", 123, true, undefined]);\n * // ➔ string | number | boolean | undefined\n *\n * // Tuple example:\n * const tuple = [1, \"two\", true] as const;\n * getRandomItem(tuple); // 1 | \"two\" | true\n */\nexport function getRandomItem(array: undefined): undefined;\nexport function getRandomItem(array: []): undefined;\nexport function getRandomItem<T extends readonly unknown[]>(\n  array: T\n): T extends never[][]\n  ? undefined\n  : number extends T[\"length\"]\n    ? NullToUndefined<FixNeverArrayRecursive<T[number]>>\n    : IfNonEmptyArray<\n        T,\n        NullToUndefined<FixNeverArrayRecursive<T[number]>>,\n        undefined\n      >;\nexport function getRandomItem<T extends readonly unknown[] | undefined | null>(\n  array: T\n): T extends readonly unknown[]\n  ? NullToUndefined<FixNeverArrayRecursive<T[number]>> | undefined\n  : undefined;\nexport function getRandomItem<T>(array: T): unknown extends T\n  ? unknown\n  : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    Extends<any[] | readonly any[], T> extends true\n    ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n    : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      Extends<any[], T> extends true\n      ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n      : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        Extends<readonly any[], T> extends true\n        ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n        : undefined;\nexport function getRandomItem(array: unknown): unknown {\n  if (!isNonEmptyArray(array)) return undefined;\n\n  const randomIndex = Math.floor(Math.random() * (array.length || 0));\n  return array[randomIndex];\n}\n","import { isNumber } from \"@/predicates/is/isNumber\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** -----------------------------------------------------------------------\n * * ***Utility: `randomInt`.***\n * ------------------------------------------------------------------------\n * **Generates a random integer within a specified range (inclusive).**\n * - **Generates a random integer between `min` and `max` (inclusive), with safety constraints:**\n *    - `min` will be forced to be at least `1`.\n *    - `max` will be capped at `Number.MAX_SAFE_INTEGER`.\n * @param {number} min - The minimum value (inclusive), must be an integer.\n * @param {number} max - The maximum value (inclusive), must be an integer.\n * @returns {number} A random integer N where `min ≤ N ≤ max`.\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `min` or `max` is not an integer, or value is `Number.MIN_VALUE`.\n * - `min` is greater than `max`.\n * @example\n * randomInt(1, 10);   // ➔ returns 1 up-to 10 (random)\n * randomInt(50, 100); // ➔ returns 50 up-to 100 (random)\n * randomInt(5, 5);    // ➔ always returns 5 (exact)\n * randomInt(-5, 3);   // ➔ always returns ≥ 1, since min is adjusted (exact)\n * randomInt(1, Number.MAX_SAFE_INTEGER + 10000);\n * // ➔ still safely capped at MAX_SAFE_INTEGER\n * randomInt(Number.MIN_VALUE, 3);\n * // ➔ Error, min or max cant be as `Number.MIN_VALUE` value.\n */\nexport const randomInt = (min: number, max: number): number => {\n  if (!isInteger(min) || !isInteger(max)) {\n    throw new TypeError(\n      `First parameter (\\`min\\`) and second parameter (\\`max\\`) must be of type \\`integer-number\\`${minValueNote(\n        min,\n        max\n      )}value, but received: ['min': \\`${getPreciseType(\n        min\n      )}\\` - (with value: \\`${safeStableStringify(min, {\n        keepUndefined: true\n      })})\\`, 'max': \\`${getPreciseType(max)}\\` - (with value: \\`${safeStableStringify(\n        max,\n        {\n          keepUndefined: true\n        }\n      )}\\`)].`\n    );\n  }\n  if (min > max) {\n    throw new RangeError(\n      `First parameter (\\`min\\`) must be less than or equal to second parameter (\\`max\\`), but received: ['min': ${formatValue(\n        min\n      )} - (with value: \\`${safeStableStringify(min, {\n        keepUndefined: true\n      })})\\`, 'max': ${formatValue(max)} - (with value: \\`${safeStableStringify(\n        max,\n        {\n          keepUndefined: true\n        }\n      )})\\`].`\n    );\n  }\n\n  // Ensure `min` is at least 1\n  min = Math.max(1, min);\n\n  // Ensure `max` does not exceed Number.MAX_SAFE_INTEGER\n  max = Math.min(Number.MAX_SAFE_INTEGER, max);\n\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n};\n\nconst formatValue = (value: unknown): string => {\n  return isNumber(value, { includeNaN: true })\n    ? value === Number.MIN_VALUE\n      ? \"`Number.MIN_VALUE`\"\n      : `${value}`\n    : `\\`${getPreciseType(value)}\\``;\n};\n\nconst minValueNote = (...values: unknown[]) => {\n  return values.some(\n    (v) => isNumber(v, { includeNaN: true }) && v === Number.MIN_VALUE\n  )\n    ? \" and can't be `Number.MIN_VALUE` \"\n    : \" \";\n};\n","import { randomInt } from \"./randomInt\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\ntype OptionsRandomIntByLength = {\n  /** * Minimum length of the random number, the `allowed minimal value` `integer` is `1` `and not bigger than value of` `maxLength`, defaultValue: `1`.\n   *\n   * @default 1\n   */\n  minLength?: number;\n  /** * Maximum length of the random number, the `allowed maximal value` `integer` is `16`, defaultValue: `16`.\n   *\n   * @default 16\n   */\n  maxLength?: number;\n  /** * If true, prevents the result from being zero, defaultValue: `false`.\n   *\n   * @default false\n   */\n  avoidZero?: boolean;\n};\n\n/** ----------------------------------------------------------------------------\n * * ***Utility: `randomIntByLength`.***\n * -----------------------------------------------------------------------------\n * **Generates a random integer within a specified range of digit lengths.**\n * @description\n * This function allows generating random integers that strictly conform to a specified minimum and\n * maximum digit length, it is useful for scenarios such as generating realistic-looking IDs, codes,\n * or random test data.\n * - **The function ensures:**\n *    - `minLength` is at least 1 and not greater than `maxLength`.\n *    - `maxLength` is no more than 16 (due to JavaScript's `Number.MAX_SAFE_INTEGER`).\n *    - If `avoidZero` is `true`, ensures that `0` is never returned.\n * @param {OptionsRandomIntByLength} [options] - Configuration options.\n * @param {OptionsRandomIntByLength[\"minLength\"]} [options.minLength=1] - Minimum number of digits (must be ≥ `1` and ≤ `maxLength`).\n * @param {OptionsRandomIntByLength[\"maxLength\"]} [options.maxLength=16] - Maximum number of digits (must be ≤ `16`).\n * @param {OptionsRandomIntByLength[\"avoidZero\"]} [options.avoidZero=false] - If true, will ensure the result is never zero.\n * @returns {number} A randomly generated integer within the specified constraints.\n * @throws **{@link TypeError | `TypeError`}** if parameters are invalid, such as:\n * - `minLength` < `1`\n * - `maxLength` > `16`\n * - `minLength` > `maxLength`\n * - non-integer values for `minLength` or `maxLength`\n * @example\n * randomIntByLength({ minLength: 3, maxLength: 5 });\n * // ➔ `4829` (random), `192` (random) or `71492` (random).\n * randomIntByLength({ minLength: 4, maxLength: 4 });\n * // ➔ `5930` (exact 4 digits)\n * randomIntByLength({ avoidZero: true });\n * // ➔ never 0\n */\nexport const randomIntByLength = (\n  options?: OptionsRandomIntByLength\n): number => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) {\n    options = {};\n  }\n\n  const { minLength = 1, maxLength = 16, avoidZero = false } = options;\n\n  assertIsBoolean(avoidZero, {\n    message({ currentType, validType }) {\n      return `Parameters \\`avoidZero\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`;\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n        minLength\n      )}\\` - (with value: ${safeStableStringify(minLength, {\n        keepUndefined: true\n      })}), 'maxLength': \\`${getPreciseType(\n        maxLength\n      )}\\` - (with value: ${safeStableStringify(maxLength, {\n        keepUndefined: true\n      })})].`\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 16 || minLength > maxLength) {\n    throw new RangeError(\n      `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 16, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n    );\n  }\n\n  // Generate a random length between minLength and maxLength\n  const randomLength =\n    minLength === maxLength ? minLength : randomInt(minLength, maxLength);\n\n  // Define min and max value based on the selected length\n  const minValue = 10 ** (randomLength - 1); // Example: minLength=3 ➔ minValue=100\n  const maxValue = 10 ** randomLength - 1; // Example: maxLength=4 ➔ maxValue=9999\n\n  // Generate a random number within the valid range\n  let result = randomInt(minValue, maxValue);\n\n  // Ensure the number is not zero if `avoidZero` is true\n  if (avoidZero && result === 0) {\n    result = minValue; // Assign the smallest valid number instead of looping\n  }\n\n  return result;\n};\n","import type { OptionsRandomStr } from \"./_private/randomSTR.types\";\n\nimport { randomInt } from \"../integer/randomInt\";\n\nimport { isNaN } from \"@/predicates/is/isNaN\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\n\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** ---------------------------------------------------------------------------------\n * * ***Utility: `randomStr`.***\n * ---------------------------------------------------------------------------------\n * **Generates a random alphanumeric string or number with a specified length range.**\n * @description\n * This function allows you to generate random strings or numbers with fully\n * customizable options, such as length range, character sets, inclusion of\n * additional characters, and whether to avoid whitespace.\n * @param {OptionsRandomStr} [options] - Configuration options for generating the string.\n * @param {OptionsRandomStr[\"minLength\"]} [options.minLength=40] - Minimum length of the generated string (must be `≥` `1`).\n * @param {OptionsRandomStr[\"maxLength\"]} [options.maxLength=40] - Maximum length of the generated string (must be `≤` `5000`).\n * @param {OptionsRandomStr[\"type\"]} [options.type=\"string\"] - Whether to generate a general alphanumeric string or purely numeric string.\n * @param {OptionsRandomStr[\"avoidWhiteSpace\"]} [options.avoidWhiteSpace=true] - If true, removes all whitespace, tabs, and newlines from the character set before generating.\n * @param {OptionsRandomStr[\"replaceGenStr\"]} [options.replaceGenStr] - A custom character set to use when `type` is `\"string\"`.\n * @param {OptionsRandomStr[\"replaceGenInt\"]} [options.replaceGenInt] - A custom character set to use when `type` is `\"number\"`.\n * @param {OptionsRandomStr[\"addChar\"]} [options.addChar] - Additional characters to always include in the character set.\n * @returns {string} The randomly generated string or numeric string of the desired length.\n * @throws **{@link TypeError | `TypeError`}** if provided options are invalid (such as minLength > maxLength, invalid type, or empty character set).\n * @example\n * randomStr();\n * // ➔ Generates a 40-character random alphanumeric string\n * randomStr({ minLength: 10, maxLength: 20 });\n * // ➔ Generates a string between 10 and 20 characters\n * randomStr({ type: \"number\", minLength: 5, maxLength: 5 });\n * // ➔ \"48302\"\n * randomStr({ replaceGenStr: \"ABC \", avoidWhiteSpace: false });\n * // ➔ String using A, B, C and space\n * randomStr({ addChar: \"!@#\", minLength: 15, maxLength: 15 });\n * // ➔ Guaranteed to include !@# in the set\n */\nexport const randomStr = (options?: OptionsRandomStr): string => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) {\n    options = {};\n  }\n\n  const {\n    minLength = 40,\n    maxLength = 40,\n    type = \"string\",\n    avoidWhiteSpace = true\n  } = options;\n\n  // Validate `avoidWhiteSpace`\n  assertIsBoolean(avoidWhiteSpace, {\n    message({ currentType, validType }) {\n      return `Parameters \\`avoidWhiteSpace\\` property of the \\`options\\` (first-parameter) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`;\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n        minLength\n      )}\\` - (with value: ${safeStableStringify(minLength, {\n        keepUndefined: true\n      })}), 'maxLength': \\`${getPreciseType(\n        maxLength\n      )}\\` - (with value: ${safeStableStringify(maxLength, {\n        keepUndefined: true\n      })})].`\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 5000 || minLength > maxLength) {\n    throw new RangeError(\n      `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 5000, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n    );\n  }\n\n  // Validate `type` value props (is not typeof)\n  if (type !== \"string\" && type !== \"number\") {\n    throw new TypeError(\n      `Parameter \\`type\\` must be of type \\`string\\` with value one of \"string\" | \"number\", but received: \\`${getPreciseType(\n        type\n      )}\\`, with value: ${safeStableStringify(type, {\n        keepUndefined: true\n      })}.`\n    );\n  }\n\n  // Generate a random length within the range\n  const length = randomInt(minLength, maxLength);\n\n  // Function to clean characters based on `avoidWhiteSpace`\n  const cleanCharacters = (charSet: string) => {\n    return avoidWhiteSpace ? charSet.replace(/\\s|\\n|\\t/g, \"\") : charSet;\n  };\n\n  // Define character sets\n  const defaultNumberSet = \"0123456789\";\n  const defaultStringSet =\n    \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n\n  const baseCharSet =\n    type === \"number\"\n      ? ((!isNaN(Number(options.replaceGenInt))\n          ? options.replaceGenInt\n          : undefined) ?? defaultNumberSet)\n      : ((options.replaceGenStr ? options.replaceGenStr : undefined) ??\n        defaultStringSet);\n\n  // Get the final character set\n  const characterSet = cleanCharacters(baseCharSet) + (options.addChar || \"\");\n\n  // Ensure characterSet is not empty\n  if (!characterSet.length) {\n    const errCharSet = () => {\n      if (type === \"number\") {\n        if (avoidWhiteSpace) {\n          return \"If `avoidWhiteSpace` is true, and `replaceGenInt` cant be empty-string value, ensure `replaceGenInt` has valid characters and non-nan string number.\";\n        }\n        return \"Ensure `replaceGenInt` has valid characters and not a NaN number string while convert to number.\";\n      }\n      return \"Ensure `replaceGenStr` has valid characters and non empty string.\";\n    };\n\n    throw new Error(`Character set is empty. ${errCharSet()}`);\n  }\n\n  // Generate random string\n  let result = \"\";\n  for (let i = 0; i < length; i++) {\n    result += characterSet.charAt(\n      Math.floor(Math.random() * characterSet.length)\n    );\n  }\n\n  return result;\n};\n","import { isBoolean } from \"@/predicates/is/isBoolean\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/**\n * Configuration options for `randomUUID()`.\n */\ntype OptionsRandomUUID = {\n  /**\n   * Specifies which UUID version to generate.\n   *\n   * - `\"v4\"` — Fully random UUID (RFC 4122). No timestamp, no ordering guarantees.\n   * - `\"v7\"` — Time-ordered UUID (RFC 9562). Uses Unix timestamp + randomness.\n   *\n   * @default \"v4\"\n   *\n   * @example\n   * // Random v4 UUID\n   * randomUUID({ version: \"v4\" }); // ➔ \"3ec0de5a-b8a9-4ffb-a62a-fcc76851e9c2\"\n   *\n   * @example\n   * // Time-ordered v7 UUID\n   * randomUUID({ version: \"v7\" }); // ➔ \"0199f3f6-3c5e-744b-affa-46b2cfd496f8\"\n   */\n  version?: \"v4\" | \"v7\";\n\n  /**\n   * Enables monotonic sequencing for UUID v7.\n   *\n   * - Guarantees that multiple UUIDs generated within the same millisecond\n   *   are strictly non-decreasing (lexicographically and timestamp-wise).\n   * - Only valid when `version === \"v7\"`. Using with `v4` will throw a `TypeError`.\n   * - Useful for database inserts, logs, or any system where order matters.\n   *\n   * @default false\n   *\n   * @example\n   * // Monotonic v7 UUIDs\n   * const a = randomUUID({ version: \"v7\", monotonic: true });\n   * const b = randomUUID({ version: \"v7\", monotonic: true });\n   * console.log(a < b); // true, guaranteed\n   */\n  monotonic?: boolean;\n};\n\n/** -----------------------------------------------------------------------\n * * ***Utility: `randomUUID`.***\n * ------------------------------------------------------------------------\n * **Generates a UUID string according to the specified version and options.**\n *\n * - **Supported versions**:\n *    - **`\"v4\"` (default)** ➔ Fully random UUID, RFC 4122 compliant.\n *        - Uses `crypto.randomUUID()` if available.\n *        - Falls back to `crypto.getRandomValues()` or `Math.random()`\n *          if needed.\n *    - **`\"v7\"`** ➔ Time-ordered UUID, RFC 9562 compliant.\n *        - Timestamp (Unix ms, 48 bits) + 80 bits randomness.\n *        - Good for database indexing / sorting.\n *    - **`\"v7\"` + `monotonic: true`** ➔ Ensures strictly non-decreasing UUIDs\n *      for multiple calls in the same millisecond (per-process).\n *\n * - **Behavior / Safety Notes**:\n *    - **v4**: Fully random; probability of duplicates is astronomically low.\n *    - **v7**: Time-ordered; collisions extremely unlikely unless same ms + random repeat.\n *    - **Monotonic v7**: Guaranteed ordering per-process if multiple UUIDs are generated\n *      in the same millisecond.\n *    - **All versions**: Fallback safely if `crypto` APIs are unavailable.\n *\n * @param {object} [options] - Optional settings object.\n * @param {\"v4\" | \"v7\"} [options.version=\"v4\"] - UUID version to generate.\n * @param {boolean} [options.monotonic=false] - For v7 only: generate monotonic UUIDs\n *                                              to maintain strict lexicographic order\n *                                              when generating multiple UUIDs within the same ms.\n *\n * @returns {string} A 36-character UUID string compliant with the selected version.\n *\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `options` is not a plain object.\n * - `options.version` is provided but not a string.\n * - `options.monotonic` is provided but not a boolean.\n * - `monotonic: true` is used with `version` other than `\"v7\"`.\n * @throws **{@link RangeError | `RangeError`}** if `options.version` is provided but not `\"v4\"` or `\"v7\"`.\n *\n * @example\n * // Default (v4)\n * const id = randomUUID();\n * // ➔ \"3b12f1df-5232-4804-897e-917bf397618a\"\n *\n * @example\n * // Explicit v4\n * const id4 = randomUUID({ version: \"v4\" });\n *\n * @example\n * // Time-ordered v7\n * const id7 = randomUUID({ version: \"v7\" });\n * // ➔ \"018f48d2-84c1-7ccd-b5a3-2f9463b3a889\"\n *\n * @example\n * // Monotonic v7\n * const a = randomUUID({ version: \"v7\", monotonic: true });\n * const b = randomUUID({ version: \"v7\", monotonic: true });\n * // a < b lexicographically (guaranteed)\n *\n * @example\n * // Throws TypeError\n * randomUUID(\"v4\" as any); // options must be object\n * randomUUID({ version: 123 as any }); // version must be string\n * randomUUID({ version: \"v4\", monotonic: true } as any); // monotonic only for v7\n *\n * @example\n * // Throws RangeError\n * randomUUID({ version: \"v1\" as any }); // unsupported version\n */\nexport function randomUUID(options: OptionsRandomUUID = {}): string {\n  // Validate options is a plain object if provided\n  if (!isPlainObject(options)) {\n    throw new TypeError(\n      `First parameter (\\`options\\`) must be a plain object with optional properties \\`version\\` and \\`monotonic\\`, but received: \\`${getPreciseType(\n        options\n      )}\\` - (with value: \\`${safeStableStringify(options, { keepUndefined: true })}\\`).`\n    );\n  }\n\n  const { version = \"v4\", monotonic = false } = options;\n\n  // Validate version type\n  if (!isNonEmptyString(version)) {\n    throw new TypeError(\n      `Parameter \\`version\\` property of the \\`options\\` (first parameter) must be a \\`string\\` of either \"v4\" or \"v7\", but received type: \\`${getPreciseType(\n        version\n      )}\\` - (with value: \\`${safeStableStringify(version, { keepUndefined: true })}\\`).`\n    );\n  }\n\n  if (version !== \"v4\" && version !== \"v7\") {\n    throw new RangeError(\n      `Unsupported UUID version. Allowed values are \"v4\" or \"v7\". (received: \\`${safeStableStringify(\n        version,\n        {\n          keepUndefined: true\n        }\n      )}\\`).`\n    );\n  }\n\n  // Validate monotonic type\n  if (!isBoolean(monotonic)) {\n    throw new TypeError(\n      `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) must be a \\`boolean\\` when provided, but received type: \\`${getPreciseType(\n        monotonic\n      )}\\` - (with value: \\`${safeStableStringify(monotonic, {\n        keepUndefined: true\n      })}\\`).`\n    );\n  }\n\n  // monotonic only allowed with v7\n  if (monotonic && version !== \"v7\") {\n    throw new TypeError(\n      `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) is only supported for version \"v7\". Received: version=${safeStableStringify(\n        version,\n        { keepUndefined: true }\n      )}.`\n    );\n  }\n\n  if (version === \"v4\") {\n    return generateUUIDv4();\n  }\n\n  // version === \"v7\"\n  return generateUUIDv7({ monotonic });\n}\n\n//todo: Helpers & Implementations\n\nfunction hasCryptoGetRandomValues(): boolean {\n  return (\n    typeof crypto !== \"undefined\" &&\n    typeof crypto.getRandomValues === \"function\"\n  );\n}\n\nfunction hasCryptoRandomUUID(): boolean {\n  return (\n    typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\"\n  );\n}\n\nfunction getRandomBytes(len: number): Uint8Array {\n  if (hasCryptoGetRandomValues()) {\n    return crypto.getRandomValues(new Uint8Array(len));\n  }\n  // Fallback: not cryptographically secure, but avoids crash\n  const arr = new Uint8Array(len);\n  for (let i = 0; i < len; i++) {\n    arr[i] = Math.floor(Math.random() * 256);\n  }\n  return arr;\n}\n\nconst byteToHex: string[] = (() => {\n  const arr: string[] = [];\n  for (let i = 0; i < 256; ++i) {\n    arr.push((i + 0x100).toString(16).substring(1));\n  }\n  return arr;\n})();\n\nfunction generateUUIDv4(): string {\n  // Prefer native if available\n  if (hasCryptoRandomUUID()) {\n    return crypto.randomUUID();\n  }\n\n  // If crypto.getRandomValues available, use it for 16 bytes\n  if (hasCryptoGetRandomValues()) {\n    const rnd = crypto.getRandomValues(new Uint8Array(16));\n\n    if (\n      !rnd[0] ||\n      !rnd[1] ||\n      !rnd[2] ||\n      !rnd[3] ||\n      !rnd[4] ||\n      !rnd[5] ||\n      !rnd[6] ||\n      !rnd[7] ||\n      !rnd[8] ||\n      !rnd[9] ||\n      !rnd[10] ||\n      !rnd[11] ||\n      !rnd[12] ||\n      !rnd[13] ||\n      !rnd[14] ||\n      !rnd[15]\n    ) {\n      return \"\";\n    }\n\n    const byteToHex0 = byteToHex[rnd[0]];\n    const byteToHex1 = byteToHex[rnd[1]];\n\n    if (!byteToHex0 || !byteToHex1) return \"\";\n\n    // Per RFC 4122: set version and variant\n    rnd[6] = (rnd[6]! & 0x0f) | 0x40; // version 4\n    rnd[8] = (rnd[8]! & 0x3f) | 0x80; // variant 10xx\n\n    return (\n      byteToHex0 +\n      byteToHex1 +\n      byteToHex[rnd[2]] +\n      byteToHex[rnd[3]] +\n      \"-\" +\n      byteToHex[rnd[4]] +\n      byteToHex[rnd[5]] +\n      \"-\" +\n      byteToHex[rnd[6]] +\n      byteToHex[rnd[7]] +\n      \"-\" +\n      byteToHex[rnd[8]] +\n      byteToHex[rnd[9]] +\n      \"-\" +\n      byteToHex[rnd[10]] +\n      byteToHex[rnd[11]] +\n      byteToHex[rnd[12]] +\n      byteToHex[rnd[13]] +\n      byteToHex[rnd[14]] +\n      byteToHex[rnd[15]]\n    );\n  }\n\n  // Last-resort fallback using Math.random (not crypto-secure)\n  return \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, (c) => {\n    const r = (Math.random() * 16) | 0;\n    const v = c === \"x\" ? r : (r & 0x3) | 0x8;\n    return v.toString(16);\n  });\n}\n\n/* ---------------------------\n   Monotonic state (singleton per-process)\n   --------------------------- */\n\n/**\n * Internal monotonic state:\n * - lastTimestampMs: last generated timestamp (ms)\n * - lastRand: last random 10-byte block used for v7 (used to increment on same ms)\n */\nconst monotonicState: {\n  lastTimestampMs: number;\n  lastRand: Uint8Array | null;\n} = {\n  lastTimestampMs: -1,\n  lastRand: null\n};\n\nfunction incrementUint8ArrayBigEndian(arr: Uint8Array): boolean {\n  // Increment arr in big-endian order. Return true if overflowed back to zero.\n  for (let i = arr.length - 1; i >= 0; i--) {\n    if (arr[i] === 0xff) {\n      arr[i] = 0x00;\n      continue;\n    }\n\n    arr[i] = (arr[i]! + 1) & 0xff;\n\n    return false; // no overflow\n  }\n  // overflowed (wrapped to zero)\n  return true;\n}\n\nfunction generateUUIDv7({\n  monotonic = false\n}: { monotonic?: boolean } = {}): string {\n  const nowMs = Date.now();\n  const tsHex = BigInt(nowMs).toString(16).padStart(12, \"0\"); // 48 bits ➔ 12 hex chars\n\n  // We'll use 10 random bytes (80 bits)\n  let rand = getRandomBytes(10);\n\n  if (monotonic) {\n    // ensure monotonicState is consistent per-process\n    if (monotonicState.lastTimestampMs === nowMs && monotonicState.lastRand) {\n      // We are in the same ms bucket — increment lastRand (big-endian)\n      const copy = new Uint8Array(monotonicState.lastRand); // copy for use\n      const overflow = incrementUint8ArrayBigEndian(copy);\n      if (overflow) {\n        // Practically impossible (2^80 increments in 1ms). Throw to be safe.\n        throw new RangeError(\n          \"Monotonic UUID sequence overflow: too many UUIDs generated within the same millisecond.\"\n        );\n      }\n      // use incremented copy as rand\n      rand = copy;\n      // update state\n      monotonicState.lastRand = copy;\n    } else {\n      // New ms: generate fresh randomness and store\n      const fresh = getRandomBytes(10);\n      monotonicState.lastRand = new Uint8Array(fresh);\n      monotonicState.lastTimestampMs = nowMs;\n      rand = fresh;\n    }\n  }\n\n  // if (!rand[0] || !rand[2]) return \"\";\n  // If not monotonic, rand remains randomly generated above.\n\n  // Now set version & variant bits into proper positions.\n  // For v7 layout we used: timestamp (48 bits) + rand[0..9] (80 bits)\n  // We must set version nibble into high nibble of rand[0] (time_hi_and_version)\n  // and set variant bits into rand[2]'s high bits (clock_seq_hi_and_reserved)\n  rand[0] = rand[0] ? (rand[0] & 0x0f) | 0x70 : 0; // version 7 (0x7 << 4)\n  rand[2] = rand[2] ? (rand[2] & 0x3f) | 0x80 : 0; // variant 10xx\n\n  const randHex = Array.from(rand, (b) => byteToHex[b]).join(\"\");\n\n  // Assemble UUID groups:\n  // - 8 hex (timestamp[0..7])\n  // - 4 hex (timestamp[8..11])\n  // - 4 hex (rand[0..1]) ➔ contains version in high nibble of rand[0]\n  // - 4 hex (rand[2..3]) ➔ contains variant in high bits of rand[2]\n  // - 12 hex (rand[4..9])\n  const part1 = tsHex.slice(0, 8);\n  const part2 = tsHex.slice(8, 12);\n  const part3 = randHex.slice(0, 4);\n  const part4 = randHex.slice(4, 8);\n  const part5 = randHex.slice(8, 20);\n\n  return [part1, part2, part3, part4, part5].join(\"-\");\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["isNonEmptyArray","isInteger","errorMsg","getPreciseType","safeStableStringify","isNumber","createMessage","isPlainObject","errorMsg","isInteger","getPreciseType","safeStableStringify","createMessage","isPlainObject","errorMsg","isInteger","getPreciseType","safeStableStringify","isNaN","joinLines","createMessage","isPlainObject","isNonEmptyString","getPreciseType","safeStableStringify","isBoolean","createMessage"],"sources":["../../src/generators/random/array/getRandomItem.ts","../../src/generators/random/integer/randomInt.ts","../../src/generators/random/integer/randomIntByLength.ts","../../src/generators/random/string/randomStr.ts","../../src/generators/random/uuid/randomUUID.ts"],"sourcesContent":["import type {\n  Extends,\n  FixNeverArrayRecursive,\n  IfNonEmptyArray,\n  NullToUndefined\n} from \"@rzl-zone/ts-types-plus\";\n\nimport { isNonEmptyArray } from \"@/predicates/is/isNonEmptyArray\";\n\n/** -------------------------------------------------------------------------------------\n * * ***Utility: `getRandomItem`.***\n * --------------------------------------------------------------------------------------\n * **Function to get a random element from a given array.**\n *\n * ---\n * @template T - The type of the input array.\n *\n * ---\n * @param {*} array - The input array, can be `null`, `undefined`, or an empty array.\n *\n * ---\n * @returns\n * - If `array` is a non-empty tuple, returns one of its elements.\n * - If `array` is empty, `null`, or `undefined`, returns `undefined`.\n *\n * ---\n * @example\n * getRandomItem([]);\n * // ➔ undefined\n * getRandomItem(null);\n * // ➔ undefined\n * getRandomItem(undefined);\n * // ➔ undefined\n * getRandomItem([1, 2, 3, 4]);\n * // ➔ number\n * getRandomItem([\"apple\", \"banana\", \"cherry\"]);\n * // ➔ string\n * getRandomItem([\"apple\", 123, true]);\n * // ➔ string | number | boolean\n * getRandomItem([\"apple\", 123, true, null]);\n * // ➔ string | number | boolean | undefined\n * getRandomItem([\"apple\", 123, true, undefined]);\n * // ➔ string | number | boolean | undefined\n *\n * // Tuple example:\n * const tuple = [1, \"two\", true] as const;\n * getRandomItem(tuple); // 1 | \"two\" | true\n */\nexport function getRandomItem(array: undefined): undefined;\nexport function getRandomItem(array: []): undefined;\nexport function getRandomItem<T extends readonly unknown[]>(\n  array: T\n): T extends never[][]\n  ? undefined\n  : number extends T[\"length\"]\n    ? NullToUndefined<FixNeverArrayRecursive<T[number]>>\n    : IfNonEmptyArray<\n        T,\n        NullToUndefined<FixNeverArrayRecursive<T[number]>>,\n        undefined\n      >;\nexport function getRandomItem<T extends readonly unknown[] | undefined | null>(\n  array: T\n): T extends readonly unknown[]\n  ? NullToUndefined<FixNeverArrayRecursive<T[number]>> | undefined\n  : undefined;\nexport function getRandomItem<T>(array: T): unknown extends T\n  ? unknown\n  : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    Extends<any[] | readonly any[], T> extends true\n    ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n    : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      Extends<any[], T> extends true\n      ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n      : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        Extends<readonly any[], T> extends true\n        ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n        : undefined;\nexport function getRandomItem(array: unknown): unknown {\n  if (!isNonEmptyArray(array)) return undefined;\n\n  const randomIndex = Math.floor(Math.random() * (array.length || 0));\n  return array[randomIndex];\n}\n","import { createMessage } from \"@/_private/logger\";\n\nimport { isNumber } from \"@/predicates/is/isNumber\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** -----------------------------------------------------------------------------------------------------\n * * ***Utility: `randomInt`.***\n * ------------------------------------------------------------------------------------------------------\n * **Generates a random integer within a specified range (inclusive).**\n *\n * ---\n * - **Generates a random integer between `min` and `max` (inclusive), with safety constraints:**\n *     - `min` will be forced to be at least `1`.\n *     - `max` will be capped at `Number.MAX_SAFE_INTEGER`.\n *\n * ---\n * @param {number} min - The minimum value (inclusive), must be an integer.\n * @param {number} max - The maximum value (inclusive), must be an integer.\n *\n * ---\n * @returns {number} A random integer N where `min ≤ N ≤ max`.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `min` or `max` is not an integer, or value is `Number.MIN_VALUE`.\n * - `min` is greater than `max`.\n *\n * ---\n * @example\n * randomInt(1, 10);\n * // ➔ returns 1 up-to 10 (random)\n * randomInt(50, 100);\n * // ➔ returns 50 up-to 100 (random)\n * randomInt(5, 5);\n * // ➔ always returns 5 (exact)\n * randomInt(-5, 3);\n * // ➔ always returns ≥ 1, since min is adjusted (exact)\n * randomInt(1, Number.MAX_SAFE_INTEGER + 10000);\n * // ➔ still safely capped at MAX_SAFE_INTEGER\n * randomInt(Number.MIN_VALUE, 3);\n * // ➔ Error, min or max cant be as `Number.MIN_VALUE` value.\n */\nexport const randomInt = (min: number, max: number): number => {\n  if (!isInteger(min) || !isInteger(max)) {\n    throw new TypeError(\n      errorMsg(\n        `First parameter (\\`min\\`) and second parameter (\\`max\\`) must be of type \\`integer-number\\`${minValueNote(\n          min,\n          max\n        )}value, but received: ['min': \\`${getPreciseType(\n          min\n        )}\\` - (with value: \\`${safeStableStringify(min, {\n          keepUndefined: true\n        })})\\`, 'max': \\`${getPreciseType(max)}\\` - (with value: \\`${safeStableStringify(\n          max,\n          {\n            keepUndefined: true\n          }\n        )}\\`)].`\n      )\n    );\n  }\n\n  if (min > max) {\n    throw new RangeError(\n      errorMsg(\n        `First parameter (\\`min\\`) must be less than or equal to second parameter (\\`max\\`), but received: ['min': ${formatValue(\n          min\n        )} - (with value: \\`${safeStableStringify(min, {\n          keepUndefined: true\n        })})\\`, 'max': ${formatValue(max)} - (with value: \\`${safeStableStringify(\n          max,\n          {\n            keepUndefined: true\n          }\n        )})\\`].`\n      )\n    );\n  }\n\n  // Ensure `min` is at least 1\n  min = Math.max(1, min);\n\n  // Ensure `max` does not exceed Number.MAX_SAFE_INTEGER\n  max = Math.min(Number.MAX_SAFE_INTEGER, max);\n\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst formatValue = (value: unknown): string => {\n  return isNumber(value, { includeNaN: true })\n    ? value === Number.MIN_VALUE\n      ? \"`Number.MIN_VALUE`\"\n      : `${value}`\n    : `\\`${getPreciseType(value)}\\``;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst minValueNote = (...values: unknown[]) => {\n  return values.some(\n    (v) => isNumber(v, { includeNaN: true }) && v === Number.MIN_VALUE\n  )\n    ? \" and can't be `Number.MIN_VALUE` \"\n    : \" \";\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomInt\", msg);\n","import { createMessage } from \"@/_private/logger\";\n\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\nimport { randomInt } from \"./randomInt\";\n\ntype OptionsRandomIntByLength = {\n  /** -----------------------------------------------------------------------------------\n   * * ***Minimum length of the random number, the `allowed minimal value` `integer` is `1` `and not bigger than value of` `maxLength`, defaultValue: `1`.***\n   * ------------------------------------------------------------------------------------\n   *\n   * @default 1\n   */\n  minLength?: number;\n  /** -----------------------------------------------------------------------------------\n   * * ***Maximum length of the random number, the `allowed maximal value` `integer` is `16`, defaultValue: `16`.***\n   * ------------------------------------------------------------------------------------\n   *\n   * @default 16\n   */\n  maxLength?: number;\n  /** -----------------------------------------------------------------------------------\n   * * ***If true, prevents the result from being zero, defaultValue: `false`.***\n   * ------------------------------------------------------------------------------------\n   *\n   * @default false\n   */\n  avoidZero?: boolean;\n};\n\n/** ----------------------------------------------------------------------------\n * * ***Utility: `randomIntByLength`.***\n * -----------------------------------------------------------------------------\n * **Generates a random integer within a specified range of digit lengths.**\n *\n * ---\n * @description\n * This function allows generating random integers that strictly conform to a specified minimum and\n * maximum digit length, it is useful for scenarios such as generating realistic-looking IDs, codes,\n * or random test data.\n *\n * ---\n * - **The function ensures:**\n *     - `minLength` is at least 1 and not greater than `maxLength`.\n *     - `maxLength` is no more than 16 (due to JavaScript's `Number.MAX_SAFE_INTEGER`).\n *     - If `avoidZero` is `true`, ensures that `0` is never returned.\n *\n * ---\n * @param {OptionsRandomIntByLength} [options] - Configuration options.\n * @param {OptionsRandomIntByLength[\"minLength\"]} [options.minLength=1] - Minimum number of digits (must be ≥ `1` and ≤ `maxLength`).\n * @param {OptionsRandomIntByLength[\"maxLength\"]} [options.maxLength=16] - Maximum number of digits (must be ≤ `16`).\n * @param {OptionsRandomIntByLength[\"avoidZero\"]} [options.avoidZero=false] - If true, will ensure the result is never zero.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if parameters are invalid, such as:\n * - `minLength` < `1`.\n * - `maxLength` > `16`.\n * - `minLength` > `maxLength`.\n * - non-integer values for `minLength` or `maxLength`.\n *\n * ---\n * @returns {number} A randomly generated integer within the specified constraints.\n *\n * ---\n * @example\n * randomIntByLength({ minLength: 3, maxLength: 5 });\n * // ➔ `xxx` (random int), `xxxx` (random int) or `xxxxx` (random int).\n * randomIntByLength({ minLength: 4, maxLength: 4 });\n * // ➔ `xxxx` (exact 4 digits int)\n * randomIntByLength({ avoidZero: true }); // never 0\n */\nexport const randomIntByLength = (\n  options?: OptionsRandomIntByLength\n): number => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) options = {};\n\n  const { minLength = 1, maxLength = 16, avoidZero = false } = options;\n\n  assertIsBoolean(avoidZero, {\n    message({ currentType, validType }) {\n      return errorMsg(\n        `Parameters \\`avoidZero\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n      );\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n          minLength\n        )}\\` - (with value: ${safeStableStringify(minLength, {\n          keepUndefined: true\n        })}), 'maxLength': \\`${getPreciseType(\n          maxLength\n        )}\\` - (with value: ${safeStableStringify(maxLength, {\n          keepUndefined: true\n        })})].`\n      )\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 16 || minLength > maxLength) {\n    throw new RangeError(\n      errorMsg(\n        `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 16, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n      )\n    );\n  }\n\n  // Generate a random length between minLength and maxLength\n  const randomLength =\n    minLength === maxLength ? minLength : randomInt(minLength, maxLength);\n\n  // Define min and max value based on the selected length\n  const minValue = 10 ** (randomLength - 1); // Example: minLength=3 ➔ minValue=100\n  const maxValue = 10 ** randomLength - 1; // Example: maxLength=4 ➔ maxValue=9999\n\n  // Generate a random number within the valid range\n  let result = randomInt(minValue, maxValue);\n\n  // Ensure the number is not zero if `avoidZero` is true\n  if (avoidZero && result === 0) {\n    result = minValue; // Assign the smallest valid number instead of looping\n  }\n\n  return result;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomIntByLength\", msg);\n","import type { OptionsRandomStr } from \"./_private/randomSTR.types\";\n\nimport { joinLines } from \"@rzl-zone/build-tools/utils\";\n\nimport { createMessage } from \"@/_private/logger\";\n\nimport { isNaN } from \"@/predicates/is/isNaN\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\n\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\nimport { randomInt } from \"../integer/randomInt\";\n\n/** -----------------------------------------------------------------------------------\n * * ***Utility: `randomStr`.***\n * ------------------------------------------------------------------------------------\n * **Generates a random alphanumeric string or number with a specified length range.**\n *\n * ---\n * @description\n * This function allows you to generate random strings or numbers with fully\n * customizable options, such as length range, character sets, inclusion of\n * additional characters, and whether to avoid whitespace.\n *\n * ---\n * @param {OptionsRandomStr} [options] - Configuration options for generating the string.\n * @param {OptionsRandomStr[\"minLength\"]} [options.minLength=40] - Minimum length of the generated string (must be `≥` `1`).\n * @param {OptionsRandomStr[\"maxLength\"]} [options.maxLength=40] - Maximum length of the generated string (must be `≤` `5000`).\n * @param {OptionsRandomStr[\"type\"]} [options.type=\"string\"] - Whether to generate a general alphanumeric string or purely numeric string.\n * @param {OptionsRandomStr[\"avoidWhiteSpace\"]} [options.avoidWhiteSpace=true] - If true, removes all whitespace, tabs, and newlines from the character set before generating.\n * @param {OptionsRandomStr[\"replaceGenStr\"]} [options.replaceGenStr] - A custom character set to use when `type` is `\"string\"`.\n * @param {OptionsRandomStr[\"replaceGenInt\"]} [options.replaceGenInt] - A custom character set to use when `type` is `\"number\"`.\n * @param {OptionsRandomStr[\"addChar\"]} [options.addChar] - Additional characters to always include in the character set.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if provided options are invalid (such as minLength > maxLength, invalid type, or empty character set).\n *\n * ---\n * @returns {string} The randomly generated string or numeric string of the desired length.\n *\n * ---\n * @example\n * randomStr();\n * // ➔ Generates a 40-character random alphanumeric string\n * randomStr({ minLength: 10, maxLength: 20 });\n * // ➔ Generates a string between 10 and 20 characters\n * randomStr({ type: \"number\", minLength: 5, maxLength: 5 });\n * // ➔ \"48302\"\n * randomStr({ replaceGenStr: \"ABC \", avoidWhiteSpace: false });\n * // ➔ String using A, B, C and space\n * randomStr({ addChar: \"!@#\", minLength: 15, maxLength: 15 });\n * // ➔ Guaranteed to include !@# in the set\n */\nexport const randomStr = (options?: OptionsRandomStr): string => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) options = {};\n\n  const {\n    minLength = 40,\n    maxLength = 40,\n    type = \"string\",\n    avoidWhiteSpace = true\n  } = options;\n\n  // Validate `avoidWhiteSpace`\n  assertIsBoolean(avoidWhiteSpace, {\n    message({ currentType, validType }) {\n      return errorMsg(\n        `Parameters \\`avoidWhiteSpace\\` property of the \\`options\\` (first-parameter) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n      );\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n          minLength\n        )}\\` - (with value: ${safeStableStringify(minLength, {\n          keepUndefined: true\n        })}), 'maxLength': \\`${getPreciseType(\n          maxLength\n        )}\\` - (with value: ${safeStableStringify(maxLength, {\n          keepUndefined: true\n        })})].`\n      )\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 5000 || minLength > maxLength) {\n    throw new RangeError(\n      errorMsg(\n        `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 5000, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n      )\n    );\n  }\n\n  // Validate `type` value props (is not typeof)\n  if (type !== \"string\" && type !== \"number\") {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`type\\` must be of type \\`string\\` with value one of \"string\" | \"number\", but received: \\`${getPreciseType(\n          type\n        )}\\`, with value: ${safeStableStringify(type, {\n          keepUndefined: true\n        })}.`\n      )\n    );\n  }\n\n  // Generate a random length within the range\n  const length = randomInt(minLength, maxLength);\n\n  // Function to clean characters based on `avoidWhiteSpace`\n  const cleanCharacters = (charSet: string) => {\n    return avoidWhiteSpace ? charSet.replace(/\\s|\\n|\\t/g, \"\") : charSet;\n  };\n\n  // Define character sets\n  const defaultNumberSet = \"0123456789\";\n  const defaultStringSet =\n    \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n\n  const baseCharSet =\n    type === \"number\"\n      ? ((!isNaN(Number(options.replaceGenInt))\n          ? options.replaceGenInt\n          : undefined) ?? defaultNumberSet)\n      : ((options.replaceGenStr ? options.replaceGenStr : undefined) ??\n        defaultStringSet);\n\n  // Get the final character set\n  const characterSet = cleanCharacters(baseCharSet) + (options.addChar || \"\");\n\n  // Ensure characterSet is not empty\n  if (!characterSet.length) {\n    const errCharSet = (() => {\n      if (type === \"number\") {\n        if (avoidWhiteSpace) {\n          return \"If `avoidWhiteSpace` is true, and `replaceGenInt` cant be empty-string value, ensure `replaceGenInt` has valid characters and non-nan string number.\";\n        }\n        return \"Ensure `replaceGenInt` has valid characters and not a NaN number string while convert to number.\";\n      }\n      return \"Ensure `replaceGenStr` has valid characters and non empty string.\";\n    })();\n\n    throw new Error(\n      errorMsg(joinLines(\"Character set is empty.\", `  > ${errCharSet}`))\n    );\n  }\n\n  // Generate random string\n  let result = \"\";\n  for (let i = 0; i < length; i++) {\n    result += characterSet.charAt(\n      Math.floor(Math.random() * characterSet.length)\n    );\n  }\n\n  return result;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomStr\", msg);\n","import { createMessage } from \"@/_private/logger\";\n\nimport { isBoolean } from \"@/predicates/is/isBoolean\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** ---------------------------------------------------------\n * * ***Configuration options for `randomUUID()`.***\n * ----------------------------------------------------------\n */\ntype OptionsRandomUUID = {\n  /** ---------------------------------------------------------\n   * * ***Specifies which UUID version to generate.***\n   * ----------------------------------------------------------\n   *\n   * - `\"v4\"` — Fully random UUID (RFC 4122), no timestamp, no ordering guarantees.\n   * - `\"v7\"` — Time-ordered UUID (RFC 9562), uses Unix timestamp + randomness.\n   *\n   * ---\n   * @default\n   * ```ts\n   * \"v4\"\n   * ```\n   *\n   * ---\n   * @example\n   * 1. #### Random `v4` UUID:\n   *    ```ts\n   *    randomUUID({ version: \"v4\" });\n   *    // ➔ \"xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx\"\n   *    ```\n   *    ---\n   * 2. #### Time-ordered `v7` UUID:\n   *    ```ts\n   *    randomUUID({ version: \"v7\" });\n   *    // ➔ \"xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx\"\n   *    ```\n   */\n  version?: \"v4\" | \"v7\";\n\n  /** ---------------------------------------------------------\n   * * ***Enables monotonic sequencing for UUID v7.***\n   *  ----------------------------------------------------------\n   *\n   * - Guarantees that multiple UUIDs generated within the same millisecond\n   *   are strictly non-decreasing (lexicographically and timestamp-wise).\n   * - Only valid when `version === \"v7\"`, using with `v4` will throw a `TypeError`.\n   * - Useful for database inserts, logs, or any system where order matters.\n   *\n   * ---\n   * @default\n   * ```ts\n   * false\n   * ```\n   *\n   * ---\n   * @example\n   * - #### Monotonic `v7` UUIDs:\n   *   ```ts\n   *   const a = randomUUID({ version: \"v7\", monotonic: true });\n   *   const b = randomUUID({ version: \"v7\", monotonic: true });\n   *   console.log(a < b);\n   *   // ➔ true (guaranteed)\n   *   ```\n   */\n  monotonic?: boolean;\n};\n\n/** -----------------------------------------------------------------------\n * * ***Utility: `randomUUID`.***\n * ------------------------------------------------------------------------\n * **Generates a UUID string according to the specified version and options.**\n *\n * ---\n * - #### Supported versions:\n *     - #### **`\"v4\"` *(default)*** ➔ Fully random UUID, RFC 4122 compliant.\n *          - Uses `crypto.randomUUID()` if available.\n *          - Falls back to `crypto.getRandomValues()` or `Math.random()`\n *            if needed.\n *          ---\n *     - #### **`\"v7\"`** ➔ Time-ordered UUID, RFC 9562 compliant.\n *          - Timestamp (Unix ms, 48 bits) + 80 bits randomness.\n *          - Good for database indexing / sorting.\n *          ---\n *     - #### **`\"v7\"` + `monotonic: true`** ➔ Ensures strictly non-decreasing UUIDs\n *          for multiple calls in the same millisecond (per-process).\n *\n * ---\n * - #### Behavior / Safety Notes:\n *     - **v4**: Fully random; probability of duplicates is astronomically low.\n *     - **v7**: Time-ordered; collisions extremely unlikely unless same ms + random repeat.\n *     - **Monotonic v7**: Guaranteed ordering per-process if multiple UUIDs are generated\n *       in the same millisecond.\n *     - **All versions**: Fallback safely if `crypto` APIs are unavailable.\n *\n * ---\n * @param {object} [options] - Optional settings object.\n * @param {\"v4\" | \"v7\"} [options.version=\"v4\"] - UUID version to generate.\n * @param {boolean} [options.monotonic=false] - ***For v7 only***, generate monotonic UUIDs\n *                                              to maintain strict lexicographic order\n *                                              when generating multiple UUIDs within the same ms.\n *\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `options.version` is provided but not a string.\n * - `options.monotonic` is provided but not a boolean.\n * - `monotonic: true` is used with `version` other than `\"v7\"`.\n *\n * ---\n * @returns {string} A 36-character UUID string compliant with the selected version.\n *\n * @throws **{@link RangeError | `RangeError`}** if `options.version` is provided but not `\"v4\"` or `\"v7\"`.\n *\n * @example\n * 1. #### Default (v4):\n *    ```ts\n *    const id = randomUUID();\n *    // ➔ \"xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx\"\n *    ```\n *    ---\n * 2. #### Explicit `v4`:\n *    ```ts\n *    const id4 = randomUUID({ version: \"v4\" });\n *    // ➔ \"xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx\"\n *    ```\n *    ---\n * 3. #### Time-ordered `v7`:\n *    ```ts\n *    const id7 = randomUUID({ version: \"v7\" });\n *    // ➔ \"xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx\"\n *    ```\n *    ---\n * 4. #### Monotonic `v7`:\n *    ```ts\n *    const a = randomUUID({ version: \"v7\", monotonic: true });\n *    const b = randomUUID({ version: \"v7\", monotonic: true });\n *    // a < b lexicographically (guaranteed)\n *    ```\n * ---\n * - #### *Throws:*\n *      - #### `TypeError`:\n *        ```ts\n *        randomUUID({ version: 123 as any });\n *        // version must be string\n *        randomUUID({ version: \"v4\", monotonic: true } as any);\n *        // monotonic only for v7\n *        ```\n *        ---\n *      - #### `RangeError`:\n *        ```ts\n *        randomUUID({ version: \"v1\" as any });\n *        // unsupported version\n *        ```\n */\nexport function randomUUID(options: OptionsRandomUUID = {}): string {\n  // Validate options is a plain object if provided\n  if (!isPlainObject(options)) options = {};\n\n  const { version = \"v4\", monotonic = false } = options;\n\n  // Validate version type\n  if (!isNonEmptyString(version)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`version\\` property of the \\`options\\` (first parameter) must be a \\`string\\` of either \"v4\" or \"v7\", but received type: \\`${getPreciseType(\n          version\n        )}\\` - (with value: \\`${safeStableStringify(version, { keepUndefined: true })}\\`).`\n      )\n    );\n  }\n\n  if (version !== \"v4\" && version !== \"v7\") {\n    throw new RangeError(\n      errorMsg(\n        `Unsupported UUID version. Allowed values are \"v4\" or \"v7\". (received: \\`${safeStableStringify(\n          version,\n          {\n            keepUndefined: true\n          }\n        )}\\`).`\n      )\n    );\n  }\n\n  // Validate monotonic type\n  if (!isBoolean(monotonic)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) must be a \\`boolean\\` when provided, but received type: \\`${getPreciseType(\n          monotonic\n        )}\\` - (with value: \\`${safeStableStringify(monotonic, {\n          keepUndefined: true\n        })}\\`).`\n      )\n    );\n  }\n\n  // monotonic only allowed with v7\n  if (monotonic && version !== \"v7\") {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) is only supported for version \"v7\". Received: version=${safeStableStringify(\n          version,\n          { keepUndefined: true }\n        )}.`\n      )\n    );\n  }\n\n  if (version === \"v4\") {\n    return generateUUIDv4();\n  }\n\n  // version === \"v7\"\n  return generateUUIDv7({ monotonic });\n}\n\n//todo: Helpers & Implementations\n\nfunction hasCryptoGetRandomValues(): boolean {\n  return (\n    typeof crypto !== \"undefined\" &&\n    typeof crypto.getRandomValues === \"function\"\n  );\n}\n\nfunction hasCryptoRandomUUID(): boolean {\n  return (\n    typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\"\n  );\n}\n\nfunction getRandomBytes(len: number): Uint8Array {\n  if (hasCryptoGetRandomValues()) {\n    return crypto.getRandomValues(new Uint8Array(len));\n  }\n  // Fallback: not cryptographically secure, but avoids crash\n  const arr = new Uint8Array(len);\n  for (let i = 0; i < len; i++) {\n    arr[i] = Math.floor(Math.random() * 256);\n  }\n  return arr;\n}\n\nconst byteToHex: string[] = (() => {\n  const arr: string[] = [];\n  for (let i = 0; i < 256; ++i) {\n    arr.push((i + 0x100).toString(16).substring(1));\n  }\n  return arr;\n})();\n\nfunction generateUUIDv4(): string {\n  // Prefer native if available\n  if (hasCryptoRandomUUID()) {\n    return crypto.randomUUID();\n  }\n\n  // If crypto.getRandomValues available, use it for 16 bytes\n  if (hasCryptoGetRandomValues()) {\n    const rnd = crypto.getRandomValues(new Uint8Array(16));\n\n    if (\n      !rnd[0] ||\n      !rnd[1] ||\n      !rnd[2] ||\n      !rnd[3] ||\n      !rnd[4] ||\n      !rnd[5] ||\n      !rnd[6] ||\n      !rnd[7] ||\n      !rnd[8] ||\n      !rnd[9] ||\n      !rnd[10] ||\n      !rnd[11] ||\n      !rnd[12] ||\n      !rnd[13] ||\n      !rnd[14] ||\n      !rnd[15]\n    ) {\n      return \"\";\n    }\n\n    const byteToHex0 = byteToHex[rnd[0]];\n    const byteToHex1 = byteToHex[rnd[1]];\n\n    if (!byteToHex0 || !byteToHex1) return \"\";\n\n    // Per RFC 4122: set version and variant\n    rnd[6] = (rnd[6]! & 0x0f) | 0x40; // version 4\n    rnd[8] = (rnd[8]! & 0x3f) | 0x80; // variant 10xx\n\n    return (\n      byteToHex0 +\n      byteToHex1 +\n      byteToHex[rnd[2]] +\n      byteToHex[rnd[3]] +\n      \"-\" +\n      byteToHex[rnd[4]] +\n      byteToHex[rnd[5]] +\n      \"-\" +\n      byteToHex[rnd[6]] +\n      byteToHex[rnd[7]] +\n      \"-\" +\n      byteToHex[rnd[8]] +\n      byteToHex[rnd[9]] +\n      \"-\" +\n      byteToHex[rnd[10]] +\n      byteToHex[rnd[11]] +\n      byteToHex[rnd[12]] +\n      byteToHex[rnd[13]] +\n      byteToHex[rnd[14]] +\n      byteToHex[rnd[15]]\n    );\n  }\n\n  // Last-resort fallback using Math.random (not crypto-secure)\n  return \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, (c) => {\n    const r = (Math.random() * 16) | 0;\n    const v = c === \"x\" ? r : (r & 0x3) | 0x8;\n    return v.toString(16);\n  });\n}\n\n/* ---------------------------\n *  Monotonic state (singleton per-process)\n *  ---------------------------\n */\n\n/**\n * Internal monotonic state:\n * - lastTimestampMs: last generated timestamp (ms)\n * - lastRand: last random 10-byte block used for v7 (used to increment on same ms)\n */\nconst monotonicState: {\n  lastTimestampMs: number;\n  lastRand: Uint8Array | null;\n} = {\n  lastTimestampMs: -1,\n  lastRand: null\n};\n\nfunction incrementUint8ArrayBigEndian(arr: Uint8Array): boolean {\n  // Increment arr in big-endian order. Return true if overflowed back to zero.\n  for (let i = arr.length - 1; i >= 0; i--) {\n    if (arr[i] === 0xff) {\n      arr[i] = 0x00;\n      continue;\n    }\n\n    arr[i] = (arr[i]! + 1) & 0xff;\n\n    return false; // no overflow\n  }\n  // overflowed (wrapped to zero)\n  return true;\n}\n\nfunction generateUUIDv7({\n  monotonic = false\n}: { monotonic?: boolean } = {}): string {\n  const nowMs = Date.now();\n  const tsHex = BigInt(nowMs).toString(16).padStart(12, \"0\"); // 48 bits ➔ 12 hex chars\n\n  // We'll use 10 random bytes (80 bits)\n  let rand = getRandomBytes(10);\n\n  if (monotonic) {\n    // ensure monotonicState is consistent per-process\n    if (monotonicState.lastTimestampMs === nowMs && monotonicState.lastRand) {\n      // We are in the same ms bucket — increment lastRand (big-endian)\n      const copy = new Uint8Array(monotonicState.lastRand); // copy for use\n      const overflow = incrementUint8ArrayBigEndian(copy);\n      if (overflow) {\n        // Practically impossible (2^80 increments in 1ms). Throw to be safe.\n        throw new RangeError(\n          errorMsg(\n            \"Monotonic UUID sequence overflow, too many UUIDs generated within the same millisecond.\"\n          )\n        );\n      }\n      // use incremented copy as rand\n      rand = copy;\n      // update state\n      monotonicState.lastRand = copy;\n    } else {\n      // New ms: generate fresh randomness and store\n      const fresh = getRandomBytes(10);\n      monotonicState.lastRand = new Uint8Array(fresh);\n      monotonicState.lastTimestampMs = nowMs;\n      rand = fresh;\n    }\n  }\n\n  // if (!rand[0] || !rand[2]) return \"\";\n  // If not monotonic, rand remains randomly generated above.\n\n  // Now set version & variant bits into proper positions.\n  // For v7 layout we used: timestamp (48 bits) + rand[0..9] (80 bits)\n  // We must set version nibble into high nibble of rand[0] (time_hi_and_version)\n  // and set variant bits into rand[2]'s high bits (clock_seq_hi_and_reserved)\n  rand[0] = rand[0] ? (rand[0] & 0x0f) | 0x70 : 0; // version 7 (0x7 << 4)\n  rand[2] = rand[2] ? (rand[2] & 0x3f) | 0x80 : 0; // variant 10xx\n\n  const randHex = Array.from(rand, (b) => byteToHex[b]).join(\"\");\n\n  // Assemble UUID groups:\n  // - 8 hex (timestamp[0..7])\n  // - 4 hex (timestamp[8..11])\n  // - 4 hex (rand[0..1]) ➔ contains version in high nibble of rand[0]\n  // - 4 hex (rand[2..3]) ➔ contains variant in high bits of rand[2]\n  // - 12 hex (rand[4..9])\n  const part1 = tsHex.slice(0, 8);\n  const part2 = tsHex.slice(8, 12);\n  const part3 = randHex.slice(0, 4);\n  const part4 = randHex.slice(4, 8);\n  const part5 = randHex.slice(8, 20);\n\n  return [part1, part2, part3, part4, part5].join(\"-\");\n}\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomUUID\", msg);\n"],"mappings":"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"}

package/dist/generators/index.d.cts

@@ -2,11 +2,11 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1`
+*  Version: `3.14.0-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
 */
 
-import { a as randomInt, i as randomIntByLength, n as randomUUID, o as getRandomItem, r as randomStr, t as noop } from "../index-ORbo-7zA.cjs";
+import { a as randomInt, i as randomIntByLength, n as randomUUID, o as getRandomItem, r as randomStr, t as noop } from "../index-lI0b7iUz.cjs";
 export { getRandomItem, noop, randomInt, randomIntByLength, randomStr, randomUUID };

package/dist/generators/index.d.ts

@@ -2,11 +2,11 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1`
+*  Version: `3.14.0-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
 */
 
-import { a as randomInt, i as randomIntByLength, n as randomUUID, o as getRandomItem, r as randomStr, t as noop } from "../index-ORbo-7zA.js";
+import { a as randomInt, i as randomIntByLength, n as randomUUID, o as getRandomItem, r as randomStr, t as noop } from "../index-BP3sUrAx.js";
 export { getRandomItem, noop, randomInt, randomIntByLength, randomStr, randomUUID };

package/dist/generators/index.js

@@ -2,22 +2,24 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1`
+*  Version: `3.14.0-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
 */
-import { A as isPlainObject, D as isNaN, F as isBoolean, p as isNonEmptyArray, r as getPreciseType, t as assertIsBoolean, w as isNumber, y as isNonEmptyString } from "../assertIsBoolean-CWUs-I5l.js";
-import { t as safeStableStringify } from "../safeStableStringify-B2KTTS3r.js";
-import { t as noop } from "../noop-CjY8xVHv.js";
-import { t as isInteger } from "../isInteger-DEDbBGez.js";
+import { E as isPlainObject, S as isNaN, i as getPreciseType, j as isBoolean, m as isNonEmptyArray, n as assertIsBoolean, t as createMessage, w as isNonEmptyString } from "../logger-CLWnKRKE.js";
+import { t as isNumber } from "../isNumber-BCWD4dW0.js";
+import { t as safeStableStringify } from "../safeStableStringify-DfwxmiWn.js";
+import { t as noop } from "../noop-qxrcogt5.js";
+import { t as isInteger } from "../isInteger-aZgzTTZG.js";
+import { n as joinLines } from "../formatter-ekJQF_bA-xLD9mGk4.js";
 function getRandomItem(array) {
 	if (!isNonEmptyArray(array)) return void 0;
 	return array[Math.floor(Math.random() * (array.length || 0))];
 }
 const randomInt = (min, max) => {
-	if (!isInteger(min) || !isInteger(max)) throw new TypeError(`First parameter (\`min\`) and second parameter (\`max\`) must be of type \`integer-number\`${minValueNote(min, max)}value, but received: ['min': \`${getPreciseType(min)}\` - (with value: \`${safeStableStringify(min, { keepUndefined: true })})\`, 'max': \`${getPreciseType(max)}\` - (with value: \`${safeStableStringify(max, { keepUndefined: true })}\`)].`);
-	if (min > max) throw new RangeError(`First parameter (\`min\`) must be less than or equal to second parameter (\`max\`), but received: ['min': ${formatValue(min)} - (with value: \`${safeStableStringify(min, { keepUndefined: true })})\`, 'max': ${formatValue(max)} - (with value: \`${safeStableStringify(max, { keepUndefined: true })})\`].`);
+	if (!isInteger(min) || !isInteger(max)) throw new TypeError(errorMsg$3(`First parameter (\`min\`) and second parameter (\`max\`) must be of type \`integer-number\`${minValueNote(min, max)}value, but received: ['min': \`${getPreciseType(min)}\` - (with value: \`${safeStableStringify(min, { keepUndefined: true })})\`, 'max': \`${getPreciseType(max)}\` - (with value: \`${safeStableStringify(max, { keepUndefined: true })}\`)].`));
+	if (min > max) throw new RangeError(errorMsg$3(`First parameter (\`min\`) must be less than or equal to second parameter (\`max\`), but received: ['min': ${formatValue(min)} - (with value: \`${safeStableStringify(min, { keepUndefined: true })})\`, 'max': ${formatValue(max)} - (with value: \`${safeStableStringify(max, { keepUndefined: true })})\`].`));
 	min = Math.max(1, min);
 	max = Math.min(Number.MAX_SAFE_INTEGER, max);
 	return Math.floor(Math.random() * (max - min + 1)) + min;
@@ -28,55 +30,58 @@ const formatValue = (value) => {
 const minValueNote = (...values) => {
 	return values.some((v) => isNumber(v, { includeNaN: true }) && v === Number.MIN_VALUE) ? " and can't be `Number.MIN_VALUE` " : " ";
 };
+const errorMsg$3 = (msg) => createMessage("randomInt", msg);
 const randomIntByLength = (options) => {
 	if (!isPlainObject(options)) options = {};
 	const { minLength = 1, maxLength = 16, avoidZero = false } = options;
 	assertIsBoolean(avoidZero, { message({ currentType, validType }) {
-		return `Parameters \`avoidZero\` must be of type \`${validType}\`, but received: \`${currentType}\`.`;
+		return errorMsg$2(`Parameters \`avoidZero\` must be of type \`${validType}\`, but received: \`${currentType}\`.`);
 	} });
-	if (!isInteger(minLength) || !isInteger(maxLength)) throw new TypeError(`Parameters \`minLength\` and \`maxLength\` must be of type \`integer-number\`, but received: ['minLength': \`${getPreciseType(minLength)}\` - (with value: ${safeStableStringify(minLength, { keepUndefined: true })}), 'maxLength': \`${getPreciseType(maxLength)}\` - (with value: ${safeStableStringify(maxLength, { keepUndefined: true })})].`);
-	if (minLength < 1 || maxLength > 16 || minLength > maxLength) throw new RangeError(`Invalid range at parameters \`minLength\` must be ≥ 1, \`maxLength\` must be ≤ 16, and \`minLength\` ≤ \`maxLength\`, but received: ['minLength': \`${minLength}\`, 'maxLength': \`${maxLength}\`].`);
+	if (!isInteger(minLength) || !isInteger(maxLength)) throw new TypeError(errorMsg$2(`Parameters \`minLength\` and \`maxLength\` must be of type \`integer-number\`, but received: ['minLength': \`${getPreciseType(minLength)}\` - (with value: ${safeStableStringify(minLength, { keepUndefined: true })}), 'maxLength': \`${getPreciseType(maxLength)}\` - (with value: ${safeStableStringify(maxLength, { keepUndefined: true })})].`));
+	if (minLength < 1 || maxLength > 16 || minLength > maxLength) throw new RangeError(errorMsg$2(`Invalid range at parameters \`minLength\` must be ≥ 1, \`maxLength\` must be ≤ 16, and \`minLength\` ≤ \`maxLength\`, but received: ['minLength': \`${minLength}\`, 'maxLength': \`${maxLength}\`].`));
 	const randomLength = minLength === maxLength ? minLength : randomInt(minLength, maxLength);
 	const minValue = 10 ** (randomLength - 1);
 	let result = randomInt(minValue, 10 ** randomLength - 1);
 	if (avoidZero && result === 0) result = minValue;
 	return result;
 };
+const errorMsg$2 = (msg) => createMessage("randomIntByLength", msg);
 const randomStr = (options) => {
 	if (!isPlainObject(options)) options = {};
 	const { minLength = 40, maxLength = 40, type = "string", avoidWhiteSpace = true } = options;
 	assertIsBoolean(avoidWhiteSpace, { message({ currentType, validType }) {
-		return `Parameters \`avoidWhiteSpace\` property of the \`options\` (first-parameter) must be of type \`${validType}\`, but received: \`${currentType}\`.`;
+		return errorMsg$1(`Parameters \`avoidWhiteSpace\` property of the \`options\` (first-parameter) must be of type \`${validType}\`, but received: \`${currentType}\`.`);
 	} });
-	if (!isInteger(minLength) || !isInteger(maxLength)) throw new TypeError(`Parameters \`minLength\` and \`maxLength\` must be of type \`integer-number\`, but received: ['minLength': \`${getPreciseType(minLength)}\` - (with value: ${safeStableStringify(minLength, { keepUndefined: true })}), 'maxLength': \`${getPreciseType(maxLength)}\` - (with value: ${safeStableStringify(maxLength, { keepUndefined: true })})].`);
-	if (minLength < 1 || maxLength > 5e3 || minLength > maxLength) throw new RangeError(`Invalid range at parameters \`minLength\` must be ≥ 1, \`maxLength\` must be ≤ 5000, and \`minLength\` ≤ \`maxLength\`, but received: ['minLength': \`${minLength}\`, 'maxLength': \`${maxLength}\`].`);
-	if (type !== "string" && type !== "number") throw new TypeError(`Parameter \`type\` must be of type \`string\` with value one of "string" | "number", but received: \`${getPreciseType(type)}\`, with value: ${safeStableStringify(type, { keepUndefined: true })}.`);
+	if (!isInteger(minLength) || !isInteger(maxLength)) throw new TypeError(errorMsg$1(`Parameters \`minLength\` and \`maxLength\` must be of type \`integer-number\`, but received: ['minLength': \`${getPreciseType(minLength)}\` - (with value: ${safeStableStringify(minLength, { keepUndefined: true })}), 'maxLength': \`${getPreciseType(maxLength)}\` - (with value: ${safeStableStringify(maxLength, { keepUndefined: true })})].`));
+	if (minLength < 1 || maxLength > 5e3 || minLength > maxLength) throw new RangeError(errorMsg$1(`Invalid range at parameters \`minLength\` must be ≥ 1, \`maxLength\` must be ≤ 5000, and \`minLength\` ≤ \`maxLength\`, but received: ['minLength': \`${minLength}\`, 'maxLength': \`${maxLength}\`].`));
+	if (type !== "string" && type !== "number") throw new TypeError(errorMsg$1(`Parameter \`type\` must be of type \`string\` with value one of "string" | "number", but received: \`${getPreciseType(type)}\`, with value: ${safeStableStringify(type, { keepUndefined: true })}.`));
 	const length = randomInt(minLength, maxLength);
 	const cleanCharacters = (charSet) => {
 		return avoidWhiteSpace ? charSet.replace(/\s|\n|\t/g, "") : charSet;
 	};
 	const characterSet = cleanCharacters(type === "number" ? (!isNaN(Number(options.replaceGenInt)) ? options.replaceGenInt : void 0) ?? "0123456789" : (options.replaceGenStr ? options.replaceGenStr : void 0) ?? "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789") + (options.addChar || "");
 	if (!characterSet.length) {
-		const errCharSet = () => {
+		const errCharSet = (() => {
 			if (type === "number") {
 				if (avoidWhiteSpace) return "If `avoidWhiteSpace` is true, and `replaceGenInt` cant be empty-string value, ensure `replaceGenInt` has valid characters and non-nan string number.";
 				return "Ensure `replaceGenInt` has valid characters and not a NaN number string while convert to number.";
 			}
 			return "Ensure `replaceGenStr` has valid characters and non empty string.";
-		};
-		throw new Error(`Character set is empty. ${errCharSet()}`);
+		})();
+		throw new Error(errorMsg$1(joinLines("Character set is empty.", `  > ${errCharSet}`)));
 	}
 	let result = "";
 	for (let i = 0; i < length; i++) result += characterSet.charAt(Math.floor(Math.random() * characterSet.length));
 	return result;
 };
+const errorMsg$1 = (msg) => createMessage("randomStr", msg);
 function randomUUID(options = {}) {
-	if (!isPlainObject(options)) throw new TypeError(`First parameter (\`options\`) must be a plain object with optional properties \`version\` and \`monotonic\`, but received: \`${getPreciseType(options)}\` - (with value: \`${safeStableStringify(options, { keepUndefined: true })}\`).`);
+	if (!isPlainObject(options)) options = {};
 	const { version = "v4", monotonic = false } = options;
-	if (!isNonEmptyString(version)) throw new TypeError(`Parameter \`version\` property of the \`options\` (first parameter) must be a \`string\` of either "v4" or "v7", but received type: \`${getPreciseType(version)}\` - (with value: \`${safeStableStringify(version, { keepUndefined: true })}\`).`);
-	if (version !== "v4" && version !== "v7") throw new RangeError(`Unsupported UUID version. Allowed values are "v4" or "v7". (received: \`${safeStableStringify(version, { keepUndefined: true })}\`).`);
-	if (!isBoolean(monotonic)) throw new TypeError(`Parameter \`monotonic\` property of the \`options\` (first parameter) must be a \`boolean\` when provided, but received type: \`${getPreciseType(monotonic)}\` - (with value: \`${safeStableStringify(monotonic, { keepUndefined: true })}\`).`);
-	if (monotonic && version !== "v7") throw new TypeError(`Parameter \`monotonic\` property of the \`options\` (first parameter) is only supported for version "v7". Received: version=${safeStableStringify(version, { keepUndefined: true })}.`);
+	if (!isNonEmptyString(version)) throw new TypeError(errorMsg(`Parameter \`version\` property of the \`options\` (first parameter) must be a \`string\` of either "v4" or "v7", but received type: \`${getPreciseType(version)}\` - (with value: \`${safeStableStringify(version, { keepUndefined: true })}\`).`));
+	if (version !== "v4" && version !== "v7") throw new RangeError(errorMsg(`Unsupported UUID version. Allowed values are "v4" or "v7". (received: \`${safeStableStringify(version, { keepUndefined: true })}\`).`));
+	if (!isBoolean(monotonic)) throw new TypeError(errorMsg(`Parameter \`monotonic\` property of the \`options\` (first parameter) must be a \`boolean\` when provided, but received type: \`${getPreciseType(monotonic)}\` - (with value: \`${safeStableStringify(monotonic, { keepUndefined: true })}\`).`));
+	if (monotonic && version !== "v7") throw new TypeError(errorMsg(`Parameter \`monotonic\` property of the \`options\` (first parameter) is only supported for version "v7". Received: version=${safeStableStringify(version, { keepUndefined: true })}.`));
 	if (version === "v4") return generateUUIDv4();
 	return generateUUIDv7({ monotonic });
 }
@@ -135,7 +140,7 @@ function generateUUIDv7({ monotonic = false } = {}) {
 	let rand = getRandomBytes(10);
 	if (monotonic) if (monotonicState.lastTimestampMs === nowMs && monotonicState.lastRand) {
 		const copy = new Uint8Array(monotonicState.lastRand);
-		if (incrementUint8ArrayBigEndian(copy)) throw new RangeError("Monotonic UUID sequence overflow: too many UUIDs generated within the same millisecond.");
+		if (incrementUint8ArrayBigEndian(copy)) throw new RangeError(errorMsg("Monotonic UUID sequence overflow, too many UUIDs generated within the same millisecond."));
 		rand = copy;
 		monotonicState.lastRand = copy;
 	} else {
@@ -155,5 +160,6 @@ function generateUUIDv7({ monotonic = false } = {}) {
 		randHex.slice(8, 20)
 	].join("-");
 }
+const errorMsg = (msg) => createMessage("randomUUID", msg);
 export { getRandomItem, noop, randomInt, randomIntByLength, randomStr, randomUUID };
 //# sourceMappingURL=index.js.map

package/dist/generators/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/generators/random/array/getRandomItem.ts","../../src/generators/random/integer/randomInt.ts","../../src/generators/random/integer/randomIntByLength.ts","../../src/generators/random/string/randomStr.ts","../../src/generators/random/uuid/randomUUID.ts"],"sourcesContent":["import type {\n  Extends,\n  FixNeverArrayRecursive,\n  IfNonEmptyArray,\n  NullToUndefined\n} from \"@rzl-zone/ts-types-plus\";\n\nimport { isNonEmptyArray } from \"@/predicates/is/isNonEmptyArray\";\n\n/** ---------------------------------\n * * ***Utility: `getRandomItem`.***\n * ---------------------------------\n * **Function to get a random element from a given array.**\n * @template T - The type of the input array.\n * @param {*} array - The input array, can be `null`, `undefined`, or an empty array.\n * @returns\n * - If `array` is a non-empty tuple, returns one of its elements.\n * - If `array` is empty, `null`, or `undefined`, returns `undefined`.\n * @example\n * getRandomItem([]);\n * // ➔ undefined\n * getRandomItem(null);\n * // ➔ undefined\n * getRandomItem(undefined);\n * // ➔ undefined\n * getRandomItem([1, 2, 3, 4]);\n * // ➔ number\n * getRandomItem([\"apple\", \"banana\", \"cherry\"]);\n * // ➔ string\n * getRandomItem([\"apple\", 123, true]);\n * // ➔ string | number | boolean\n * getRandomItem([\"apple\", 123, true, null]);\n * // ➔ string | number | boolean | undefined\n * getRandomItem([\"apple\", 123, true, undefined]);\n * // ➔ string | number | boolean | undefined\n *\n * // Tuple example:\n * const tuple = [1, \"two\", true] as const;\n * getRandomItem(tuple); // 1 | \"two\" | true\n */\nexport function getRandomItem(array: undefined): undefined;\nexport function getRandomItem(array: []): undefined;\nexport function getRandomItem<T extends readonly unknown[]>(\n  array: T\n): T extends never[][]\n  ? undefined\n  : number extends T[\"length\"]\n    ? NullToUndefined<FixNeverArrayRecursive<T[number]>>\n    : IfNonEmptyArray<\n        T,\n        NullToUndefined<FixNeverArrayRecursive<T[number]>>,\n        undefined\n      >;\nexport function getRandomItem<T extends readonly unknown[] | undefined | null>(\n  array: T\n): T extends readonly unknown[]\n  ? NullToUndefined<FixNeverArrayRecursive<T[number]>> | undefined\n  : undefined;\nexport function getRandomItem<T>(array: T): unknown extends T\n  ? unknown\n  : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    Extends<any[] | readonly any[], T> extends true\n    ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n    : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      Extends<any[], T> extends true\n      ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n      : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        Extends<readonly any[], T> extends true\n        ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n        : undefined;\nexport function getRandomItem(array: unknown): unknown {\n  if (!isNonEmptyArray(array)) return undefined;\n\n  const randomIndex = Math.floor(Math.random() * (array.length || 0));\n  return array[randomIndex];\n}\n","import { isNumber } from \"@/predicates/is/isNumber\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** -----------------------------------------------------------------------\n * * ***Utility: `randomInt`.***\n * ------------------------------------------------------------------------\n * **Generates a random integer within a specified range (inclusive).**\n * - **Generates a random integer between `min` and `max` (inclusive), with safety constraints:**\n *    - `min` will be forced to be at least `1`.\n *    - `max` will be capped at `Number.MAX_SAFE_INTEGER`.\n * @param {number} min - The minimum value (inclusive), must be an integer.\n * @param {number} max - The maximum value (inclusive), must be an integer.\n * @returns {number} A random integer N where `min ≤ N ≤ max`.\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `min` or `max` is not an integer, or value is `Number.MIN_VALUE`.\n * - `min` is greater than `max`.\n * @example\n * randomInt(1, 10);   // ➔ returns 1 up-to 10 (random)\n * randomInt(50, 100); // ➔ returns 50 up-to 100 (random)\n * randomInt(5, 5);    // ➔ always returns 5 (exact)\n * randomInt(-5, 3);   // ➔ always returns ≥ 1, since min is adjusted (exact)\n * randomInt(1, Number.MAX_SAFE_INTEGER + 10000);\n * // ➔ still safely capped at MAX_SAFE_INTEGER\n * randomInt(Number.MIN_VALUE, 3);\n * // ➔ Error, min or max cant be as `Number.MIN_VALUE` value.\n */\nexport const randomInt = (min: number, max: number): number => {\n  if (!isInteger(min) || !isInteger(max)) {\n    throw new TypeError(\n      `First parameter (\\`min\\`) and second parameter (\\`max\\`) must be of type \\`integer-number\\`${minValueNote(\n        min,\n        max\n      )}value, but received: ['min': \\`${getPreciseType(\n        min\n      )}\\` - (with value: \\`${safeStableStringify(min, {\n        keepUndefined: true\n      })})\\`, 'max': \\`${getPreciseType(max)}\\` - (with value: \\`${safeStableStringify(\n        max,\n        {\n          keepUndefined: true\n        }\n      )}\\`)].`\n    );\n  }\n  if (min > max) {\n    throw new RangeError(\n      `First parameter (\\`min\\`) must be less than or equal to second parameter (\\`max\\`), but received: ['min': ${formatValue(\n        min\n      )} - (with value: \\`${safeStableStringify(min, {\n        keepUndefined: true\n      })})\\`, 'max': ${formatValue(max)} - (with value: \\`${safeStableStringify(\n        max,\n        {\n          keepUndefined: true\n        }\n      )})\\`].`\n    );\n  }\n\n  // Ensure `min` is at least 1\n  min = Math.max(1, min);\n\n  // Ensure `max` does not exceed Number.MAX_SAFE_INTEGER\n  max = Math.min(Number.MAX_SAFE_INTEGER, max);\n\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n};\n\nconst formatValue = (value: unknown): string => {\n  return isNumber(value, { includeNaN: true })\n    ? value === Number.MIN_VALUE\n      ? \"`Number.MIN_VALUE`\"\n      : `${value}`\n    : `\\`${getPreciseType(value)}\\``;\n};\n\nconst minValueNote = (...values: unknown[]) => {\n  return values.some(\n    (v) => isNumber(v, { includeNaN: true }) && v === Number.MIN_VALUE\n  )\n    ? \" and can't be `Number.MIN_VALUE` \"\n    : \" \";\n};\n","import { randomInt } from \"./randomInt\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\ntype OptionsRandomIntByLength = {\n  /** * Minimum length of the random number, the `allowed minimal value` `integer` is `1` `and not bigger than value of` `maxLength`, defaultValue: `1`.\n   *\n   * @default 1\n   */\n  minLength?: number;\n  /** * Maximum length of the random number, the `allowed maximal value` `integer` is `16`, defaultValue: `16`.\n   *\n   * @default 16\n   */\n  maxLength?: number;\n  /** * If true, prevents the result from being zero, defaultValue: `false`.\n   *\n   * @default false\n   */\n  avoidZero?: boolean;\n};\n\n/** ----------------------------------------------------------------------------\n * * ***Utility: `randomIntByLength`.***\n * -----------------------------------------------------------------------------\n * **Generates a random integer within a specified range of digit lengths.**\n * @description\n * This function allows generating random integers that strictly conform to a specified minimum and\n * maximum digit length, it is useful for scenarios such as generating realistic-looking IDs, codes,\n * or random test data.\n * - **The function ensures:**\n *    - `minLength` is at least 1 and not greater than `maxLength`.\n *    - `maxLength` is no more than 16 (due to JavaScript's `Number.MAX_SAFE_INTEGER`).\n *    - If `avoidZero` is `true`, ensures that `0` is never returned.\n * @param {OptionsRandomIntByLength} [options] - Configuration options.\n * @param {OptionsRandomIntByLength[\"minLength\"]} [options.minLength=1] - Minimum number of digits (must be ≥ `1` and ≤ `maxLength`).\n * @param {OptionsRandomIntByLength[\"maxLength\"]} [options.maxLength=16] - Maximum number of digits (must be ≤ `16`).\n * @param {OptionsRandomIntByLength[\"avoidZero\"]} [options.avoidZero=false] - If true, will ensure the result is never zero.\n * @returns {number} A randomly generated integer within the specified constraints.\n * @throws **{@link TypeError | `TypeError`}** if parameters are invalid, such as:\n * - `minLength` < `1`\n * - `maxLength` > `16`\n * - `minLength` > `maxLength`\n * - non-integer values for `minLength` or `maxLength`\n * @example\n * randomIntByLength({ minLength: 3, maxLength: 5 });\n * // ➔ `4829` (random), `192` (random) or `71492` (random).\n * randomIntByLength({ minLength: 4, maxLength: 4 });\n * // ➔ `5930` (exact 4 digits)\n * randomIntByLength({ avoidZero: true });\n * // ➔ never 0\n */\nexport const randomIntByLength = (\n  options?: OptionsRandomIntByLength\n): number => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) {\n    options = {};\n  }\n\n  const { minLength = 1, maxLength = 16, avoidZero = false } = options;\n\n  assertIsBoolean(avoidZero, {\n    message({ currentType, validType }) {\n      return `Parameters \\`avoidZero\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`;\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n        minLength\n      )}\\` - (with value: ${safeStableStringify(minLength, {\n        keepUndefined: true\n      })}), 'maxLength': \\`${getPreciseType(\n        maxLength\n      )}\\` - (with value: ${safeStableStringify(maxLength, {\n        keepUndefined: true\n      })})].`\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 16 || minLength > maxLength) {\n    throw new RangeError(\n      `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 16, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n    );\n  }\n\n  // Generate a random length between minLength and maxLength\n  const randomLength =\n    minLength === maxLength ? minLength : randomInt(minLength, maxLength);\n\n  // Define min and max value based on the selected length\n  const minValue = 10 ** (randomLength - 1); // Example: minLength=3 ➔ minValue=100\n  const maxValue = 10 ** randomLength - 1; // Example: maxLength=4 ➔ maxValue=9999\n\n  // Generate a random number within the valid range\n  let result = randomInt(minValue, maxValue);\n\n  // Ensure the number is not zero if `avoidZero` is true\n  if (avoidZero && result === 0) {\n    result = minValue; // Assign the smallest valid number instead of looping\n  }\n\n  return result;\n};\n","import type { OptionsRandomStr } from \"./_private/randomSTR.types\";\n\nimport { randomInt } from \"../integer/randomInt\";\n\nimport { isNaN } from \"@/predicates/is/isNaN\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\n\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** ---------------------------------------------------------------------------------\n * * ***Utility: `randomStr`.***\n * ---------------------------------------------------------------------------------\n * **Generates a random alphanumeric string or number with a specified length range.**\n * @description\n * This function allows you to generate random strings or numbers with fully\n * customizable options, such as length range, character sets, inclusion of\n * additional characters, and whether to avoid whitespace.\n * @param {OptionsRandomStr} [options] - Configuration options for generating the string.\n * @param {OptionsRandomStr[\"minLength\"]} [options.minLength=40] - Minimum length of the generated string (must be `≥` `1`).\n * @param {OptionsRandomStr[\"maxLength\"]} [options.maxLength=40] - Maximum length of the generated string (must be `≤` `5000`).\n * @param {OptionsRandomStr[\"type\"]} [options.type=\"string\"] - Whether to generate a general alphanumeric string or purely numeric string.\n * @param {OptionsRandomStr[\"avoidWhiteSpace\"]} [options.avoidWhiteSpace=true] - If true, removes all whitespace, tabs, and newlines from the character set before generating.\n * @param {OptionsRandomStr[\"replaceGenStr\"]} [options.replaceGenStr] - A custom character set to use when `type` is `\"string\"`.\n * @param {OptionsRandomStr[\"replaceGenInt\"]} [options.replaceGenInt] - A custom character set to use when `type` is `\"number\"`.\n * @param {OptionsRandomStr[\"addChar\"]} [options.addChar] - Additional characters to always include in the character set.\n * @returns {string} The randomly generated string or numeric string of the desired length.\n * @throws **{@link TypeError | `TypeError`}** if provided options are invalid (such as minLength > maxLength, invalid type, or empty character set).\n * @example\n * randomStr();\n * // ➔ Generates a 40-character random alphanumeric string\n * randomStr({ minLength: 10, maxLength: 20 });\n * // ➔ Generates a string between 10 and 20 characters\n * randomStr({ type: \"number\", minLength: 5, maxLength: 5 });\n * // ➔ \"48302\"\n * randomStr({ replaceGenStr: \"ABC \", avoidWhiteSpace: false });\n * // ➔ String using A, B, C and space\n * randomStr({ addChar: \"!@#\", minLength: 15, maxLength: 15 });\n * // ➔ Guaranteed to include !@# in the set\n */\nexport const randomStr = (options?: OptionsRandomStr): string => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) {\n    options = {};\n  }\n\n  const {\n    minLength = 40,\n    maxLength = 40,\n    type = \"string\",\n    avoidWhiteSpace = true\n  } = options;\n\n  // Validate `avoidWhiteSpace`\n  assertIsBoolean(avoidWhiteSpace, {\n    message({ currentType, validType }) {\n      return `Parameters \\`avoidWhiteSpace\\` property of the \\`options\\` (first-parameter) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`;\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n        minLength\n      )}\\` - (with value: ${safeStableStringify(minLength, {\n        keepUndefined: true\n      })}), 'maxLength': \\`${getPreciseType(\n        maxLength\n      )}\\` - (with value: ${safeStableStringify(maxLength, {\n        keepUndefined: true\n      })})].`\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 5000 || minLength > maxLength) {\n    throw new RangeError(\n      `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 5000, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n    );\n  }\n\n  // Validate `type` value props (is not typeof)\n  if (type !== \"string\" && type !== \"number\") {\n    throw new TypeError(\n      `Parameter \\`type\\` must be of type \\`string\\` with value one of \"string\" | \"number\", but received: \\`${getPreciseType(\n        type\n      )}\\`, with value: ${safeStableStringify(type, {\n        keepUndefined: true\n      })}.`\n    );\n  }\n\n  // Generate a random length within the range\n  const length = randomInt(minLength, maxLength);\n\n  // Function to clean characters based on `avoidWhiteSpace`\n  const cleanCharacters = (charSet: string) => {\n    return avoidWhiteSpace ? charSet.replace(/\\s|\\n|\\t/g, \"\") : charSet;\n  };\n\n  // Define character sets\n  const defaultNumberSet = \"0123456789\";\n  const defaultStringSet =\n    \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n\n  const baseCharSet =\n    type === \"number\"\n      ? ((!isNaN(Number(options.replaceGenInt))\n          ? options.replaceGenInt\n          : undefined) ?? defaultNumberSet)\n      : ((options.replaceGenStr ? options.replaceGenStr : undefined) ??\n        defaultStringSet);\n\n  // Get the final character set\n  const characterSet = cleanCharacters(baseCharSet) + (options.addChar || \"\");\n\n  // Ensure characterSet is not empty\n  if (!characterSet.length) {\n    const errCharSet = () => {\n      if (type === \"number\") {\n        if (avoidWhiteSpace) {\n          return \"If `avoidWhiteSpace` is true, and `replaceGenInt` cant be empty-string value, ensure `replaceGenInt` has valid characters and non-nan string number.\";\n        }\n        return \"Ensure `replaceGenInt` has valid characters and not a NaN number string while convert to number.\";\n      }\n      return \"Ensure `replaceGenStr` has valid characters and non empty string.\";\n    };\n\n    throw new Error(`Character set is empty. ${errCharSet()}`);\n  }\n\n  // Generate random string\n  let result = \"\";\n  for (let i = 0; i < length; i++) {\n    result += characterSet.charAt(\n      Math.floor(Math.random() * characterSet.length)\n    );\n  }\n\n  return result;\n};\n","import { isBoolean } from \"@/predicates/is/isBoolean\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/**\n * Configuration options for `randomUUID()`.\n */\ntype OptionsRandomUUID = {\n  /**\n   * Specifies which UUID version to generate.\n   *\n   * - `\"v4\"` — Fully random UUID (RFC 4122). No timestamp, no ordering guarantees.\n   * - `\"v7\"` — Time-ordered UUID (RFC 9562). Uses Unix timestamp + randomness.\n   *\n   * @default \"v4\"\n   *\n   * @example\n   * // Random v4 UUID\n   * randomUUID({ version: \"v4\" }); // ➔ \"3ec0de5a-b8a9-4ffb-a62a-fcc76851e9c2\"\n   *\n   * @example\n   * // Time-ordered v7 UUID\n   * randomUUID({ version: \"v7\" }); // ➔ \"0199f3f6-3c5e-744b-affa-46b2cfd496f8\"\n   */\n  version?: \"v4\" | \"v7\";\n\n  /**\n   * Enables monotonic sequencing for UUID v7.\n   *\n   * - Guarantees that multiple UUIDs generated within the same millisecond\n   *   are strictly non-decreasing (lexicographically and timestamp-wise).\n   * - Only valid when `version === \"v7\"`. Using with `v4` will throw a `TypeError`.\n   * - Useful for database inserts, logs, or any system where order matters.\n   *\n   * @default false\n   *\n   * @example\n   * // Monotonic v7 UUIDs\n   * const a = randomUUID({ version: \"v7\", monotonic: true });\n   * const b = randomUUID({ version: \"v7\", monotonic: true });\n   * console.log(a < b); // true, guaranteed\n   */\n  monotonic?: boolean;\n};\n\n/** -----------------------------------------------------------------------\n * * ***Utility: `randomUUID`.***\n * ------------------------------------------------------------------------\n * **Generates a UUID string according to the specified version and options.**\n *\n * - **Supported versions**:\n *    - **`\"v4\"` (default)** ➔ Fully random UUID, RFC 4122 compliant.\n *        - Uses `crypto.randomUUID()` if available.\n *        - Falls back to `crypto.getRandomValues()` or `Math.random()`\n *          if needed.\n *    - **`\"v7\"`** ➔ Time-ordered UUID, RFC 9562 compliant.\n *        - Timestamp (Unix ms, 48 bits) + 80 bits randomness.\n *        - Good for database indexing / sorting.\n *    - **`\"v7\"` + `monotonic: true`** ➔ Ensures strictly non-decreasing UUIDs\n *      for multiple calls in the same millisecond (per-process).\n *\n * - **Behavior / Safety Notes**:\n *    - **v4**: Fully random; probability of duplicates is astronomically low.\n *    - **v7**: Time-ordered; collisions extremely unlikely unless same ms + random repeat.\n *    - **Monotonic v7**: Guaranteed ordering per-process if multiple UUIDs are generated\n *      in the same millisecond.\n *    - **All versions**: Fallback safely if `crypto` APIs are unavailable.\n *\n * @param {object} [options] - Optional settings object.\n * @param {\"v4\" | \"v7\"} [options.version=\"v4\"] - UUID version to generate.\n * @param {boolean} [options.monotonic=false] - For v7 only: generate monotonic UUIDs\n *                                              to maintain strict lexicographic order\n *                                              when generating multiple UUIDs within the same ms.\n *\n * @returns {string} A 36-character UUID string compliant with the selected version.\n *\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `options` is not a plain object.\n * - `options.version` is provided but not a string.\n * - `options.monotonic` is provided but not a boolean.\n * - `monotonic: true` is used with `version` other than `\"v7\"`.\n * @throws **{@link RangeError | `RangeError`}** if `options.version` is provided but not `\"v4\"` or `\"v7\"`.\n *\n * @example\n * // Default (v4)\n * const id = randomUUID();\n * // ➔ \"3b12f1df-5232-4804-897e-917bf397618a\"\n *\n * @example\n * // Explicit v4\n * const id4 = randomUUID({ version: \"v4\" });\n *\n * @example\n * // Time-ordered v7\n * const id7 = randomUUID({ version: \"v7\" });\n * // ➔ \"018f48d2-84c1-7ccd-b5a3-2f9463b3a889\"\n *\n * @example\n * // Monotonic v7\n * const a = randomUUID({ version: \"v7\", monotonic: true });\n * const b = randomUUID({ version: \"v7\", monotonic: true });\n * // a < b lexicographically (guaranteed)\n *\n * @example\n * // Throws TypeError\n * randomUUID(\"v4\" as any); // options must be object\n * randomUUID({ version: 123 as any }); // version must be string\n * randomUUID({ version: \"v4\", monotonic: true } as any); // monotonic only for v7\n *\n * @example\n * // Throws RangeError\n * randomUUID({ version: \"v1\" as any }); // unsupported version\n */\nexport function randomUUID(options: OptionsRandomUUID = {}): string {\n  // Validate options is a plain object if provided\n  if (!isPlainObject(options)) {\n    throw new TypeError(\n      `First parameter (\\`options\\`) must be a plain object with optional properties \\`version\\` and \\`monotonic\\`, but received: \\`${getPreciseType(\n        options\n      )}\\` - (with value: \\`${safeStableStringify(options, { keepUndefined: true })}\\`).`\n    );\n  }\n\n  const { version = \"v4\", monotonic = false } = options;\n\n  // Validate version type\n  if (!isNonEmptyString(version)) {\n    throw new TypeError(\n      `Parameter \\`version\\` property of the \\`options\\` (first parameter) must be a \\`string\\` of either \"v4\" or \"v7\", but received type: \\`${getPreciseType(\n        version\n      )}\\` - (with value: \\`${safeStableStringify(version, { keepUndefined: true })}\\`).`\n    );\n  }\n\n  if (version !== \"v4\" && version !== \"v7\") {\n    throw new RangeError(\n      `Unsupported UUID version. Allowed values are \"v4\" or \"v7\". (received: \\`${safeStableStringify(\n        version,\n        {\n          keepUndefined: true\n        }\n      )}\\`).`\n    );\n  }\n\n  // Validate monotonic type\n  if (!isBoolean(monotonic)) {\n    throw new TypeError(\n      `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) must be a \\`boolean\\` when provided, but received type: \\`${getPreciseType(\n        monotonic\n      )}\\` - (with value: \\`${safeStableStringify(monotonic, {\n        keepUndefined: true\n      })}\\`).`\n    );\n  }\n\n  // monotonic only allowed with v7\n  if (monotonic && version !== \"v7\") {\n    throw new TypeError(\n      `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) is only supported for version \"v7\". Received: version=${safeStableStringify(\n        version,\n        { keepUndefined: true }\n      )}.`\n    );\n  }\n\n  if (version === \"v4\") {\n    return generateUUIDv4();\n  }\n\n  // version === \"v7\"\n  return generateUUIDv7({ monotonic });\n}\n\n//todo: Helpers & Implementations\n\nfunction hasCryptoGetRandomValues(): boolean {\n  return (\n    typeof crypto !== \"undefined\" &&\n    typeof crypto.getRandomValues === \"function\"\n  );\n}\n\nfunction hasCryptoRandomUUID(): boolean {\n  return (\n    typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\"\n  );\n}\n\nfunction getRandomBytes(len: number): Uint8Array {\n  if (hasCryptoGetRandomValues()) {\n    return crypto.getRandomValues(new Uint8Array(len));\n  }\n  // Fallback: not cryptographically secure, but avoids crash\n  const arr = new Uint8Array(len);\n  for (let i = 0; i < len; i++) {\n    arr[i] = Math.floor(Math.random() * 256);\n  }\n  return arr;\n}\n\nconst byteToHex: string[] = (() => {\n  const arr: string[] = [];\n  for (let i = 0; i < 256; ++i) {\n    arr.push((i + 0x100).toString(16).substring(1));\n  }\n  return arr;\n})();\n\nfunction generateUUIDv4(): string {\n  // Prefer native if available\n  if (hasCryptoRandomUUID()) {\n    return crypto.randomUUID();\n  }\n\n  // If crypto.getRandomValues available, use it for 16 bytes\n  if (hasCryptoGetRandomValues()) {\n    const rnd = crypto.getRandomValues(new Uint8Array(16));\n\n    if (\n      !rnd[0] ||\n      !rnd[1] ||\n      !rnd[2] ||\n      !rnd[3] ||\n      !rnd[4] ||\n      !rnd[5] ||\n      !rnd[6] ||\n      !rnd[7] ||\n      !rnd[8] ||\n      !rnd[9] ||\n      !rnd[10] ||\n      !rnd[11] ||\n      !rnd[12] ||\n      !rnd[13] ||\n      !rnd[14] ||\n      !rnd[15]\n    ) {\n      return \"\";\n    }\n\n    const byteToHex0 = byteToHex[rnd[0]];\n    const byteToHex1 = byteToHex[rnd[1]];\n\n    if (!byteToHex0 || !byteToHex1) return \"\";\n\n    // Per RFC 4122: set version and variant\n    rnd[6] = (rnd[6]! & 0x0f) | 0x40; // version 4\n    rnd[8] = (rnd[8]! & 0x3f) | 0x80; // variant 10xx\n\n    return (\n      byteToHex0 +\n      byteToHex1 +\n      byteToHex[rnd[2]] +\n      byteToHex[rnd[3]] +\n      \"-\" +\n      byteToHex[rnd[4]] +\n      byteToHex[rnd[5]] +\n      \"-\" +\n      byteToHex[rnd[6]] +\n      byteToHex[rnd[7]] +\n      \"-\" +\n      byteToHex[rnd[8]] +\n      byteToHex[rnd[9]] +\n      \"-\" +\n      byteToHex[rnd[10]] +\n      byteToHex[rnd[11]] +\n      byteToHex[rnd[12]] +\n      byteToHex[rnd[13]] +\n      byteToHex[rnd[14]] +\n      byteToHex[rnd[15]]\n    );\n  }\n\n  // Last-resort fallback using Math.random (not crypto-secure)\n  return \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, (c) => {\n    const r = (Math.random() * 16) | 0;\n    const v = c === \"x\" ? r : (r & 0x3) | 0x8;\n    return v.toString(16);\n  });\n}\n\n/* ---------------------------\n   Monotonic state (singleton per-process)\n   --------------------------- */\n\n/**\n * Internal monotonic state:\n * - lastTimestampMs: last generated timestamp (ms)\n * - lastRand: last random 10-byte block used for v7 (used to increment on same ms)\n */\nconst monotonicState: {\n  lastTimestampMs: number;\n  lastRand: Uint8Array | null;\n} = {\n  lastTimestampMs: -1,\n  lastRand: null\n};\n\nfunction incrementUint8ArrayBigEndian(arr: Uint8Array): boolean {\n  // Increment arr in big-endian order. Return true if overflowed back to zero.\n  for (let i = arr.length - 1; i >= 0; i--) {\n    if (arr[i] === 0xff) {\n      arr[i] = 0x00;\n      continue;\n    }\n\n    arr[i] = (arr[i]! + 1) & 0xff;\n\n    return false; // no overflow\n  }\n  // overflowed (wrapped to zero)\n  return true;\n}\n\nfunction generateUUIDv7({\n  monotonic = false\n}: { monotonic?: boolean } = {}): string {\n  const nowMs = Date.now();\n  const tsHex = BigInt(nowMs).toString(16).padStart(12, \"0\"); // 48 bits ➔ 12 hex chars\n\n  // We'll use 10 random bytes (80 bits)\n  let rand = getRandomBytes(10);\n\n  if (monotonic) {\n    // ensure monotonicState is consistent per-process\n    if (monotonicState.lastTimestampMs === nowMs && monotonicState.lastRand) {\n      // We are in the same ms bucket — increment lastRand (big-endian)\n      const copy = new Uint8Array(monotonicState.lastRand); // copy for use\n      const overflow = incrementUint8ArrayBigEndian(copy);\n      if (overflow) {\n        // Practically impossible (2^80 increments in 1ms). Throw to be safe.\n        throw new RangeError(\n          \"Monotonic UUID sequence overflow: too many UUIDs generated within the same millisecond.\"\n        );\n      }\n      // use incremented copy as rand\n      rand = copy;\n      // update state\n      monotonicState.lastRand = copy;\n    } else {\n      // New ms: generate fresh randomness and store\n      const fresh = getRandomBytes(10);\n      monotonicState.lastRand = new Uint8Array(fresh);\n      monotonicState.lastTimestampMs = nowMs;\n      rand = fresh;\n    }\n  }\n\n  // if (!rand[0] || !rand[2]) return \"\";\n  // If not monotonic, rand remains randomly generated above.\n\n  // Now set version & variant bits into proper positions.\n  // For v7 layout we used: timestamp (48 bits) + rand[0..9] (80 bits)\n  // We must set version nibble into high nibble of rand[0] (time_hi_and_version)\n  // and set variant bits into rand[2]'s high bits (clock_seq_hi_and_reserved)\n  rand[0] = rand[0] ? (rand[0] & 0x0f) | 0x70 : 0; // version 7 (0x7 << 4)\n  rand[2] = rand[2] ? (rand[2] & 0x3f) | 0x80 : 0; // variant 10xx\n\n  const randHex = Array.from(rand, (b) => byteToHex[b]).join(\"\");\n\n  // Assemble UUID groups:\n  // - 8 hex (timestamp[0..7])\n  // - 4 hex (timestamp[8..11])\n  // - 4 hex (rand[0..1]) ➔ contains version in high nibble of rand[0]\n  // - 4 hex (rand[2..3]) ➔ contains variant in high bits of rand[2]\n  // - 12 hex (rand[4..9])\n  const part1 = tsHex.slice(0, 8);\n  const part2 = tsHex.slice(8, 12);\n  const part3 = randHex.slice(0, 4);\n  const part4 = randHex.slice(4, 8);\n  const part5 = randHex.slice(8, 20);\n\n  return [part1, part2, part3, part4, part5].join(\"-\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsEA,SAAgB,cAAc,OAAyB;CACrD,IAAI,CAAC,gBAAgB,KAAK,GAAG,OAAO;CAGpC,OAAO,MADa,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,UAAU,EACzC;AACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/CA,MAAa,aAAa,KAAa,QAAwB;CAC7D,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,GAAG,GACnC,MAAM,IAAI,UACR,8FAA8F,aAC5F,KACA,GACF,EAAE,iCAAiC,eACjC,GACF,EAAE,sBAAsB,oBAAoB,KAAK,EAC/C,eAAe,KACjB,CAAC,EAAE,gBAAgB,eAAe,GAAG,EAAE,sBAAsB,oBAC3D,KACA,EACE,eAAe,KACjB,CACF,EAAE,MACJ;CAEF,IAAI,MAAM,KACR,MAAM,IAAI,WACR,6GAA6G,YAC3G,GACF,EAAE,oBAAoB,oBAAoB,KAAK,EAC7C,eAAe,KACjB,CAAC,EAAE,cAAc,YAAY,GAAG,EAAE,oBAAoB,oBACpD,KACA,EACE,eAAe,KACjB,CACF,EAAE,MACJ;CAIF,MAAM,KAAK,IAAI,GAAG,GAAG;CAGrB,MAAM,KAAK,IAAI,OAAO,kBAAkB,GAAG;CAE3C,OAAO,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,MAAM,EAAE,IAAI;AACvD;AAEA,MAAM,eAAe,UAA2B;CAC9C,OAAO,SAAS,OAAO,EAAE,YAAY,KAAK,CAAC,IACvC,UAAU,OAAO,YACf,uBACA,GAAG,UACL,KAAK,eAAe,KAAK,EAAE;AACjC;AAEA,MAAM,gBAAgB,GAAG,WAAsB;CAC7C,OAAO,OAAO,MACX,MAAM,SAAS,GAAG,EAAE,YAAY,KAAK,CAAC,KAAK,MAAM,OAAO,SAC3D,IACI,sCACA;AACN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC7BA,MAAa,qBACX,YACW;CAEX,IAAI,CAAC,cAAc,OAAO,GACxB,UAAU,CAAC;CAGb,MAAM,EAAE,YAAY,GAAG,YAAY,IAAI,YAAY,UAAU;CAE7D,gBAAgB,WAAW,EACzB,QAAQ,EAAE,aAAa,aAAa;EAClC,OAAO,8CAA8C,UAAU,sBAAsB,YAAY;CACnG,EACF,CAAC;CAGD,IAAI,CAAC,UAAU,SAAS,KAAK,CAAC,UAAU,SAAS,GAC/C,MAAM,IAAI,UACR,gHAAgH,eAC9G,SACF,EAAE,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,KACjB,CAAC,EAAE,oBAAoB,eACrB,SACF,EAAE,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,KACjB,CAAC,EAAE,IACL;CAIF,IAAI,YAAY,KAAK,YAAY,MAAM,YAAY,WACjD,MAAM,IAAI,WACR,uJAAuJ,UAAU,qBAAqB,UAAU,KAClM;CAIF,MAAM,eACJ,cAAc,YAAY,YAAY,UAAU,WAAW,SAAS;CAGtE,MAAM,WAAW,OAAO,eAAe;CAIvC,IAAI,SAAS,UAAU,UAHN,MAAM,eAAe,CAGG;CAGzC,IAAI,aAAa,WAAW,GAC1B,SAAS;CAGX,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACpEA,MAAa,aAAa,YAAuC;CAE/D,IAAI,CAAC,cAAc,OAAO,GACxB,UAAU,CAAC;CAGb,MAAM,EACJ,YAAY,IACZ,YAAY,IACZ,OAAO,UACP,kBAAkB,SAChB;CAGJ,gBAAgB,iBAAiB,EAC/B,QAAQ,EAAE,aAAa,aAAa;EAClC,OAAO,kGAAkG,UAAU,sBAAsB,YAAY;CACvJ,EACF,CAAC;CAGD,IAAI,CAAC,UAAU,SAAS,KAAK,CAAC,UAAU,SAAS,GAC/C,MAAM,IAAI,UACR,gHAAgH,eAC9G,SACF,EAAE,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,KACjB,CAAC,EAAE,oBAAoB,eACrB,SACF,EAAE,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,KACjB,CAAC,EAAE,IACL;CAIF,IAAI,YAAY,KAAK,YAAY,OAAQ,YAAY,WACnD,MAAM,IAAI,WACR,yJAAyJ,UAAU,qBAAqB,UAAU,KACpM;CAIF,IAAI,SAAS,YAAY,SAAS,UAChC,MAAM,IAAI,UACR,wGAAwG,eACtG,IACF,EAAE,kBAAkB,oBAAoB,MAAM,EAC5C,eAAe,KACjB,CAAC,EAAE,EACL;CAIF,MAAM,SAAS,UAAU,WAAW,SAAS;CAG7C,MAAM,mBAAmB,YAAoB;EAC3C,OAAO,kBAAkB,QAAQ,QAAQ,aAAa,EAAE,IAAI;CAC9D;CAgBA,MAAM,eAAe,gBARnB,SAAS,YACH,CAAC,MAAM,OAAO,QAAQ,aAAa,CAAC,IAClC,QAAQ,gBACR,WAAc,gBAChB,QAAQ,gBAAgB,QAAQ,gBAAgB,WAClD,gEAG0C,KAAK,QAAQ,WAAW;CAGxE,IAAI,CAAC,aAAa,QAAQ;EACxB,MAAM,mBAAmB;GACvB,IAAI,SAAS,UAAU;IACrB,IAAI,iBACF,OAAO;IAET,OAAO;GACT;GACA,OAAO;EACT;EAEA,MAAM,IAAI,MAAM,2BAA2B,WAAW,GAAG;CAC3D;CAGA,IAAI,SAAS;CACb,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAC1B,UAAU,aAAa,OACrB,KAAK,MAAM,KAAK,OAAO,IAAI,aAAa,MAAM,CAChD;CAGF,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC5BA,SAAgB,WAAW,UAA6B,CAAC,GAAW;CAElE,IAAI,CAAC,cAAc,OAAO,GACxB,MAAM,IAAI,UACR,gIAAgI,eAC9H,OACF,EAAE,sBAAsB,oBAAoB,SAAS,EAAE,eAAe,KAAK,CAAC,EAAE,KAChF;CAGF,MAAM,EAAE,UAAU,MAAM,YAAY,UAAU;CAG9C,IAAI,CAAC,iBAAiB,OAAO,GAC3B,MAAM,IAAI,UACR,yIAAyI,eACvI,OACF,EAAE,sBAAsB,oBAAoB,SAAS,EAAE,eAAe,KAAK,CAAC,EAAE,KAChF;CAGF,IAAI,YAAY,QAAQ,YAAY,MAClC,MAAM,IAAI,WACR,2EAA2E,oBACzE,SACA,EACE,eAAe,KACjB,CACF,EAAE,KACJ;CAIF,IAAI,CAAC,UAAU,SAAS,GACtB,MAAM,IAAI,UACR,mIAAmI,eACjI,SACF,EAAE,sBAAsB,oBAAoB,WAAW,EACrD,eAAe,KACjB,CAAC,EAAE,KACL;CAIF,IAAI,aAAa,YAAY,MAC3B,MAAM,IAAI,UACR,+HAA+H,oBAC7H,SACA,EAAE,eAAe,KAAK,CACxB,EAAE,EACJ;CAGF,IAAI,YAAY,MACd,OAAO,eAAe;CAIxB,OAAO,eAAe,EAAE,UAAU,CAAC;AACrC;AAIA,SAAS,2BAAoC;CAC3C,OACE,OAAO,WAAW,eAClB,OAAO,OAAO,oBAAoB;AAEtC;AAEA,SAAS,sBAA+B;CACtC,OACE,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe;AAElE;AAEA,SAAS,eAAe,KAAyB;CAC/C,IAAI,yBAAyB,GAC3B,OAAO,OAAO,gBAAgB,IAAI,WAAW,GAAG,CAAC;CAGnD,MAAM,MAAM,IAAI,WAAW,GAAG;CAC9B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,KACvB,IAAI,KAAK,KAAK,MAAM,KAAK,OAAO,IAAI,GAAG;CAEzC,OAAO;AACT;AAEA,MAAM,mBAA6B;CACjC,MAAM,MAAgB,CAAC;CACvB,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,EAAE,GACzB,IAAI,MAAM,IAAI,KAAO,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;CAEhD,OAAO;AACT,GAAG;AAEH,SAAS,iBAAyB;CAEhC,IAAI,oBAAoB,GACtB,OAAO,OAAO,WAAW;CAI3B,IAAI,yBAAyB,GAAG;EAC9B,MAAM,MAAM,OAAO,gBAAgB,IAAI,WAAW,EAAE,CAAC;EAErD,IACE,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,MACL,CAAC,IAAI,OACL,CAAC,IAAI,OACL,CAAC,IAAI,OACL,CAAC,IAAI,OACL,CAAC,IAAI,OACL,CAAC,IAAI,KAEL,OAAO;EAGT,MAAM,aAAa,UAAU,IAAI;EACjC,MAAM,aAAa,UAAU,IAAI;EAEjC,IAAI,CAAC,cAAc,CAAC,YAAY,OAAO;EAGvC,IAAI,KAAM,IAAI,KAAM,KAAQ;EAC5B,IAAI,KAAM,IAAI,KAAM,KAAQ;EAE5B,OACE,aACA,aACA,UAAU,IAAI,MACd,UAAU,IAAI,MACd,MACA,UAAU,IAAI,MACd,UAAU,IAAI,MACd,MACA,UAAU,IAAI,MACd,UAAU,IAAI,MACd,MACA,UAAU,IAAI,MACd,UAAU,IAAI,MACd,MACA,UAAU,IAAI,OACd,UAAU,IAAI,OACd,UAAU,IAAI,OACd,UAAU,IAAI,OACd,UAAU,IAAI,OACd,UAAU,IAAI;CAElB;CAGA,OAAO,uCAAuC,QAAQ,UAAU,MAAM;EACpE,MAAM,IAAK,KAAK,OAAO,IAAI,KAAM;EAEjC,QADU,MAAM,MAAM,IAAK,IAAI,IAAO,GAC7B,SAAS,EAAE;CACtB,CAAC;AACH;;;;;;AAWA,MAAM,iBAGF;CACF,iBAAiB;CACjB,UAAU;AACZ;AAEA,SAAS,6BAA6B,KAA0B;CAE9D,KAAK,IAAI,IAAI,IAAI,SAAS,GAAG,KAAK,GAAG,KAAK;EACxC,IAAI,IAAI,OAAO,KAAM;GACnB,IAAI,KAAK;GACT;EACF;EAEA,IAAI,KAAM,IAAI,KAAM,IAAK;EAEzB,OAAO;CACT;CAEA,OAAO;AACT;AAEA,SAAS,eAAe,EACtB,YAAY,UACe,CAAC,GAAW;CACvC,MAAM,QAAQ,KAAK,IAAI;CACvB,MAAM,QAAQ,OAAO,KAAK,EAAE,SAAS,EAAE,EAAE,SAAS,IAAI,GAAG;CAGzD,IAAI,OAAO,eAAe,EAAE;CAE5B,IAAI,WAEF,IAAI,eAAe,oBAAoB,SAAS,eAAe,UAAU;EAEvE,MAAM,OAAO,IAAI,WAAW,eAAe,QAAQ;EAEnD,IADiB,6BAA6B,IACnC,GAET,MAAM,IAAI,WACR,yFACF;EAGF,OAAO;EAEP,eAAe,WAAW;CAC5B,OAAO;EAEL,MAAM,QAAQ,eAAe,EAAE;EAC/B,eAAe,WAAW,IAAI,WAAW,KAAK;EAC9C,eAAe,kBAAkB;EACjC,OAAO;CACT;CAUF,KAAK,KAAK,KAAK,KAAM,KAAK,KAAK,KAAQ,MAAO;CAC9C,KAAK,KAAK,KAAK,KAAM,KAAK,KAAK,KAAQ,MAAO;CAE9C,MAAM,UAAU,MAAM,KAAK,OAAO,MAAM,UAAU,EAAE,EAAE,KAAK,EAAE;CAc7D,OAAO;EANO,MAAM,MAAM,GAAG,CAMjB;EALE,MAAM,MAAM,GAAG,EAKV;EAJL,QAAQ,MAAM,GAAG,CAIL;EAHZ,QAAQ,MAAM,GAAG,CAGE;EAFnB,QAAQ,MAAM,GAAG,EAES;CAAC,EAAE,KAAK,GAAG;AACrD"}
+{"version":3,"file":"index.js","names":["errorMsg","errorMsg","errorMsg"],"sources":["../../src/generators/random/array/getRandomItem.ts","../../src/generators/random/integer/randomInt.ts","../../src/generators/random/integer/randomIntByLength.ts","../../src/generators/random/string/randomStr.ts","../../src/generators/random/uuid/randomUUID.ts"],"sourcesContent":["import type {\n  Extends,\n  FixNeverArrayRecursive,\n  IfNonEmptyArray,\n  NullToUndefined\n} from \"@rzl-zone/ts-types-plus\";\n\nimport { isNonEmptyArray } from \"@/predicates/is/isNonEmptyArray\";\n\n/** -------------------------------------------------------------------------------------\n * * ***Utility: `getRandomItem`.***\n * --------------------------------------------------------------------------------------\n * **Function to get a random element from a given array.**\n *\n * ---\n * @template T - The type of the input array.\n *\n * ---\n * @param {*} array - The input array, can be `null`, `undefined`, or an empty array.\n *\n * ---\n * @returns\n * - If `array` is a non-empty tuple, returns one of its elements.\n * - If `array` is empty, `null`, or `undefined`, returns `undefined`.\n *\n * ---\n * @example\n * getRandomItem([]);\n * // ➔ undefined\n * getRandomItem(null);\n * // ➔ undefined\n * getRandomItem(undefined);\n * // ➔ undefined\n * getRandomItem([1, 2, 3, 4]);\n * // ➔ number\n * getRandomItem([\"apple\", \"banana\", \"cherry\"]);\n * // ➔ string\n * getRandomItem([\"apple\", 123, true]);\n * // ➔ string | number | boolean\n * getRandomItem([\"apple\", 123, true, null]);\n * // ➔ string | number | boolean | undefined\n * getRandomItem([\"apple\", 123, true, undefined]);\n * // ➔ string | number | boolean | undefined\n *\n * // Tuple example:\n * const tuple = [1, \"two\", true] as const;\n * getRandomItem(tuple); // 1 | \"two\" | true\n */\nexport function getRandomItem(array: undefined): undefined;\nexport function getRandomItem(array: []): undefined;\nexport function getRandomItem<T extends readonly unknown[]>(\n  array: T\n): T extends never[][]\n  ? undefined\n  : number extends T[\"length\"]\n    ? NullToUndefined<FixNeverArrayRecursive<T[number]>>\n    : IfNonEmptyArray<\n        T,\n        NullToUndefined<FixNeverArrayRecursive<T[number]>>,\n        undefined\n      >;\nexport function getRandomItem<T extends readonly unknown[] | undefined | null>(\n  array: T\n): T extends readonly unknown[]\n  ? NullToUndefined<FixNeverArrayRecursive<T[number]>> | undefined\n  : undefined;\nexport function getRandomItem<T>(array: T): unknown extends T\n  ? unknown\n  : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    Extends<any[] | readonly any[], T> extends true\n    ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n    : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      Extends<any[], T> extends true\n      ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n      : // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        Extends<readonly any[], T> extends true\n        ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined\n        : undefined;\nexport function getRandomItem(array: unknown): unknown {\n  if (!isNonEmptyArray(array)) return undefined;\n\n  const randomIndex = Math.floor(Math.random() * (array.length || 0));\n  return array[randomIndex];\n}\n","import { createMessage } from \"@/_private/logger\";\n\nimport { isNumber } from \"@/predicates/is/isNumber\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** -----------------------------------------------------------------------------------------------------\n * * ***Utility: `randomInt`.***\n * ------------------------------------------------------------------------------------------------------\n * **Generates a random integer within a specified range (inclusive).**\n *\n * ---\n * - **Generates a random integer between `min` and `max` (inclusive), with safety constraints:**\n *     - `min` will be forced to be at least `1`.\n *     - `max` will be capped at `Number.MAX_SAFE_INTEGER`.\n *\n * ---\n * @param {number} min - The minimum value (inclusive), must be an integer.\n * @param {number} max - The maximum value (inclusive), must be an integer.\n *\n * ---\n * @returns {number} A random integer N where `min ≤ N ≤ max`.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `min` or `max` is not an integer, or value is `Number.MIN_VALUE`.\n * - `min` is greater than `max`.\n *\n * ---\n * @example\n * randomInt(1, 10);\n * // ➔ returns 1 up-to 10 (random)\n * randomInt(50, 100);\n * // ➔ returns 50 up-to 100 (random)\n * randomInt(5, 5);\n * // ➔ always returns 5 (exact)\n * randomInt(-5, 3);\n * // ➔ always returns ≥ 1, since min is adjusted (exact)\n * randomInt(1, Number.MAX_SAFE_INTEGER + 10000);\n * // ➔ still safely capped at MAX_SAFE_INTEGER\n * randomInt(Number.MIN_VALUE, 3);\n * // ➔ Error, min or max cant be as `Number.MIN_VALUE` value.\n */\nexport const randomInt = (min: number, max: number): number => {\n  if (!isInteger(min) || !isInteger(max)) {\n    throw new TypeError(\n      errorMsg(\n        `First parameter (\\`min\\`) and second parameter (\\`max\\`) must be of type \\`integer-number\\`${minValueNote(\n          min,\n          max\n        )}value, but received: ['min': \\`${getPreciseType(\n          min\n        )}\\` - (with value: \\`${safeStableStringify(min, {\n          keepUndefined: true\n        })})\\`, 'max': \\`${getPreciseType(max)}\\` - (with value: \\`${safeStableStringify(\n          max,\n          {\n            keepUndefined: true\n          }\n        )}\\`)].`\n      )\n    );\n  }\n\n  if (min > max) {\n    throw new RangeError(\n      errorMsg(\n        `First parameter (\\`min\\`) must be less than or equal to second parameter (\\`max\\`), but received: ['min': ${formatValue(\n          min\n        )} - (with value: \\`${safeStableStringify(min, {\n          keepUndefined: true\n        })})\\`, 'max': ${formatValue(max)} - (with value: \\`${safeStableStringify(\n          max,\n          {\n            keepUndefined: true\n          }\n        )})\\`].`\n      )\n    );\n  }\n\n  // Ensure `min` is at least 1\n  min = Math.max(1, min);\n\n  // Ensure `max` does not exceed Number.MAX_SAFE_INTEGER\n  max = Math.min(Number.MAX_SAFE_INTEGER, max);\n\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst formatValue = (value: unknown): string => {\n  return isNumber(value, { includeNaN: true })\n    ? value === Number.MIN_VALUE\n      ? \"`Number.MIN_VALUE`\"\n      : `${value}`\n    : `\\`${getPreciseType(value)}\\``;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst minValueNote = (...values: unknown[]) => {\n  return values.some(\n    (v) => isNumber(v, { includeNaN: true }) && v === Number.MIN_VALUE\n  )\n    ? \" and can't be `Number.MIN_VALUE` \"\n    : \" \";\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomInt\", msg);\n","import { createMessage } from \"@/_private/logger\";\n\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\nimport { randomInt } from \"./randomInt\";\n\ntype OptionsRandomIntByLength = {\n  /** -----------------------------------------------------------------------------------\n   * * ***Minimum length of the random number, the `allowed minimal value` `integer` is `1` `and not bigger than value of` `maxLength`, defaultValue: `1`.***\n   * ------------------------------------------------------------------------------------\n   *\n   * @default 1\n   */\n  minLength?: number;\n  /** -----------------------------------------------------------------------------------\n   * * ***Maximum length of the random number, the `allowed maximal value` `integer` is `16`, defaultValue: `16`.***\n   * ------------------------------------------------------------------------------------\n   *\n   * @default 16\n   */\n  maxLength?: number;\n  /** -----------------------------------------------------------------------------------\n   * * ***If true, prevents the result from being zero, defaultValue: `false`.***\n   * ------------------------------------------------------------------------------------\n   *\n   * @default false\n   */\n  avoidZero?: boolean;\n};\n\n/** ----------------------------------------------------------------------------\n * * ***Utility: `randomIntByLength`.***\n * -----------------------------------------------------------------------------\n * **Generates a random integer within a specified range of digit lengths.**\n *\n * ---\n * @description\n * This function allows generating random integers that strictly conform to a specified minimum and\n * maximum digit length, it is useful for scenarios such as generating realistic-looking IDs, codes,\n * or random test data.\n *\n * ---\n * - **The function ensures:**\n *     - `minLength` is at least 1 and not greater than `maxLength`.\n *     - `maxLength` is no more than 16 (due to JavaScript's `Number.MAX_SAFE_INTEGER`).\n *     - If `avoidZero` is `true`, ensures that `0` is never returned.\n *\n * ---\n * @param {OptionsRandomIntByLength} [options] - Configuration options.\n * @param {OptionsRandomIntByLength[\"minLength\"]} [options.minLength=1] - Minimum number of digits (must be ≥ `1` and ≤ `maxLength`).\n * @param {OptionsRandomIntByLength[\"maxLength\"]} [options.maxLength=16] - Maximum number of digits (must be ≤ `16`).\n * @param {OptionsRandomIntByLength[\"avoidZero\"]} [options.avoidZero=false] - If true, will ensure the result is never zero.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if parameters are invalid, such as:\n * - `minLength` < `1`.\n * - `maxLength` > `16`.\n * - `minLength` > `maxLength`.\n * - non-integer values for `minLength` or `maxLength`.\n *\n * ---\n * @returns {number} A randomly generated integer within the specified constraints.\n *\n * ---\n * @example\n * randomIntByLength({ minLength: 3, maxLength: 5 });\n * // ➔ `xxx` (random int), `xxxx` (random int) or `xxxxx` (random int).\n * randomIntByLength({ minLength: 4, maxLength: 4 });\n * // ➔ `xxxx` (exact 4 digits int)\n * randomIntByLength({ avoidZero: true }); // never 0\n */\nexport const randomIntByLength = (\n  options?: OptionsRandomIntByLength\n): number => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) options = {};\n\n  const { minLength = 1, maxLength = 16, avoidZero = false } = options;\n\n  assertIsBoolean(avoidZero, {\n    message({ currentType, validType }) {\n      return errorMsg(\n        `Parameters \\`avoidZero\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n      );\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n          minLength\n        )}\\` - (with value: ${safeStableStringify(minLength, {\n          keepUndefined: true\n        })}), 'maxLength': \\`${getPreciseType(\n          maxLength\n        )}\\` - (with value: ${safeStableStringify(maxLength, {\n          keepUndefined: true\n        })})].`\n      )\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 16 || minLength > maxLength) {\n    throw new RangeError(\n      errorMsg(\n        `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 16, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n      )\n    );\n  }\n\n  // Generate a random length between minLength and maxLength\n  const randomLength =\n    minLength === maxLength ? minLength : randomInt(minLength, maxLength);\n\n  // Define min and max value based on the selected length\n  const minValue = 10 ** (randomLength - 1); // Example: minLength=3 ➔ minValue=100\n  const maxValue = 10 ** randomLength - 1; // Example: maxLength=4 ➔ maxValue=9999\n\n  // Generate a random number within the valid range\n  let result = randomInt(minValue, maxValue);\n\n  // Ensure the number is not zero if `avoidZero` is true\n  if (avoidZero && result === 0) {\n    result = minValue; // Assign the smallest valid number instead of looping\n  }\n\n  return result;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomIntByLength\", msg);\n","import type { OptionsRandomStr } from \"./_private/randomSTR.types\";\n\nimport { joinLines } from \"@rzl-zone/build-tools/utils\";\n\nimport { createMessage } from \"@/_private/logger\";\n\nimport { isNaN } from \"@/predicates/is/isNaN\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\n\nimport { assertIsBoolean } from \"@/assertions/booleans/assertIsBoolean\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\nimport { randomInt } from \"../integer/randomInt\";\n\n/** -----------------------------------------------------------------------------------\n * * ***Utility: `randomStr`.***\n * ------------------------------------------------------------------------------------\n * **Generates a random alphanumeric string or number with a specified length range.**\n *\n * ---\n * @description\n * This function allows you to generate random strings or numbers with fully\n * customizable options, such as length range, character sets, inclusion of\n * additional characters, and whether to avoid whitespace.\n *\n * ---\n * @param {OptionsRandomStr} [options] - Configuration options for generating the string.\n * @param {OptionsRandomStr[\"minLength\"]} [options.minLength=40] - Minimum length of the generated string (must be `≥` `1`).\n * @param {OptionsRandomStr[\"maxLength\"]} [options.maxLength=40] - Maximum length of the generated string (must be `≤` `5000`).\n * @param {OptionsRandomStr[\"type\"]} [options.type=\"string\"] - Whether to generate a general alphanumeric string or purely numeric string.\n * @param {OptionsRandomStr[\"avoidWhiteSpace\"]} [options.avoidWhiteSpace=true] - If true, removes all whitespace, tabs, and newlines from the character set before generating.\n * @param {OptionsRandomStr[\"replaceGenStr\"]} [options.replaceGenStr] - A custom character set to use when `type` is `\"string\"`.\n * @param {OptionsRandomStr[\"replaceGenInt\"]} [options.replaceGenInt] - A custom character set to use when `type` is `\"number\"`.\n * @param {OptionsRandomStr[\"addChar\"]} [options.addChar] - Additional characters to always include in the character set.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if provided options are invalid (such as minLength > maxLength, invalid type, or empty character set).\n *\n * ---\n * @returns {string} The randomly generated string or numeric string of the desired length.\n *\n * ---\n * @example\n * randomStr();\n * // ➔ Generates a 40-character random alphanumeric string\n * randomStr({ minLength: 10, maxLength: 20 });\n * // ➔ Generates a string between 10 and 20 characters\n * randomStr({ type: \"number\", minLength: 5, maxLength: 5 });\n * // ➔ \"48302\"\n * randomStr({ replaceGenStr: \"ABC \", avoidWhiteSpace: false });\n * // ➔ String using A, B, C and space\n * randomStr({ addChar: \"!@#\", minLength: 15, maxLength: 15 });\n * // ➔ Guaranteed to include !@# in the set\n */\nexport const randomStr = (options?: OptionsRandomStr): string => {\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) options = {};\n\n  const {\n    minLength = 40,\n    maxLength = 40,\n    type = \"string\",\n    avoidWhiteSpace = true\n  } = options;\n\n  // Validate `avoidWhiteSpace`\n  assertIsBoolean(avoidWhiteSpace, {\n    message({ currentType, validType }) {\n      return errorMsg(\n        `Parameters \\`avoidWhiteSpace\\` property of the \\`options\\` (first-parameter) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n      );\n    }\n  });\n\n  // Validate `minLength` & `maxLength` type\n  if (!isInteger(minLength) || !isInteger(maxLength)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameters \\`minLength\\` and \\`maxLength\\` must be of type \\`integer-number\\`, but received: ['minLength': \\`${getPreciseType(\n          minLength\n        )}\\` - (with value: ${safeStableStringify(minLength, {\n          keepUndefined: true\n        })}), 'maxLength': \\`${getPreciseType(\n          maxLength\n        )}\\` - (with value: ${safeStableStringify(maxLength, {\n          keepUndefined: true\n        })})].`\n      )\n    );\n  }\n\n  // Validate `minLength` & `maxLength` range.\n  if (minLength < 1 || maxLength > 5000 || minLength > maxLength) {\n    throw new RangeError(\n      errorMsg(\n        `Invalid range at parameters \\`minLength\\` must be ≥ 1, \\`maxLength\\` must be ≤ 5000, and \\`minLength\\` ≤ \\`maxLength\\`, but received: ['minLength': \\`${minLength}\\`, 'maxLength': \\`${maxLength}\\`].`\n      )\n    );\n  }\n\n  // Validate `type` value props (is not typeof)\n  if (type !== \"string\" && type !== \"number\") {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`type\\` must be of type \\`string\\` with value one of \"string\" | \"number\", but received: \\`${getPreciseType(\n          type\n        )}\\`, with value: ${safeStableStringify(type, {\n          keepUndefined: true\n        })}.`\n      )\n    );\n  }\n\n  // Generate a random length within the range\n  const length = randomInt(minLength, maxLength);\n\n  // Function to clean characters based on `avoidWhiteSpace`\n  const cleanCharacters = (charSet: string) => {\n    return avoidWhiteSpace ? charSet.replace(/\\s|\\n|\\t/g, \"\") : charSet;\n  };\n\n  // Define character sets\n  const defaultNumberSet = \"0123456789\";\n  const defaultStringSet =\n    \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n\n  const baseCharSet =\n    type === \"number\"\n      ? ((!isNaN(Number(options.replaceGenInt))\n          ? options.replaceGenInt\n          : undefined) ?? defaultNumberSet)\n      : ((options.replaceGenStr ? options.replaceGenStr : undefined) ??\n        defaultStringSet);\n\n  // Get the final character set\n  const characterSet = cleanCharacters(baseCharSet) + (options.addChar || \"\");\n\n  // Ensure characterSet is not empty\n  if (!characterSet.length) {\n    const errCharSet = (() => {\n      if (type === \"number\") {\n        if (avoidWhiteSpace) {\n          return \"If `avoidWhiteSpace` is true, and `replaceGenInt` cant be empty-string value, ensure `replaceGenInt` has valid characters and non-nan string number.\";\n        }\n        return \"Ensure `replaceGenInt` has valid characters and not a NaN number string while convert to number.\";\n      }\n      return \"Ensure `replaceGenStr` has valid characters and non empty string.\";\n    })();\n\n    throw new Error(\n      errorMsg(joinLines(\"Character set is empty.\", `  > ${errCharSet}`))\n    );\n  }\n\n  // Generate random string\n  let result = \"\";\n  for (let i = 0; i < length; i++) {\n    result += characterSet.charAt(\n      Math.floor(Math.random() * characterSet.length)\n    );\n  }\n\n  return result;\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomStr\", msg);\n","import { createMessage } from \"@/_private/logger\";\n\nimport { isBoolean } from \"@/predicates/is/isBoolean\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** ---------------------------------------------------------\n * * ***Configuration options for `randomUUID()`.***\n * ----------------------------------------------------------\n */\ntype OptionsRandomUUID = {\n  /** ---------------------------------------------------------\n   * * ***Specifies which UUID version to generate.***\n   * ----------------------------------------------------------\n   *\n   * - `\"v4\"` — Fully random UUID (RFC 4122), no timestamp, no ordering guarantees.\n   * - `\"v7\"` — Time-ordered UUID (RFC 9562), uses Unix timestamp + randomness.\n   *\n   * ---\n   * @default\n   * ```ts\n   * \"v4\"\n   * ```\n   *\n   * ---\n   * @example\n   * 1. #### Random `v4` UUID:\n   *    ```ts\n   *    randomUUID({ version: \"v4\" });\n   *    // ➔ \"xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx\"\n   *    ```\n   *    ---\n   * 2. #### Time-ordered `v7` UUID:\n   *    ```ts\n   *    randomUUID({ version: \"v7\" });\n   *    // ➔ \"xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx\"\n   *    ```\n   */\n  version?: \"v4\" | \"v7\";\n\n  /** ---------------------------------------------------------\n   * * ***Enables monotonic sequencing for UUID v7.***\n   *  ----------------------------------------------------------\n   *\n   * - Guarantees that multiple UUIDs generated within the same millisecond\n   *   are strictly non-decreasing (lexicographically and timestamp-wise).\n   * - Only valid when `version === \"v7\"`, using with `v4` will throw a `TypeError`.\n   * - Useful for database inserts, logs, or any system where order matters.\n   *\n   * ---\n   * @default\n   * ```ts\n   * false\n   * ```\n   *\n   * ---\n   * @example\n   * - #### Monotonic `v7` UUIDs:\n   *   ```ts\n   *   const a = randomUUID({ version: \"v7\", monotonic: true });\n   *   const b = randomUUID({ version: \"v7\", monotonic: true });\n   *   console.log(a < b);\n   *   // ➔ true (guaranteed)\n   *   ```\n   */\n  monotonic?: boolean;\n};\n\n/** -----------------------------------------------------------------------\n * * ***Utility: `randomUUID`.***\n * ------------------------------------------------------------------------\n * **Generates a UUID string according to the specified version and options.**\n *\n * ---\n * - #### Supported versions:\n *     - #### **`\"v4\"` *(default)*** ➔ Fully random UUID, RFC 4122 compliant.\n *          - Uses `crypto.randomUUID()` if available.\n *          - Falls back to `crypto.getRandomValues()` or `Math.random()`\n *            if needed.\n *          ---\n *     - #### **`\"v7\"`** ➔ Time-ordered UUID, RFC 9562 compliant.\n *          - Timestamp (Unix ms, 48 bits) + 80 bits randomness.\n *          - Good for database indexing / sorting.\n *          ---\n *     - #### **`\"v7\"` + `monotonic: true`** ➔ Ensures strictly non-decreasing UUIDs\n *          for multiple calls in the same millisecond (per-process).\n *\n * ---\n * - #### Behavior / Safety Notes:\n *     - **v4**: Fully random; probability of duplicates is astronomically low.\n *     - **v7**: Time-ordered; collisions extremely unlikely unless same ms + random repeat.\n *     - **Monotonic v7**: Guaranteed ordering per-process if multiple UUIDs are generated\n *       in the same millisecond.\n *     - **All versions**: Fallback safely if `crypto` APIs are unavailable.\n *\n * ---\n * @param {object} [options] - Optional settings object.\n * @param {\"v4\" | \"v7\"} [options.version=\"v4\"] - UUID version to generate.\n * @param {boolean} [options.monotonic=false] - ***For v7 only***, generate monotonic UUIDs\n *                                              to maintain strict lexicographic order\n *                                              when generating multiple UUIDs within the same ms.\n *\n * @throws **{@link TypeError | `TypeError`}** if:\n * - `options.version` is provided but not a string.\n * - `options.monotonic` is provided but not a boolean.\n * - `monotonic: true` is used with `version` other than `\"v7\"`.\n *\n * ---\n * @returns {string} A 36-character UUID string compliant with the selected version.\n *\n * @throws **{@link RangeError | `RangeError`}** if `options.version` is provided but not `\"v4\"` or `\"v7\"`.\n *\n * @example\n * 1. #### Default (v4):\n *    ```ts\n *    const id = randomUUID();\n *    // ➔ \"xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx\"\n *    ```\n *    ---\n * 2. #### Explicit `v4`:\n *    ```ts\n *    const id4 = randomUUID({ version: \"v4\" });\n *    // ➔ \"xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx\"\n *    ```\n *    ---\n * 3. #### Time-ordered `v7`:\n *    ```ts\n *    const id7 = randomUUID({ version: \"v7\" });\n *    // ➔ \"xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx\"\n *    ```\n *    ---\n * 4. #### Monotonic `v7`:\n *    ```ts\n *    const a = randomUUID({ version: \"v7\", monotonic: true });\n *    const b = randomUUID({ version: \"v7\", monotonic: true });\n *    // a < b lexicographically (guaranteed)\n *    ```\n * ---\n * - #### *Throws:*\n *      - #### `TypeError`:\n *        ```ts\n *        randomUUID({ version: 123 as any });\n *        // version must be string\n *        randomUUID({ version: \"v4\", monotonic: true } as any);\n *        // monotonic only for v7\n *        ```\n *        ---\n *      - #### `RangeError`:\n *        ```ts\n *        randomUUID({ version: \"v1\" as any });\n *        // unsupported version\n *        ```\n */\nexport function randomUUID(options: OptionsRandomUUID = {}): string {\n  // Validate options is a plain object if provided\n  if (!isPlainObject(options)) options = {};\n\n  const { version = \"v4\", monotonic = false } = options;\n\n  // Validate version type\n  if (!isNonEmptyString(version)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`version\\` property of the \\`options\\` (first parameter) must be a \\`string\\` of either \"v4\" or \"v7\", but received type: \\`${getPreciseType(\n          version\n        )}\\` - (with value: \\`${safeStableStringify(version, { keepUndefined: true })}\\`).`\n      )\n    );\n  }\n\n  if (version !== \"v4\" && version !== \"v7\") {\n    throw new RangeError(\n      errorMsg(\n        `Unsupported UUID version. Allowed values are \"v4\" or \"v7\". (received: \\`${safeStableStringify(\n          version,\n          {\n            keepUndefined: true\n          }\n        )}\\`).`\n      )\n    );\n  }\n\n  // Validate monotonic type\n  if (!isBoolean(monotonic)) {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) must be a \\`boolean\\` when provided, but received type: \\`${getPreciseType(\n          monotonic\n        )}\\` - (with value: \\`${safeStableStringify(monotonic, {\n          keepUndefined: true\n        })}\\`).`\n      )\n    );\n  }\n\n  // monotonic only allowed with v7\n  if (monotonic && version !== \"v7\") {\n    throw new TypeError(\n      errorMsg(\n        `Parameter \\`monotonic\\` property of the \\`options\\` (first parameter) is only supported for version \"v7\". Received: version=${safeStableStringify(\n          version,\n          { keepUndefined: true }\n        )}.`\n      )\n    );\n  }\n\n  if (version === \"v4\") {\n    return generateUUIDv4();\n  }\n\n  // version === \"v7\"\n  return generateUUIDv7({ monotonic });\n}\n\n//todo: Helpers & Implementations\n\nfunction hasCryptoGetRandomValues(): boolean {\n  return (\n    typeof crypto !== \"undefined\" &&\n    typeof crypto.getRandomValues === \"function\"\n  );\n}\n\nfunction hasCryptoRandomUUID(): boolean {\n  return (\n    typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\"\n  );\n}\n\nfunction getRandomBytes(len: number): Uint8Array {\n  if (hasCryptoGetRandomValues()) {\n    return crypto.getRandomValues(new Uint8Array(len));\n  }\n  // Fallback: not cryptographically secure, but avoids crash\n  const arr = new Uint8Array(len);\n  for (let i = 0; i < len; i++) {\n    arr[i] = Math.floor(Math.random() * 256);\n  }\n  return arr;\n}\n\nconst byteToHex: string[] = (() => {\n  const arr: string[] = [];\n  for (let i = 0; i < 256; ++i) {\n    arr.push((i + 0x100).toString(16).substring(1));\n  }\n  return arr;\n})();\n\nfunction generateUUIDv4(): string {\n  // Prefer native if available\n  if (hasCryptoRandomUUID()) {\n    return crypto.randomUUID();\n  }\n\n  // If crypto.getRandomValues available, use it for 16 bytes\n  if (hasCryptoGetRandomValues()) {\n    const rnd = crypto.getRandomValues(new Uint8Array(16));\n\n    if (\n      !rnd[0] ||\n      !rnd[1] ||\n      !rnd[2] ||\n      !rnd[3] ||\n      !rnd[4] ||\n      !rnd[5] ||\n      !rnd[6] ||\n      !rnd[7] ||\n      !rnd[8] ||\n      !rnd[9] ||\n      !rnd[10] ||\n      !rnd[11] ||\n      !rnd[12] ||\n      !rnd[13] ||\n      !rnd[14] ||\n      !rnd[15]\n    ) {\n      return \"\";\n    }\n\n    const byteToHex0 = byteToHex[rnd[0]];\n    const byteToHex1 = byteToHex[rnd[1]];\n\n    if (!byteToHex0 || !byteToHex1) return \"\";\n\n    // Per RFC 4122: set version and variant\n    rnd[6] = (rnd[6]! & 0x0f) | 0x40; // version 4\n    rnd[8] = (rnd[8]! & 0x3f) | 0x80; // variant 10xx\n\n    return (\n      byteToHex0 +\n      byteToHex1 +\n      byteToHex[rnd[2]] +\n      byteToHex[rnd[3]] +\n      \"-\" +\n      byteToHex[rnd[4]] +\n      byteToHex[rnd[5]] +\n      \"-\" +\n      byteToHex[rnd[6]] +\n      byteToHex[rnd[7]] +\n      \"-\" +\n      byteToHex[rnd[8]] +\n      byteToHex[rnd[9]] +\n      \"-\" +\n      byteToHex[rnd[10]] +\n      byteToHex[rnd[11]] +\n      byteToHex[rnd[12]] +\n      byteToHex[rnd[13]] +\n      byteToHex[rnd[14]] +\n      byteToHex[rnd[15]]\n    );\n  }\n\n  // Last-resort fallback using Math.random (not crypto-secure)\n  return \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, (c) => {\n    const r = (Math.random() * 16) | 0;\n    const v = c === \"x\" ? r : (r & 0x3) | 0x8;\n    return v.toString(16);\n  });\n}\n\n/* ---------------------------\n *  Monotonic state (singleton per-process)\n *  ---------------------------\n */\n\n/**\n * Internal monotonic state:\n * - lastTimestampMs: last generated timestamp (ms)\n * - lastRand: last random 10-byte block used for v7 (used to increment on same ms)\n */\nconst monotonicState: {\n  lastTimestampMs: number;\n  lastRand: Uint8Array | null;\n} = {\n  lastTimestampMs: -1,\n  lastRand: null\n};\n\nfunction incrementUint8ArrayBigEndian(arr: Uint8Array): boolean {\n  // Increment arr in big-endian order. Return true if overflowed back to zero.\n  for (let i = arr.length - 1; i >= 0; i--) {\n    if (arr[i] === 0xff) {\n      arr[i] = 0x00;\n      continue;\n    }\n\n    arr[i] = (arr[i]! + 1) & 0xff;\n\n    return false; // no overflow\n  }\n  // overflowed (wrapped to zero)\n  return true;\n}\n\nfunction generateUUIDv7({\n  monotonic = false\n}: { monotonic?: boolean } = {}): string {\n  const nowMs = Date.now();\n  const tsHex = BigInt(nowMs).toString(16).padStart(12, \"0\"); // 48 bits ➔ 12 hex chars\n\n  // We'll use 10 random bytes (80 bits)\n  let rand = getRandomBytes(10);\n\n  if (monotonic) {\n    // ensure monotonicState is consistent per-process\n    if (monotonicState.lastTimestampMs === nowMs && monotonicState.lastRand) {\n      // We are in the same ms bucket — increment lastRand (big-endian)\n      const copy = new Uint8Array(monotonicState.lastRand); // copy for use\n      const overflow = incrementUint8ArrayBigEndian(copy);\n      if (overflow) {\n        // Practically impossible (2^80 increments in 1ms). Throw to be safe.\n        throw new RangeError(\n          errorMsg(\n            \"Monotonic UUID sequence overflow, too many UUIDs generated within the same millisecond.\"\n          )\n        );\n      }\n      // use incremented copy as rand\n      rand = copy;\n      // update state\n      monotonicState.lastRand = copy;\n    } else {\n      // New ms: generate fresh randomness and store\n      const fresh = getRandomBytes(10);\n      monotonicState.lastRand = new Uint8Array(fresh);\n      monotonicState.lastTimestampMs = nowMs;\n      rand = fresh;\n    }\n  }\n\n  // if (!rand[0] || !rand[2]) return \"\";\n  // If not monotonic, rand remains randomly generated above.\n\n  // Now set version & variant bits into proper positions.\n  // For v7 layout we used: timestamp (48 bits) + rand[0..9] (80 bits)\n  // We must set version nibble into high nibble of rand[0] (time_hi_and_version)\n  // and set variant bits into rand[2]'s high bits (clock_seq_hi_and_reserved)\n  rand[0] = rand[0] ? (rand[0] & 0x0f) | 0x70 : 0; // version 7 (0x7 << 4)\n  rand[2] = rand[2] ? (rand[2] & 0x3f) | 0x80 : 0; // variant 10xx\n\n  const randHex = Array.from(rand, (b) => byteToHex[b]).join(\"\");\n\n  // Assemble UUID groups:\n  // - 8 hex (timestamp[0..7])\n  // - 4 hex (timestamp[8..11])\n  // - 4 hex (rand[0..1]) ➔ contains version in high nibble of rand[0]\n  // - 4 hex (rand[2..3]) ➔ contains variant in high bits of rand[2]\n  // - 12 hex (rand[4..9])\n  const part1 = tsHex.slice(0, 8);\n  const part2 = tsHex.slice(8, 12);\n  const part3 = randHex.slice(0, 4);\n  const part4 = randHex.slice(4, 8);\n  const part5 = randHex.slice(8, 20);\n\n  return [part1, part2, part3, part4, part5].join(\"-\");\n}\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"randomUUID\", msg);\n"],"mappings":"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"}