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

package/dist/urls/index.d.ts

@@ -1,393 +1,393 @@
 /** ----------------------------------------------------------
-* * ***Type-Utility: `QueryParamPairs`.***
-* ----------------------------------------------------------
-* **Represents a non-empty array of key–value pairs.**
-* @description
-* Type for `queryParams` parameter, the second parameter of **{@link constructURL}**.
-* - **Behavior:**
-*    - Each inner tuple strictly follows the `[string, string | number]` shape.
-*    - Ensures the outer array contains **at least one pair** (non-empty).
-*    - Commonly used for URL construction parameters,
-*      query string segments, or other key–value structured data.
-* @example
-* // ✅ valid usage
-* const params: QueryParamPairs = [
-*   ["foo", 1],
-*   ["bar", "baz"]
-* ];
-* constructURL("https://example.com", params);
-*
-* // ❌ invalid: must contain at least one item
-* const empty: QueryParamPairs = [];
-*
-* // ❌ invalid: key without value pairs.
-* const empty2: QueryParamPairs = [["key"]];
-*/
+ * * ***Type-Utility: `QueryParamPairs`.***
+ * ----------------------------------------------------------
+ * **Represents a non-empty array of key–value pairs.**
+ * @description
+ * Type for `queryParams` parameter, the second parameter of **{@link constructURL}**.
+ * - **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 {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
-*    1. #### Basic Usage:
-* ```ts
-*   constructURL(
-*     "https://example.com/path",
-*     new URLSearchParams({ a: "1", b: "2" }).entries()
-*   );
-*   // ➔ URL { href: "https://example.com/path?a=1&b=2", ... }
-* ```
-*    2. #### Remove parameters from Base and Added:
-* ```ts
-*   // with new URLSearchParams({ ... }).entries();
-*   constructURL(
-*     "https://example.com/path?foo=1&bar=2",
-*     new URLSearchParams({ bar: "ignored", baz: "3" }).entries(),
-*     ["bar"]
-*   );
-*   // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
-*
-*   // with [[string, string | number]...]
-*   constructURL(
-*     "https://example.com/path?foo=1&bar=2",
-*     [["bar", "ignored"],["baz", 3]],
-*     ["bar"]
-*   );
-*   // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
-*
-*   const params: QueryParamPairs = [
-*     ["foo", 1],
-*     ["bar", 2],
-*     ["baz", 3]
-*   ];
-*
-*   constructURL("https://example.com", params, ["bar"]);
-*   // ➔ URL { href: "https://example.com/?foo=1&baz=3", ... }
-* ```
-*/
+ * * ***Utility: `constructURL`.***
+ * ---------------------------------
+ * **Constructs a valid URL with optional query parameters and allows selective removal of duplicate parameters.**
+ * @param {string | URL} baseUrl The base URL to build upon. Must include protocol (e.g., `"https://"`), `domain`, and may include port and existing query parameters.
+ * @param {Iterable<[string, string]> | URLSearchParamsIterator<[string, string]> | QueryParamPairs} [queryParams]
+ *   Additional query parameters to append or overwrite on the URL.
+ *   - Accepts any iterable of key-value pairs (like `new URLSearchParams().entries()` and `[[string, string | number]...]`).
+ * @param {string[]} [removeParams]
+ *   A list of query parameter keys to remove from the final URL, whether they were in the base URL or provided queryParams.
+ * @returns {URL} A new URL object representing the constructed URL with merged and cleaned query parameters.
+ * @throws {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
+ *    1. #### Basic Usage:
+ * ```ts
+ *   constructURL(
+ *     "https://example.com/path",
+ *     new URLSearchParams({ a: "1", b: "2" }).entries()
+ *   );
+ *   // ➔ URL { href: "https://example.com/path?a=1&b=2", ... }
+ * ```
+ *    2. #### Remove parameters from Base and Added:
+ * ```ts
+ *   // with new URLSearchParams({ ... }).entries();
+ *   constructURL(
+ *     "https://example.com/path?foo=1&bar=2",
+ *     new URLSearchParams({ bar: "ignored", baz: "3" }).entries(),
+ *     ["bar"]
+ *   );
+ *   // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
+ *
+ *   // with [[string, string | number]...]
+ *   constructURL(
+ *     "https://example.com/path?foo=1&bar=2",
+ *     [["bar", "ignored"],["baz", 3]],
+ *     ["bar"]
+ *   );
+ *   // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
+ *
+ *   const params: QueryParamPairs = [
+ *     ["foo", 1],
+ *     ["bar", 2],
+ *     ["baz", 3]
+ *   ];
+ *
+ *   constructURL("https://example.com", params, ["bar"]);
+ *   // ➔ URL { href: "https://example.com/?foo=1&baz=3", ... }
+ * ```
+ */
 declare const constructURL:(baseUrl:string|URL,queryParams?:URLSearchParamsIterator<[string,string|number]>|QueryParamPairs,removeParams?:string[])=>URL;
 /** ---------------------------------
-* * ***Utility: `extractURLs`.***
-* ---------------------------------
-* **Extracts all valid URLs from a given string.**
-* @description
-* This function scans the input url and returns an array of URLs
-* that match a valid `http` or `https` format.
-* - **Supports:**
-*    - Internationalized domain names (IDN), e.g. `https://münich.de`
-*    - Unicode & emoji paths, e.g. `https://example.com/🎉/page`
-*    - Long URLs with multiple queries & fragments, e.g. `https://example.com/path?foo=1#hash`
-* - **Ignores:**
-*    - Non-string inputs
-*    - Empty or whitespace-only strings
-*    - Non-HTTP(S) protocols (ftp, mailto, etc)
-* @param {string | null | undefined} url - The input string containing potential URLs.
-* @returns {string[] | null} An array of extracted URLs or `null` if no URLs are found.
-* @example
-* extractURLs("Visit https://example.com and https://例子.公司");
-* // ➔ ["https://example.com", "https://例子.公司"]
-* extractURLs("Here: https://example.com/🎉/page");
-* // ➔ ["https://example.com/🎉/page"]
-* extractURLs("ftp://example.com http://example.com");
-* // ➔ ["http://example.com"]
-*/
+ * * ***Utility: `extractURLs`.***
+ * ---------------------------------
+ * **Extracts all valid URLs from a given string.**
+ * @description
+ * This function scans the input url and returns an array of URLs
+ * that match a valid `http` or `https` format.
+ * - **Supports:**
+ *    - Internationalized domain names (IDN), e.g. `https://münich.de`
+ *    - Unicode & emoji paths, e.g. `https://example.com/🎉/page`
+ *    - Long URLs with multiple queries & fragments, e.g. `https://example.com/path?foo=1#hash`
+ * - **Ignores:**
+ *    - Non-string inputs
+ *    - Empty or whitespace-only strings
+ *    - Non-HTTP(S) protocols (ftp, mailto, etc)
+ * @param {string | null | undefined} url - The input string containing potential URLs.
+ * @returns {string[] | null} An array of extracted URLs or `null` if no URLs are found.
+ * @example
+ * extractURLs("Visit https://example.com and https://例子.公司");
+ * // ➔ ["https://example.com", "https://例子.公司"]
+ * extractURLs("Here: https://example.com/🎉/page");
+ * // ➔ ["https://example.com/🎉/page"]
+ * extractURLs("ftp://example.com http://example.com");
+ * // ➔ ["http://example.com"]
+ */
 declare const extractURLs:(url:string|null|undefined)=>string[]|null;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
-*/
+ *
+ * @default 1
+ */
 levels?:number;
 /** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`).
-*
-* @default 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"`).
-*    - 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.
-*    });
-* ```
-* - #### ✅ **Correct Usage (With Single URL and Single Base):**
-* ```ts
-*    const result = getPrefixPathname("/settings/profile", "/settings");
-*    console.log(result); // ➔ "/settings"
-* ```
-* - #### ✅ **Correct Usage (With Multiple URLs and Single Base):**
-* ```ts
-*    const result = getPrefixPathname(
-*      ["/settings/profile", "/settings/password"],
-*      "/settings"
-*    );
-*    console.log(result); // ➔ "/settings"
-*
-*    const result2 = getPrefixPathname(
-*      ["/settings/profile", "/other/password"],
-*      "/other"
-*    );
-*    console.log(result2); // ➔ "/other"
-* ```
-* - #### ✅ **Correct Usage (With Multiple URLs and Multiple Bases)**
-* ```ts
-*    const result = getPrefixPathname(
-*      ["/settings/profile", "/admin/password"],
-*      ["/settings", "/admin"]
-*    );
-*    console.log(result); // ➔ ["/settings", "/admin"]
-* ```
-* - #### ✅ **Auto-detection of Prefix**
-* ```ts
-*    const result = getPrefixPathname("/settings/profile");
-*    console.log(result); // ➔ "/settings"
-*
-*    const result2 = getPrefixPathname(
-*      "/settings/profile/info",
-*      null,
-*      { levels: 2 }
-*    );
-*    console.log(result2); // ➔ "/settings/profile"
-* ```
-* - #### ✅ **Multiple URLs with Auto-detection**
-* ```ts
-*    const result = getPrefixPathname(["/admin/profile", "/settings/password"]);
-*    console.log(result); // ➔ ["/admin", "/settings"]
-* ```
-* - #### ✅ **Handling Duplicates**
-* ```ts
-*    const result = getPrefixPathname(
-*      ["/settings/profile", "/settings/password"],
-*      "/settings"
-*    );
-*    console.log(result); // ➔ "/settings" (deduped to single string)
-*
-*    const result2 = getPrefixPathname(
-*      ["/settings/profile", "/settings/profile"],
-*      "/settings",
-*      { removeDuplicates: false }
-*    );
-*    console.log(result2); // ➔ ["/settings", "/settings"]
-* ```
-* - #### ❌ **Incorrect Usage (URL Does Not Match Base)**
-* ```ts
-*    const result = getPrefixPathname("/other-path/profile", "/settings");
-*    console.log(result); // ➔ null
-* ```
-*/
+ * * ***Utility: `getPrefixPathname`.***
+ * --------------------------------------------------------
+ * **Get Prefix from URL with Optional Base or Auto-detection (Supports String or Array of URLs).**
+ * - **This function extracts the prefix from one or more URLs. It can either:**
+ *    - Use a provided `base` string or an array of strings to check and return the matching prefix.
+ *    - Automatically detect the prefix if no `base` is provided by analyzing the first part of the URL.
+ * - **The function is flexible and can handle both scenarios:**
+ *    1. **When the base is provided as a single string or an array of strings**:
+ *        - The function will check if the URL starts with one of the provided base(s) and return the matching base.
+ *    2. **When the base is not provided**:
+ *        - The function will automatically detect the prefix by splitting the URL or using a regex.
+ * - **Important Notes**:
+ *    - If a base (or an array of bases) is provided, the URL must start with one of the given base(s).
+ *    - If no base is provided, the function will attempt to detect the prefix automatically.
+ *    - The `url` parameter can be either a string or an array of strings.
+ *    - Supports deduplication of results (enabled by default).
+ *    - Automatically returns a single string if only one unique result exists after processing.
+ * @param {string|string[]} url The full URL(s) from which the prefix should be extracted.
+ *    - Can be a `string` or an `array of strings`.
+ * @param {string|string[]|null} [base=null] The base URL(s) (e.g., `"/settings"`).
+ *    - 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.
+ *    });
+ * ```
+ * - #### ✅ **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;
 /** --------------------------------------------------------
-* * ***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.
-*      - 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 string or empty-string.
-*/
+ * * ***Utility: `getFirstPrefixPathname`.***
+ * --------------------------------------------------------
+ * **Extract First Valid Prefix from Path Array or String.**
+ * - **Main Purpose:**
+ *    - This function helps extract the first valid URL prefix from various possible inputs.
+ *    - It is especially useful in routing systems, middleware, or frontend apps that need to
+ *      decide layout, active navigation, or permissions based on the first segment (or prefix) of a pathname.
+ * - **Typical uses include:**
+ *    - Determining which layout to render (e.g., `/admin` vs `/dashboard` vs `/`).
+ *    - Highlighting the active menu item in a sidebar based on the current URL.
+ *    - Enforcing route guards or access controls depending on the URL prefix.
+ *    - Parsing multi-level route prefixes and selecting the most relevant one.
+ * - **Behavior:**
+ *    - It works as follows:
+ *        - If `result` is an array of strings, it normalizes each element and returns
+ *          the first non-root path (i.e., not just `"/"`).
+ *        - If all items normalize to `"/"`,
+ *          it returns the `defaultValue` (normalized).
+ *        - If `result` is a single string, it normalizes it and returns it if valid,
+ *          otherwise falls back to the normalized `defaultValue`.
+ *        - If `result` is `null` or `undefined`, it returns the normalized `defaultValue`.
+ * - **Validation & Errors:**
+ *    - Throws a `TypeError` if:
+ *      - `defaultValue` is not a string or empty-string.
+ *      - `result` is an array that contains non-string elements.
+ *      - `result` is a value that is neither `string`, `string[]`, nor `null`.
+ * @example
+ * 1. #### For React (*Determining layout*):
+ * ```ts
+ *   const prefix = getFirstPrefixPathname(
+ *      getPrefixPathname(
+ *        "/admin/settings",
+ *        ["/admin", "/dashboard"]
+ *      )
+ *   );
+ *
+ *   if (prefix === "/admin") {
+ *     renderAdminLayout();
+ *   }
+ * ```
+ *
+ * 2. #### Setting active menu state:
+ * ```ts
+ *   const activeSection = getFirstPrefixPathname(["", "/dashboard", "/profile"]);
+ *   // ➔ "/dashboard"
+ * ```
+ *
+ * 3. #### Providing graceful fallback:
+ * ```ts
+ *   const section = getFirstPrefixPathname([], "/home");
+ *   // ➔ "/home"
+ * ```
+ * 4. #### ✅ Using with an Array of Pathnames:
+ * ```ts
+ *   const result = getPrefixPathname(["   ", "/dashboard", "/settings"]);
+ *   console.log(getFirstPrefixPathname(result));
+ *   // ➔ "/dashboard"
+ * ```
+ *
+ * 5. #### ✅ Using with Single String:
+ * ```ts
+ *   console.log(getFirstPrefixPathname("/profile/settings"));
+ *   // ➔ "/profile/settings"
+ *   console.log(getFirstPrefixPathname("   "));
+ *   // ➔ "/"
+ * ```
+ *
+ * 6. #### ✅ Fallback to Custom Default:
+ * ```ts
+ *   console.log(getFirstPrefixPathname(["   ", ""], "/home"));
+ *   // ➔ "/home"
+ *   console.log(getFirstPrefixPathname(null, "/dashboard"));
+ *   // ➔ "/dashboard"
+ * ```
+ *
+ * 7. #### ✅ Throws on Invalid Input:
+ * ```ts
+ *   getFirstPrefixPathname([1, 2] as any); // ➔ ❌ throws TypeError
+ *   getFirstPrefixPathname({} as any);     // ➔ ❌ throws TypeError
+ *   getFirstPrefixPathname(null, "   ");   // ➔ ❌ throws TypeError
+ * ```
+ * @param {string | string[] | null | undefined} result
+ *    The pathname(s) to process, can be:
+ *    - A string path (e.g. `"/profile"`),
+ *    - An array of string paths (e.g. `["   ", "/dashboard"]`),
+ *    - Or `null`.
+ * @param {string} [defaultValue="/"]
+ *    A custom default path to use if `result` is null or no valid prefix is found.
+ *      - 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 string or empty-string.
+ */
 declare const getFirstPrefixPathname:(result:string|string[]|null|undefined,defaultValue?:string)=>string;
 /** --------------------------------------------------------
-* * ***Utility: `normalizePathname`.***
-* --------------------------------------------------------
-* **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 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 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("   ");
-* // ➔ "/"
-* normalizePathname(null, "/home");
-* // ➔ "/home"
-* normalizePathname("/double//slashes");
-* // ➔ "/double/slashes"
-* normalizePathname(" nested / path / 🚀 ");
-* // ➔ "/nested/path/🚀"
-*/
+ * * ***Utility: `normalizePathname`.***
+ * --------------------------------------------------------
+ * **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 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 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("   ");
+ * // ➔ "/"
+ * normalizePathname(null, "/home");
+ * // ➔ "/home"
+ * normalizePathname("/double//slashes");
+ * // ➔ "/double/slashes"
+ * normalizePathname(" nested / path / 🚀 ");
+ * // ➔ "/nested/path/🚀"
+ */
 declare const normalizePathname:(pathname:string|null|undefined,defaultPath?:string)=>string;type FormatEnvPortOptions={
 /** Add prefix with a colon, defaultValue: `false`.
-*
-* @default 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 {TypeError} If `options` is not an object or `prefixColon` is not boolean.
-* @example
-* formatEnvPort("port:8080");
-* // ➔ "8080"
-* formatEnvPort("port:8080", { prefixColon: true });
-* // ➔ ":8080"
-*/
+ * * ***Utility: `formatEnvPort`.***
+ * -----------------------------------------------
+ * **Retrieves and formats an environment port variable.**
+ * - **Behavior:**
+ *    - Extracts only digits from the input.
+ *    - If no digits found, returns an empty string.
+ *    - By default does NOT prefix with a colon.
+ *      - Use `{ prefixColon: true }` to prefix with a colon.
+ * @param {string | null | undefined} envVar The environment variable string.
+ * @param {FormatEnvPortOptions} [options] Optional object: `{ prefixColon?: boolean }`.
+ * @returns {string} A string like `":8080"` or `"8080"`, or `""` if no digits.
+ * @throws {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;export{type QueryParamPairs,constructURL,extractURLs,formatEnvPort,getFirstPrefixPathname,getPrefixPathname,normalizePathname};