@rzl-zone/utils-js 3.7.1 → 3.9.0

package/dist/formatters/index.cjs

@@ -2,61 +2,61 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
 'use strict';
 
-var chunkOS5OT5JA_cjs = require('../chunk-OS5OT5JA.cjs');
-require('../chunk-B6UIKBHR.cjs');
-require('../chunk-EK7FSI7F.cjs');
-require('../chunk-B4SDEBN7.cjs');
+var chunkWLEZ2KSG_cjs = require('../chunk-WLEZ2KSG.cjs');
+require('../chunk-QZI5PVCI.cjs');
+require('../chunk-2XGQQZ6A.cjs');
+require('../chunk-PWKOFPAH.cjs');
 require('../chunk-DVMHRLKP.cjs');
-require('../chunk-NREACG6M.cjs');
-require('../chunk-K63WO3XA.cjs');
-require('../chunk-YC7AK3KX.cjs');
+require('../chunk-FWWPEL7J.cjs');
+require('../chunk-WKM6UVMG.cjs');
+require('../chunk-H44QVAZL.cjs');
 require('../chunk-UDA26MCU.cjs');
-require('../chunk-F3WBQKRI.cjs');
+require('../chunk-7C7TQC5J.cjs');
 
 Object.defineProperty(exports, "censorEmail", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.censorEmail; }
+  get: function () { return chunkWLEZ2KSG_cjs.censorEmail; }
 });
 Object.defineProperty(exports, "chunkString", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.chunkString; }
+  get: function () { return chunkWLEZ2KSG_cjs.chunkString; }
 });
 Object.defineProperty(exports, "formatCurrency", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.formatCurrency; }
+  get: function () { return chunkWLEZ2KSG_cjs.formatCurrency; }
 });
 Object.defineProperty(exports, "formatDateFns", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.formatDateFns; }
+  get: function () { return chunkWLEZ2KSG_cjs.formatDateFns; }
 });
 Object.defineProperty(exports, "formatDateIntl", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.formatDateIntl; }
+  get: function () { return chunkWLEZ2KSG_cjs.formatDateIntl; }
 });
 Object.defineProperty(exports, "formatDateTime", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.formatDateTime; }
+  get: function () { return chunkWLEZ2KSG_cjs.formatDateTime; }
 });
 Object.defineProperty(exports, "formatNumber", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.formatNumber; }
+  get: function () { return chunkWLEZ2KSG_cjs.formatNumber; }
 });
 Object.defineProperty(exports, "formatPhoneNumber", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.formatPhoneNumber; }
+  get: function () { return chunkWLEZ2KSG_cjs.formatPhoneNumber; }
 });
 Object.defineProperty(exports, "getGMTOffset", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.getGMTOffset; }
+  get: function () { return chunkWLEZ2KSG_cjs.getGMTOffset; }
 });
 Object.defineProperty(exports, "truncateString", {
   enumerable: true,
-  get: function () { return chunkOS5OT5JA_cjs.truncateString; }
+  get: function () { return chunkWLEZ2KSG_cjs.truncateString; }
 });

package/dist/formatters/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -148,7 +148,7 @@ indianFormat?:boolean;};
  *          - `"CHF 12'345.60"` ***(Swiss)***.
  *          - `"1,23,456.78"` ***(Indian)***.
  * - Auto extracts numeric value with smart multi-locale parsing
- *   via ***{@link parseCurrencyString | `parseCurrencyString`}***.
+ *   via ***`parseCurrencyString` utility function***.
  * - Strong type checks & clear errors for misconfigured options.
  * - **Handles:**
  *    - Thousands separators: `.`, `,`, `'`, ` `.
@@ -228,8 +228,7 @@ indianFormat?:boolean;};
  *    - `"Rp 15.000,10.-"`.
  *    - `"15'000.10 USD"`.
  *    - `"12,34,567.89"`.
- * @throws {TypeError}
- *  ***Will throw TypeError If:***
+ * @throws **{@link TypeError | `TypeError`}** ***If:***
  *    - The `value` is not string or number.
  *    - Cannot parse to valid number.
  *    - Options have invalid types.
