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

package/dist/next/index.d.cts

@@ -2,7 +2,7 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.12.1-beta.0`
+*  Version: `3.12.1-beta.1`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
@@ -10,217 +10,211 @@
 
 import { IsAny } from "@rzl-zone/ts-types-plus";
 /** ---------------------------------------------------------
- * * ***Extracts dynamic route parameters from a given route string.***
- * ---------------------------------------------------------
- * **This utility type recursively searches for dynamic segments within a route,
- * extracting each parameter and constructing an object where each key represents
- * a dynamic segment and its value is of type `string`.**
- * - ***⚠️ Warning:***
- *    - ***This types only support when using ***[`NextJS`](https://nextjs.org/)***.***
- * @template T - The route string containing potential dynamic segments.
- * @example
- * ```ts
- * type Params1 = ExtractRouteParams<"/user/[id]">;
- * // ➔ { id: string }
- * type Params2 = ExtractRouteParams<"/post/[slug]/comment/[commentId]">;
- * // ➔ { slug: string; commentId: string }
- * type Params3 = ExtractRouteParams<"/dashboard">;
- * // ➔ {} (no dynamic parameters)
- * ```
- */
+* * ***Extracts dynamic route parameters from a given route string.***
+* ---------------------------------------------------------
+* **This utility type recursively searches for dynamic segments within a route,
+* extracting each parameter and constructing an object where each key represents
+* a dynamic segment and its value is of type `string`.**
+* - ***⚠️ Warning:***
+*    - ***This types only support when using ***[`NextJS`](https://nextjs.org/)***.***
+* @template T - The route string containing potential dynamic segments.
+* @example
+* ```ts
+* type Params1 = ExtractRouteParams<"/user/[id]">;
+* // ➔ { id: string }
+* type Params2 = ExtractRouteParams<"/post/[slug]/comment/[commentId]">;
+* // ➔ { slug: string; commentId: string }
+* type Params3 = ExtractRouteParams<"/dashboard">;
+* // ➔ {} (no dynamic parameters)
+* ```
+*/
 type ExtractRouteParams<T> = T extends string ? HasDynamicSegments<T> extends true ? T extends `${infer _Start}[${infer Param}]${infer Rest}` ? { [K in Param | keyof ExtractRouteParams<Rest>]: string } : unknown : unknown : unknown;
 /** ---------------------------------------------------------
- * * ***Determines whether a given route contains dynamic segments.***
- * ---------------------------------------------------------
- * **This type checks if the route includes at least one `[param]` pattern.
- * If it does, the result is `true`, otherwise `false`.**
- * - ***⚠️ Warning:***
- *    - ***This types only support when using ***[`NextJS`](https://nextjs.org/)***.***
- * @template T - The route string to be evaluated.
- * @example
- * ```ts
- * type HasParams1 = HasDynamicSegments<"/user/[id]">;
- * // ➔ true
- * type HasParams2 = HasDynamicSegments<"/settings/profile">;
- * // ➔ false
- * type HasParams3 = HasDynamicSegments<"/blog/[category]/[slug]">;
- * // ➔ true
- * ```
- */
+* * ***Determines whether a given route contains dynamic segments.***
+* ---------------------------------------------------------
+* **This type checks if the route includes at least one `[param]` pattern.
+* If it does, the result is `true`, otherwise `false`.**
+* - ***⚠️ Warning:***
+*    - ***This types only support when using ***[`NextJS`](https://nextjs.org/)***.***
+* @template T - The route string to be evaluated.
+* @example
+* ```ts
+* type HasParams1 = HasDynamicSegments<"/user/[id]">;
+* // ➔ true
+* type HasParams2 = HasDynamicSegments<"/settings/profile">;
+* // ➔ false
+* type HasParams3 = HasDynamicSegments<"/blog/[category]/[slug]">;
+* // ➔ true
+* ```
+*/
 type HasDynamicSegments<T> = T extends `${string}[${string}]${string}` ? true : false;
 type GenerateRouteResult<T> = true extends IsAny<T> ? unknown : T extends string ? string : unknown;
 /** ---------------------------------
- * * ***Utility for NextJS: `generateRoute`.***
- * ---------------------------------
- * **Generates a URL by replacing dynamic route parameters with provided values.**
- * - ***⚠️ Warning:***
- *    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
- * @template T - The route string containing dynamic segments in the format `[param]`.
- * @param {T} route - The route string containing dynamic segments.
- * @param {ExtractRouteParams<T>} [params] - An object containing key-value pairs that match the dynamic segments in the route.
- * @returns {string} The formatted URL with all dynamic segments replaced.
- * @throws **{@link Error | `Error`}** if the route contains dynamic segments but no parameters object is provided.
- * @throws **{@link Error | `Error`}** if a required parameter is missing from the `params` object.
- * @throws **{@link Error | `Error`}** if a parameter value is an empty string.
- * @throws **{@link Error | `Error`}** if any parameter contains invalid characters like `?`, `&`, `=`, `#`, `/`, spaces, `'`, `"`, `(`, `)`, `+`, `;`, `%`, `@`, or `:`, which can cause URL issues.
- * @example
- * // Basic usage
- * generateRoute("/user/[id]", { id: "123" });
- * // ➔ "/user/123"
- *
- * // No dynamic segments, returns as-is
- * generateRoute("/dashboard");
- * // ➔ "/dashboard"
- *
- * // Throws an error due to missing parameters object
- * generateRoute("/profile/[username]");
- * // ➔ ❌ Error: ❌ Missing parameters object for route: "/profile/[username]"
- *
- * // Throws an error due to an empty parameter value
- * generateRoute("/post/[category]/[slug]", { category: "tech", slug: "" });
- * // ➔ ❌ Error: ❌ Parameter "slug" cannot be empty in route: "/post/[category]/[slug]"
- *
- * // Throws an error due to parameter containing invalid characters
- * generateRoute("/search/[query]", { query: "how to?learn" });
- * // ➔ ❌ Error: ❌ Parameter "query" contains invalid character "?" in route: "/search/[query]"
- *
- * // Handles leading/trailing slashes correctly
- * generateRoute("/blog/[category]/[slug]", { category: "/news/", slug: "/latest-update/" });
- * // ➔ ❌ Error: ❌ Parameter "category" and "slug" contains slashes "/" which is not allowed.
- */
+* * ***Utility for NextJS: `generateRoute`.***
+* ---------------------------------
+* **Generates a URL by replacing dynamic route parameters with provided values.**
+* - ***⚠️ Warning:***
+*    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
+* @template T - The route string containing dynamic segments in the format `[param]`.
+* @param {T} route - The route string containing dynamic segments.
+* @param {ExtractRouteParams<T>} [params] - An object containing key-value pairs that match the dynamic segments in the route.
+* @returns {string} The formatted URL with all dynamic segments replaced.
+* @throws **{@link Error | `Error`}** if the route contains dynamic segments but no parameters object is provided.
+* @throws **{@link Error | `Error`}** if a required parameter is missing from the `params` object.
+* @throws **{@link Error | `Error`}** if a parameter value is an empty string.
+* @throws **{@link Error | `Error`}** if any parameter contains invalid characters like `?`, `&`, `=`, `#`, `/`, spaces, `'`, `"`, `(`, `)`, `+`, `;`, `%`, `@`, or `:`, which can cause URL issues.
+* @example
+* // Basic usage
+* generateRoute("/user/[id]", { id: "123" });
+* // ➔ "/user/123"
+*
+* // No dynamic segments, returns as-is
+* generateRoute("/dashboard");
+* // ➔ "/dashboard"
+*
+* // Throws an error due to missing parameters object
+* generateRoute("/profile/[username]");
+* // ➔ ❌ Error: ❌ Missing parameters object for route: "/profile/[username]"
+*
+* // Throws an error due to an empty parameter value
+* generateRoute("/post/[category]/[slug]", { category: "tech", slug: "" });
+* // ➔ ❌ Error: ❌ Parameter "slug" cannot be empty in route: "/post/[category]/[slug]"
+*
+* // Throws an error due to parameter containing invalid characters
+* generateRoute("/search/[query]", { query: "how to?learn" });
+* // ➔ ❌ Error: ❌ Parameter "query" contains invalid character "?" in route: "/search/[query]"
+*
+* // Handles leading/trailing slashes correctly
+* generateRoute("/blog/[category]/[slug]", { category: "/news/", slug: "/latest-update/" });
+* // ➔ ❌ Error: ❌ Parameter "category" and "slug" contains slashes "/" which is not allowed.
+*/
 declare function generateRoute<T extends string>(route: T extends string ? HasDynamicSegments<T> extends true ? T : never : never, params: T extends string ? ExtractRouteParams<T> : undefined): GenerateRouteResult<T>;
 declare function generateRoute<T extends string>(route: T extends string ? T : never, params?: Extract<ExtractRouteParams<T>, Record<string, unknown>>): GenerateRouteResult<T>;
 declare function generateRoute<T = unknown>(route: T extends string ? HasDynamicSegments<T> extends true ? T : unknown : unknown, params?: T extends string ? ExtractRouteParams<T> : undefined): unknown;
 type OptionsCreateBeApiUrl = {
   /** * The prefix pathname api url, e.g:`"http://localhost.com/your-target-prefix-entri-point-api-is-here"`, default: `"/api"`.
-   *
-   * @default "/api" */
+  *
+  * @default "/api" */
   prefix?: string;
   /** * Option to getting `prefix` and `pathname` of api url only `(removing origin base api url)`, default: `true`.
-   *
-   * @default true */
+  *
+  * @default true */
   withOrigin?: boolean;
 };
 /** ---------------------------------
- * * ***Utility for NextJS: `createBeApiUrl`.***
- * ---------------------------------
- * **Constructs a backend API URL by appending a given pathname to the base API URL.**
- * - **ℹ️ Note:**
- *    - This function builds on top of `getBeApiUrl()`.
- * - **Determines the base API URL from:**
- *    - `NEXT_PUBLIC_BACKEND_API_URL` environment variable (or defaults to `"http://localhost:8000"`).
- *    - Automatically appends `NEXT_PUBLIC_PORT_BE` if the base URL does not already include a port.
- * - **Features of this function:**
- *    - Allows customizing the API path with an optional `prefix` (defaults to `"/api"`).
- *    - Can include or exclude the origin (protocol + host) via `withOrigin`.
- *    - Normalizes paths to avoid duplicate slashes.
- * - ***⚠️ Warning:***
- *    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
- * @param {string|null|undefined} pathname - The API endpoint path (e.g., `/users` or `/v1/posts`), defaultValue: `""`.
- * @param {OptionsCreateBeApiUrl} [options] - Configuration options.
- * @param {OptionsCreateBeApiUrl["prefix"]} [options.prefix="/api"] - The prefix for the API path (default is `"/api"`).
- * @param {OptionsCreateBeApiUrl["withOrigin"]} [options.withOrigin=true] - Whether to include the full base URL or return only the API path.
- * @returns {string} The formatted API URL.
- * @throws **{@link TypeError | `TypeError`}** if `withOrigin` is not a boolean.
- * @throws **{@link TypeError | `TypeError`}** if `prefix` and `pathname` is not a string.
- * @throws **{@link Error | `Error`}** if constructing the API URL fails due to an invalid base URL.
- * @example
- * createBeApiUrl("/users")
- * // ➔ "http://localhost:8000/api/users"
- * createBeApiUrl("/api/users")
- * // ➔ "http://localhost:8000/api/users"
- * createBeApiUrl("/v1", { prefix: "/v1" })
- * // ➔ "http://localhost:8000/v1"
- * createBeApiUrl("/v1/users")
- * // ➔ "http://localhost:8000/api/v1/users"
- * createBeApiUrl("/v1/users", { prefix: "/v1" })
- * // ➔ "http://localhost:8000/v1/users"
- * createBeApiUrl("/users", { withOrigin: false })
- * // ➔ "/api/users"
- * createBeApiUrl(null, { withOrigin: false })
- * // ➔ "/api"
- * createBeApiUrl(undefined, { withOrigin: false })
- * // ➔ "/api"
- */
-declare const createBeApiUrl: (
-/** * The pathname api url, e.g:`"http://localhost.com/your-target-prefix-entri-point-api-is-here/your-target-pathname-is-here"`.
- *
- * @default ""
- */
-
-pathname: string | null | undefined, options?: OptionsCreateBeApiUrl) => string;
+* * ***Utility for NextJS: `createBeApiUrl`.***
+* ---------------------------------
+* **Constructs a backend API URL by appending a given pathname to the base API URL.**
+* - **ℹ️ Note:**
+*    - This function builds on top of `getBeApiUrl()`.
+* - **Determines the base API URL from:**
+*    - `NEXT_PUBLIC_BACKEND_API_URL` environment variable (or defaults to `"http://localhost:8000"`).
+*    - Automatically appends `NEXT_PUBLIC_PORT_BE` if the base URL does not already include a port.
+* - **Features of this function:**
+*    - Allows customizing the API path with an optional `prefix` (defaults to `"/api"`).
+*    - Can include or exclude the origin (protocol + host) via `withOrigin`.
+*    - Normalizes paths to avoid duplicate slashes.
+* - ***⚠️ Warning:***
+*    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
+* @param {string|null|undefined} pathname - The API endpoint path (e.g., `/users` or `/v1/posts`), defaultValue: `""`.
+* @param {OptionsCreateBeApiUrl} [options] - Configuration options.
+* @param {OptionsCreateBeApiUrl["prefix"]} [options.prefix="/api"] - The prefix for the API path (default is `"/api"`).
+* @param {OptionsCreateBeApiUrl["withOrigin"]} [options.withOrigin=true] - Whether to include the full base URL or return only the API path.
+* @returns {string} The formatted API URL.
+* @throws **{@link TypeError | `TypeError`}** if `withOrigin` is not a boolean.
+* @throws **{@link TypeError | `TypeError`}** if `prefix` and `pathname` is not a string.
+* @throws **{@link Error | `Error`}** if constructing the API URL fails due to an invalid base URL.
+* @example
+* createBeApiUrl("/users")
+* // ➔ "http://localhost:8000/api/users"
+* createBeApiUrl("/api/users")
+* // ➔ "http://localhost:8000/api/users"
+* createBeApiUrl("/v1", { prefix: "/v1" })
+* // ➔ "http://localhost:8000/v1"
+* createBeApiUrl("/v1/users")
+* // ➔ "http://localhost:8000/api/v1/users"
+* createBeApiUrl("/v1/users", { prefix: "/v1" })
+* // ➔ "http://localhost:8000/v1/users"
+* createBeApiUrl("/users", { withOrigin: false })
+* // ➔ "/api/users"
+* createBeApiUrl(null, { withOrigin: false })
+* // ➔ "/api"
+* createBeApiUrl(undefined, { withOrigin: false })
+* // ➔ "/api"
+*/
+declare const createBeApiUrl: (pathname: string | null | undefined, options?: OptionsCreateBeApiUrl) => string;
 type OptionsGetBeApiUrl = {
   /** * ***The Suffix origin base api url, e.g:`http://localhost.com/api`, default: `"/"`.***
-   *
-   * @default "/" */
+  *
+  * @default "/" */
   suffix?: string;
 };
 /** ---------------------------------------------------
- * * ***Utility for NextJS: `getBeApiUrl`.***
- * ---------------------------------------------------
- * **This function determines the backend API base URL from the `NEXT_PUBLIC_BACKEND_API_URL` environment variable (retrieves the base API URL of the backend).**
- * - **Behavior:**
- *    - If the variable is not set, it defaults to `"http://localhost:8000"`.
- *    - It also allows adding an optional suffix to the returned URL.
- * - ***⚠️ Warning:***
- *    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
- * @description
- * This function determines the backend API base URL from the `NEXT_PUBLIC_BACKEND_API_URL` environment variable.
- * - If `NEXT_PUBLIC_BACKEND_API_URL` is not set, it defaults to `"http://localhost:8000"`.
- * - If `NEXT_PUBLIC_BACKEND_API_URL` does **not** contain a port, it appends one from `NEXT_PUBLIC_PORT_BE` if available.
- * - Supports appending optional suffix (like `"/api"`).
- * @param {OptionsGetBeApiUrl|undefined} options - Configuration options.
- * @param {OptionsGetBeApiUrl["suffix"]} [options.suffix="/"] - The suffix to append to the base API URL.
- * @returns {string} The formatted backend API base URL.
- * @throws **{@link TypeError | `TypeError`}** if `suffix` is not a `string`.
- * @throws **{@link Error | `Error`}** if `NEXT_PUBLIC_BACKEND_API_URL` is invalid.
- * @example
- * // With NEXT_PUBLIC_BACKEND_API_URL set at `*.env` file
- * NEXT_PUBLIC_BACKEND_API_URL = "https://api.example.com";
- * getBeApiUrl();
- * // ➔ "https://api.example.com/"
- *
- * // With NEXT_PUBLIC_BACKEND_API_URL but no port, using NEXT_PUBLIC_PORT_BE at `*.env` file
- * NEXT_PUBLIC_BACKEND_API_URL = "http://localhost";
- * NEXT_PUBLIC_PORT_BE = "5000";
- * getBeApiUrl({ suffix: "/api" });
- * // ➔ "http://localhost:5000/api"
- *
- * // Without NEXT_PUBLIC_BACKEND_API_URL at `*.env` file (defaults to localhost:8000)
- * delete NEXT_PUBLIC_BACKEND_API_URL;
- * getBeApiUrl({ suffix: "/v1" });
- * // ➔ "http://localhost:8000/v1"
- */
+* * ***Utility for NextJS: `getBeApiUrl`.***
+* ---------------------------------------------------
+* **This function determines the backend API base URL from the `NEXT_PUBLIC_BACKEND_API_URL` environment variable (retrieves the base API URL of the backend).**
+* - **Behavior:**
+*    - If the variable is not set, it defaults to `"http://localhost:8000"`.
+*    - It also allows adding an optional suffix to the returned URL.
+* - ***⚠️ Warning:***
+*    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
+* @description
+* This function determines the backend API base URL from the `NEXT_PUBLIC_BACKEND_API_URL` environment variable.
+* - If `NEXT_PUBLIC_BACKEND_API_URL` is not set, it defaults to `"http://localhost:8000"`.
+* - If `NEXT_PUBLIC_BACKEND_API_URL` does **not** contain a port, it appends one from `NEXT_PUBLIC_PORT_BE` if available.
+* - Supports appending optional suffix (like `"/api"`).
+* @param {OptionsGetBeApiUrl|undefined} options - Configuration options.
+* @param {OptionsGetBeApiUrl["suffix"]} [options.suffix="/"] - The suffix to append to the base API URL.
+* @returns {string} The formatted backend API base URL.
+* @throws **{@link TypeError | `TypeError`}** if `suffix` is not a `string`.
+* @throws **{@link Error | `Error`}** if `NEXT_PUBLIC_BACKEND_API_URL` is invalid.
+* @example
+* // With NEXT_PUBLIC_BACKEND_API_URL set at `*.env` file
+* NEXT_PUBLIC_BACKEND_API_URL = "https://api.example.com";
+* getBeApiUrl();
+* // ➔ "https://api.example.com/"
+*
+* // With NEXT_PUBLIC_BACKEND_API_URL but no port, using NEXT_PUBLIC_PORT_BE at `*.env` file
+* NEXT_PUBLIC_BACKEND_API_URL = "http://localhost";
+* NEXT_PUBLIC_PORT_BE = "5000";
+* getBeApiUrl({ suffix: "/api" });
+* // ➔ "http://localhost:5000/api"
+*
+* // Without NEXT_PUBLIC_BACKEND_API_URL at `*.env` file (defaults to localhost:8000)
+* delete NEXT_PUBLIC_BACKEND_API_URL;
+* getBeApiUrl({ suffix: "/v1" });
+* // ➔ "http://localhost:8000/v1"
+*/
 declare const getBeApiUrl: (options?: OptionsGetBeApiUrl) => string;
 /** ---------------------------------------------------
- * * ***Utility for NextJS: `getBaseUrl`.***
- * ---------------------------------------------------
- * **Retrieves the base URL of the application.**
- * - **Behavior:**
- *    - It determines the base URL from the `NEXT_PUBLIC_BASE_URL` environment variable.
- *    - If `NEXT_PUBLIC_BASE_URL` is not set, it defaults to `"http://localhost:3000"`.
- *    - If `NEXT_PUBLIC_BASE_URL` does **not** contain a port, it appends one from `NEXT_PUBLIC_PORT_FE` if available.
- *    - Ensures the final URL is valid and normalized (no trailing slashes).
- * - ***⚠️ Warning:***
- *    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
- * @returns {string} The resolved base URL of the application.
- * @throws **{@link Error | `Error`}** if the constructed URL is invalid or malformed.
- * @example
- * // With environment variable set at `*.env` file
- * NEXT_PUBLIC_BASE_URL = "https://example.com";
- * getBaseUrl();
- * // ➔ "https://example.com"
- *
- * // With custom port via NEXT_PUBLIC_PORT_FE at `*.env` file
- * NEXT_PUBLIC_BASE_URL = "http://localhost";
- * NEXT_PUBLIC_PORT_FE = "4000";
- * getBaseUrl();
- * // ➔ "http://localhost:4000"
- *
- * // Without environment variable at `*.env` file
- * delete NEXT_PUBLIC_BASE_URL;
- * getBaseUrl();
- * // ➔ "http://localhost:3000"
- */
+* * ***Utility for NextJS: `getBaseUrl`.***
+* ---------------------------------------------------
+* **Retrieves the base URL of the application.**
+* - **Behavior:**
+*    - It determines the base URL from the `NEXT_PUBLIC_BASE_URL` environment variable.
+*    - If `NEXT_PUBLIC_BASE_URL` is not set, it defaults to `"http://localhost:3000"`.
+*    - If `NEXT_PUBLIC_BASE_URL` does **not** contain a port, it appends one from `NEXT_PUBLIC_PORT_FE` if available.
+*    - Ensures the final URL is valid and normalized (no trailing slashes).
+* - ***⚠️ Warning:***
+*    - ***This function only support when using ***[`NextJS`](https://nextjs.org/)***.***
+* @returns {string} The resolved base URL of the application.
+* @throws **{@link Error | `Error`}** if the constructed URL is invalid or malformed.
+* @example
+* // With environment variable set at `*.env` file
+* NEXT_PUBLIC_BASE_URL = "https://example.com";
+* getBaseUrl();
+* // ➔ "https://example.com"
+*
+* // With custom port via NEXT_PUBLIC_PORT_FE at `*.env` file
+* NEXT_PUBLIC_BASE_URL = "http://localhost";
+* NEXT_PUBLIC_PORT_FE = "4000";
+* getBaseUrl();
+* // ➔ "http://localhost:4000"
+*
+* // Without environment variable at `*.env` file
+* delete NEXT_PUBLIC_BASE_URL;
+* getBaseUrl();
+* // ➔ "http://localhost:3000"
+*/
 declare const getBaseUrl: () => string;
 export { ExtractRouteParams, HasDynamicSegments, createBeApiUrl, generateRoute, getBaseUrl, getBeApiUrl };