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

package/dist/urls/index.d.cts

@@ -0,0 +1,737 @@
+/*!
+* ========================================================================
+*  @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 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", ... }
+* ```
+*/
+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"]
+*/
+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.***
+*/
+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;
+};
+/** --------------------------------------------------------
+* * ***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.
+*/
+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`.***
+  *
+  * @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`).***
+  *
+  * - ***⚠️ 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`.***
+  * --------------------------------------------------------
+  *
+  * @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"
+*/
+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;
+};
+/** -----------------------------------------------
+* * ***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;
+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 };