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

package/dist/urls/index.d.cts

@@ -2,7 +2,7 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1-beta.0`
+*  Version: `3.14.0-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
@@ -11,95 +11,138 @@
 * * ***Type-Utility: `QueryParamPairs`.***
 * ----------------------------------------------------------
 * **Represents a non-empty array of key–value pairs.**
+*
+* ---
 * @description
 * Type for `queryParams` parameter, the second parameter of ***`constructURL` utility function***.
+*
+* ---
 * - **Behavior:**
-*    - Each inner tuple strictly follows the `[string, string | number]` shape.
-*    - Ensures the outer array contains **at least one pair** (non-empty).
-*    - Commonly used for URL construction parameters,
+*     - Each inner tuple strictly follows the `[string, string | number]` shape.
+*     - Ensures the outer array contains **at least one pair** (non-empty).
+*     - Commonly used for URL construction parameters,
 *      query string segments, or other key–value structured data.
+*
+* ---
 * @example
-* // ✅ valid usage
-* const params: QueryParamPairs = [
-*   ["foo", 1],
-*   ["bar", "baz"]
-* ];
-* constructURL("https://example.com", params);
-*
-* // ❌ invalid: must contain at least one item
-* const empty: QueryParamPairs = [];
-*
-* // ❌ invalid: key without value pairs.
-* const empty2: QueryParamPairs = [["key"]];
+* 1. #### Valid usage:
+*    ```ts
+*    const params: QueryParamPairs = [
+*      ["foo", 1],
+*      ["bar", "baz"]
+*    ];
+*    constructURL("https://example.com", params);
+*    ```
+*    ---
+* 2. #### Invalid: must contain at least one item:
+*    ```ts
+*    const empty: QueryParamPairs = [];
+*    ```
+*    ---
+* 3. #### Invalid: key without value pairs:
+*    ```ts
+*    const empty2: QueryParamPairs = [["key"]];
+*    ```
 */
 type QueryParamPairs = [[string, string | number], ...[string, string | number][]];
