@rzl-zone/utils-js 3.11.1 → 3.12.1-beta.0

package/dist/urls/index.d.ts

@@ -1,12 +1,12 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.11.1.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
 /** ----------------------------------------------------------
  * * ***Type-Utility: `QueryParamPairs`.***
  * ----------------------------------------------------------
@@ -83,7 +83,6 @@ type QueryParamPairs = [[string, string | number], ...[string, string | number][
  * ```
  */
 declare const constructURL: (baseUrl: string | URL, queryParams?: URLSearchParamsIterator<[string, string | number]> | QueryParamPairs, removeParams?: string[]) => URL;
-
 /** ---------------------------------
  * * ***Utility: `extractURLs`.***
  * ---------------------------------
@@ -110,7 +109,6 @@ declare const constructURL: (baseUrl: string | URL, queryParams?: URLSearchParam
  * // ➔ ["http://example.com"]
  */
 declare const extractURLs: (url: string | null | undefined) => string[] | null;
-
 /** --------------------------------------------------------
  * * ***Utility: `getFirstPrefixPathname`.***
  * --------------------------------------------------------
@@ -207,20 +205,19 @@ declare const extractURLs: (url: string | null | undefined) => string[] | null;
  * @throws **{@link TypeError | `TypeError`}** ***if `result` is not a valid type, or `defaultValue` is not a string or empty-string.***
  */
 declare const getFirstPrefixPathname: (result: string | string[] | null | undefined, defaultValue?: string) => string;
-
 type GetPrefixPathnameOptions = {
-    /** The number of levels to include in the prefix (default is `1`).
-     *
-     * - For example, with `levels = 2`, the function will return the first two parts of the URL.
-     *
-     * @default 1
-     */
-    levels?: number;
-    /** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`).
-     *
-     * @default true
-     */
-    removeDuplicates?: boolean;
+  /** The number of levels to include in the prefix (default is `1`).
+   *
+   * - For example, with `levels = 2`, the function will return the first two parts of the URL.
+   *
+   * @default 1
+   */
+  levels?: number;
+  /** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`).
+   *
+   * @default true
+   */
+  removeDuplicates?: boolean;
 };
 /** --------------------------------------------------------
  * * ***Utility: `getPrefixPathname`.***
@@ -351,141 +348,140 @@ type GetPrefixPathnameOptions = {
  * ```
  */
 declare const getPrefixPathname: (url: string | string[], base?: string | string[] | null, options?: GetPrefixPathnameOptions) => string | string[] | null;