@@ -379,8 +378,7 @@ declare const formatCurrency:(value:string|number,options?:FormatCurrencyOptions
  * @param {string} [separator=","] - The thousands separator to use, examples: `","` ***(default)***, `"."`, `" "`, etc.
  * @returns {string} The formatted string with thousands separators and
  *   appropriate decimal separator.
- * @throws {TypeError} If `value` is not a string or number,
- * or `separator` is not a string.
+ * @throws **{@link TypeError | `TypeError`}** if `value` is not a string or number, or `separator` is not a string.
  * @example
  * formatNumber(1000000);
  * // ➔ "1,000,000"
@@ -1118,8 +1116,8 @@ takeNumberOnly:true;}>;
  * - **E.164 compliance:**
  *    - Optional leading `+` is recommended but **not required**.
  *    - If Without leading `+`, you must passing `defaultCountry`.
- * @throws {TypeError} If `value` is not string, number, null or undefined.
- * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @throws **{@link TypeError | `TypeError`}** if `value` is not string, number, null or undefined.
+ * @throws **{@link TypeError | `TypeError`}** if `options` is not an object or contains wrong types.
  * @param {ValueFormatPhoneNumber} value
  *  ***Phone number to format, accepts:***
  *   - `string` (recommended to preserve leading zeros).
@@ -1243,8 +1241,8 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * - **E.164 compliance:**
  *    - Optional leading `+` is recommended but **not required**.
  *    - If Without leading `+`, you must passing `defaultCountry`.
- * @throws {TypeError} If `value` is not string, number, null or undefined.
- * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @throws **{@link TypeError | `TypeError`}** if `value` is not string, number, null or undefined.
+ * @throws **{@link TypeError | `TypeError`}** if `options` is not an object or contains wrong types.
  * @param {ValueFormatPhoneNumber} value
  *   Phone number to format. Accepts:
  *   - `string` (recommended to preserve leading zeros)
@@ -1299,8 +1297,8 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * - **E.164 compliance:**
  *    - Optional leading `+` is recommended but **not required**.
  *    - If Without leading `+`, you must passing `defaultCountry`.
- * @throws {TypeError} If `value` is not string, number, null or undefined.
- * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @throws **{@link TypeError | `TypeError`}** if `value` is not string, number, null or undefined.
+ * @throws **{@link TypeError | `TypeError`}** if `options` is not an object or contains wrong types.
  * @param {ValueFormatPhoneNumber} value
  *  Phone number to format. Accepts:
  *   - `string` (recommended to preserve leading zeros).
@@ -1359,8 +1357,8 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * - **E.164 compliance:**
  *    - Optional leading `+` is recommended but **not required**.
  *    - If Without leading `+`, you must passing `defaultCountry`.
- * @throws {TypeError} If `value` is not string, number, null or undefined.
- * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @throws **{@link TypeError | `TypeError`}** if `value` is not string, number, null or undefined.
+ * @throws **{@link TypeError | `TypeError`}** if `options` is not an object or contains wrong types.
  * @param {ValueFormatPhoneNumber} value
  *  Phone number to format. Accepts:
  *   - `string` (recommended to preserve leading zeros).
@@ -1475,8 +1473,8 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * - **E.164 compliance:**
  *    - Optional leading `+` is recommended but **not required**.
  *    - If Without leading `+`, you must passing `defaultCountry`.
- * @throws {TypeError} If `value` is not string, number, null or undefined.
- * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @throws **{@link TypeError | `TypeError`}** if `value` is not string, number, null or undefined.
+ * @throws **{@link TypeError | `TypeError`}** if `options` is not an object or contains wrong types.
  * @param {ValueFormatPhoneNumber} value
  *   Phone number to format. Accepts:
  *   - `string` (recommended to preserve leading zeros)
@@ -1554,8 +1552,8 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * - **E.164 compliance:**
  *    - Optional leading `+` is recommended but **not required**.
  *    - If Without leading `+`, you must passing `defaultCountry`.
- * @throws {TypeError} If `value` is not string, number, null or undefined.
- * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @throws **{@link TypeError | `TypeError`}** if `value` is not string, number, null or undefined.
+ * @throws **{@link TypeError | `TypeError`}** if `options` is not an object or contains wrong types.
  * @param {ValueFormatPhoneNumber} value
  *  Phone number to format. Accepts:
  *   - `string` (recommended to preserve leading zeros).
@@ -1699,7 +1697,7 @@ mode?:"random"|"fixed";};
  * @param {string | null | undefined} email - The email address to censor.
  * @param {CensorEmailOptions} [options={}] - Options object for mode.
  * @returns {string} The censored email, or an empty string if input is invalid.
