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

package/dist/next/index.d.cts

@@ -0,0 +1,226 @@
+/*!
+* ========================================================================
+*  @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`
+* ========================================================================
+*/
+
+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)
+ * ```
+ */
+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
+ * ```
+ */
+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.
+ */
+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" */
+  prefix?: string;
+  /** * Option to getting `prefix` and `pathname` of api url only `(removing origin base api url)`, 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;
+type OptionsGetBeApiUrl = {
+  /** * ***The Suffix origin base api url, e.g:`http://localhost.com/api`, 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"
+ */
+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"
+ */
+declare const getBaseUrl: () => string;
+export { ExtractRouteParams, HasDynamicSegments, createBeApiUrl, generateRoute, getBaseUrl, getBeApiUrl };

package/dist/next/index.d.ts

@@ -1,14 +1,14 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.12.0.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-import { IsAny } from '@rzl-zone/ts-types-plus';
+* ========================================================================
+*  @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`
+* ========================================================================
+*/
 
+import { IsAny } from "@rzl-zone/ts-types-plus";
 /** ---------------------------------------------------------
  * * ***Extracts dynamic route parameters from a given route string.***
  * ---------------------------------------------------------
@@ -28,9 +28,7 @@ import { IsAny } from '@rzl-zone/ts-types-plus';
  * // ➔ {} (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;
+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.***
  * ---------------------------------------------------------
@@ -90,19 +88,18 @@ type GenerateRouteResult<T> = true extends IsAny<T> ? unknown : T extends string
  * 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 ? 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;
-
+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" */
-    prefix?: string;
-    /** * Option to getting `prefix` and `pathname` of api url only `(removing origin base api url)`, default: `true`.
-     *
-     * @default true */
-    withOrigin?: boolean;
+  /** * The prefix pathname api url, e.g:`"http://localhost.com/your-target-prefix-entri-point-api-is-here"`, 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 */
+  withOrigin?: boolean;
 };
 /** ---------------------------------
  * * ***Utility for NextJS: `createBeApiUrl`.***
@@ -150,13 +147,13 @@ declare const createBeApiUrl: (
  *
  * @default ""
  */
-pathname: string | null | undefined, options?: OptionsCreateBeApiUrl) => string;
 
+pathname: string | null | undefined, options?: OptionsCreateBeApiUrl) => string;
 type OptionsGetBeApiUrl = {
-    /** * ***The Suffix origin base api url, e.g:`http://localhost.com/api`, default: `"/"`.***
-     *
-     * @default "/" */
-    suffix?: string;
+  /** * ***The Suffix origin base api url, e.g:`http://localhost.com/api`, default: `"/"`.***
+   *
+   * @default "/" */
+  suffix?: string;
 };
 /** ---------------------------------------------------
  * * ***Utility for NextJS: `getBeApiUrl`.***
@@ -195,7 +192,6 @@ type OptionsGetBeApiUrl = {
  * // ➔ "http://localhost:8000/v1"
  */
 declare const getBeApiUrl: (options?: OptionsGetBeApiUrl) => string;
-
 /** ---------------------------------------------------
  * * ***Utility for NextJS: `getBaseUrl`.***
  * ---------------------------------------------------
@@ -227,5 +223,4 @@ declare const getBeApiUrl: (options?: OptionsGetBeApiUrl) => string;
  * // ➔ "http://localhost:3000"
  */
 declare const getBaseUrl: () => string;
-
-export { type ExtractRouteParams, type HasDynamicSegments, createBeApiUrl, generateRoute, getBaseUrl, getBeApiUrl };
+export { ExtractRouteParams, HasDynamicSegments, createBeApiUrl, generateRoute, getBaseUrl, getBeApiUrl };