-
 /** Options when `keepNullable` is false (default).
  *
  * Returns `defaultPath` if `pathname` is empty or invalid.
  */
 type UnKeepNullableOptions = {
-    /** * ***Fallback value returned if `pathname` is empty-string or invalid.***
-     *
-     * Must be a **`non-empty string`**, defaultValue: `"/"`.
-     *
-     * @defaultValue `"/"`.
-     */
-    defaultPath?: string;
-    /** * ***Whether to preserve `null` or `undefined`, defaultValue: `false`.***
-     *
-     * @defaultValue `false`.
-     */
-    keepNullable?: false;
+  /** * ***Fallback value returned if `pathname` is empty-string or invalid.***
+   *
+   * Must be a **`non-empty string`**, defaultValue: `"/"`.
+   *
+   * @defaultValue `"/"`.
+   */
+  defaultPath?: string;
+  /** * ***Whether to preserve `null` or `undefined`, defaultValue: `false`.***
+   *
+   * @defaultValue `false`.
+   */
+  keepNullable?: false;
 };
 /** Options when `keepNullable` is true.
  *
  * Preserves `null` or `undefined` instead of returning `defaultPath`.
  */
 type KeepNullableOptions = {
-    /** * ***Fallback path is ignored when `keepNullable` is true **(except if
-     * `pathname` is empty-string or invalid, even this `true`)**,
-     * defaultValue: `"/"`.***
-     *
-     * @defaultValue `"/"`.
-     */
-    defaultPath?: string;
-    /** * ***Preserve `null` or `undefined` as-is if `true` (defaultValue: `false`).***
-     *
-     * - ***⚠️ Notes:***
-     *      - Keep returning `defaultPath` if `pathname` is empty-string, even this `true`.
-     *
-     * **Must be `true` in this type.**
-     */
-    keepNullable?: true;
+  /** * ***Fallback path is ignored when `keepNullable` is true **(except if
+   * `pathname` is empty-string or invalid, even this `true`)**,
+   * defaultValue: `"/"`.***
+   *
+   * @defaultValue `"/"`.
+   */
+  defaultPath?: string;
+  /** * ***Preserve `null` or `undefined` as-is if `true` (defaultValue: `false`).***
+   *
+   * - ***⚠️ Notes:***
+   *      - Keep returning `defaultPath` if `pathname` is empty-string, even this `true`.
+   *
+   * **Must be `true` in this type.**
+   */
+  keepNullable?: true;
 };
 type MainNormalizePathnameOptions = {
-    /** --------------------------------------------------------
-     * * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `false`.***
-     * --------------------------------------------------------
-     *
-     * @defaultValue `false`
-     */
-    keepTrailingSlash?: boolean;
-    /** --------------------------------------------------------
-     * * ***Allow special localhost domain at the beginning of the pathname.***
-     * --------------------------------------------------------
-     * @description
-     * If `true`, the first segment of the pathname that is `/localhost` or `localhost`
-     * (with or without a port, e.g., `localhost:3000`) will be treated as a special domain
-     * and **removed** from the normalized pathname.
-     *
-     * - **Examples (`localhostDomain: true`)**:
-     *    - `"/localhost/path"` ➔ `"/path"`
-     *    - `"localhost:3000/path"` ➔ `"/path"`
-     *    - `"localhost"` ➔ `"/"` (entire path removed)
-     *
-     * - Only the **first path segment** is affected. Any subsequent occurrences of `"localhost"`
-     *   will remain intact.
-     *
-     * @defaultValue `false`
-     */
-    localhostDomain?: boolean;
-    /**
-     * --------------------------------------------------------
-     * * ***Custom list of file extensions that prevent the first path segment from being treated as a domain.***
-     * --------------------------------------------------------
-     *
-     * **Description:**
-     * - The first segment of a pathname is often interpreted as a domain (e.g., `example.com`).
-     * - If this first segment ends with any of the extensions listed here, it will **not** be considered a domain,
-     *   and will instead be preserved as part of the relative path.
-     * - This is useful for cases where filenames appear at the start of a path and you want them treated as relative paths,
-     *   such as `"image.png?version=2"` or `"archive.tar.gz#download"`.
-     * - Only the **first path segment** is affected; all other segments are processed normally.
-     * - **Ignored** if:
-     *    1. The pathname starts with a full URL protocol (`http://` or `https://`), e.g., `"https://example.com/file.png"`.
-     *    2. The first path segment is already a valid domain, e.g., `"example.com/image.png"`.
-     *
-     * **Type & Validation:**
-     * - Must be a `Set<string>` or `string[]`.
-     * - Each string **must include the leading dot**, e.g., `.png`, `.tar.gz`.
-     * - Multi-part extensions (like `.tar.gz`, `.tar.bz`) are supported.
-     * - Throws a **TypeError** if:
-     *    1. The type is not a `Set<string>` or `string[]`.
-     *    2. Any string in the array/set is empty.
-     *    3. Any string does not start with a dot (`.`).
-     *
-     * **Usage Notes:**
-     * - Only applied when the first segment is otherwise domain-like **and** pathname is relative or domain-like without protocol.
-     * - Query strings (`?x=1`) and hash fragments (`#section`) are preserved.
-     *
-     * **Examples (relative paths, option active):**
-     * ```ts
-     * normalizePathname("image.png?version=2", {
-     *   ignoreDomainExtensions: [".png", ".jpg"]
-     * });
-     * // ➔ "/image.png?version=2"
-     *
-     * normalizePathname("archive.tar.gz#download", {
-     *   ignoreDomainExtensions: new Set([".tar.gz"])
-     * });
-     * // ➔ "/archive.tar.gz#download"
-     *
-     * normalizePathname("script.js?module=true#top", {
-     *   ignoreDomainExtensions: [".js"]
-     * });
-     * // ➔ "/script.js?module=true#top"
-     * ```
-     *
-     * **Examples (full URL or explicit domain - option ignored):**
-     * ```ts
-     * normalizePathname("https://example.com/image.png?version=2", {
-     *   ignoreDomainExtensions: [".png"]
-     * });
-     * // ➔ "/image.png?version=2"  // URL is parsed normally; ignoreDomainExtensions has no effect
-     *
-     * normalizePathname("example.com/script.js?module=true#top", {
-     *   ignoreDomainExtensions: [".js"]
-     * });
-     * // ➔ "/script.js?module=true#top"  // domain recognized; option ignored
-     * ```
-     *
-     * **Notes:**
-     * - Only the **first path segment** is checked.
-     * - Prevents false-positive domain stripping for filenames that look like domains.
-     * - Throws **TypeError** if invalid type or invalid string is provided.
-     *
-     * @defaultValue `undefined` (feature inactive if not provided)
-     */
-    ignoreDomainExtensions?: Set<string> | string[];
+  /** --------------------------------------------------------
+   * * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `false`.***
+   * --------------------------------------------------------
+   *
+   * @defaultValue `false`
+   */
+  keepTrailingSlash?: boolean;
+  /** --------------------------------------------------------
+   * * ***Allow special localhost domain at the beginning of the pathname.***
+   * --------------------------------------------------------
+   * @description
+   * If `true`, the first segment of the pathname that is `/localhost` or `localhost`
+   * (with or without a port, e.g., `localhost:3000`) will be treated as a special domain
+   * and **removed** from the normalized pathname.
+   *
+   * - **Examples (`localhostDomain: true`)**:
+   *    - `"/localhost/path"` ➔ `"/path"`
+   *    - `"localhost:3000/path"` ➔ `"/path"`
+   *    - `"localhost"` ➔ `"/"` (entire path removed)
+   *
+   * - Only the **first path segment** is affected. Any subsequent occurrences of `"localhost"`
+   *   will remain intact.
+   *
+   * @defaultValue `false`
+   */
+  localhostDomain?: boolean;
+  /**
+   * --------------------------------------------------------
+   * * ***Custom list of file extensions that prevent the first path segment from being treated as a domain.***
+   * --------------------------------------------------------
+   *
+   * **Description:**
+   * - The first segment of a pathname is often interpreted as a domain (e.g., `example.com`).
+   * - If this first segment ends with any of the extensions listed here, it will **not** be considered a domain,
+   *   and will instead be preserved as part of the relative path.
+   * - This is useful for cases where filenames appear at the start of a path and you want them treated as relative paths,
+   *   such as `"image.png?version=2"` or `"archive.tar.gz#download"`.
+   * - Only the **first path segment** is affected; all other segments are processed normally.
+   * - **Ignored** if:
+   *    1. The pathname starts with a full URL protocol (`http://` or `https://`), e.g., `"https://example.com/file.png"`.
+   *    2. The first path segment is already a valid domain, e.g., `"example.com/image.png"`.
+   *
+   * **Type & Validation:**
+   * - Must be a `Set<string>` or `string[]`.
+   * - Each string **must include the leading dot**, e.g., `.png`, `.tar.gz`.
+   * - Multi-part extensions (like `.tar.gz`, `.tar.bz`) are supported.
+   * - Throws a **TypeError** if:
+   *    1. The type is not a `Set<string>` or `string[]`.
+   *    2. Any string in the array/set is empty.
+   *    3. Any string does not start with a dot (`.`).
+   *
+   * **Usage Notes:**
+   * - Only applied when the first segment is otherwise domain-like **and** pathname is relative or domain-like without protocol.
+   * - Query strings (`?x=1`) and hash fragments (`#section`) are preserved.
+   *
+   * **Examples (relative paths, option active):**
+   * ```ts
+   * normalizePathname("image.png?version=2", {
+   *   ignoreDomainExtensions: [".png", ".jpg"]
+   * });
+   * // ➔ "/image.png?version=2"
+   *
+   * normalizePathname("archive.tar.gz#download", {
+   *   ignoreDomainExtensions: new Set([".tar.gz"])
+   * });
+   * // ➔ "/archive.tar.gz#download"
+   *
+   * normalizePathname("script.js?module=true#top", {
+   *   ignoreDomainExtensions: [".js"]
+   * });
+   * // ➔ "/script.js?module=true#top"
+   * ```
+   *
+   * **Examples (full URL or explicit domain - option ignored):**
+   * ```ts
+   * normalizePathname("https://example.com/image.png?version=2", {
+   *   ignoreDomainExtensions: [".png"]
+   * });
+   * // ➔ "/image.png?version=2"  // URL is parsed normally; ignoreDomainExtensions has no effect
+   *
+   * normalizePathname("example.com/script.js?module=true#top", {
+   *   ignoreDomainExtensions: [".js"]
+   * });
+   * // ➔ "/script.js?module=true#top"  // domain recognized; option ignored
+   * ```
+   *
+   * **Notes:**
+   * - Only the **first path segment** is checked.
+   * - Prevents false-positive domain stripping for filenames that look like domains.
+   * - Throws **TypeError** if invalid type or invalid string is provided.
+   *
+   * @defaultValue `undefined` (feature inactive if not provided)
+   */
+  ignoreDomainExtensions?: Set<string> | string[];
 };
 type NormalizePathnameOptionsKeepNullableTrue = MainNormalizePathnameOptions & KeepNullableOptions;
 type NormalizePathnameOptionsKeepNullableFalse = MainNormalizePathnameOptions & UnKeepNullableOptions;
