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

package/dist/urls/index.d.ts

@@ -1,418 +1,393 @@
 /** ----------------------------------------------------------
-* * ***Represents a non-empty array of key–value pairs.***
-* ----------------------------------------------------------
-*
-* 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.
-*
-* @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 = [];
-*
-* // ❌ 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][]];
 /** ---------------------------------
-* * ***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]>} [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
-* // 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", ... }
-*/
+ * * ***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;
 /** ---------------------------------
-* * ***Extracts all valid URLs from a given string.***
-* ---------------------------------
-*
-* 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://例子.公司"]
-*
-* @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.
-*
-* ---
-*
-* @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**
-*
-* #### ✅ **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?:{
-/** 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. */
+ * * ***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
+ */
 levels?:number;
-/** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`). */
-removeDuplicates?:boolean;})=>string|string[]|null;
+/** 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"`).
+ *    - 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;
 /** --------------------------------------------------------
-* * ***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 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*
-* ```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} 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 `"/"`.
-*
-* @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.
-*/
-declare const getFirstPrefixPathname:(result?:string|string[]|null,defaultValue?:string)=>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;
 /** --------------------------------------------------------
-* * ***Normalizes a given pathname by ensuring consistent formatting.***
-* --------------------------------------------------------
-*
-* @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 `/`.
-*
-* @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 `"/"`.
-*
-* @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 {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,defaultPath?: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/🚀"
+ */
+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.***
-* -----------------------------------------------
-*
-* - 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.
-*
-* @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};
+ * * ***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};