@rzl-zone/utils-js 3.8.0 → 3.9.0

package/dist/urls/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.8.0.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -383,153 +383,221 @@ defaultPath?:string;
  * **Must be `true` in this type.**
  */
 keepNullable?:true;};type MainNormalizePathnameOptions={
-/** * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `false`.***
+/** --------------------------------------------------------
+ * * ***Preserve trailing slash at the end of the normalized pathname, defaultValue: `false`.***
+ * --------------------------------------------------------
  *
  * @defaultValue `false`
  */
-keepTrailingSlash?:boolean;};type NormalizePathnameOptionsKeepNullableTrue=MainNormalizePathnameOptions & KeepNullableOptions;type NormalizePathnameOptionsKeepNullableFalse=MainNormalizePathnameOptions & UnKeepNullableOptions;type ResUnKeepNullable<T>=T extends undefined?string:T extends null?string:T extends null|undefined?string:string;type ResKeepNullable<T>=T extends string?string:T extends undefined?undefined:T extends null?null:T extends null|undefined?null|undefined:string|null|undefined;
+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;type ResUnKeepNullable<T>=T extends undefined?string:T extends null?string:T extends null|undefined?string:string;type ResKeepNullable<T>=T extends string?string:T extends undefined?undefined:T extends null?null:T extends null|undefined?null|undefined:string|null|undefined;
 /** --------------------------------------------------------
  * * ***Utility: `normalizePathname`.***
  * --------------------------------------------------------
+ *
  * - **Description:**
- *    - Normalizes a given pathname string for consistent routing, URL handling, and string hygiene.
- *    - It trims whitespace, collapses redundant slashes, handles full URLs, query strings, hash fragments,
- *    - Unicode characters, emojis, and optionally preserves `null` or `undefined`.
- *    - Trailing slash behavior can be controlled via `keepTrailingSlash`.
- *
- * - **Behavior Details:**
- *    - Trims leading and trailing whitespace.
- *    - Removes all internal spaces.
- *    - Collapses multiple consecutive slashes into a single `/`.
- *    - Prepends a leading slash if missing.
- *    - Preserves trailing slash only if `keepTrailingSlash` is `true`.
- *    - Supports full URLs (`http://` or `https://`) and relative paths only also detect valid domain and
- *      subdomain (with support handle wildcard eg: *.example.com) (with optional with port) eg (localhost, localhost:3000, example.com, sub.domain.com, *.domain.test, etc).
- *    - Preserves query strings (`?key=value`) and hash fragments (`#anchor`) intact.
- *    - Handles emojis and Unicode safely.
- *    - Returns `string`, `null` or `undefined` as-is if `keepNullable` is true.
- *    - Returns `undefined` if pathname is not a string and `keepNullable` is `true`.
- *    - Returns `defaultPath` if pathname is empty-string even when `keepNullable` is true.
- *    - Returns `defaultPath` if pathname is empty/invalid and `keepNullable` is `false`.
- *
- * - **Options (`options`)**:
- *    - `defaultPath` (***`string`***, default: **`"/"`**)
- *       - Fallback path if the input is invalid (**empty-string**, **null**, **undefined**) and
- *          `keepNullable` is **false**, if `keepNullable` is true, used only when pathname is empty-string.
- *    - `keepNullable` (***`boolean`***, default: **`false`**)
- *       - If **true**, preserves `null` or `undefined` as-is instead of returning
- *         `defaultPath` (except if `pathname` is **empty-string**).
- *    - `keepTrailingSlash` (***`boolean`***, default: **`false`**)
- *      - If **true**, preserves a trailing slash at the end of the normalized pathname.
- *
- * @param {string | null | undefined} pathname - ***The pathname to normalize.***
- * @param {NormalizePathnameOptions} [options] - ***Configuration options.***
- *
- * @returns {string | null | undefined} ***Normalized pathname, or original nullable value if `keepNullable` is `true`
- * _(except if `pathname` is empty-string, will keep returning `defaultPath`)_.***
- *
- * @throws **{@link TypeError | `TypeError`}** if `defaultPath` is invalid when `keepNullable` is false.
- * @throws **`NormalizePathnameError` extends {@link Error | `Error`}** If normalization fails (e.g., invalid URL).
+ *    Normalizes any pathname or URL string to a clean, predictable format.
+ *    Useful for routing, file paths, and URL handling.
+ *    - Handles:
+ *      - Leading/trailing spaces
+ *      - Internal spaces in path segments
+ *      - Redundant slashes (`//`)
+ *      - Full URLs vs relative paths
+ *      - Query (`?`) and hash (`#`) preservation
+ *      - Unicode & emoji characters
+ *      - Optional nullable preservation (`keepNullable`)
+ *      - Optional trailing slash preservation (`keepTrailingSlash`)
+ *      - Optional removal of localhost first segment (`localhostDomain`)
+ *      - Prevention of false-positive domain stripping (`ignoreDomainExtensions`)
+ *
+ * - **Key Steps Internally:**
+ *    1. Validate `options` (plain object, correct types)
+ *    2. Validate `defaultPath` (non-empty string if `keepNullable` is false)
+ *    3. Validate `ignoreDomainExtensions` (Set<string> | string[], each starts with `.`)
+ *    4. Handle nullable:
+ *       - Returns `null` / `undefined` if `keepNullable: true`
+ *       - Otherwise uses `defaultPath`
+ *    5. Trim spaces, remove internal spaces
+ *    6. If full URL: parse using `URL` constructor
+ *    7. If relative path or domain-like:
+ *       - Remove `localhost`/`localhost:port` if `localhostDomain`
+ *       - Remove first segment if domain-like and **not** in `ignoreDomainExtensions`
+ *    8. Normalize slashes
+ *    9. Ensure leading slash
+ *    10. Handle trailing slash
+ *    11. Decode Unicode safely
+ *    12. Return normalized pathname + search + hash
+ *
+ * - **Error Handling:**
+ *    - **TypeError**:
+ *       - `defaultPath` invalid (non-string or empty) when `keepNullable: false`
+ *       - `keepNullable`, `keepTrailingSlash`, `localhostDomain` not boolean
+ *       - `ignoreDomainExtensions` invalid
+ *    - **NormalizePathnameError** (extends ***Error***):
+ *       - Invalid URL parsing
+ *       - Unexpected normalization errors
+ *
+ * - **Options:**
+ *    ```ts
+ *    {
+ *      // fallback if invalid path, default: "/"
+ *      defaultPath?: string;
+ *      // preserve null/undefined, default: false
+ *      keepNullable?: boolean;
+ *      // preserve trailing slash, default: false
+ *      keepTrailingSlash?: boolean;
+ *      // remove localhost:port first segment, default: false
+ *      localhostDomain?: boolean;
+ *      // prevent domain stripping, default: undefined
+ *      ignoreDomainExtensions?: Set<string> | string[];
+ *    }
+ *    ```
  *
  * @example
- * // Basic normalization
+ * // Basic path cleaning
  * normalizePathname("   /foo//bar  ");
  * // ➔ "/foo/bar"
  *
- * // Full URL with query and hash
+ * // Trailing slash control
+ * normalizePathname("/api//v1//user//", { keepTrailingSlash: true });
+ * // ➔ "/api/v1/user/"
+ * normalizePathname("/api//v1//user//", { keepTrailingSlash: false });
+ * // ➔ "/api/v1/user"
+ *
+ * // Full URL normalization
  * normalizePathname("https://example.com//path///to/resource?x=1#hash");
  * // ➔ "/path/to/resource?x=1#hash"
  *
- * // Empty string returns defaultPath
- * normalizePathname("   ");
- * // ➔ "/"
- *
- * // Return defaultPath if isn't valid pathname and keepNullable is `undefined` or `false`.
- * normalizePathname(null, { defaultPath: "/home" });
- * // ➔ "/home"
- *
- * // Preserve null
+ * // Null/undefined preservation
  * normalizePathname(null, { keepNullable: true });
  * // ➔ null
- *
- * // Preserve undefined
  * normalizePathname(undefined, { keepNullable: true });
  * // ➔ undefined
  *
- * // Return defaultPath if pathname is empty-string even with keepNullable
- * normalizePathname("  ", { keepNullable: true, defaultPath:"/home" });
+ * // Default fallback
+ * normalizePathname("", { defaultPath: "/home" });
  * // ➔ "/home"
  *
- * // Return undefined if pathname is not a valid-string.
- * normalizePathname(true, { keepNullable: true, defaultPath:"/home" });
- * // ➔ undefined
- *
- * // Collapse multiple slashes
- * normalizePathname("/double//slashes");
- * // ➔ "/double/slashes"
- *
- * // Handles emoji and Unicode
- * normalizePathname(" nested / path / 🚀 ");
- * // ➔ "/nested/path/🚀"
+ * // Localhost removal
+ * normalizePathname("localhost:3000/path/to/resource", { localhostDomain: true });
+ * // ➔ "/path/to/resource"
  *
- * // Query and hash preserved
- * normalizePathname("/dashboard///stats?view=all#top");
- * // ➔ "/dashboard/stats?view=all#top"
+ * // Prevent false-positive domain stripping
+ * normalizePathname("archive.tar.gz#download", { ignoreDomainExtensions: [".tar.gz"] });
+ * // ➔ "/archive.tar.gz#download"
+ * normalizePathname("image.png?version=2", { ignoreDomainExtensions: [".png"] });
+ * // ➔ "/image.png?version=2"
  *
- * // Leading/trailing slashes normalized
- * normalizePathname("///api//v1///user/");
- * // ➔ "/api/v1/user"
- *
- * // Keep trailing slash if option enabled
- * normalizePathname("///api//v1///user//", { keepTrailingSlash: true });
- * // ➔ "/api/v1/user/"
- *
- * // Relative-like paths handled safely
- * normalizePathname("path/to/page");
- * // ➔ "/path/to/page"
+ * // Emojis and Unicode
+ * normalizePathname("🔥//deep//path///🚀");
+ * // ➔ "/🔥/deep/path/🚀"
  *
- * // Query-only path
+ * // Query-only or hash-only
  * normalizePathname("?page=2");
  * // ➔ "/?page=2"
- *
- * // Hash-only path
  * normalizePathname("#section3");
  * // ➔ "/#section3"
  *
- * // URL parsing failure triggers custom error
+ * // Complex nested paths
+ * normalizePathname("   //nested///folder//file.txt  ");
+ * // ➔ "/nested/folder/file.txt"
+ *
+ * // Invalid URL triggers error
  * try {
- *    normalizePathname("http://");
+ *   normalizePathname("http://");
  * } catch (e) {
- *    // ➔ console.log(e);
+ *   // console.log(e);
  * }
  *
- * // Internal encoded spaces preserved
- * normalizePathname("/search/%20item%20");
- * // ➔ "/search/%20item%20"
- *
- * // Edge case: relative URL-like input
- * normalizePathname("localhost/path");
- * // ➔ "/path"
- * normalizePathname("localhost:3000/path");
- * // ➔ "/path"
- * normalizePathname("example.com/path");
- * // ➔ "/path"
- * normalizePathname("sub.domain.com/path");
- * // ➔ "/path"
- * normalizePathname("*.domain.com/path");
- * // ➔ "/path"
- *
- * // Deeply nested messy path
- * normalizePathname("   /🔥//deep//path///🚀  ");
- * // ➔ "/🔥/deep/path/🚀"
- *
- * // Edge case: root slash
- * normalizePathname("/");
- * // ➔ "/"
- *
- * // Edge case: multiple spaces only
- * normalizePathname("    ");
- * // ➔ "/"
+ * // First segment is domain but ignored due to extension
+ * normalizePathname("example.tar.bz/file", { ignoreDomainExtensions: [".tar.bz"] });
+ * // ➔ "/example.tar.bz/file"
  */
 declare function normalizePathname<T>(pathname:T,options?:NormalizePathnameOptionsKeepNullableFalse):ResUnKeepNullable<T>;declare function normalizePathname<T>(pathname:T,options?:NormalizePathnameOptionsKeepNullableTrue):ResKeepNullable<T>;type FormatEnvPortOptions={
 /** Add prefix with a colon, defaultValue: `false`.

package/dist/urls/index.js

@@ -2,24 +2,26 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.8.0.
+ * Version: 3.9.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-export { constructURL, extractURLs, getFirstPrefixPathname, getPrefixPathname } from '../chunk-5IKZ3JDV.js';
+export { constructURL, extractURLs, getFirstPrefixPathname, getPrefixPathname } from '../chunk-6WVOUVWD.js';
 import '../chunk-ONZFBJVW.js';
-import '../chunk-GAJBF6DR.js';
-import '../chunk-TDYGYHSH.js';
-import '../chunk-PZQC3FZY.js';
-import '../chunk-7ZNEUWYP.js';
+import '../chunk-UXT4XSUK.js';
+import '../chunk-SN5HAK3Y.js';
+import '../chunk-44X74C26.js';
+import '../chunk-MZ3T6L7Z.js';
 import '../chunk-WVSPXFTY.js';
-export { formatEnvPort, normalizePathname } from '../chunk-PW2VMJLT.js';
-export { punycodeUtilsJS } from '../chunk-YS27V6LS.js';
-import '../chunk-4ACKNPL5.js';
-import '../chunk-JY4HLZ4W.js';
-import '../chunk-VCVND6CH.js';
-import '../chunk-6WMB5AJR.js';
-import '../chunk-2VO2CBTU.js';
+export { formatEnvPort, normalizePathname } from '../chunk-R2DR7SPJ.js';
+import '../chunk-3LE6NX57.js';
+export { punycodeUtilsJS } from '../chunk-GKDSBOYE.js';
+import '../chunk-5KDVIEVO.js';
+import '../chunk-5O66AUEC.js';
+import '../chunk-OSSFLQDD.js';
+import '../chunk-M5QB2GM5.js';
+import '../chunk-TXOVQZPU.js';
+import '../chunk-X6ULJZ3X.js';
 import '../chunk-QNKGP5DY.js';
-import '../chunk-3KTD3QDI.js';
+import '../chunk-J4TT33ZX.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rzl-zone/utils-js",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "sideEffects": false,
   "engineStrict": true,
   "license": "MIT",