/*!
* ========================================================================
*  @rzl-zone/utils-js
* ------------------------------------------------------------------------
*  Version: `3.15.0`
*  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
* 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.
* @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.
*
* ---
* @example
* 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.
*
* ---
* - #### *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://例子.公司"]
* 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`.
*
* ---
* @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 `"/"`.
*
* ---
* @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`).***
  * ---------------------------------------------------------
  *
  * - 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`).***
  * ---------------------------------------------------------
  *
  * - ***⚠️ 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.
* ---
*
* - **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.
*
* ---
* @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`.
*
* ---
* @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"
*
*      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/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).***
* ---------------------------------------------------------
* 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: `"/"`.
  *
  * ---
  * @default "/"
  */
  defaultPath?: string;
  /** --------------------------------------------------------
  * * ***Whether to preserve `null` or `undefined`, defaultValue: `false`.***
  * ---------------------------------------------------------
  *
  * - ***⚠️ Warning:***
  *      - Non-boolean values will throw `TypeError`.
  * ---
  * @default false
  */
  keepNullable?: false;
};
/** --------------------------------------------------------
* * ***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
  * `pathname` is empty-string or invalid, even this `true`)**,
  * defaultValue: `"/"`.***
  * --------------------------------------------------------
  *
  * @default "/"
  */
  defaultPath?: string;
  /** --------------------------------------------------------
  *  * ***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;
};
type MainNormalizePathnameOptions = {
  /** --------------------------------------------------------
  * * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `false`.***
  * ---------------------------------------------------------
  *
  * - ***⚠️ Warning:***
  *      - Non-boolean values will throw `TypeError`.
  * ---
  *
  * @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.
  * ---
  * - ***⚠️ 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.***
  * --------------------------------------------------------
  *
  * - **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)
  */
  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`.***
* --------------------------------------------------------
*
* **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
* 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`.***
  * ------------------------------------------------
  *
  * - ***⚠️ 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, invalid type `prefixColon` will throw **TypeError**.
*
* ---
* @param {string | null | undefined} envVar The environment variable string.
* @param {FormatEnvPortOptions} [options] Optional object: `{ prefixColon?: boolean }`.
*
* ---
* @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"
* formatEnvPort("port:8080", { prefixColon: true });
* // ➔ ":8080"
*/
declare const formatEnvPort: (envVar: string | null | undefined, options?: FormatEnvPortOptions) => string;
type PunycodeUtilsJS = {
  /** ---------------------------------------------------------
  * * ***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;
  /** ---------------------------------------------------------
  * * ***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.
*/
declare const punycodeUtilsJS: PunycodeUtilsJS;
/**
* Export individual functions.
*/
export { QueryParamPairs, constructURL, extractURLs, formatEnvPort, getFirstPrefixPathname, getPrefixPathname, normalizePathname, punycodeUtilsJS };