@rzl-zone/utils-js 3.7.1 → 3.8.0

package/dist/generators/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.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,12 +2,12 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.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-SLP24LUV.js';
 import '../chunk-WVSPXFTY.js';
 export { noop } from '../chunk-YWHHVDT4.js';
 import '../chunk-2VO2CBTU.js';

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.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.8.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.

package/dist/next/index.cjs

@@ -2,14 +2,14 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
 'use strict';
 
-var chunkBG3AS5BU_cjs = require('../chunk-BG3AS5BU.cjs');
+var chunkSGCN4ED4_cjs = require('../chunk-SGCN4ED4.cjs');
 require('../chunk-VJVCXEH7.cjs');
 var chunkLIU4S3JA_cjs = require('../chunk-LIU4S3JA.cjs');
 var chunkNREACG6M_cjs = require('../chunk-NREACG6M.cjs');
@@ -25,7 +25,9 @@ function generateRoute(route, params) {
 - Invalid 'route' value.
 - Must be of type \`string\` and non-empty string, but received: "${chunkF3WBQKRI_cjs.getPreciseType(
         route
-      )}": \`${chunkYC7AK3KX_cjs.safeStableStringify(route)}\`.`
+      )}": \`${chunkYC7AK3KX_cjs.safeStableStringify(route, {
+        keepUndefined: true
+      })}\`.`
     );
   }
   if (!/[\\[\]]/.test(route)) {
@@ -137,12 +139,12 @@ var createBeApiUrl = (pathname, options = {}) => {
     chunkF3WBQKRI_cjs.assertIsBoolean(withOrigin, {
       message: ({ currentType, validType }) => `Parameter \`withOrigin\` property of the \`options\` (second parameter) must be of type \`${validType}\`, but received: \`${currentType}\`.`
     });
-    pathname = chunkBG3AS5BU_cjs.normalizePathname(pathname);
-    prefix = chunkBG3AS5BU_cjs.normalizePathname(prefix);
+    pathname = chunkSGCN4ED4_cjs.normalizePathname(pathname);
+    prefix = chunkSGCN4ED4_cjs.normalizePathname(prefix);
     const normalizedPrefix = prefix.endsWith("/") ? prefix : prefix + "/";
     if (pathname === prefix || pathname === prefix + "/" || pathname.startsWith(normalizedPrefix)) {
       pathname = pathname.slice(prefix.length);
-      pathname = chunkBG3AS5BU_cjs.normalizePathname(pathname);
+      pathname = chunkSGCN4ED4_cjs.normalizePathname(pathname);
     }
     const baseApiUrl = getBeApiUrl({ suffix: prefix });
     const fullPath = withOrigin ? joinPath2(baseApiUrl, pathname) : joinPath2(new URL(baseApiUrl).pathname, pathname);
@@ -172,12 +174,12 @@ var getBeApiUrl = (options = {}) => {
       const urlObj = new URL(rawBaseUrl);
       const hasPort = !!urlObj.port;
       if (!hasPort && process.env.NEXT_PUBLIC_PORT_BE) {
-        rawBaseUrl = urlObj.origin + chunkBG3AS5BU_cjs.formatEnvPort(process.env.NEXT_PUBLIC_PORT_BE, {
+        rawBaseUrl = urlObj.origin + chunkSGCN4ED4_cjs.formatEnvPort(process.env.NEXT_PUBLIC_PORT_BE, {
           prefixColon: true
         });
       }
     } else {
-      rawBaseUrl = "http://localhost" + chunkBG3AS5BU_cjs.formatEnvPort(process.env.NEXT_PUBLIC_PORT_BE || "8000", {
+      rawBaseUrl = "http://localhost" + chunkSGCN4ED4_cjs.formatEnvPort(process.env.NEXT_PUBLIC_PORT_BE || "8000", {
         prefixColon: true
       });
     }
@@ -200,7 +202,7 @@ var getBaseUrl = () => {
     baseUrl = chunkLIU4S3JA_cjs.removeSpaces(baseUrl).replace(/\/+$/, "");
     const hasPort = /:\/\/[^/]+:\d+/.test(baseUrl);
     if (!hasPort && portEnv) {
-      baseUrl += chunkBG3AS5BU_cjs.formatEnvPort(portEnv, { prefixColon: true });
+      baseUrl += chunkSGCN4ED4_cjs.formatEnvPort(portEnv, { prefixColon: true });
     } else if (!hasPort && !baseEnv) {
       baseUrl += ":3000";
     }

package/dist/next/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -57,10 +57,10 @@ type HasDynamicSegments<T>=T extends`${string}[${string}]${string}`?true:false;t
  * @param {T} route - The route string containing dynamic segments.
  * @param {ExtractRouteParams<T>} [params] - An object containing key-value pairs that match the dynamic segments in the route.
  * @returns {string} The formatted URL with all dynamic segments replaced.
- * @throws {Error} If the route contains dynamic segments but no parameters object is provided.
- * @throws {Error} If a required parameter is missing from the `params` object.
- * @throws {Error} If a parameter value is an empty string.
- * @throws {Error} If any parameter contains invalid characters like `?`, `&`, `=`, `#`, `/`, spaces, `'`, `"`, `(`, `)`, `+`, `;`, `%`, `@`, or `:`, which can cause URL issues.
+ * @throws **{@link Error | `Error`}** if the route contains dynamic segments but no parameters object is provided.
+ * @throws **{@link Error | `Error`}** if a required parameter is missing from the `params` object.
+ * @throws **{@link Error | `Error`}** if a parameter value is an empty string.
+ * @throws **{@link Error | `Error`}** if any parameter contains invalid characters like `?`, `&`, `=`, `#`, `/`, spaces, `'`, `"`, `(`, `)`, `+`, `;`, `%`, `@`, or `:`, which can cause URL issues.
  * @example
  * // Basic usage
  * generateRoute("/user/[id]", { id: "123" });
@@ -115,9 +115,9 @@ withOrigin?:boolean;};
  * @param {OptionsCreateBeApiUrl["prefix"]} [options.prefix="/api"] - The prefix for the API path (default is `"/api"`).
  * @param {OptionsCreateBeApiUrl["withOrigin"]} [options.withOrigin=true] - Whether to include the full base URL or return only the API path.
  * @returns {string} The formatted API URL.
- * @throws {TypeError} If `withOrigin` is not a boolean.
- * @throws {TypeError} If `prefix` and `pathname` is not a string.
- * @throws {Error} If constructing the API URL fails due to an invalid base URL.
+ * @throws **{@link TypeError | `TypeError`}** if `withOrigin` is not a boolean.
+ * @throws **{@link TypeError | `TypeError`}** if `prefix` and `pathname` is not a string.
+ * @throws **{@link Error | `Error`}** if constructing the API URL fails due to an invalid base URL.
  * @example
  * createBeApiUrl("/users")
  * // ➔ "http://localhost:8000/api/users"
@@ -163,8 +163,8 @@ suffix?:string;};
  * @param {OptionsGetBeApiUrl|undefined} options - Configuration options.
  * @param {OptionsGetBeApiUrl["suffix"]} [options.suffix="/"] - The suffix to append to the base API URL.
  * @returns {string} The formatted backend API base URL.
- * @throws {TypeError} If `suffix` is not a `string`.
- * @throws {Error} If `NEXT_PUBLIC_BACKEND_API_URL` is invalid.
+ * @throws **{@link TypeError | `TypeError`}** if `suffix` is not a `string`.
+ * @throws **{@link Error | `Error`}** if `NEXT_PUBLIC_BACKEND_API_URL` is invalid.
  * @example
  * // With NEXT_PUBLIC_BACKEND_API_URL set at `*.env` file
  * NEXT_PUBLIC_BACKEND_API_URL = "https://api.example.com";
@@ -195,7 +195,7 @@ declare const getBeApiUrl:(options?:OptionsGetBeApiUrl)=>string;
  * - ***⚠️ Warning:***
  *    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
  * @returns {string} The resolved base URL of the application.
- * @throws {Error} If the constructed URL is invalid or malformed.
+ * @throws **{@link Error | `Error`}** if the constructed URL is invalid or malformed.
  * @example
  * // With environment variable set at `*.env` file
  * NEXT_PUBLIC_BASE_URL = "https://example.com";

package/dist/next/index.js

@@ -2,12 +2,12 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-import { normalizePathname, formatEnvPort } from '../chunk-WNO3EPYT.js';
+import { normalizePathname, formatEnvPort } from '../chunk-PW2VMJLT.js';
 import '../chunk-YS27V6LS.js';
 import { removeSpaces } from '../chunk-4ACKNPL5.js';
 import { isEmptyString } from '../chunk-JY4HLZ4W.js';
@@ -23,7 +23,9 @@ function generateRoute(route, params) {
 - Invalid 'route' value.
 - Must be of type \`string\` and non-empty string, but received: "${getPreciseType(
         route
-      )}": \`${safeStableStringify(route)}\`.`
+      )}": \`${safeStableStringify(route, {
+        keepUndefined: true
+      })}\`.`
     );
   }
   if (!/[\\[\]]/.test(route)) {

package/dist/next/server/index.cjs

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

package/dist/next/server/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -14,12 +14,12 @@ import{NextRequest}from'next/server';
  * **Retrieves the real client IP address and constructs the full URL using headers like `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-port`.**
  * - **ℹ️ Note:**
  *    - Only supported in **Next.js** environments (specifically in `server-only` contexts).
- *    - Should be used in **middleware** or **server actions** that have access to ***[`NextRequest - NextJS`](https://nextjs.org/docs/app/api-reference/functions/next-request)***.
+ *    - Should be used in **middleware**, **route-handler** or **server actions** that have access to ***[`NextRequest - NextJS`](https://nextjs.org/docs/app/api-reference/functions/next-request)***.
  * @param {NextRequest} request - The incoming ***`NextJS`*** request object, must be instanceof `NextRequest` from `next/server`.
  * @param {boolean|undefined} [includeFullUrl=true] - Whether to return the full URL (`protocol`, `IP`, and `port` like `protocol://ip:port`) or just the IP address, defaultValue: `true`.
  * @returns {string} The extracted client IP address or the full constructed URL.
- * @throws {Error} If the function is used outside a Next.js server environment.
- * @throws {TypeError} If the arguments do not match the expected types.
+ * @throws **{@link Error | `Error`}** if the function is used outside a Next.js server environment.
+ * @throws **{@link TypeError | `TypeError`}** if the arguments do not match the expected types.
  * @example
  * // Basic usage in Next.js middleware
  * import { NextRequest } from "next/server";

package/dist/next/server/index.js

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

package/dist/operations/index.cjs

@@ -2,15 +2,15 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
 'use strict';
 
-var chunkRMJC3B5P_cjs = require('../chunk-RMJC3B5P.cjs');
-require('../chunk-66WLOZOD.cjs');
+var chunkA4H7474O_cjs = require('../chunk-A4H7474O.cjs');
+require('../chunk-6NORJBI6.cjs');
 require('../chunk-7QQV66RX.cjs');
 require('../chunk-ATLFMKAF.cjs');
 require('../chunk-7WBMA2VE.cjs');
@@ -21,13 +21,13 @@ require('../chunk-F3WBQKRI.cjs');
 
 Object.defineProperty(exports, "findDuplicates", {
   enumerable: true,
-  get: function () { return chunkRMJC3B5P_cjs.findDuplicates; }
+  get: function () { return chunkA4H7474O_cjs.findDuplicates; }
 });
 Object.defineProperty(exports, "omitKeys", {
   enumerable: true,
-  get: function () { return chunkRMJC3B5P_cjs.omitKeys; }
+  get: function () { return chunkA4H7474O_cjs.omitKeys; }
 });
 Object.defineProperty(exports, "omitKeysDeep", {
   enumerable: true,
-  get: function () { return chunkRMJC3B5P_cjs.omitKeysDeep; }
+  get: function () { return chunkA4H7474O_cjs.omitKeysDeep; }
 });

package/dist/operations/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -13,7 +13,7 @@ import{NumberRangeUnion}from'@rzl-zone/ts-types-plus';
  * ----------------------------------------------------------------------
  * **Finds duplicate values in an array by deep equality comparison.**
  * - **Behavior:**
- *    - Uses ***{@link isEqual | `isEqual`}*** to compare elements
+ *    - Uses ***`isEqual` utility function*** to compare elements
  *      (handles objects, arrays, dates, NaN, etc.).
  *    - Returns a new array containing only the *first occurrences* of duplicated values.
  *    - Does **not mutate** the original array.
@@ -22,7 +22,7 @@ import{NumberRangeUnion}from'@rzl-zone/ts-types-plus';
  * @param {T[]} values - The array to check for duplicates.
  * @returns {T[]} An array of the duplicate values found in the input,
  *                preserving order of their first duplicate appearance.
- * @throws {TypeError} If the provided `values` argument is not an array.
+ * @throws **{@link TypeError | `TypeError`}** if the provided `values` argument is not an array.
  * @example
  * findDuplicates([1, 2, 2, 3, 4, 4]);
  * // ➔ [2, 4]
@@ -47,15 +47,15 @@ declare const findDuplicates:<T>(values:T[])=>T[];
  *    - It will return a new object without mutating the original.
  *    - It also validates that ***`keysToOmit`*** does not contain duplicate keys.
  * - **ℹ️ Internally:**
- *    - It uses ***{@link isEqual | `isEqual`}*** to check for duplicates in
+ *    - It uses ***`isEqual`*** to check for duplicates in
  *      the ***`keysToOmit`*** array.
  * @template I The type of the input object.
  * @template K The keys to omit from the object.
  * @param {I} object - The source object to omit keys from.
  * @param {K[]} keysToOmit - An array of keys to exclude from the returned object.
  * @returns {Omit<I, K>} A new object without the specified keys.
- * @throws {TypeError} If `keysToOmit` is not an array.
- * @throws {Error} If duplicate keys are found in `keysToOmit`.
+ * @throws **{@link TypeError | `TypeError`}** if `keysToOmit` is not an array.
+ * @throws **{@link Error | `Error`}** if duplicate keys are found in `keysToOmit`.
  * @example
  * omitKeys({ a: 1, b: 2, c: 3 }, ["b", "c"]);
  * //➔ { a: 1 }
@@ -90,9 +90,8 @@ declare const omitKeys:<I extends Record<string,unknown>,K extends keyof I>(obje
  * @returns {Partial<I>}
  *  A new deeply cloned object with the specified keys omitted, with resulting
  *  empty objects or arrays fully removed (even if it collapses to `{}`).
- * @throws {TypeError}
- *    If `keysToOmit` is not an array will throw TypeError.
- * @throws {Error} If `keysToOmit` contains duplicate paths will throw Error.
+ * @throws **{@link TypeError | `TypeError`}** if `keysToOmit` is not an array.
+ * @throws **{@link Error | `Error`}** if `keysToOmit` contains duplicate paths.
  * @example
  * omitKeysDeep({ arr: [{ a: 1 }] }, ["arr.0.a"]);
  * // ➔ {} (array becomes empty and removed)

package/dist/operations/index.js

@@ -2,13 +2,13 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.7.1.
+ * Version: 3.8.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-export { findDuplicates, omitKeys, omitKeysDeep } from '../chunk-D53CE4BT.js';
-import '../chunk-XFTUHS4Y.js';
+export { findDuplicates, omitKeys, omitKeysDeep } from '../chunk-P3ST4UZA.js';
+import '../chunk-KVZ3HL2B.js';
 import '../chunk-SZJ7OI4S.js';
 import '../chunk-VCVND6CH.js';
 import '../chunk-6WMB5AJR.js';

package/dist/parsers/index.cjs

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

package/dist/parsers/index.d.ts

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

package/dist/parsers/index.js

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

package/dist/predicates/index.cjs

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