@rzl-zone/utils-js 3.0.1-beta.0 → 3.1.0-beta.2

package/dist/urls/index.d.ts

@@ -1,24 +1,22 @@
 /** ----------------------------------------------------------
-* * ***Represents a non-empty array of key–value pairs.***
+* * ***Type-Utility: `QueryParamPairs`.***
 * ----------------------------------------------------------
-*
+* **Represents a non-empty array of key–value pairs.**
+* @description
 * Type for `queryParams` parameter, the second parameter of **{@link constructURL}**.
-*
-* - 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.
-*
+* - **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);
 *
-* @example
 * // ❌ invalid: must contain at least one item
 * const empty: QueryParamPairs = [];
 *
@@ -27,354 +25,335 @@
 */
 type QueryParamPairs=[[string,string|number],...[string,string|number][]];
 /** ---------------------------------
-* * ***Constructs a valid URL with optional query parameters and allows selective removal of duplicate parameters.***
+* * ***Utility: `constructURL`.***
 * ---------------------------------
-*
-* @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]>} [queryParams]
+* **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]...]`).
-*
+*   - 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 {TypeError}
-*   Throws 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.
-*
+*   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 {TypeError} Throws 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
-* // Basic usage
-* constructURL("https://example.com/path", new URLSearchParams({ a: "1", b: "2" }).entries());
-* // ➔ URL { href: "https://example.com/path?a=1&b=2", ... }
-*
-* @example
-* // Remove parameters from base and added
-*
-* // with new URLSearchParams({ ... }).entries();
-* constructURL("https://example.com/path?foo=1&bar=2", new URLSearchParams({ bar: "ignored", baz: "3" }).entries(), ["bar"]);
-* // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
-*
-* // with [[string, string | number]...]
-* constructURL("https://example.com/path?foo=1&bar=2", [["bar", "ignored"],["baz", 3]], ["bar"]);
-* // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
-*
-* const params: QueryParamPairs = [
-*    ["foo", 1],
-*    ["bar", 2],
-*    ["baz", 3]
-* ];
-*
-* constructURL("https://example.com", params, ["bar"]);
-* // ➔ URL { href: "https://example.com/?foo=1&baz=3", ... }
+*    1. #### Basic Usage:
+* ```ts
+*   constructURL(
+*     "https://example.com/path",
+*     new URLSearchParams({ a: "1", b: "2" }).entries()
+*   );
+*   // ➔ 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;
 /** ---------------------------------
-* * ***Extracts all valid URLs from a given string.***
+* * ***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.
+* - **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://例子.公司"]
-*
-* @example
 * extractURLs("Here: https://example.com/🎉/page");
 * // ➔ ["https://example.com/🎉/page"]
-*
-* @example
 * extractURLs("ftp://example.com http://example.com");
 * // ➔ ["http://example.com"]
 */
-declare const extractURLs:(url?:string|null)=>string[]|null;
-/** --------------------------------------------------------
-* * ***Get Prefix from URL with Optional Base or Auto-detection (Supports String or Array of URLs).***
-* --------------------------------------------------------
-*
-* @description
-* 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.
-*
-* ---
+declare const extractURLs:(url:string|null|undefined)=>string[]|null;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.
 *
-* @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"). 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 {{ levels?: number; removeDuplicates?: boolean }} [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 {TypeError}
-* Throws if:
-* - `url` is not a string or 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.
-*
-* ---
-*
-* ### **🔹 Usage Examples**
+* @default 1
+*/
+levels?:number;
+/** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`).
 *
-* #### ✅ **Correct Usage (With an Array of URLs and Base)**
+* @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"`).
+*    - 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 {TypeError} Throws 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.
-* });
+*    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)**
+* - #### ✅ **Correct Usage (With Single URL and Single Base):**
 * ```ts
-* const result = getPrefixPathname("/settings/profile", "/settings");
-* console.log(result); // ➔ "/settings"
+*    const result = getPrefixPathname("/settings/profile", "/settings");
+*    console.log(result); // ➔ "/settings"
 * ```
-*
-* #### ✅ **Correct Usage (With Multiple URLs and Single Base)**
+* - #### ✅ **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"
+*    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)**
+* - #### ✅ **Correct Usage (With Multiple URLs and Multiple Bases)**
 * ```ts
-* const result = getPrefixPathname(["/settings/profile", "/admin/password"], ["/settings", "/admin"]);
-* console.log(result); // ➔ ["/settings", "/admin"]
+*    const result = getPrefixPathname(
+*      ["/settings/profile", "/admin/password"],
+*      ["/settings", "/admin"]
+*    );
+*    console.log(result); // ➔ ["/settings", "/admin"]
 * ```
-*
-* #### ✅ **Auto-detection of Prefix**
+* - #### ✅ **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"
+*    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**
+* - #### ✅ **Multiple URLs with Auto-detection**
 * ```ts
-* const result = getPrefixPathname(["/admin/profile", "/settings/password"]);
-* console.log(result); // ➔ ["/admin", "/settings"]
+*    const result = getPrefixPathname(["/admin/profile", "/settings/password"]);
+*    console.log(result); // ➔ ["/admin", "/settings"]
 * ```
-*
-* #### ✅ **Handling Duplicates**
+* - #### ✅ **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"]
+*    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)**
+* - #### ❌ **Incorrect Usage (URL Does Not Match Base)**
 * ```ts
-* const result = getPrefixPathname("/other-path/profile", "/settings");
-* console.log(result); // ➔ null
+*    const result = getPrefixPathname("/other-path/profile", "/settings");
+*    console.log(result); // ➔ null
 * ```
 */