-/** ---------------------------------
+/** ---------------------------------------------------------------------------------------------------
 * * ***Utility: `constructURL`.***
-* ---------------------------------
-* **Constructs a valid URL with optional query parameters and allows selective removal of duplicate parameters.**
-* @param {string | URL} baseUrl The base URL to build upon. Must include protocol (e.g., `"https://"`), `domain`, and may include port and existing query parameters.
+* ----------------------------------------------------------------------------------------------------
+* **Constructs a valid URL with optional query parameters and allows selective removal
+* of duplicate parameters.**
+*
+* ---
+* @param {string | URL} baseUrl
+*        The base URL to build upon. Must include protocol (e.g., `"https://"`), `domain`, and may include port and existing query parameters.
 * @param {Iterable<[string, string]> | URLSearchParamsIterator<[string, string]> | QueryParamPairs} [queryParams]
 *   Additional query parameters to append or overwrite on the URL.
 *   - Accepts any iterable of key-value pairs (like `new URLSearchParams().entries()` and `[[string, string | number]...]`).
 * @param {string[]} [removeParams]
 *   A list of query parameter keys to remove from the final URL, whether they were in the base URL or provided queryParams.
+*
+* ---
+* @throws **{@link TypeError | `TypeError`}** if `baseUrl` is not a valid non-empty string or URL object, or if `queryParams` is not iterable, or
+*        if `removeParams` is not an array of strings.
+*
+* ---
 * @returns {URL} A new URL object representing the constructed URL with merged and cleaned query parameters.
-* @throws **{@link TypeError | `TypeError`}** if `baseUrl` is not a valid non-empty string or URL object, or if `queryParams` is not iterable, or if `removeParams` is not an array of strings.
+*
+* ---
 * @example
-*    1. #### Basic Usage:
-* ```ts
-*   constructURL(
-*     "https://example.com/path",
-*     new URLSearchParams({ a: "1", b: "2" }).entries()
-*   );
-*   // ➔ URL { href: "https://example.com/path?a=1&b=2", ... }
-* ```
-*    2. #### Remove parameters from Base and Added:
-* ```ts
-*   // with new URLSearchParams({ ... }).entries();
-*   constructURL(
-*     "https://example.com/path?foo=1&bar=2",
-*     new URLSearchParams({ bar: "ignored", baz: "3" }).entries(),
-*     ["bar"]
-*   );
-*   // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
-*
-*   // with [[string, string | number]...]
-*   constructURL(
-*     "https://example.com/path?foo=1&bar=2",
-*     [["bar", "ignored"],["baz", 3]],
-*     ["bar"]
-*   );
-*   // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
-*
-*   const params: QueryParamPairs = [
-*     ["foo", 1],
-*     ["bar", 2],
-*     ["baz", 3]
-*   ];
-*
-*   constructURL("https://example.com", params, ["bar"]);
-*   // ➔ URL { href: "https://example.com/?foo=1&baz=3", ... }
-* ```
+* 1. #### Basic Usage:
+*    ```ts
+*    constructURL(
+*      "https://example.com/path",
+*      new URLSearchParams({ a: "1", b: "2" }).entries()
+*    );
+*    ```
+*    #### Result ➔ `URL { href: "https://example.com/path?a=1&b=2", ... }`
+*    ---
+* 2. #### Remove parameters from Base and Added:
+*       - #### With `new URLSearchParams({ ... }).entries();`:
+*            ```ts
+*            constructURL(
+*              "https://example.com/path?foo=1&bar=2",
+*              new URLSearchParams({ bar: "ignored", baz: "3" }).entries(),
+*              ["bar"]
+*            );
+*            ```
+*            #### Result ➔ `URL { href: "https://example.com/path?foo=1&baz=3", ... }`
+*            ---
+*
+*       - #### With `[[string, string | number]...]`:
+*            ```ts
+*            constructURL(
+*              "https://example.com/path?foo=1&bar=2",
+*              [["bar", "ignored"],["baz", 3]],
+*              ["bar"]
+*            );
+*            ```
+*            #### Result ➔ `URL { href: "https://example.com/path?foo=1&baz=3", ... }`
+*            ---
+*
+*       - #### With separated variable and `[[string, number]...]` :
+*            ```ts
+*            const params: QueryParamPairs = [
+*              ["foo", 1],
+*              ["bar", 2],
+*              ["baz", 3]
+*            ];
+*
+*            constructURL("https://example.com", params, ["bar"]);
+*            ```
+*            #### Result ➔ `URL { href: "https://example.com/?foo=1&baz=3", ... }`
 */
 declare const constructURL: (baseUrl: string | URL, queryParams?: URLSearchParamsIterator<[string, string | number]> | QueryParamPairs, removeParams?: string[]) => URL;
 /** ---------------------------------
 * * ***Utility: `extractURLs`.***
 * ---------------------------------
 * **Extracts all valid URLs from a given string.**
+*
+* ---
 * @description
 * This function scans the input url and returns an array of URLs
 * that match a valid `http` or `https` format.
-* - **Supports:**
-*    - Internationalized domain names (IDN), e.g. `https://münich.de`
-*    - Unicode & emoji paths, e.g. `https://example.com/🎉/page`
-*    - Long URLs with multiple queries & fragments, e.g. `https://example.com/path?foo=1#hash`
-* - **Ignores:**
-*    - Non-string inputs
-*    - Empty or whitespace-only strings
-*    - Non-HTTP(S) protocols (ftp, mailto, etc)
+*
+* ---
+* - #### *Behavior:*
+*      - #### Supports:
+*           - Internationalized domain names (IDN), e.g. `https://münich.de`.
+*           - Unicode & emoji paths, e.g. `https://example.com/🎉/page`.
+*           - Long URLs with multiple queries & fragments, e.g. `https://example.com/path?foo=1#hash`.
+*           ---
+*      - #### Ignores:
+*           - Non-string inputs.
+*           - Empty or whitespace-only strings.
+*           - Non-HTTP(S) protocols (ftp, mailto, etc).
+*
+* ---
 * @param {string | null | undefined} url - The input string containing potential URLs.
+*
+* ---
 * @returns {string[] | null} An array of extracted URLs or `null` if no URLs are found.
+*
+* ---
 * @example
 * extractURLs("Visit https://example.com and https://例子.公司");
 * // ➔ ["https://example.com", "https://例子.公司"]
@@ -113,17 +156,23 @@ declare const extractURLs: (url: string | null | undefined) => string[] | null;
 * * ***Utility: `getFirstPrefixPathname`.***
 * --------------------------------------------------------
 * **Extract First Valid Prefix from Path Array or String.**
+*
+* ---
 * - **Main Purpose:**
-*    - This function helps extract the first valid URL prefix from various possible inputs.
-*    - It is especially useful in routing systems, middleware, or frontend apps that need to
-*      decide layout, active navigation, or permissions based on the first segment (or prefix) of a pathname.
+*     - This function helps extract the first valid URL prefix from various possible inputs.
+*     - It is especially useful in routing systems, middleware, or frontend apps that need to
+*       decide layout, active navigation, or permissions based on the first segment (or prefix) of a pathname.
+*
+* ---
 * - **Typical uses include:**
-*    - Determining which layout to render (e.g., `/admin` vs `/dashboard` vs `/`).
-*    - Highlighting the active menu item in a sidebar based on the current URL.
-*    - Enforcing route guards or access controls depending on the URL prefix.
-*    - Parsing multi-level route prefixes and selecting the most relevant one.
+*     - Determining which layout to render (e.g., `/admin` vs `/dashboard` vs `/`).
+*     - Highlighting the active menu item in a sidebar based on the current URL.
+*     - Enforcing route guards or access controls depending on the URL prefix.
+*     - Parsing multi-level route prefixes and selecting the most relevant one.
+*
+* ---
 * - **Behavior:**
-*    - It works as follows:
+*     - It works as follows:
 *        - If `result` is an array of strings, it normalizes each element and returns
 *          the first non-root path (i.e., not just `"/"`).
 *        - If all items normalize to `"/"`,
@@ -131,66 +180,15 @@ declare const extractURLs: (url: string | null | undefined) => string[] | null;
 *        - If `result` is a single string, it normalizes it and returns it if valid,
 *          otherwise falls back to the normalized `defaultValue`.
 *        - If `result` is `null` or `undefined`, it returns the normalized `defaultValue`.
-* - **Validation & Errors:**
-*    - Throws a `TypeError` if:
-*      - `defaultValue` is not a string or empty-string.
-*      - `result` is an array that contains non-string elements.
-*      - `result` is a value that is neither `string`, `string[]`, nor `null`.
-* @example
-* 1. #### For React (*Determining layout*):
-* ```ts
-*   const prefix = getFirstPrefixPathname(
-*      getPrefixPathname(
-*        "/admin/settings",
-*        ["/admin", "/dashboard"]
-*      )
-*   );
-*
-*   if (prefix === "/admin") {
-*     renderAdminLayout();
-*   }
-* ```
 *
-* 2. #### Setting active menu state:
-* ```ts
-*   const activeSection = getFirstPrefixPathname(["", "/dashboard", "/profile"]);
-*   // ➔ "/dashboard"
-* ```
+* ---
+* - **Validation & Errors:**
+*     - Throws a `TypeError` if:
+*       - `defaultValue` is not a string or empty-string.
+*       - `result` is an array that contains non-string elements.
+*       - `result` is a value that is neither `string`, `string[]`, nor `null`.
 *
-* 3. #### Providing graceful fallback:
-* ```ts
-*   const section = getFirstPrefixPathname([], "/home");
-*   // ➔ "/home"
-* ```
-* 4. #### ✅ Using with an Array of Pathnames:
-* ```ts
-*   const result = getPrefixPathname(["   ", "/dashboard", "/settings"]);
-*   console.log(getFirstPrefixPathname(result));
-*   // ➔ "/dashboard"
-* ```
-*
-* 5. #### ✅ Using with Single String:
-* ```ts
-*   console.log(getFirstPrefixPathname("/profile/settings"));
-*   // ➔ "/profile/settings"
-*   console.log(getFirstPrefixPathname("   "));
-*   // ➔ "/"
-* ```
-*
-* 6. #### ✅ Fallback to Custom Default:
-* ```ts
-*   console.log(getFirstPrefixPathname(["   ", ""], "/home"));
-*   // ➔ "/home"
-*   console.log(getFirstPrefixPathname(null, "/dashboard"));
-*   // ➔ "/dashboard"
-* ```
-*
-* 7. #### ✅ Throws on Invalid Input:
-* ```ts
-*   getFirstPrefixPathname([1, 2] as any); // ➔ ❌ throws TypeError
-*   getFirstPrefixPathname({} as any);     // ➔ ❌ throws TypeError
-*   getFirstPrefixPathname(null, "   ");   // ➔ ❌ throws TypeError
-* ```
+* ---
 * @param {string | string[] | null | undefined} result
 *  ***The pathname(s) to process, can be:***
 *    - A string path (e.g. `"/profile"`),
@@ -200,191 +198,309 @@ declare const extractURLs: (url: string | null | undefined) => string[] | null;
 *  ***A custom default path to use if `result` is null or no valid prefix is found, behavior:***
 *      - Must be a string and non-empty string.
 *      - Defaults to `"/"`.
-* @returns {string}
-*   ***The first valid normalized pathname, or the normalized default.***
+*
+* ---
 * @throws **{@link TypeError | `TypeError`}** ***if `result` is not a valid type, or `defaultValue` is not a string or empty-string.***
+*
+* ---
+* @returns {string} ***The first valid normalized pathname, or the normalized default.***
+*
+* ---
+* @example
+* 1. #### For React (*Determining layout*):
+*    ```ts
+*    const prefix = getFirstPrefixPathname(
+*       getPrefixPathname(
+*         "/admin/settings",
+*         ["/admin", "/dashboard"]
+*       )
+*    );
+*
+*    if (prefix === "/admin") {
+*      renderAdminLayout();
+*    }
+*    ```
+*    ---
+* 2. #### Setting active menu state:
+*    ```ts
+*    const activeSection = getFirstPrefixPathname(["", "/dashboard", "/profile"]);
+*    // ➔ "/dashboard"
+*    ```
+*    ---
+* 3. #### Providing graceful fallback:
+*    ```ts
+*    const section = getFirstPrefixPathname([], "/home");
+*    // ➔ "/home"
+*    ```
+*    ---
+* 4. #### Using with an Array of Pathnames:
+*    ```ts
+*    const result = getPrefixPathname(["   ", "/dashboard", "/settings"]);
+*    console.log(getFirstPrefixPathname(result));
+*    // ➔ "/dashboard"
+*    ```
+*    ---
+* 5. #### Using with Single String:
+*    ```ts
+*    console.log(getFirstPrefixPathname("/profile/settings"));
+*    // ➔ "/profile/settings"
+*    console.log(getFirstPrefixPathname("   "));
+*    // ➔ "/"
+*    ```
+*    ---
+* 6. #### Fallback to Custom Default:
+*    ```ts
+*    console.log(getFirstPrefixPathname(["   ", ""], "/home"));
+*    // ➔ "/home"
+*    console.log(getFirstPrefixPathname(null, "/dashboard"));
+*    // ➔ "/dashboard"
+*    ```
+*    ---
+* 7. #### Throws on Invalid Input:
+*    ```ts
+*    getFirstPrefixPathname([1, 2] as any);
+*    // ➔ ❌ throws TypeError
+*    getFirstPrefixPathname({} as any);
+*    // ➔ ❌ throws TypeError
+*    getFirstPrefixPathname(null, "   ");
+*    // ➔ ❌ throws TypeError
+*    ```
 */
 declare const getFirstPrefixPathname: (result: string | string[] | null | undefined, defaultValue?: string) => string;
 type GetPrefixPathnameOptions = {
-  /** The number of levels to include in the prefix (default is `1`).
+  /** --------------------------------------------------------
+  * * ***The number of levels to include in the prefix (default is `1`).***
+  * ---------------------------------------------------------
   *
   * - For example, with `levels = 2`, the function will return the first two parts of the URL.
-  *
+  * ---
   * @default 1
   */
   levels?: number;
-  /** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`).
+  /** --------------------------------------------------------
+  * * ***Whether to remove duplicates from the result if multiple URLs are passed (default is `true`).***
+  * ---------------------------------------------------------
   *
+  * - ***⚠️ Warning:***
+  *      - Non-boolean values will throw `TypeError`.
+  * ---
   * @default true
   */
   removeDuplicates?: boolean;
 };
 /** --------------------------------------------------------
 * * ***Utility: `getPrefixPathname`.***
-* --------------------------------------------------------
+* ---------------------------------------------------------
 * **Get Prefix from URL with Optional Base or Auto-detection (Supports String or Array of URLs).**
+*
+* ---
 * - **This function extracts the prefix from one or more URLs. It can either:**
-*    - Use a provided `base` string or an array of strings to check and return the matching prefix.
-*    - Automatically detect the prefix if no `base` is provided by analyzing the first part of the URL.
+*     - Use a provided `base` string or an array of strings to check and return the matching prefix.
+*     - Automatically detect the prefix if no `base` is provided by analyzing the first part of the URL.
+* ---
+*
 * - **The function is flexible and can handle both scenarios:**
-*    1. **When the base is provided as a single string or an array of strings**:
-*        - The function will check if the URL starts with one of the provided base(s) and return the matching base.
-*    2. **When the base is not provided**:
-*        - The function will automatically detect the prefix by splitting the URL or using a regex.
+*     1. **When the base is provided as a single string or an array of strings**:
+*          - The function will check if the URL starts with one of the provided base(s) and return the matching base.
+*     2. **When the base is not provided**:
+*          - The function will automatically detect the prefix by splitting the URL or using a regex.
+* ---
 * - **Important Notes**:
-*    - If a base (or an array of bases) is provided, the URL must start with one of the given base(s).
-*    - If no base is provided, the function will attempt to detect the prefix automatically.
-*    - The `url` parameter can be either a string or an array of strings.
-*    - Supports deduplication of results (enabled by default).
-*    - Automatically returns a single string if only one unique result exists after processing.
+*     - If a base (or an array of bases) is provided, the URL must start with one of the given base(s).
+*     - If no base is provided, the function will attempt to detect the prefix automatically.
+*     - The `url` parameter can be either a string or an array of strings.
+*     - Supports deduplication of results (enabled by default).
+*     - Automatically returns a single string if only one unique result exists after processing.
+* ---
+*
 * @param {string|string[]} url
 *  ***The full URL(s) from which the prefix should be extracted, can be a `string` or an `array of strings`.***
 * @param {string|string[]|null} [base=null]
 *  ***The base URL(s) (e.g., `"/settings"`), behavior:***
-*    - It can be a `string`, an `array of strings`, or `null`.
-*    - If `provided`, it will be used to check the URL(s).
-*    - If `not provided`, the prefix will be auto-detected.
+*     - It can be a `string`, an `array of strings`, or `null`.
+*     - If `provided`, it will be used to check the URL(s).
+*     - If `not provided`, the prefix will be auto-detected.
 * @param {GetPrefixPathnameOptions} [options]
 *  ***Additional options object:***
-*    - `levels` (default `1`): The number of segments to include when auto-detecting the prefix (e.g. `/foo/bar` for `levels: 2`).
-*    - `removeDuplicates` (default `true`): Whether to remove duplicate prefixes from the final array result.
-* @returns {string|string[]|null}
-*  ***Returns one of:***
-*    - A single string if only one unique prefix/base is found.
-*    - An array of strings if multiple different prefixes/bases are found.
-*    - `null` if no matching base is found when using `base`.
+*     - `levels` (default `1`): The number of segments to include when auto-detecting the prefix (e.g. `/foo/bar` for `levels: 2`).
+*     - `removeDuplicates` (default `true`): Whether to remove duplicate prefixes from the final array result.
+*
+* ---
 * @throws **{@link TypeError | `TypeError`}**
 *  ***if:***
-*    - `url` is `not a string` or `not an array of strings`.
-*    - `base` is `not a string`, `array of strings`, or `null`.
-*    - `options` is `not an object`.
-*    - `levels` is `not a number`.
-*    - `removeDuplicates` is `not a boolean`.
-* @example
-* - #### ✅ **Correct Usage (With an Array of URLs and Base):**
-* ```ts
-*    const routes = [
-*      "/settings/profile",
-*      "/settings/password",
-*      "/settings/other-path",
-*      "/other-path/xyz",
-*    ];
+*     - `url` is `not a string` or `not an array of strings`.
+*     - `base` is `not a string`, `array of strings`, or `null`.
+*     - `options` is `not an object`.
+*     - `levels` is `not a number`.
+*     - `removeDuplicates` is `not a boolean`.
 *
-*    // With base provided as a string
-*    routes.forEach(route => {
-*      console.log(getPrefixPathname(route, '/settings'));
+* ---
+* @returns {string|string[]|null}
+*  ***Returns one of:***
+*     - A single string if only one unique prefix/base is found.
+*     - An array of strings if multiple different prefixes/bases are found.
+*     - `null` if no matching base is found when using `base`.
+*
+* ---
+* @example
+* 1.  #### Correct Usage (With an Array of URLs and Base):
+*      ```ts
+*      const routes = [
+*        "/settings/profile",
+*        "/settings/password",
+*        "/settings/other-path",
+*        "/other-path/xyz",
+*      ];
+*
+*      // With base provided as a string
+*      routes.forEach(route => {
+*        console.log(getPrefixPathname(route, '/settings'));
+*        // ➔ "/settings"
+*      });
+*
+*      // With base provided as an array
+*      routes.forEach(route => {
+*        console.log(getPrefixPathname(route, ['/settings', '/admin']));
+*        // ➔ "/settings" or "/admin" depending on the current URL.
+*      });
+*      ```
+*      ---
+* 2.  #### Correct Usage (With Single URL and Single Base):
+*      ```ts
+*      const result = getPrefixPathname("/settings/profile", "/settings");
+*      console.log(result);
+*      // ➔ "/settings"
+*      ```
+*      ---
+* 3.  #### Correct Usage (With Multiple URLs and Single Base):
+*      ```ts
+*      const result = getPrefixPathname(
+*        ["/settings/profile", "/settings/password"],
+*        "/settings"
+*      );
+*      console.log(result);
 *      // ➔ "/settings"
-*    });
-*
-*    // With base provided as an array
-*    routes.forEach(route => {
-*      console.log(getPrefixPathname(route, ['/settings', '/admin']));
-*      // ➔ "/settings" or "/admin" depending on the current URL.
-*    });
-* ```
-* - #### ✅ **Correct Usage (With Single URL and Single Base):**
-* ```ts
-*    const result = getPrefixPathname("/settings/profile", "/settings");
-*    console.log(result); // ➔ "/settings"
-* ```
-* - #### ✅ **Correct Usage (With Multiple URLs and Single Base):**
-* ```ts
-*    const result = getPrefixPathname(
-*      ["/settings/profile", "/settings/password"],
-*      "/settings"
-*    );
-*    console.log(result); // ➔ "/settings"
 *
-*    const result2 = getPrefixPathname(
-*      ["/settings/profile", "/other/password"],
-*      "/other"
-*    );
-*    console.log(result2); // ➔ "/other"
-* ```
-* - #### ✅ **Correct Usage (With Multiple URLs and Multiple Bases)**
-* ```ts
-*    const result = getPrefixPathname(
-*      ["/settings/profile", "/admin/password"],
-*      ["/settings", "/admin"]
-*    );
-*    console.log(result); // ➔ ["/settings", "/admin"]
-* ```
-* - #### ✅ **Auto-detection of Prefix**
-* ```ts
-*    const result = getPrefixPathname("/settings/profile");
-*    console.log(result); // ➔ "/settings"
-*
-*    const result2 = getPrefixPathname(
-*      "/settings/profile/info",
-*      null,
-*      { levels: 2 }
-*    );
-*    console.log(result2); // ➔ "/settings/profile"
-* ```
-* - #### ✅ **Multiple URLs with Auto-detection**
-* ```ts
-*    const result = getPrefixPathname(["/admin/profile", "/settings/password"]);
-*    console.log(result); // ➔ ["/admin", "/settings"]
-* ```
-* - #### ✅ **Handling Duplicates**
-* ```ts
-*    const result = getPrefixPathname(
-*      ["/settings/profile", "/settings/password"],
-*      "/settings"
-*    );
-*    console.log(result); // ➔ "/settings" (deduped to single string)
+*      const result2 = getPrefixPathname(
+*        ["/settings/profile", "/other/password"],
+*        "/other"
+*      );
+*      console.log(result2);
+*      // ➔ "/other"
+*      ```
+*      ---
+* 4.  #### Correct Usage (With Multiple URLs and Multiple Bases):
+*      ```ts
+*      const result = getPrefixPathname(
+*        ["/settings/profile", "/admin/password"],
+*        ["/settings", "/admin"]
+*      );
+*      console.log(result);
+*      // ➔ ["/settings", "/admin"]
+*      ```
+*      ---
+* 5.  #### Auto-detection of Prefix:
+*      ```ts
+*      const result = getPrefixPathname("/settings/profile");
+*      console.log(result);
+*      // ➔ "/settings"
 *
-*    const result2 = getPrefixPathname(
-*      ["/settings/profile", "/settings/profile"],
-*      "/settings",
-*      { removeDuplicates: false }
-*    );
-*    console.log(result2); // ➔ ["/settings", "/settings"]
-* ```
-* - #### ❌ **Incorrect Usage (URL Does Not Match Base)**
-* ```ts
-*    const result = getPrefixPathname("/other-path/profile", "/settings");
-*    console.log(result); // ➔ null
-* ```
+*      const result2 = getPrefixPathname(
+*        "/settings/profile/info",
+*        null,
+*        { levels: 2 }
+*      );
+*      console.log(result2);
+*      // ➔ "/settings/profile"
+*      ```
+*      ---
+* 6.  #### Multiple URLs with Auto-detection:
+*      ```ts
+*      const result = getPrefixPathname(["/admin/profile", "/settings/password"]);
+*      console.log(result);
+*      // ➔ ["/admin", "/settings"]
+*      ```
+*      ---
+* 7.  #### Handling Duplicates:
+*      ```ts
+*      const result = getPrefixPathname(
+*        ["/settings/profile", "/settings/password"],
+*        "/settings"
+*      );
+*      console.log(result);
+*      // ➔ "/settings" (deduped to single string)
+*
+*      const result2 = getPrefixPathname(
+*        ["/settings/profile", "/settings/profile"],
+*        "/settings",
+*        { removeDuplicates: false }
+*      );
+*      console.log(result2);
+*      // ➔ ["/settings", "/settings"]
+*      ```
+*      ---
+* 8.  #### Incorrect Usage (URL Does Not Match Base):
+*      ```ts
+*      const result = getPrefixPathname("/other-path/profile", "/settings");
+*      console.log(result);
+*      // ➔ null
+*      ```
 */
 declare const getPrefixPathname: (url: string | string[], base?: string | string[] | null, options?: GetPrefixPathnameOptions) => string | string[] | null;