@@ -615,13 +611,12 @@ type ResKeepNullable<T> = T extends string ? string : T extends undefined ? unde
  */
 declare function normalizePathname<T>(pathname: T, options?: NormalizePathnameOptionsKeepNullableFalse): ResUnKeepNullable<T>;
 declare function normalizePathname<T>(pathname: T, options?: NormalizePathnameOptionsKeepNullableTrue): ResKeepNullable<T>;
-
 type FormatEnvPortOptions = {
-    /** Add prefix with a colon, defaultValue: `false`.
-     *
-     * @default false
-     */
-    prefixColon?: boolean;
+  /** Add prefix with a colon, defaultValue: `false`.
+   *
+   * @default false
+   */
+  prefixColon?: boolean;
 };
 /** -----------------------------------------------
  * * ***Utility: `formatEnvPort`.***
@@ -643,7 +638,6 @@ type FormatEnvPortOptions = {
  * // ➔ ":8080"
  */
 declare const formatEnvPort: (envVar: string | null | undefined, options?: FormatEnvPortOptions) => string;
-
 /** ---------------------------------------------------------
  * * ***Constants for `Punycode-UtilsJS` algorithm.***
  * ---------------------------------------------------------
@@ -652,86 +646,86 @@ declare const formatEnvPort: (envVar: string | null | undefined, options?: Forma
  * Unicode domain names to ASCII (`Punycode-UtilsJS`) and vice versa.
  */
 type PunycodeUtilsJS = {
+  /** ---------------------------------------------------------
+   * * ***Version of the `Punycode-UtilsJS` implementation.***
+   * ---------------------------------------------------------
+   *
+   * @example
+   * console.log(punycodeUtilsJS.version); // "1.0.0"
+   */
+  version: string;
+  /** ---------------------------------------------------------
+   * * ***UCS-2 utility functions.***
+   * ---------------------------------------------------------
+   */
+  ucs2: {
     /** ---------------------------------------------------------
-     * * ***Version of the `Punycode-UtilsJS` implementation.***
-     * ---------------------------------------------------------
-     *
-     * @example
-     * console.log(punycodeUtilsJS.version); // "1.0.0"
-     */
-    version: string;
-    /** ---------------------------------------------------------
-     * * ***UCS-2 utility functions.***
-     * ---------------------------------------------------------
-     */
-    ucs2: {
-        /** ---------------------------------------------------------
-         * * ***Decodes a UCS-2 encoded string to an array of Unicode code points.***
-         * ---------------------------------------------------------
-         *
-         * @param input - The UCS-2 string to decode.
-         * @returns Array of Unicode code points.
-         * @example
-         * punycodeUtilsJS.ucs2.decode("𐍈");
-         * // ➔ [66376]
-         */
-        decode: (input: string) => number[];
-        /** ---------------------------------------------------------
-         * * ***Encodes an array of Unicode code points to a UCS-2 string.***
-         * ---------------------------------------------------------
-         *
-         * @param points - Array of Unicode code points.
-         * @returns Encoded string.
-         * @example
-         * punycodeUtilsJS.ucs2.encode([66376]);
-         * // ➔ "𐍈"
-         */
-        encode: (points: number[]) => string;
-    };
-    /** ---------------------------------------------------------
-     * * ***Decodes a `Punycode-UtilsJS` string to a Unicode string.***
-     * ---------------------------------------------------------
-     *
-     * @param input - The `Punycode-UtilsJS` string to decode.
-     * @returns Decoded Unicode string.
-     * @example
-     * punycodeUtilsJS.decode("xn--fsq");
-     * // ➔ "ü"
-     */
-    decode: (input: string) => string;
-    /** ---------------------------------------------------------
-     * * ***Encodes a Unicode string to `Punycode-UtilsJS`.***
-     * ---------------------------------------------------------
-     *
-     * @param input - Unicode string to encode.
-     * @returns `Punycode-UtilsJS` string.
-     * @example
-     * punycodeUtilsJS.encode("ü");
-     * // ➔ "xn--fsq"
-     */
-    encode: (input: string) => string;
-    /** ---------------------------------------------------------
-     * * ***Converts a Unicode domain or label to ASCII (`Punycode-UtilsJS`).***
+     * * ***Decodes a UCS-2 encoded string to an array of Unicode code points.***
      * ---------------------------------------------------------
      *
-     * @param input - Domain or label string.
-     * @returns ASCII string suitable for DNS.
+     * @param input - The UCS-2 string to decode.
+     * @returns Array of Unicode code points.
      * @example
-     * punycodeUtilsJS.toASCII("пример.рф");
-     * // ➔ "xn--e1afmkfd.xn--p1ai"
+     * punycodeUtilsJS.ucs2.decode("𐍈");
+     * // ➔ [66376]
      */
-    toASCII: (input: string) => string;
+    decode: (input: string) => number[];
     /** ---------------------------------------------------------
-     * * ***Converts an ASCII (`Punycode-UtilsJS`) domain or label to Unicode.***
+     * * ***Encodes an array of Unicode code points to a UCS-2 string.***
      * ---------------------------------------------------------
      *
-     * @param input - ASCII string (with xn-- prefix if needed).
-     * @returns Unicode string.
+     * @param points - Array of Unicode code points.
+     * @returns Encoded string.
      * @example
-     * punycodeUtilsJS.toUnicode("xn--e1afmkfd.xn--p1ai");
-     * // ➔ "пример.рф"
+     * punycodeUtilsJS.ucs2.encode([66376]);
+     * // ➔ "𐍈"
      */
-    toUnicode: (input: string) => string;
+    encode: (points: number[]) => string;
+  };
+  /** ---------------------------------------------------------
+   * * ***Decodes a `Punycode-UtilsJS` string to a Unicode string.***
+   * ---------------------------------------------------------
+   *
+   * @param input - The `Punycode-UtilsJS` string to decode.
+   * @returns Decoded Unicode string.
+   * @example
+   * punycodeUtilsJS.decode("xn--fsq");
+   * // ➔ "ü"
+   */
+  decode: (input: string) => string;
+  /** ---------------------------------------------------------
+   * * ***Encodes a Unicode string to `Punycode-UtilsJS`.***
+   * ---------------------------------------------------------
+   *
+   * @param input - Unicode string to encode.
+   * @returns `Punycode-UtilsJS` string.
+   * @example
+   * punycodeUtilsJS.encode("ü");
+   * // ➔ "xn--fsq"
+   */
+  encode: (input: string) => string;
+  /** ---------------------------------------------------------
+   * * ***Converts a Unicode domain or label to ASCII (`Punycode-UtilsJS`).***
+   * ---------------------------------------------------------
+   *
+   * @param input - Domain or label string.
+   * @returns ASCII string suitable for DNS.
+   * @example
+   * punycodeUtilsJS.toASCII("пример.рф");
+   * // ➔ "xn--e1afmkfd.xn--p1ai"
+   */
+  toASCII: (input: string) => string;
+  /** ---------------------------------------------------------
+   * * ***Converts an ASCII (`Punycode-UtilsJS`) domain or label to Unicode.***
+   * ---------------------------------------------------------
+   *
+   * @param input - ASCII string (with xn-- prefix if needed).
+   * @returns Unicode string.
+   * @example
+   * punycodeUtilsJS.toUnicode("xn--e1afmkfd.xn--p1ai");
+   * // ➔ "пример.рф"
+   */
+  toUnicode: (input: string) => string;
 };
 /** ---------------------------------------------------------
  * * ***`Punycode-UtilsJS` object exposing all API functions and version.***
@@ -742,5 +736,5 @@ type PunycodeUtilsJS = {
  * - Useful for IDN (Internationalized Domain Names) support.
  */
 declare const punycodeUtilsJS: PunycodeUtilsJS;
-
-export { type QueryParamPairs, constructURL, extractURLs, formatEnvPort, getFirstPrefixPathname, getPrefixPathname, normalizePathname, punycodeUtilsJS };
+/** Export individual functions */
+export { QueryParamPairs, constructURL, extractURLs, formatEnvPort, getFirstPrefixPathname, getPrefixPathname, normalizePathname, punycodeUtilsJS };