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

package/dist/urls/index.d.ts

@@ -1,746 +1,737 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.12.0.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
 /** ----------------------------------------------------------
- * * ***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,
- *      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"]];
- */
+* * ***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,
+*      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"]];
+*/
 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.
- * @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.
- * @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", ... }
- * ```
- */
+* * ***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.
+* @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.
+* @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", ... }
+* ```
+*/
 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)
- * @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://例子.公司"]
- * extractURLs("Here: https://example.com/🎉/page");
- * // ➔ ["https://example.com/🎉/page"]
- * extractURLs("ftp://example.com http://example.com");
- * // ➔ ["http://example.com"]
- */
+* * ***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)
+* @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://例子.公司"]
+* extractURLs("Here: https://example.com/🎉/page");
+* // ➔ ["https://example.com/🎉/page"]
+* extractURLs("ftp://example.com http://example.com");
+* // ➔ ["http://example.com"]
+*/
 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.
- * - **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.
- * - **Behavior:**
- *    - 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 `"/"`,
- *          it returns the `defaultValue` (normalized).
- *        - 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"
- * ```
- *
- * 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"`),
- *    - An array of string paths (e.g. `["   ", "/dashboard"]`),
- *    - Or `null`.
- * @param {string} [defaultValue="/"]
- *  ***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.***
- */
+* * ***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.
+* - **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.
+* - **Behavior:**
+*    - 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 `"/"`,
+*          it returns the `defaultValue` (normalized).
+*        - 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"
+* ```
+*
+* 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"`),
+*    - An array of string paths (e.g. `["   ", "/dashboard"]`),
+*    - Or `null`.
+* @param {string} [defaultValue="/"]
+*  ***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.***
+*/
 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`).
-     *
-     * - 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`).
-     *
-     * @default true
-     */
-    removeDuplicates?: boolean;
+  /** 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`).
+  *
+  * @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.
- * - **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.
- * - **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.
- * @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.
- * @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`.
- * @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",
- *    ];
- *
- *    // 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.
- *    });
- * ```
- * - #### ✅ **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", "/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
- * ```
- */
+* * ***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.
+* - **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.
+* - **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.
+* @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.
+* @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`.
+* @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",
+*    ];
+*
+*    // 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.
+*    });
+* ```
+* - #### ✅ **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", "/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
+* ```
+*/
 declare const getPrefixPathname: (url: string | string[], base?: string | string[] | null, options?: GetPrefixPathnameOptions) => string | string[] | null;
-
 /** Options when `keepNullable` is false (default).
- *
- * Returns `defaultPath` if `pathname` is empty or invalid.
- */
+*
+* Returns `defaultPath` if `pathname` is empty or invalid.
+*/
 type UnKeepNullableOptions = {
-    /** * ***Fallback value returned if `pathname` is empty-string or invalid.***
-     *
-     * Must be a **`non-empty string`**, defaultValue: `"/"`.
-     *
-     * @defaultValue `"/"`.
-     */
-    defaultPath?: string;
-    /** * ***Whether to preserve `null` or `undefined`, defaultValue: `false`.***
-     *
-     * @defaultValue `false`.
-     */
-    keepNullable?: false;
+  /** * ***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`.***
+  *
+  * @default false
+  */
+  keepNullable?: false;
 };
 /** Options when `keepNullable` is true.
- *
- * Preserves `null` or `undefined` instead of returning `defaultPath`.
- */
+*
+* Preserves `null` or `undefined` instead of returning `defaultPath`.
+*/
 type KeepNullableOptions = {
-    /** * ***Fallback path is ignored when `keepNullable` is true **(except if
-     * `pathname` is empty-string or invalid, even this `true`)**,
-     * defaultValue: `"/"`.***
-     *
-     * @defaultValue `"/"`.
-     */
-    defaultPath?: string;
-    /** * ***Preserve `null` or `undefined` as-is if `true` (defaultValue: `false`).***
-     *
-     * - ***⚠️ Notes:***
-     *      - Keep returning `defaultPath` if `pathname` is empty-string, even this `true`.
-     *
-     * **Must be `true` in this type.**
-     */
-    keepNullable?: true;
+  /** * ***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`.
+  *
+  * **Must be `true` in this type.**
+  *
+  * @default false
+  */
+  keepNullable?: true;
 };
 type MainNormalizePathnameOptions = {
-    /** --------------------------------------------------------
-     * * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `false`.***
-     * --------------------------------------------------------
-     *
-     * @defaultValue `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)
-     *
-     * - Only the **first path segment** is affected. Any subsequent occurrences of `"localhost"`
-     *   will remain intact.
-     *
-     * @defaultValue `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:**
-     * - 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.
-     *
-     * @defaultValue `undefined` (feature inactive if not provided)
-     */
-    ignoreDomainExtensions?: Set<string> | string[];
+  /** --------------------------------------------------------
+  * * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `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)
+  *
+  * - Only the **first path segment** is affected. Any subsequent occurrences of `"localhost"`
+  *   will remain intact.
+  *
+  * @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:**
+  * - 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)
+  */
+  ignoreDomainExtensions?: Set<string> | string[];
 };
 type NormalizePathnameOptionsKeepNullableTrue = MainNormalizePathnameOptions & KeepNullableOptions;
 type NormalizePathnameOptionsKeepNullableFalse = MainNormalizePathnameOptions & UnKeepNullableOptions;
 type ResUnKeepNullable<T> = T extends undefined ? string : T extends null ? string : T extends null | undefined ? string : string;
 type ResKeepNullable<T> = T extends string ? string : T extends undefined ? undefined : T extends null ? null : T extends null | undefined ? null | undefined : string | null | undefined;
 /** --------------------------------------------------------
- * * ***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`)
- *
- * - **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
- *
- * - **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
- *
- * - **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[];
- *    }
- *    ```
- *
- * @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"
- */
+* * ***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`)
+*
+* - **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
+*
+* - **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
+*
+* - **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[];
+*    }
+*    ```
+*
+* @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"
+*/
 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`.
-     *
-     * @default false
-     */
-    prefixColon?: boolean;
+  /** Add prefix with a colon, defaultValue: `false`.
+  *
+  * @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.
- * @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.
- * @example
- * formatEnvPort("port:8080");
- * // ➔ "8080"
- * formatEnvPort("port:8080", { prefixColon: true });
- * // ➔ ":8080"
- */
+* * ***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.
+* @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.
+* @example
+* formatEnvPort("port:8080");
+* // ➔ "8080"
+* formatEnvPort("port:8080", { prefixColon: true });
+* // ➔ ":8080"
+*/
 declare const formatEnvPort: (envVar: string | null | undefined, options?: FormatEnvPortOptions) => string;
-
-/** ---------------------------------------------------------
- * * ***Constants for `Punycode-UtilsJS` algorithm.***
- * ---------------------------------------------------------
- * These constants are used internally for encoding and decoding.
- *
- * Unicode domain names to ASCII (`Punycode-UtilsJS`) and vice versa.
- */
 type PunycodeUtilsJS = {
+  /** ---------------------------------------------------------
+  * * ***Version of the `Punycode-UtilsJS` implementation.***
+  * ---------------------------------------------------------
+  *
+  * @example
+  * console.log(punycodeUtilsJS.version); // "1.0.0"
+  */
+  version: string;
+  /** ---------------------------------------------------------
+  * * ***UCS-2 utility functions.***
+  * ---------------------------------------------------------
+  */
+  ucs2: {
     /** ---------------------------------------------------------
-     * * ***Version of the `Punycode-UtilsJS` implementation.***
-     * ---------------------------------------------------------
-     *
-     * @example
-     * console.log(punycodeUtilsJS.version); // "1.0.0"
-     */
-    version: string;
-    /** ---------------------------------------------------------
-     * * ***UCS-2 utility functions.***
-     * ---------------------------------------------------------
-     */
-    ucs2: {
-        /** ---------------------------------------------------------
-         * * ***Decodes a UCS-2 encoded string to an array of Unicode code points.***
-         * ---------------------------------------------------------
-         *
-         * @param input - The UCS-2 string to decode.
-         * @returns Array of Unicode code points.
-         * @example
-         * punycodeUtilsJS.ucs2.decode("𐍈");
-         * // ➔ [66376]
-         */
-        decode: (input: string) => number[];
-        /** ---------------------------------------------------------
-         * * ***Encodes an array of Unicode code points to a UCS-2 string.***
-         * ---------------------------------------------------------
-         *
-         * @param points - Array of Unicode code points.
-         * @returns Encoded string.
-         * @example
-         * punycodeUtilsJS.ucs2.encode([66376]);
-         * // ➔ "𐍈"
-         */
-        encode: (points: number[]) => string;
-    };
-    /** ---------------------------------------------------------
-     * * ***Decodes a `Punycode-UtilsJS` string to a Unicode string.***
-     * ---------------------------------------------------------
-     *
-     * @param input - The `Punycode-UtilsJS` string to decode.
-     * @returns Decoded Unicode string.
-     * @example
-     * punycodeUtilsJS.decode("xn--fsq");
-     * // ➔ "ü"
-     */
-    decode: (input: string) => string;
-    /** ---------------------------------------------------------
-     * * ***Encodes a Unicode string to `Punycode-UtilsJS`.***
-     * ---------------------------------------------------------
-     *
-     * @param input - Unicode string to encode.
-     * @returns `Punycode-UtilsJS` string.
-     * @example
-     * punycodeUtilsJS.encode("ü");
-     * // ➔ "xn--fsq"
-     */
-    encode: (input: string) => string;
-    /** ---------------------------------------------------------
-     * * ***Converts a Unicode domain or label to ASCII (`Punycode-UtilsJS`).***
-     * ---------------------------------------------------------
-     *
-     * @param input - Domain or label string.
-     * @returns ASCII string suitable for DNS.
-     * @example
-     * punycodeUtilsJS.toASCII("пример.рф");
-     * // ➔ "xn--e1afmkfd.xn--p1ai"
-     */
-    toASCII: (input: string) => string;
+    * * ***Decodes a UCS-2 encoded string to an array of Unicode code points.***
+    * ---------------------------------------------------------
+    *
+    * @param input - The UCS-2 string to decode.
+    * @returns Array of Unicode code points.
+    * @example
+    * punycodeUtilsJS.ucs2.decode("𐍈");
+    * // ➔ [66376]
+    */
+    decode: (input: string) => number[];
     /** ---------------------------------------------------------
-     * * ***Converts an ASCII (`Punycode-UtilsJS`) domain or label to Unicode.***
-     * ---------------------------------------------------------
-     *
-     * @param input - ASCII string (with xn-- prefix if needed).
-     * @returns Unicode string.
-     * @example
-     * punycodeUtilsJS.toUnicode("xn--e1afmkfd.xn--p1ai");
-     * // ➔ "пример.рф"
-     */
-    toUnicode: (input: string) => string;
+    * * ***Encodes an array of Unicode code points to a UCS-2 string.***
+    * ---------------------------------------------------------
+    *
+    * @param points - Array of Unicode code points.
+    * @returns Encoded string.
+    * @example
+    * punycodeUtilsJS.ucs2.encode([66376]);
+    * // ➔ "𐍈"
+    */
+    encode: (points: number[]) => string;
+  };
+  /** ---------------------------------------------------------
+  * * ***Decodes a `Punycode-UtilsJS` string to a Unicode string.***
+  * ---------------------------------------------------------
+  *
+  * @param input - The `Punycode-UtilsJS` string to decode.
+  * @returns Decoded Unicode string.
+  * @example
+  * punycodeUtilsJS.decode("xn--fsq");
+  * // ➔ "ü"
+  */
+  decode: (input: string) => string;
+  /** ---------------------------------------------------------
+  * * ***Encodes a Unicode string to `Punycode-UtilsJS`.***
+  * ---------------------------------------------------------
+  *
+  * @param input - Unicode string to encode.
+  * @returns `Punycode-UtilsJS` string.
+  * @example
+  * punycodeUtilsJS.encode("ü");
+  * // ➔ "xn--fsq"
+  */
+  encode: (input: string) => string;
+  /** ---------------------------------------------------------
+  * * ***Converts a Unicode domain or label to ASCII (`Punycode-UtilsJS`).***
+  * ---------------------------------------------------------
+  *
+  * @param input - Domain or label string.
+  * @returns ASCII string suitable for DNS.
+  * @example
+  * punycodeUtilsJS.toASCII("пример.рф");
+  * // ➔ "xn--e1afmkfd.xn--p1ai"
+  */
+  toASCII: (input: string) => string;
+  /** ---------------------------------------------------------
+  * * ***Converts an ASCII (`Punycode-UtilsJS`) domain or label to Unicode.***
+  * ---------------------------------------------------------
+  *
+  * @param input - ASCII string (with xn-- prefix if needed).
+  * @returns Unicode string.
+  * @example
+  * punycodeUtilsJS.toUnicode("xn--e1afmkfd.xn--p1ai");
+  * // ➔ "пример.рф"
+  */
+  toUnicode: (input: string) => string;
 };
 /** ---------------------------------------------------------
- * * ***`Punycode-UtilsJS` object exposing all API functions and version.***
- * ---------------------------------------------------------
- * Provides encoding and decoding of Unicode domain names to ASCII (`Punycode-UtilsJS`)
- * and vice versa.
- *
- * - Useful for IDN (Internationalized Domain Names) support.
- */
+* * ***`Punycode-UtilsJS` object exposing all API functions and version.***
+* ---------------------------------------------------------
+* Provides encoding and decoding of Unicode domain names to ASCII (`Punycode-UtilsJS`)
+* and vice versa.
+*
+* - Useful for IDN (Internationalized Domain Names) support.
+*/
 declare const punycodeUtilsJS: PunycodeUtilsJS;
-
-export { type QueryParamPairs, constructURL, extractURLs, formatEnvPort, getFirstPrefixPathname, getPrefixPathname, normalizePathname, punycodeUtilsJS };
+/**
+* Export individual functions.
+*/
+export { QueryParamPairs, constructURL, extractURLs, formatEnvPort, getFirstPrefixPathname, getPrefixPathname, normalizePathname, punycodeUtilsJS };