@rzl-zone/utils-js 3.12.1-beta.0 → 3.12.1-beta.1

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    // 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      byteToHex[rnd[0]] +\n      byteToHex[rnd[1]] +\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    arr[i] = (arr[i] + 1) & 0xff;\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 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] & 0x0f) | 0x70; // version 7 (0x7 << 4)\n  rand[2] = (rand[2] & 0x3f) | 0x80; // 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,MAAM,EAAE,OAAO;CAGpC,OAAO,MADa,KAAK,MAAM,KAAK,QAAQ,IAAI,MAAM,UAAU,GACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC9C1B,MAAa,aAAa,KAAa,QAAwB;CAC7D,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,IAAI,EACpC,MAAM,IAAI,UACR,8FAA8F,aAC5F,KACA,IACD,CAAC,iCAAiC,eACjC,IACD,CAAC,sBAAsB,oBAAoB,KAAK,EAC/C,eAAe,MAChB,CAAC,CAAC,gBAAgB,eAAe,IAAI,CAAC,sBAAsB,oBAC3D,KACA,EACE,eAAe,MAChB,CACF,CAAC,OACH;CAEH,IAAI,MAAM,KACR,MAAM,IAAI,WACR,6GAA6G,YAC3G,IACD,CAAC,oBAAoB,oBAAoB,KAAK,EAC7C,eAAe,MAChB,CAAC,CAAC,cAAc,YAAY,IAAI,CAAC,oBAAoB,oBACpD,KACA,EACE,eAAe,MAChB,CACF,CAAC,OACH;CAIH,MAAM,KAAK,IAAI,GAAG,IAAI;CAGtB,MAAM,KAAK,IAAI,OAAO,kBAAkB,IAAI;CAE5C,OAAO,KAAK,MAAM,KAAK,QAAQ,IAAI,MAAM,MAAM,GAAG,GAAG;;AAGvD,MAAM,eAAe,UAA2B;CAC9C,OAAO,SAAS,OAAO,EAAE,YAAY,MAAM,CAAC,GACxC,UAAU,OAAO,YACf,uBACA,GAAG,UACL,KAAK,eAAe,MAAM,CAAC;;AAGjC,MAAM,gBAAgB,GAAG,WAAsB;CAC7C,OAAO,OAAO,MACX,MAAM,SAAS,GAAG,EAAE,YAAY,MAAM,CAAC,IAAI,MAAM,OAAO,UAC1D,GACG,sCACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC5BN,MAAa,qBACX,YACW;CAEX,IAAI,CAAC,cAAc,QAAQ,EACzB,UAAU,EAAE;CAGd,MAAM,EAAE,YAAY,GAAG,YAAY,IAAI,YAAY,UAAU;CAE7D,gBAAgB,WAAW,EACzB,QAAQ,EAAE,aAAa,aAAa;EAClC,OAAO,8CAA8C,UAAU,sBAAsB,YAAY;IAEpG,CAAC;CAGF,IAAI,CAAC,UAAU,UAAU,IAAI,CAAC,UAAU,UAAU,EAChD,MAAM,IAAI,UACR,gHAAgH,eAC9G,UACD,CAAC,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,MAChB,CAAC,CAAC,oBAAoB,eACrB,UACD,CAAC,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,MAChB,CAAC,CAAC,KACJ;CAIH,IAAI,YAAY,KAAK,YAAY,MAAM,YAAY,WACjD,MAAM,IAAI,WACR,uJAAuJ,UAAU,qBAAqB,UAAU,MACjM;CAIH,MAAM,eACJ,cAAc,YAAY,YAAY,UAAU,WAAW,UAAU;CAGvE,MAAM,WAAW,OAAO,eAAe;CAIvC,IAAI,SAAS,UAAU,UAHN,MAAM,eAAe,EAGI;CAG1C,IAAI,aAAa,WAAW,GAC1B,SAAS;CAGX,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACnET,MAAa,aAAa,YAAuC;CAE/D,IAAI,CAAC,cAAc,QAAQ,EACzB,UAAU,EAAE;CAGd,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;IAExJ,CAAC;CAGF,IAAI,CAAC,UAAU,UAAU,IAAI,CAAC,UAAU,UAAU,EAChD,MAAM,IAAI,UACR,gHAAgH,eAC9G,UACD,CAAC,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,MAChB,CAAC,CAAC,oBAAoB,eACrB,UACD,CAAC,oBAAoB,oBAAoB,WAAW,EACnD,eAAe,MAChB,CAAC,CAAC,KACJ;CAIH,IAAI,YAAY,KAAK,YAAY,OAAQ,YAAY,WACnD,MAAM,IAAI,WACR,yJAAyJ,UAAU,qBAAqB,UAAU,MACnM;CAIH,IAAI,SAAS,YAAY,SAAS,UAChC,MAAM,IAAI,UACR,wGAAwG,eACtG,KACD,CAAC,kBAAkB,oBAAoB,MAAM,EAC5C,eAAe,MAChB,CAAC,CAAC,GACJ;CAIH,MAAM,SAAS,UAAU,WAAW,UAAU;CAG9C,MAAM,mBAAmB,YAAoB;EAC3C,OAAO,kBAAkB,QAAQ,QAAQ,aAAa,GAAG,GAAG;;CAiB9D,MAAM,eAAe,gBARnB,SAAS,YACH,CAAC,MAAM,OAAO,QAAQ,cAAc,CAAC,GACnC,QAAQ,gBACR,WAAc,gBAChB,QAAQ,gBAAgB,QAAQ,gBAAgB,WAClD,iEAG2C,IAAI,QAAQ,WAAW;CAGxE,IAAI,CAAC,aAAa,QAAQ;EACxB,MAAM,mBAAmB;GACvB,IAAI,SAAS,UAAU;IACrB,IAAI,iBACF,OAAO;IAET,OAAO;;GAET,OAAO;;EAGT,MAAM,IAAI,MAAM,2BAA2B,YAAY,GAAG;;CAI5D,IAAI,SAAS;CACb,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAC1B,UAAU,aAAa,OACrB,KAAK,MAAM,KAAK,QAAQ,GAAG,aAAa,OAAO,CAChD;CAGH,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC3BT,SAAgB,WAAW,UAA6B,EAAE,EAAU;CAElE,IAAI,CAAC,cAAc,QAAQ,EACzB,MAAM,IAAI,UACR,gIAAgI,eAC9H,QACD,CAAC,sBAAsB,oBAAoB,SAAS,EAAE,eAAe,MAAM,CAAC,CAAC,MAC/E;CAGH,MAAM,EAAE,UAAU,MAAM,YAAY,UAAU;CAG9C,IAAI,CAAC,iBAAiB,QAAQ,EAC5B,MAAM,IAAI,UACR,yIAAyI,eACvI,QACD,CAAC,sBAAsB,oBAAoB,SAAS,EAAE,eAAe,MAAM,CAAC,CAAC,MAC/E;CAGH,IAAI,YAAY,QAAQ,YAAY,MAClC,MAAM,IAAI,WACR,2EAA2E,oBACzE,SACA,EACE,eAAe,MAChB,CACF,CAAC,MACH;CAIH,IAAI,CAAC,UAAU,UAAU,EACvB,MAAM,IAAI,UACR,mIAAmI,eACjI,UACD,CAAC,sBAAsB,oBAAoB,WAAW,EACrD,eAAe,MAChB,CAAC,CAAC,MACJ;CAIH,IAAI,aAAa,YAAY,MAC3B,MAAM,IAAI,UACR,+HAA+H,oBAC7H,SACA,EAAE,eAAe,MAAM,CACxB,CAAC,GACH;CAGH,IAAI,YAAY,MACd,OAAO,gBAAgB;CAIzB,OAAO,eAAe,EAAE,WAAW,CAAC;;AAKtC,SAAS,2BAAoC;CAC3C,OACE,OAAO,WAAW,eAClB,OAAO,OAAO,oBAAoB;;AAItC,SAAS,sBAA+B;CACtC,OACE,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe;;AAIlE,SAAS,eAAe,KAAyB;CAC/C,IAAI,0BAA0B,EAC5B,OAAO,OAAO,gBAAgB,IAAI,WAAW,IAAI,CAAC;CAGpD,MAAM,MAAM,IAAI,WAAW,IAAI;CAC/B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,KACvB,IAAI,KAAK,KAAK,MAAM,KAAK,QAAQ,GAAG,IAAI;CAE1C,OAAO;;AAGT,MAAM,mBAA6B;CACjC,MAAM,MAAgB,EAAE;CACxB,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,EAAE,GACzB,IAAI,MAAM,IAAI,KAAO,SAAS,GAAG,CAAC,UAAU,EAAE,CAAC;CAEjD,OAAO;IACL;AAEJ,SAAS,iBAAyB;CAEhC,IAAI,qBAAqB,EACvB,OAAO,OAAO,YAAY;CAI5B,IAAI,0BAA0B,EAAE;EAC9B,MAAM,MAAM,OAAO,gBAAgB,IAAI,WAAW,GAAG,CAAC;EAEtD,IAAI,KAAM,IAAI,KAAK,KAAQ;EAC3B,IAAI,KAAM,IAAI,KAAK,KAAQ;EAE3B,OACE,UAAU,IAAI,MACd,UAAU,IAAI,MACd,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;;CAKlB,OAAO,uCAAuC,QAAQ,UAAU,MAAM;EACpE,MAAM,IAAK,KAAK,QAAQ,GAAG,KAAM;EAEjC,QADU,MAAM,MAAM,IAAK,IAAI,IAAO,GAC7B,SAAS,GAAG;GACrB;;;;;;;AAYJ,MAAM,iBAGF;CACF,iBAAiB;CACjB,UAAU;CACX;AAED,SAAS,6BAA6B,KAA0B;CAE9D,KAAK,IAAI,IAAI,IAAI,SAAS,GAAG,KAAK,GAAG,KAAK;EACxC,IAAI,IAAI,OAAO,KAAM;GACnB,IAAI,KAAK;GACT;;EAEF,IAAI,KAAM,IAAI,KAAK,IAAK;EACxB,OAAO;;CAGT,OAAO;;AAGT,SAAS,eAAe,EACtB,YAAY,UACe,EAAE,EAAU;CACvC,MAAM,QAAQ,KAAK,KAAK;CACxB,MAAM,QAAQ,OAAO,MAAM,CAAC,SAAS,GAAG,CAAC,SAAS,IAAI,IAAI;CAG1D,IAAI,OAAO,eAAe,GAAG;CAE7B,IAAI,WAEF,IAAI,eAAe,oBAAoB,SAAS,eAAe,UAAU;EAEvE,MAAM,OAAO,IAAI,WAAW,eAAe,SAAS;EAEpD,IADiB,6BAA6B,KAClC,EAEV,MAAM,IAAI,WACR,0FACD;EAGH,OAAO;EAEP,eAAe,WAAW;QACrB;EAEL,MAAM,QAAQ,eAAe,GAAG;EAChC,eAAe,WAAW,IAAI,WAAW,MAAM;EAC/C,eAAe,kBAAkB;EACjC,OAAO;;CAUX,KAAK,KAAM,KAAK,KAAK,KAAQ;CAC7B,KAAK,KAAM,KAAK,KAAK,KAAQ;CAE7B,MAAM,UAAU,MAAM,KAAK,OAAO,MAAM,UAAU,GAAG,CAAC,KAAK,GAAG;CAc9D,OAAO;EANO,MAAM,MAAM,GAAG,EAMhB;EALC,MAAM,MAAM,GAAG,GAKT;EAJN,QAAQ,MAAM,GAAG,EAIJ;EAHb,QAAQ,MAAM,GAAG,EAGG;EAFpB,QAAQ,MAAM,GAAG,GAEU;EAAC,CAAC,KAAK,IAAI"}
+{"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":"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"}