- * @throws {TypeError} If `options` is not a plain object or `mode` is invalid.
+ * @throws **{@link TypeError | `TypeError`}** if `options` is not a plain object or `mode` is invalid.
  * @example
  * // Fixed mode (default, deterministic)
  * censorEmail("john.doe@gmail.com");
@@ -1821,11 +1819,8 @@ trim?:boolean;};
  *    - `length` (number, default 10): Maximum length of the truncated string.
  *    - `ending` (string, default `"..."`): String to append if truncation occurs.
  *    - `trim` (boolean, default `true`): Whether to trim the input before truncation.
- * @returns {string} The truncated string with optional trimming and ending.
- *                   Returns `""` if input is empty or length < 1.
- * @throws {TypeError} If `options.length` is not a finite number,
- *                     or if `options.ending` is not a string,
- *                     or if `options.trim` is not a boolean.
+ * @returns {string} The truncated string with optional trimming and ending, returns `""` if input is empty or length < 1.
+ * @throws **{@link TypeError | `TypeError`}** if `options.length` is not a finite number, or if `options.ending` is not a string, or if `options.trim` is not a boolean.
  * @example
  * truncateString("hello world", { length: 5 });
  * // ➔ "hello..."

package/dist/formatters/index.js

@@ -2,18 +2,18 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-export { censorEmail, chunkString, formatCurrency, formatDateFns, formatDateIntl, formatDateTime, formatNumber, formatPhoneNumber, getGMTOffset, truncateString } from '../chunk-QUITZ3GP.js';
-import '../chunk-OFBFGFVH.js';
-import '../chunk-DPLL67OT.js';
-import '../chunk-7ZNEUWYP.js';
+export { censorEmail, chunkString, formatCurrency, formatDateFns, formatDateIntl, formatDateTime, formatNumber, formatPhoneNumber, getGMTOffset, truncateString } from '../chunk-7EIFPHV3.js';
+import '../chunk-JYOCB6OV.js';
+import '../chunk-EJV5AF4L.js';
+import '../chunk-MZ3T6L7Z.js';
 import '../chunk-WVSPXFTY.js';
-import '../chunk-JY4HLZ4W.js';
-import '../chunk-FI76UZRF.js';
-import '../chunk-2VO2CBTU.js';
+import '../chunk-5O66AUEC.js';
+import '../chunk-OSSFLQDD.js';
+import '../chunk-X6ULJZ3X.js';
 import '../chunk-QNKGP5DY.js';
-import '../chunk-3KTD3QDI.js';
+import '../chunk-J4TT33ZX.js';

package/dist/generators/index.cjs

@@ -2,35 +2,39 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
 'use strict';
 
-var chunkK3SONK25_cjs = require('../chunk-K3SONK25.cjs');
+var chunkNJ24M6ZH_cjs = require('../chunk-NJ24M6ZH.cjs');
 require('../chunk-DVMHRLKP.cjs');
 var chunkBAV5T2E3_cjs = require('../chunk-BAV5T2E3.cjs');
-require('../chunk-YC7AK3KX.cjs');
+require('../chunk-H44QVAZL.cjs');
 require('../chunk-UDA26MCU.cjs');