-declare const getPrefixPathname:(url:string|string[],base?:string|string[]|null,options?:{
-/** 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. */
-levels?:number;
-/** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`). */
-removeDuplicates?:boolean;})=>string|string[]|null;
+declare const getPrefixPathname:(url:string|string[],base?:string|string[]|null,options?:GetPrefixPathnameOptions)=>string|string[]|null;
 /** --------------------------------------------------------
-* * ***Extract First Valid Prefix from Path Array or String.***
+* * ***Utility: `getFirstPrefixPathname`.***
 * --------------------------------------------------------
-*
-* ### 🚀 **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 non-empty string.
-*   - `result` is an array that contains non-string elements.
-*   - `result` is a value that is neither `string`, `string[]`, nor `null`.
-*
-* ---
-*
-* ### 🛠 Usage Examples:
-*
-*  1. #### For React: *Determining layout*
+* **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();
-* }
+*   const prefix = getFirstPrefixPathname(
+*      getPrefixPathname(
+*        "/admin/settings",
+*        ["/admin", "/dashboard"]
+*      )
+*   );
+*
+*   if (prefix === "/admin") {
+*     renderAdminLayout();
+*   }
 * ```
 *
-*  2. #### Setting active menu state
+* 2. #### Setting active menu state:
 * ```ts
-* const activeSection = getFirstPrefixPathname(["", "/dashboard", "/profile"]);
-* // ➔ "/dashboard"
+*   const activeSection = getFirstPrefixPathname(["", "/dashboard", "/profile"]);
+*   // ➔ "/dashboard"
 * ```
 *
-*  3. #### Providing graceful fallback
+* 3. #### Providing graceful fallback:
 * ```ts
-* const section = getFirstPrefixPathname([], "/home");
-* // ➔ "/home"
+*   const section = getFirstPrefixPathname([], "/home");
+*   // ➔ "/home"
 * ```
-*  4. #### ✅ Using with an Array of Pathnames
+* 4. #### ✅ Using with an Array of Pathnames:
 * ```ts
-* const result = getPrefixPathname(["   ", "/dashboard", "/settings"]);
-* console.log(getFirstPrefixPathname(result));
-* // ➔ "/dashboard"
+*   const result = getPrefixPathname(["   ", "/dashboard", "/settings"]);
+*   console.log(getFirstPrefixPathname(result));
+*   // ➔ "/dashboard"
 * ```
 *
-*  5. #### ✅ Using with Single String:
+* 5. #### ✅ Using with Single String:
 * ```ts
-* console.log(getFirstPrefixPathname("/profile/settings"));
-* // ➔ "/profile/settings"
-* console.log(getFirstPrefixPathname("   "));
-* // ➔ "/"
+*   console.log(getFirstPrefixPathname("/profile/settings"));
+*   // ➔ "/profile/settings"
+*   console.log(getFirstPrefixPathname("   "));
+*   // ➔ "/"
 * ```
 *
-*  6. #### ✅ Fallback to Custom Default:
+* 6. #### ✅ Fallback to Custom Default:
 * ```ts
-* console.log(getFirstPrefixPathname(["   ", ""], "/home"));
-* // ➔ "/home"
-* console.log(getFirstPrefixPathname(null, "/dashboard"));
-* // ➔ "/dashboard"
+*   console.log(getFirstPrefixPathname(["   ", ""], "/home"));
+*   // ➔ "/home"
+*   console.log(getFirstPrefixPathname(null, "/dashboard"));
+*   // ➔ "/dashboard"
 * ```
 *
-*  7. #### ✅ Throws on Invalid Input:
+* 7. #### ✅ Throws on Invalid Input:
 * ```ts
-* getFirstPrefixPathname([1, 2] as any); // ➔ ❌ throws TypeError
-* getFirstPrefixPathname({} as any);     // ➔ ❌ throws TypeError
-* getFirstPrefixPathname(null, "   ");   // ➔ ❌ throws TypeError
+*   getFirstPrefixPathname([1, 2] as any); // ➔ ❌ throws TypeError
+*   getFirstPrefixPathname({} as any);     // ➔ ❌ throws TypeError
+*   getFirstPrefixPathname(null, "   ");   // ➔ ❌ throws TypeError
 * ```
-*
-* ---
-*
-* @param {string | string[] | null} result
-*    The pathname(s) to process. Can be:
+* @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.
-*    Must be a non-empty string. Defaults to `"/"`.
-*
+*      - Must be a string and non-empty string.
+*      - Defaults to `"/"`.
 * @returns {string}
 *    The first valid normalized pathname, or the normalized default.
-*
 * @throws {TypeError}
-*    If `result` is not a valid type, or `defaultValue` is not a non-empty string.
+*    If `result` is not a valid type, or `defaultValue` is not a string or empty-string.
 */