package/dist/index-59zbLcPr.d.ts

@@ -0,0 +1,340 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+
+import { Extends, FixNeverArrayRecursive, IfNonEmptyArray, NullToUndefined } from "@rzl-zone/ts-types-plus";
+/** ---------------------------------
+* * ***Utility: `getRandomItem`.***
+* ---------------------------------
+* **Function to get a random element from a given array.**
+* @template T - The type of the input array.
+* @param {*} array - The input array, can be `null`, `undefined`, or an empty array.
+* @returns
+* - If `array` is a non-empty tuple, returns one of its elements.
+* - If `array` is empty, `null`, or `undefined`, returns `undefined`.
+* @example
+* getRandomItem([]);
+* // ➔ undefined
+* getRandomItem(null);
+* // ➔ undefined
+* getRandomItem(undefined);
+* // ➔ undefined
+* getRandomItem([1, 2, 3, 4]);
+* // ➔ number
+* getRandomItem(["apple", "banana", "cherry"]);
+* // ➔ string
+* getRandomItem(["apple", 123, true]);
+* // ➔ string | number | boolean
+* getRandomItem(["apple", 123, true, null]);
+* // ➔ string | number | boolean | undefined
+* getRandomItem(["apple", 123, true, undefined]);
+* // ➔ string | number | boolean | undefined
+*
+* // Tuple example:
+* const tuple = [1, "two", true] as const;
+* getRandomItem(tuple); // 1 | "two" | true
+*/
+declare function getRandomItem(array: undefined): undefined;
+declare function getRandomItem(array: []): undefined;
+declare function getRandomItem<T extends readonly unknown[]>(array: T): T extends never[][] ? undefined : number extends T["length"] ? NullToUndefined<FixNeverArrayRecursive<T[number]>> : IfNonEmptyArray<T, NullToUndefined<FixNeverArrayRecursive<T[number]>>, undefined>;
+declare function getRandomItem<T extends readonly unknown[] | undefined | null>(array: T): T extends readonly unknown[] ? NullToUndefined<FixNeverArrayRecursive<T[number]>> | undefined : undefined;
+declare function getRandomItem<T>(array: T): unknown extends T ? unknown : Extends<any[] | readonly any[], T> extends true ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined : Extends<any[], T> extends true ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined : Extends<readonly any[], T> extends true ? Extract<T, unknown[] | readonly unknown[]>[number] | undefined : undefined;
+/** -----------------------------------------------------------------------
+* * ***Utility: `randomInt`.***
+* ------------------------------------------------------------------------
+* **Generates a random integer within a specified range (inclusive).**
+* - **Generates a random integer between `min` and `max` (inclusive), with safety constraints:**
+*    - `min` will be forced to be at least `1`.
+*    - `max` will be capped at `Number.MAX_SAFE_INTEGER`.
+* @param {number} min - The minimum value (inclusive), must be an integer.
+* @param {number} max - The maximum value (inclusive), must be an integer.
+* @returns {number} A random integer N where `min ≤ N ≤ max`.
+* @throws **{@link TypeError | `TypeError`}** if:
+* - `min` or `max` is not an integer, or value is `Number.MIN_VALUE`.
+* - `min` is greater than `max`.
+* @example
+* randomInt(1, 10);   // ➔ returns 1 up-to 10 (random)
+* randomInt(50, 100); // ➔ returns 50 up-to 100 (random)
+* randomInt(5, 5);    // ➔ always returns 5 (exact)
+* randomInt(-5, 3);   // ➔ always returns ≥ 1, since min is adjusted (exact)
+* randomInt(1, Number.MAX_SAFE_INTEGER + 10000);
+* // ➔ still safely capped at MAX_SAFE_INTEGER
+* randomInt(Number.MIN_VALUE, 3);
+* // ➔ Error, min or max cant be as `Number.MIN_VALUE` value.
+*/
+declare const randomInt: (min: number, max: number) => number;
+type OptionsRandomIntByLength = {
+  /** * Minimum length of the random number, the `allowed minimal value` `integer` is `1` `and not bigger than value of` `maxLength`, defaultValue: `1`.
+  *
+  * @default 1
+  */
+  minLength?: number;
+  /** * Maximum length of the random number, the `allowed maximal value` `integer` is `16`, defaultValue: `16`.
+  *
+  * @default 16
+  */
+  maxLength?: number;
+  /** * If true, prevents the result from being zero, defaultValue: `false`.
+  *
+  * @default false
+  */
+  avoidZero?: boolean;
+};
+/** ----------------------------------------------------------------------------
+* * ***Utility: `randomIntByLength`.***
+* -----------------------------------------------------------------------------
+* **Generates a random integer within a specified range of digit lengths.**
+* @description
+* This function allows generating random integers that strictly conform to a specified minimum and
+* maximum digit length, it is useful for scenarios such as generating realistic-looking IDs, codes,
+* or random test data.
+* - **The function ensures:**
+*    - `minLength` is at least 1 and not greater than `maxLength`.
+*    - `maxLength` is no more than 16 (due to JavaScript's `Number.MAX_SAFE_INTEGER`).
+*    - If `avoidZero` is `true`, ensures that `0` is never returned.
+* @param {OptionsRandomIntByLength} [options] - Configuration options.
+* @param {OptionsRandomIntByLength["minLength"]} [options.minLength=1] - Minimum number of digits (must be ≥ `1` and ≤ `maxLength`).
+* @param {OptionsRandomIntByLength["maxLength"]} [options.maxLength=16] - Maximum number of digits (must be ≤ `16`).
+* @param {OptionsRandomIntByLength["avoidZero"]} [options.avoidZero=false] - If true, will ensure the result is never zero.
+* @returns {number} A randomly generated integer within the specified constraints.
+* @throws **{@link TypeError | `TypeError`}** if parameters are invalid, such as:
+* - `minLength` < `1`
+* - `maxLength` > `16`
+* - `minLength` > `maxLength`
+* - non-integer values for `minLength` or `maxLength`
+* @example
+* randomIntByLength({ minLength: 3, maxLength: 5 });
+* // ➔ `4829` (random), `192` (random) or `71492` (random).
+* randomIntByLength({ minLength: 4, maxLength: 4 });
+* // ➔ `5930` (exact 4 digits)
+* randomIntByLength({ avoidZero: true });
+* // ➔ never 0
+*/
+declare const randomIntByLength: (options?: OptionsRandomIntByLength) => number;
+type OptionsRandomStr = {
+  /** ***Ensures no whitespace characters in the generated string, defaultValue: `true`.***
+  *
+  * @default true
+  */
+  avoidWhiteSpace?: boolean;
+  /** ***Custom characters to replace the default number set if `type` is `"number"`, defaultValue: `undefined`.***
+  *
+  * @default undefined
+  */
+  replaceGenInt?: string;
+  /** ***Custom characters to replace the default string set if `type` is `"string"`, defaultValue: `undefined`.***
+  *
+  * @default undefined
+  */
+  replaceGenStr?: string;
+  /** ***Additional characters to include in the generated string, defaultValue: `undefined`.***
+  *
+  * @default undefined
+  */
+  addChar?: string;
+  /** ***Minimum length of the generated string (1 to 5000), defaultValue: `40`.***
+  *
+  * @default 40
+  */
+  minLength?: number;
+  /** ***Maximum length of the generated string (1 to 5000), defaultValue: `40`.***
+  *
+  * @default 40
+  */
+  maxLength?: number;
+  /** ***Type of output: `"string"` or `"number"`, defaultValue: `"string"`.***
+  *
+  * @default "string"
+  */
+  type?: "string" | "number";
+};
+/** ---------------------------------------------------------------------------------
+* * ***Utility: `randomStr`.***
+* ---------------------------------------------------------------------------------
+* **Generates a random alphanumeric string or number with a specified length range.**
+* @description
+* This function allows you to generate random strings or numbers with fully
+* customizable options, such as length range, character sets, inclusion of
+* additional characters, and whether to avoid whitespace.
+* @param {OptionsRandomStr} [options] - Configuration options for generating the string.
+* @param {OptionsRandomStr["minLength"]} [options.minLength=40] - Minimum length of the generated string (must be `≥` `1`).
+* @param {OptionsRandomStr["maxLength"]} [options.maxLength=40] - Maximum length of the generated string (must be `≤` `5000`).
+* @param {OptionsRandomStr["type"]} [options.type="string"] - Whether to generate a general alphanumeric string or purely numeric string.
+* @param {OptionsRandomStr["avoidWhiteSpace"]} [options.avoidWhiteSpace=true] - If true, removes all whitespace, tabs, and newlines from the character set before generating.
+* @param {OptionsRandomStr["replaceGenStr"]} [options.replaceGenStr] - A custom character set to use when `type` is `"string"`.
+* @param {OptionsRandomStr["replaceGenInt"]} [options.replaceGenInt] - A custom character set to use when `type` is `"number"`.
+* @param {OptionsRandomStr["addChar"]} [options.addChar] - Additional characters to always include in the character set.
+* @returns {string} The randomly generated string or numeric string of the desired length.
+* @throws **{@link TypeError | `TypeError`}** if provided options are invalid (such as minLength > maxLength, invalid type, or empty character set).
+* @example
+* randomStr();
+* // ➔ Generates a 40-character random alphanumeric string
+* randomStr({ minLength: 10, maxLength: 20 });
+* // ➔ Generates a string between 10 and 20 characters
+* randomStr({ type: "number", minLength: 5, maxLength: 5 });
+* // ➔ "48302"
+* randomStr({ replaceGenStr: "ABC ", avoidWhiteSpace: false });
+* // ➔ String using A, B, C and space
+* randomStr({ addChar: "!@#", minLength: 15, maxLength: 15 });
+* // ➔ Guaranteed to include !@# in the set
+*/
+declare const randomStr: (options?: OptionsRandomStr) => string;
+/**
+* Configuration options for `randomUUID()`.
+*/
+type OptionsRandomUUID = {
+  /**
+  * Specifies which UUID version to generate.
+  *
+  * - `"v4"` — Fully random UUID (RFC 4122). No timestamp, no ordering guarantees.
+  * - `"v7"` — Time-ordered UUID (RFC 9562). Uses Unix timestamp + randomness.
+  *
+  * @default "v4"
+  *
+  * @example
+  * // Random v4 UUID
+  * randomUUID({ version: "v4" }); // ➔ "3ec0de5a-b8a9-4ffb-a62a-fcc76851e9c2"
+  *
+  * @example
+  * // Time-ordered v7 UUID
+  * randomUUID({ version: "v7" }); // ➔ "0199f3f6-3c5e-744b-affa-46b2cfd496f8"
+  */
+  version?: "v4" | "v7";
+  /**
+  * Enables monotonic sequencing for UUID v7.
+  *
+  * - Guarantees that multiple UUIDs generated within the same millisecond
+  *   are strictly non-decreasing (lexicographically and timestamp-wise).
+  * - Only valid when `version === "v7"`. Using with `v4` will throw a `TypeError`.
+  * - Useful for database inserts, logs, or any system where order matters.
+  *
+  * @default false
+  *
+  * @example
+  * // Monotonic v7 UUIDs
+  * const a = randomUUID({ version: "v7", monotonic: true });
+  * const b = randomUUID({ version: "v7", monotonic: true });
+  * console.log(a < b); // true, guaranteed
+  */
+  monotonic?: boolean;
+};
+/** -----------------------------------------------------------------------
+* * ***Utility: `randomUUID`.***
+* ------------------------------------------------------------------------
+* **Generates a UUID string according to the specified version and options.**
+*
+* - **Supported versions**:
+*    - **`"v4"` (default)** ➔ Fully random UUID, RFC 4122 compliant.
+*        - Uses `crypto.randomUUID()` if available.
+*        - Falls back to `crypto.getRandomValues()` or `Math.random()`
+*          if needed.
+*    - **`"v7"`** ➔ Time-ordered UUID, RFC 9562 compliant.
+*        - Timestamp (Unix ms, 48 bits) + 80 bits randomness.
+*        - Good for database indexing / sorting.
+*    - **`"v7"` + `monotonic: true`** ➔ Ensures strictly non-decreasing UUIDs
+*      for multiple calls in the same millisecond (per-process).
+*
+* - **Behavior / Safety Notes**:
+*    - **v4**: Fully random; probability of duplicates is astronomically low.
+*    - **v7**: Time-ordered; collisions extremely unlikely unless same ms + random repeat.
+*    - **Monotonic v7**: Guaranteed ordering per-process if multiple UUIDs are generated
+*      in the same millisecond.
+*    - **All versions**: Fallback safely if `crypto` APIs are unavailable.
+*
+* @param {object} [options] - Optional settings object.
+* @param {"v4" | "v7"} [options.version="v4"] - UUID version to generate.
+* @param {boolean} [options.monotonic=false] - For v7 only: generate monotonic UUIDs
+*                                              to maintain strict lexicographic order
+*                                              when generating multiple UUIDs within the same ms.
+*
+* @returns {string} A 36-character UUID string compliant with the selected version.
+*
+* @throws **{@link TypeError | `TypeError`}** if:
+* - `options` is not a plain object.
+* - `options.version` is provided but not a string.
+* - `options.monotonic` is provided but not a boolean.
+* - `monotonic: true` is used with `version` other than `"v7"`.
+* @throws **{@link RangeError | `RangeError`}** if `options.version` is provided but not `"v4"` or `"v7"`.
+*
+* @example
+* // Default (v4)
+* const id = randomUUID();
+* // ➔ "3b12f1df-5232-4804-897e-917bf397618a"
+*
+* @example
+* // Explicit v4
+* const id4 = randomUUID({ version: "v4" });
+*
+* @example
+* // Time-ordered v7
+* const id7 = randomUUID({ version: "v7" });
+* // ➔ "018f48d2-84c1-7ccd-b5a3-2f9463b3a889"
+*
+* @example
+* // Monotonic v7
+* const a = randomUUID({ version: "v7", monotonic: true });
+* const b = randomUUID({ version: "v7", monotonic: true });
+* // a < b lexicographically (guaranteed)
+*
+* @example
+* // Throws TypeError
+* randomUUID("v4" as any); // options must be object
+* randomUUID({ version: 123 as any }); // version must be string
+* randomUUID({ version: "v4", monotonic: true } as any); // monotonic only for v7
+*
+* @example
+* // Throws RangeError
+* randomUUID({ version: "v1" as any }); // unsupported version
+*/
+declare function randomUUID(options?: OptionsRandomUUID): string;
+/**
+* --------------------------------------------------
+* * ***Utility: `noop`.***
+* --------------------------------------------------
+* **A no-operation function that performs no action.**
+*
+* @description
+* Commonly used as a **placeholder**, **default callback**, or **stub function**.
+*
+* - **Behavior**:
+*    - Does not return any meaningful value (`void`).
+*    - Safely callable in any context without side effects.
+*
+* @remarks
+* Although this function returns `void`, it implicitly results in `undefined`,
+* but the return value should never be relied upon.
+*
+* @example
+* **1. Basic usage** — does nothing and returns undefined implicitly:
+* ```
+* import { noop } from "@rzl-zone/utils-js/generators";
+*
+* noop(); // ➔ no effect (void)
+* ```
+* @example
+* **2. Using with type-checking helpers:**
+* ```ts
+* import { noop } from "@rzl-zone/utils-js/generators";
+* import { isFunction, isUndefined } from "@rzl-zone/utils-js/predicates";
+*
+* isFunction(noop);    // ➔ true  — `noop` is a function
+* isUndefined(noop()); // ➔ true  — calling `noop()` returns `undefined`
+* isFunction(noop());  // ➔ false — the return value is `undefined`, not a function
+* ```
+* @example
+* **3. As a default callback:**
+* ```ts
+* import { noop } from "@rzl-zone/utils-js/generators";
+*
+* const callback = noop;
+* callback(); // ➔ no effect (void)
+* ```
+*/
+declare const noop: () => void;
+export { randomInt as a, randomIntByLength as i, randomUUID as n, getRandomItem as o, randomStr as r, noop as t };