-require('../chunk-F3WBQKRI.cjs');
+require('../chunk-7C7TQC5J.cjs');
 
 Object.defineProperty(exports, "getRandomItem", {
   enumerable: true,
-  get: function () { return chunkK3SONK25_cjs.getRandomItem; }
+  get: function () { return chunkNJ24M6ZH_cjs.getRandomItem; }
 });
 Object.defineProperty(exports, "randomInt", {
   enumerable: true,
-  get: function () { return chunkK3SONK25_cjs.randomInt; }
+  get: function () { return chunkNJ24M6ZH_cjs.randomInt; }
 });
 Object.defineProperty(exports, "randomIntByLength", {
   enumerable: true,
-  get: function () { return chunkK3SONK25_cjs.randomIntByLength; }
+  get: function () { return chunkNJ24M6ZH_cjs.randomIntByLength; }
 });
 Object.defineProperty(exports, "randomStr", {
   enumerable: true,
-  get: function () { return chunkK3SONK25_cjs.randomStr; }
+  get: function () { return chunkNJ24M6ZH_cjs.randomStr; }
+});
+Object.defineProperty(exports, "randomUUID", {
+  enumerable: true,
+  get: function () { return chunkNJ24M6ZH_cjs.randomUUID; }
 });
 Object.defineProperty(exports, "noop", {
   enumerable: true,

package/dist/generators/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -39,7 +39,7 @@ import{NullToUndefined,FixNeverArrayRecursive,IfNonEmptyArray,Extends}from'@rzl-
  * const tuple = [1, "two", true] as const;
  * getRandomItem(tuple); // 1 | "two" | true
  */
-declare function getRandomItem(array:undefined):undefined;declare function getRandomItem(array:null):undefined;declare function getRandomItem(array:[]):undefined;declare function getRandomItem<T extends readonly unknown[]>(array:T):T extends never[][]?[]: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;
+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`.***
  * ------------------------------------------------------------------------
@@ -50,14 +50,14 @@ declare function getRandomItem(array:undefined):undefined;declare function getRa
  * @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 {TypeError} If:
- * - `min` or `max` is not an integer and value is `Number.MIN_VALUE`.
+ * @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 to 10
- * randomInt(50, 100); // ➔ returns 50 to 100
- * randomInt(5, 5);    // ➔ always returns 5
- * randomInt(-5, 3);   // ➔ always returns ≥ 1, since min is adjusted
+ * 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);
@@ -96,14 +96,14 @@ avoidZero?:boolean;};
  * @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 {TypeError} If parameters are invalid, such as:
+ * @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).
+ * // ➔ `4829` (random), `192` (random) or `71492` (random).
  * randomIntByLength({ minLength: 4, maxLength: 4 });
  * // ➔ `5930` (exact 4 digits)
  * randomIntByLength({ avoidZero: true });
@@ -155,7 +155,7 @@ type?:"string"|"number";};
  * @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 {TypeError} If provided options are invalid (such as minLength > maxLength, invalid type, or empty character set).
+ * @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
@@ -169,25 +169,154 @@ type?:"string"|"number";};
  * // ➔ 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 always returns `undefined`.**
- * - *Useful as a default callback, placeholder, or stub function.*
- * @returns {undefined} Always returns `undefined`.
+ * **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
- * // Direct call returns undefined
- * noop();
- * // ➔ undefined
+ * **1. Basic usage** — does nothing and returns undefined implicitly:
+ * ```
+ * import { noop } from "@rzl-zone/utils-js/generators";
  *
- * // Can be used with type-checking helpers
- * isFunction(noop);    // ➔ true
- * isUndefined(noop()); // ➔ true
- * isFunction(noop());  // ➔ false
+ * 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";
  *
- * // Often used as a default function
  * const callback = noop;
- * callback();
- * // ➔ undefined
+ * callback(); // ➔ no effect (void)
+ * ```
  */
-declare const noop:()=>void;export{getRandomItem,noop,randomInt,randomIntByLength,randomStr};
+declare const noop:()=>void;export{getRandomItem,noop,randomInt,randomIntByLength,randomStr,randomUUID};

package/dist/generators/index.js

@@ -2,14 +2,14 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-export { getRandomItem, randomInt, randomIntByLength, randomStr } from '../chunk-ABA2ZSBQ.js';
+export { getRandomItem, randomInt, randomIntByLength, randomStr, randomUUID } from '../chunk-5Y6JL47L.js';
 import '../chunk-WVSPXFTY.js';
 export { noop } from '../chunk-YWHHVDT4.js';
-import '../chunk-2VO2CBTU.js';
+import '../chunk-X6ULJZ3X.js';
 import '../chunk-QNKGP5DY.js';
-import '../chunk-3KTD3QDI.js';
+import '../chunk-J4TT33ZX.js';

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================

package/dist/{isPlainObject-FWmcJF6k.d.ts → isPlainObject-BTPjv6zB.d.ts}

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -119,7 +119,7 @@ declare const isNumber:(value:unknown,options?:IsNumberOptions)=>value is number
  *    - If `T` is `unknown`, the resulting type is `Record<PropertyKey, unknown> & T`.
  *    - If `T` is an object:
  *        - If it is a non-plain object (class instance, built-in object, etc.), the result is `never`.
- *        - If it has no keys (`IsHasKeysObject<T>` checked by **{@link IsHasKeysObject}** is false), the result is `Record<PropertyKey, unknown> & T`.
+ *        - If it has no keys (`IsHasKeysObject<T>` checked by **{@link IsHasKeysObject|`IsHasKeysObject`}** is false), the result is `Record<PropertyKey, unknown> & T`.
  *        - Otherwise, the result is `T` itself.
  *    - For any other types, the result is `never`.
  * @template T - The input type to be asserted as a plain object.