-declare const getFirstPrefixPathname:(result?:string|string[]|null,defaultValue?:string)=>string;
+declare const getFirstPrefixPathname:(result:string|string[]|null|undefined,defaultValue?:string)=>string;
 /** --------------------------------------------------------
-* * ***Normalizes a given pathname by ensuring consistent formatting.***
+* * ***Utility: `normalizePathname`.***
 * --------------------------------------------------------
-*
-* @description
-* This function processes and normalizes a given pathname:
-*
-* - If `pathname` is `null`, `undefined`, empty, or only whitespace,
-*   the `defaultPath` will be returned instead.
-*
-* - If `pathname` is a full URL (starting with `http://` or `https://`),
-*   it extracts and returns the pathname along with any search parameters and hash.
-*   Example: `"https://site.com/foo/bar?x=1#sec"` becomes `"/foo/bar?x=1#sec"`.
-*
-* - All spaces inside the pathname are removed.
-*
-* - Multiple consecutive slashes (like `"//"` or `"///"`) are collapsed into a single slash `"/"`.
-*
-* - Ensures the returned string always starts with exactly one `/`.
-*
+* **This function processes and normalizes a given pathname.**
+* - **Behavior:**
+*    - If `pathname` is `null`, `undefined`, empty, or only whitespace, the `defaultPath` will be returned instead.
+*    - If `pathname` is a full URL (starting with `http://` or `https://`), it extracts and returns the pathname along
+*      with any search parameters and hash.
+*      - Example: `"https://site.com/foo/bar?x=1#sec"` becomes `"/foo/bar?x=1#sec"`.
+*    - All spaces inside the pathname are removed.
+*    - Multiple consecutive slashes (like `"//"` or `"///"`) are collapsed into a single slash `"/"`.
+*    - Ensures the returned string always starts with exactly one `/`.
 * @param {string | null | undefined} pathname - The pathname to normalize.
-* @param {string} [defaultPath="/"] - A fallback value returned if `pathname` is empty or invalid. Must be a non-empty string, default `"/"`.
-*
+* @param {string} [defaultPath="/"] - A fallback value returned if `pathname` is empty or invalid.
+*    - Must be a string and non-empty string, default `"/"`.
 * @returns {string} A properly normalized pathname starting with a single `/`,
 * or the `defaultPath` if the input is invalid or empty.
-*
-* @throws {TypeError} If `defaultPath` is not a non-empty string.
+* @throws {TypeError} If `defaultPath` is not a string or empty-string.
 * @throws {NormalizePathnameError} If an unexpected error occurs during normalization (e.g., URL parsing failure).
-*
 * @example
 * normalizePathname("   /foo//bar  ");
 * // ➔ "/foo/bar"
-*
 * normalizePathname("https://example.com//path///to/resource?x=1#hash");
 * // ➔ "/path/to/resource?x=1#hash"
 * normalizePathname("   ");
@@ -383,34 +362,32 @@ declare const getFirstPrefixPathname:(result?:string|string[]|null,defaultValue?
 * // ➔ "/home"
 * normalizePathname("/double//slashes");
 * // ➔ "/double/slashes"
-*` normalizePathname(" nested / path / 🚀 ");
+* normalizePathname(" nested / path / 🚀 ");
 * // ➔ "/nested/path/🚀"
 */
-declare const normalizePathname:(pathname?:string|null,defaultPath?:string)=>string;
+declare const normalizePathname:(pathname:string|null|undefined,defaultPath?:string)=>string;type FormatEnvPortOptions={
+/** Add prefix with a colon, defaultValue: `false`.
+*
+* @default false
+*/
+prefixColon?:boolean;};
 /** -----------------------------------------------
-* * ***Retrieves and formats an environment port variable.***
+* * ***Utility: `formatEnvPort`.***
 * -----------------------------------------------
-*
-* - 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 envVar The environment variable string.
-* @param options Optional object: `{ prefixColon?: boolean }`.
-* @returns A string like ":8080" or "8080", or "" if no digits.
-*
-* @throws TypeError if `options` is not an object or `prefixColon` is not boolean.
-*
+* **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 {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,options?:{
-/** Add prefix with a colon.
-*
-* @default false
-*/
-prefixColon?:boolean;})=>string;export{type QueryParamPairs,constructURL,extractURLs,formatEnvPort,getFirstPrefixPathname,getPrefixPathname,normalizePathname};
+declare const formatEnvPort:(envVar:string|null|undefined,options?:FormatEnvPortOptions)=>string;export{type QueryParamPairs,constructURL,extractURLs,formatEnvPort,getFirstPrefixPathname,getPrefixPathname,normalizePathname};