-/** Options when `keepNullable` is false (default).
-*
+/** --------------------------------------------------------
+* * ***Options when `keepNullable` is false (default).***
+* ---------------------------------------------------------
 * Returns `defaultPath` if `pathname` is empty or invalid.
 */
 type UnKeepNullableOptions = {
-  /** * ***Fallback value returned if `pathname` is empty-string or invalid.***
-  *
+  /** --------------------------------------------------------
+  *  * ***Fallback value returned if `pathname` is empty-string or invalid.***
+  * ---------------------------------------------------------
   * Must be a **`non-empty string`**, defaultValue: `"/"`.
   *
+  * ---
   * @default "/"
   */
   defaultPath?: string;
-  /** * ***Whether to preserve `null` or `undefined`, defaultValue: `false`.***
+  /** --------------------------------------------------------
+  * * ***Whether to preserve `null` or `undefined`, defaultValue: `false`.***
+  * ---------------------------------------------------------
   *
+  * - ***⚠️ Warning:***
+  *      - Non-boolean values will throw `TypeError`.
+  * ---
   * @default false
   */
   keepNullable?: false;
 };
-/** Options when `keepNullable` is true.
+/** --------------------------------------------------------
+* * ***Options when `keepNullable` is true.***
+* ---------------------------------------------------------
 *
 * Preserves `null` or `undefined` instead of returning `defaultPath`.
 */
 type KeepNullableOptions = {
-  /** * ***Fallback path is ignored when `keepNullable` is true **(except if
+  /** --------------------------------------------------------
+  * * ***Fallback path is ignored when `keepNullable` is true **(except if
   * `pathname` is empty-string or invalid, even this `true`)**,
   * defaultValue: `"/"`.***
+  * --------------------------------------------------------
   *
   * @default "/"
   */
   defaultPath?: string;
-  /** * ***Preserve `null` or `undefined` as-is if `true` (defaultValue: `false`).***
-  *
-  * - ***⚠️ Notes:***
-  *      - Keep returning `defaultPath` if `pathname` is empty-string, even this `true`.
+  /** --------------------------------------------------------
+  *  * ***Preserve `null` or `undefined` as-is if `true` (defaultValue: `false`).***
+  * --------------------------------------------------------
   *
+  * - ***⚠️ Warning:***
+  *      - Keeps returning `defaultPath` when `pathname` is an empty string, even if enabled.
+  *      - Non-boolean values will throw `TypeError`.
+  * ---
   * **Must be `true` in this type.**
   *
+  * ---
+  *
   * @default false
   */
   keepNullable?: true;
@@ -392,96 +508,107 @@ type KeepNullableOptions = {
 type MainNormalizePathnameOptions = {
   /** --------------------------------------------------------
   * * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `false`.***
-  * --------------------------------------------------------
+  * ---------------------------------------------------------
+  *
+  * - ***⚠️ Warning:***
+  *      - Non-boolean values will throw `TypeError`.
+  * ---
+  *
+  * @default false
   *
-  * @default `false`
   */
   keepTrailingSlash?: boolean;
   /** --------------------------------------------------------
   * * ***Allow special localhost domain at the beginning of the pathname.***
-  * --------------------------------------------------------
+  * ---------------------------------------------------------
   * @description
   * If `true`, the first segment of the pathname that is `/localhost` or `localhost`
   * (with or without a port, e.g., `localhost:3000`) will be treated as a special domain
   * and **removed** from the normalized pathname.
   *
+  * ---
   * - **Examples (`localhostDomain: true`)**:
-  *    - `"/localhost/path"` ➔ `"/path"`
-  *    - `"localhost:3000/path"` ➔ `"/path"`
-  *    - `"localhost"` ➔ `"/"` (entire path removed)
-  *
+  *      - `"/localhost/path"` ➔ `"/path"`.
+  *      - `"localhost:3000/path"` ➔ `"/path"`.
+  *      - `"localhost"` ➔ `"/"` (**entire path removed**).
+  * ---
   * - Only the **first path segment** is affected. Any subsequent occurrences of `"localhost"`
   *   will remain intact.
+  * ---
+  * - ***⚠️ Warning:***
+  *      - Non-boolean values will throw `TypeError`.
   *
   * @default false
   */
   localhostDomain?: boolean;
-  /**
-  * --------------------------------------------------------
+  /** --------------------------------------------------------
   * * ***Custom list of file extensions that prevent the first path segment from being treated as a domain.***
   * --------------------------------------------------------
   *
-  * **Description:**
-  * - The first segment of a pathname is often interpreted as a domain (e.g., `example.com`).
-  * - If this first segment ends with any of the extensions listed here, it will **not** be considered a domain,
-  *   and will instead be preserved as part of the relative path.
-  * - This is useful for cases where filenames appear at the start of a path and you want them treated as relative paths,
-  *   such as `"image.png?version=2"` or `"archive.tar.gz#download"`.
-  * - Only the **first path segment** is affected; all other segments are processed normally.
-  * - **Ignored** if:
-  *    1. The pathname starts with a full URL protocol (`http://` or `https://`), e.g., `"https://example.com/file.png"`.
-  *    2. The first path segment is already a valid domain, e.g., `"example.com/image.png"`.
-  *
-  * **Type & Validation:**
-  * - Must be a `Set<string>` or `string[]`.
-  * - Each string **must include the leading dot**, e.g., `.png`, `.tar.gz`.
-  * - Multi-part extensions (like `.tar.gz`, `.tar.bz`) are supported.
-  * - Throws a **TypeError** if:
-  *    1. The type is not a `Set<string>` or `string[]`.
-  *    2. Any string in the array/set is empty.
-  *    3. Any string does not start with a dot (`.`).
-  *
-  * **Usage Notes:**
-  * - Only applied when the first segment is otherwise domain-like **and** pathname is relative or domain-like without protocol.
-  * - Query strings (`?x=1`) and hash fragments (`#section`) are preserved.
-  *
-  * **Examples (relative paths, option active):**
-  * ```ts
-  * normalizePathname("image.png?version=2", {
-  *   ignoreDomainExtensions: [".png", ".jpg"]
-  * });
-  * // ➔ "/image.png?version=2"
-  *
-  * normalizePathname("archive.tar.gz#download", {
-  *   ignoreDomainExtensions: new Set([".tar.gz"])
-  * });
-  * // ➔ "/archive.tar.gz#download"
-  *
-  * normalizePathname("script.js?module=true#top", {
-  *   ignoreDomainExtensions: [".js"]
-  * });
-  * // ➔ "/script.js?module=true#top"
-  * ```
-  *
-  * **Examples (full URL or explicit domain - option ignored):**
-  * ```ts
-  * normalizePathname("https://example.com/image.png?version=2", {
-  *   ignoreDomainExtensions: [".png"]
-  * });
-  * // ➔ "/image.png?version=2"  // URL is parsed normally; ignoreDomainExtensions has no effect
-  *
-  * normalizePathname("example.com/script.js?module=true#top", {
-  *   ignoreDomainExtensions: [".js"]
-  * });
-  * // ➔ "/script.js?module=true#top"  // domain recognized; option ignored
-  * ```
-  *
-  * **Notes:**
+  * - **Behavior:**
+  *     - The first segment of a pathname is often interpreted as a domain (e.g., `example.com`).
+  *     - If this first segment ends with any of the extensions listed here, it will **not** be considered a domain,
+  *       and will instead be preserved as part of the relative path.
+  *     - This is useful for cases where filenames appear at the start of a path and you want them treated as relative paths,
+  *       such as `"image.png?version=2"` or `"archive.tar.gz#download"`.
+  *     - Only the **first path segment** is affected; all other segments are processed normally.
+  *     - **Ignored** if:
+  *         1. The pathname starts with a full URL protocol (`http://` or `https://`), e.g., `"https://example.com/file.png"`.
+  *         2. The first path segment is already a valid domain, e.g., `"example.com/image.png"`.
+  * ---
+  * - **Type & Validation:**
+  *     - Must be a `Set<string>` or `string[]`.
+  *     - Each string **must include the leading dot**, e.g., `.png`, `.tar.gz`.
+  *     - Multi-part extensions (like `.tar.gz`, `.tar.bz`) are supported.
+  *     - Throws a **TypeError** if:
+  *        1. The type is not a `Set<string>` or `string[]`.
+  *        2. Any string in the array/set is empty.
+  *        3. Any string does not start with a dot (`.`).
+  * ---
+  * - **Usage Notes:**
+  *     - Only applied when the first segment is otherwise domain-like **and** pathname is relative or domain-like without protocol.
+  *     - Query strings (`?x=1`) and hash fragments (`#section`) are preserved.
+  *
+  * ---
+  * @example
+  *
+  * 1.  #### Examples (relative paths, option active):
+  *     ```ts
+  *     normalizePathname("image.png?version=2", {
+  *       ignoreDomainExtensions: [".png", ".jpg"]
+  *     });
+  *     // ➔ "/image.png?version=2"
+  *
+  *     normalizePathname("archive.tar.gz#download", {
+  *       ignoreDomainExtensions: new Set([".tar.gz"])
+  *     });
+  *     // ➔ "/archive.tar.gz#download"
+  *
+  *     normalizePathname("script.js?module=true#top", {
+  *       ignoreDomainExtensions: [".js"]
+  *     });
+  *     // ➔ "/script.js?module=true#top"
+  *     ```
+  *     ---
+  * 2.  #### Examples (full URL or explicit domain - option ignored):
+  *     ```ts
+  *     normalizePathname("https://example.com/image.png?version=2", {
+  *       ignoreDomainExtensions: [".png"]
+  *     });
+  *     // ➔ "/image.png?version=2"  // URL is parsed normally; ignoreDomainExtensions has no effect
+  *
+  *     normalizePathname("example.com/script.js?module=true#top", {
+  *       ignoreDomainExtensions: [".js"]
+  *     });
+  *     // ➔ "/script.js?module=true#top"  // domain recognized; option ignored
+  *     ```
+  * ---
+  * @notes
   * - Only the **first path segment** is checked.
   * - Prevents false-positive domain stripping for filenames that look like domains.
   * - Throws **TypeError** if invalid type or invalid string is provided.
   *
-  * @default undefined (feature inactive if not provided)
+  * @default undefined // (feature inactive if not provided)
   */
   ignoreDomainExtensions?: Set<string> | string[];
 };
@@ -493,146 +620,188 @@ type ResKeepNullable<T> = T extends string ? string : T extends undefined ? unde
 * * ***Utility: `normalizePathname`.***
 * --------------------------------------------------------
 *
-* - **Description:**
-*    Normalizes any pathname or URL string to a clean, predictable format.
-*    Useful for routing, file paths, and URL handling.
-*    - Handles:
-*      - Leading/trailing spaces
-*      - Internal spaces in path segments
-*      - Redundant slashes (`//`)
-*      - Full URLs vs relative paths
-*      - Query (`?`) and hash (`#`) preservation
-*      - Unicode & emoji characters
-*      - Optional nullable preservation (`keepNullable`)
-*      - Optional trailing slash preservation (`keepTrailingSlash`)
-*      - Optional removal of localhost first segment (`localhostDomain`)
-*      - Prevention of false-positive domain stripping (`ignoreDomainExtensions`)
-*
+* **Normalizes any pathname or URL string to a clean, predictable format, useful for routing, file paths, and URL handling.**
+*
+* ---
+* - **Handles:**
+*     - Leading/trailing spaces.
+*     - Internal spaces in path segments.
+*     - Redundant slashes (`//`).
+*     - Full URLs vs relative paths.
+*     - Query (`?`) and hash (`#`) preservation.
+*     - Unicode & emoji characters.
+*     - Optional nullable preservation (`keepNullable`).
+*     - Optional trailing slash preservation (`keepTrailingSlash`).
+*     - Optional removal of localhost first segment (`localhostDomain`).
+*     - Prevention of false-positive domain stripping (`ignoreDomainExtensions`).
+* ---
 * - **Key Steps Internally:**
-*    1. Validate `options` (plain object, correct types)
-*    2. Validate `defaultPath` (non-empty string if `keepNullable` is false)
-*    3. Validate `ignoreDomainExtensions` (Set<string> | string[], each starts with `.`)
-*    4. Handle nullable:
-*       - Returns `null` / `undefined` if `keepNullable: true`
-*       - Otherwise uses `defaultPath`
-*    5. Trim spaces, remove internal spaces
-*    6. If full URL: parse using `URL` constructor
-*    7. If relative path or domain-like:
-*       - Remove `localhost`/`localhost:port` if `localhostDomain`
-*       - Remove first segment if domain-like and **not** in `ignoreDomainExtensions`
-*    8. Normalize slashes
-*    9. Ensure leading slash
-*    10. Handle trailing slash
-*    11. Decode Unicode safely
-*    12. Return normalized pathname + search + hash
-*
+*      1. Validate `options` (plain object, correct types).
+*      2. Validate `defaultPath` (non-empty string if `keepNullable` is false).
+*      3. Validate `ignoreDomainExtensions` (Set<string> | string[], each starts with `.`).
+*      4. Handle nullable:
+*         - Returns `null` / `undefined` if `keepNullable: true`.
+*         - Otherwise uses `defaultPath`.
+*      5. Trim spaces, remove internal spaces.
+*      6. If full URL: parse using `URL` constructor.
+*      7. If relative path or domain-like:
+*         - Remove `localhost`/`localhost:port` if `localhostDomain`.
+*         - Remove first segment if domain-like and **not** in `ignoreDomainExtensions`.
+*      8. Normalize slashes.
+*      9. Ensure leading slash.
+*      10. Handle trailing slash.
+*      11. Decode Unicode safely.
+*      12. Return normalized pathname + search + hash.
+* ---
 * - **Error Handling:**
-*    - **TypeError**:
-*       - `defaultPath` invalid (non-string or empty) when `keepNullable: false`
-*       - `keepNullable`, `keepTrailingSlash`, `localhostDomain` not boolean
-*       - `ignoreDomainExtensions` invalid
-*    - **NormalizePathnameError** (extends ***Error***):
-*       - Invalid URL parsing
-*       - Unexpected normalization errors
-*
+*     - ***TypeError***:
+*          - `defaultPath` invalid (non-string or empty) when `keepNullable: false`.
+*          - `keepNullable`, `keepTrailingSlash`, `localhostDomain` not boolean.
+*          - `ignoreDomainExtensions` invalid.
+*     - ***NormalizePathnameError*** (extends ***Error***):
+*          - Invalid URL parsing.
+*          - Unexpected normalization errors.
+* ---
 * - **Options:**
-*    ```ts
-*    {
-*      // fallback if invalid path, default: "/"
-*      defaultPath?: string;
-*      // preserve null/undefined, default: false
-*      keepNullable?: boolean;
-*      // preserve trailing slash, default: false
-*      keepTrailingSlash?: boolean;
-*      // remove localhost:port first segment, default: false
-*      localhostDomain?: boolean;
-*      // prevent domain stripping, default: undefined
-*      ignoreDomainExtensions?: Set<string> | string[];
-*    }
-*    ```
+*      ```ts
+*      {
+*        // fallback if invalid path, default: "/"
+*        defaultPath?: string;
+*        // preserve null/undefined, default: false
+*        keepNullable?: boolean;
+*        // preserve trailing slash, default: false
+*        keepTrailingSlash?: boolean;
+*        // remove localhost:port first segment, default: false
+*        localhostDomain?: boolean;
+*        // prevent domain stripping, default: undefined
+*        ignoreDomainExtensions?: Set<string> | string[];
+*      }
+*      ```
+*
+* ---
 *
 * @example
-* // Basic path cleaning
-* normalizePathname("   /foo//bar  ");
-* // ➔ "/foo/bar"
-*
-* // Trailing slash control
-* normalizePathname("/api//v1//user//", { keepTrailingSlash: true });
-* // ➔ "/api/v1/user/"
-* normalizePathname("/api//v1//user//", { keepTrailingSlash: false });
-* // ➔ "/api/v1/user"
-*
-* // Full URL normalization
-* normalizePathname("https://example.com//path///to/resource?x=1#hash");
-* // ➔ "/path/to/resource?x=1#hash"
-*
-* // Null/undefined preservation
-* normalizePathname(null, { keepNullable: true });
-* // ➔ null
-* normalizePathname(undefined, { keepNullable: true });
-* // ➔ undefined
-*
-* // Default fallback
-* normalizePathname("", { defaultPath: "/home" });
-* // ➔ "/home"
-*
-* // Localhost removal
-* normalizePathname("localhost:3000/path/to/resource", { localhostDomain: true });
-* // ➔ "/path/to/resource"
-*
-* // Prevent false-positive domain stripping
-* normalizePathname("archive.tar.gz#download", { ignoreDomainExtensions: [".tar.gz"] });
-* // ➔ "/archive.tar.gz#download"
-* normalizePathname("image.png?version=2", { ignoreDomainExtensions: [".png"] });
-* // ➔ "/image.png?version=2"
-*
-* // Emojis and Unicode
-* normalizePathname("🔥//deep//path///🚀");
-* // ➔ "/🔥/deep/path/🚀"
-*
-* // Query-only or hash-only
-* normalizePathname("?page=2");
-* // ➔ "/?page=2"
-* normalizePathname("#section3");
-* // ➔ "/#section3"
-*
-* // Complex nested paths
-* normalizePathname("   //nested///folder//file.txt  ");
-* // ➔ "/nested/folder/file.txt"
-*
-* // Invalid URL triggers error
-* try {
-*   normalizePathname("http://");
-* } catch (e) {
-*   // console.log(e);
-* }
-*
-* // First segment is domain but ignored due to extension
-* normalizePathname("example.tar.bz/file", { ignoreDomainExtensions: [".tar.bz"] });
-* // ➔ "/example.tar.bz/file"
+* 1.  #### Basic path cleaning:
+*     ```ts
+*     normalizePathname("   /foo//bar  ");
+*     // ➔ "/foo/bar"
+*     ```
+*     ---
+* 2.  #### Trailing slash control:
+*     ```ts
+*     normalizePathname("/api//v1//user//", { keepTrailingSlash: true });
+*     // ➔ "/api/v1/user/"
+*     normalizePathname("/api//v1//user//", { keepTrailingSlash: false });
+*     // ➔ "/api/v1/user"
+*     ```
+*     ---
+* 3.  #### Full URL normalization:
+*     ```ts
+*     normalizePathname("https://example.com//path///to/resource?x=1#hash");
+*     // ➔ "/path/to/resource?x=1#hash"
+*     ```
+*     ---
+* 4.  #### Null/undefined preservation:
+*     ```ts
+*     normalizePathname(null, { keepNullable: true });
+*     // ➔ null
+*     normalizePathname(undefined, { keepNullable: true });
+*     // ➔ undefined
+*     ```
+*     ---
+* 5.  #### Default fallback:
+*     ```ts
+*     normalizePathname("", { defaultPath: "/home" });
+*     // ➔ "/home"
+*     ```
+*     ---
+* 6.  #### Localhost removal:
+*     ```ts
+*     normalizePathname("localhost:3000/path/to/resource", { localhostDomain: true });
+*     // ➔ "/path/to/resource"
+*     ```
+*     ---
+* 7.  #### Prevent false-positive domain stripping:
+*     ```ts
+*     normalizePathname("archive.tar.gz#download", { ignoreDomainExtensions: [".tar.gz"] });
+*     // ➔ "/archive.tar.gz#download"
+*     normalizePathname("image.png?version=2", { ignoreDomainExtensions: [".png"] });
+*     // ➔ "/image.png?version=2"
+*     ```
+*     ---
+* 8.  #### Emojis and Unicode:
+*     ```ts
+*     normalizePathname("🔥//deep//path///🚀");
+*     // ➔ "/🔥/deep/path/🚀"
+*     ```
+*     ---
+* 9.  #### Query-only or hash-only:
+*     ```ts
+*     normalizePathname("?page=2");
+*     // ➔ "/?page=2"
+*     normalizePathname("#section3");
+*     // ➔ "/#section3"
+*     ```
+*     ---
+* 10. #### Complex nested paths:
+*     ```ts
+*     normalizePathname("   //nested///folder//file.txt  ");
+*     // ➔ "/nested/folder/file.txt"
+*     ```
+*     ---
+* 11. #### Invalid URL triggers error:
+*     ```ts
+*     try {
+*       normalizePathname("http://");
+*     } catch (e) {
+*       // console.log(e);
+*     }
+*     ```
+*     ---
+* 12. #### First segment is domain but ignored due to extension:
+*     ```ts
+*     normalizePathname("example.tar.bz/file", { ignoreDomainExtensions: [".tar.bz"] });
+*     // ➔ "/example.tar.bz/file"
+*     ```
 */
 declare function normalizePathname<T>(pathname: T, options?: NormalizePathnameOptionsKeepNullableFalse): ResUnKeepNullable<T>;
 declare function normalizePathname<T>(pathname: T, options?: NormalizePathnameOptionsKeepNullableTrue): ResKeepNullable<T>;
 type FormatEnvPortOptions = {
-  /** Add prefix with a colon, defaultValue: `false`.
+  /** -----------------------------------------------
+  * * ***Add prefix with a colon, defaultValue: `false`.***
+  * ------------------------------------------------
+  *
+  * - ***⚠️ Warning***:
+  *      - Non-boolean values will throw `TypeError`.
   *
+  * ---
   * @default false
   */
   prefixColon?: boolean;
 };
 /** -----------------------------------------------
 * * ***Utility: `formatEnvPort`.***
-* -----------------------------------------------
+* ------------------------------------------------
 * **Retrieves and formats an environment port variable.**
+*
+* ---
 * - **Behavior:**
-*    - Extracts only digits from the input.
-*    - If no digits found, returns an empty string.
-*    - By default does NOT prefix with a colon.
-*      - Use `{ prefixColon: true }` to prefix with a colon.
+*     - Extracts only digits from the input.
+*     - If no digits found, returns an empty string.
+*     - By default does NOT prefix with a colon.
+*       - Use `{ prefixColon: true }` to prefix with a colon, invalid type `prefixColon` will throw **TypeError**.
+*
+* ---
 * @param {string | null | undefined} envVar The environment variable string.
 * @param {FormatEnvPortOptions} [options] Optional object: `{ prefixColon?: boolean }`.
-* @returns {string} A string like `":8080"` or `"8080"`, or `""` if no digits.
+*
+* ---
 * @throws **{@link TypeError | `TypeError`}** if `options` is not an object or `prefixColon` is not boolean.
+*
+* ---
+* @returns {string} A string like `":8080"` or `"8080"`, or `""` if no digits.
+*
+* ---
 * @example
 * formatEnvPort("port:8080");
 * // ➔ "8080"
@@ -659,7 +828,11 @@ type PunycodeUtilsJS = {
     * ---------------------------------------------------------
     *
     * @param input - The UCS-2 string to decode.
+    *
+    * ---
     * @returns Array of Unicode code points.
+    *
+    * ---
     * @example
     * punycodeUtilsJS.ucs2.decode("𐍈");
     * // ➔ [66376]
@@ -670,7 +843,11 @@ type PunycodeUtilsJS = {
     * ---------------------------------------------------------
     *
     * @param points - Array of Unicode code points.
+    *
+    * ---
     * @returns Encoded string.
+    *
+    * ---
     * @example
     * punycodeUtilsJS.ucs2.encode([66376]);
     * // ➔ "𐍈"
@@ -682,7 +859,11 @@ type PunycodeUtilsJS = {
   * ---------------------------------------------------------
   *
   * @param input - The `Punycode-UtilsJS` string to decode.
+  *
+  * ---
   * @returns Decoded Unicode string.
+  *
+  * ---
   * @example
   * punycodeUtilsJS.decode("xn--fsq");
   * // ➔ "ü"
@@ -693,7 +874,11 @@ type PunycodeUtilsJS = {
   * ---------------------------------------------------------
   *
   * @param input - Unicode string to encode.
+  *
+  * ---
   * @returns `Punycode-UtilsJS` string.
+  *
+  * ---
   * @example
   * punycodeUtilsJS.encode("ü");
   * // ➔ "xn--fsq"
@@ -704,7 +889,11 @@ type PunycodeUtilsJS = {
   * ---------------------------------------------------------
   *
   * @param input - Domain or label string.
+  *
+  * ---
   * @returns ASCII string suitable for DNS.
+  *
+  * ---
   * @example
   * punycodeUtilsJS.toASCII("пример.рф");
   * // ➔ "xn--e1afmkfd.xn--p1ai"
@@ -715,7 +904,11 @@ type PunycodeUtilsJS = {
   * ---------------------------------------------------------
   *
   * @param input - ASCII string (with xn-- prefix if needed).
+  *
+  * ---
   * @returns Unicode string.
+  *
+  * ---
   * @example
   * punycodeUtilsJS.toUnicode("xn--e1afmkfd.xn--p1ai");
   * // ➔ "пример.рф"
@@ -725,10 +918,9 @@ type PunycodeUtilsJS = {
 /** ---------------------------------------------------------
 * * ***`Punycode-UtilsJS` object exposing all API functions and version.***
 * ---------------------------------------------------------
-* Provides encoding and decoding of Unicode domain names to ASCII (`Punycode-UtilsJS`)
-* and vice versa.
+* **Provides encoding and decoding of Unicode domain names to ASCII (`Punycode-UtilsJS`) and vice versa.**
 *
-* - Useful for IDN (Internationalized Domain Names) support.
+* - Useful for `IDN` (**Internationalized Domain Names**) support.
 */
 declare const punycodeUtilsJS: PunycodeUtilsJS;
 /**