@rzl-zone/utils-js 3.13.1 → 3.14.0

package/dist/operations/index.d.cts

@@ -2,28 +2,222 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1`
+*  Version: `3.14.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
 */
 
-import { NumberRangeUnion } from "@rzl-zone/ts-types-plus";
+import { D as NumberRangeUnion } from "../index-or0oP9i2.cjs";
+type CopyMethod = "clipboard" | "fallback" | "manual";
+type CopyStatus = "success" | "error";
+type CopyResult = {
+  /** ---------------------------------------------------------
+  * * ***Final operation status.***
+  * ----------------------------------------------------------
+  *
+  * ---
+  * Usually `"success"` when copy succeeds, otherwise `"error"`.
+  */
+  status: CopyStatus;
+  /** ---------------------------------------------------------
+  * * ***Indicates whether the operation succeeded.***
+  * ----------------------------------------------------------
+  *
+  * Usually `true` on successful copy operations.
+  */
+  success: boolean;
+  /** ---------------------------------------------------------
+  * * ***Copy mechanism that was used.***
+  * ----------------------------------------------------------
+  *
+  * - **Possible values:**
+  *     - `"clipboard"`.
+  *     - `"fallback"`.
+  *     - `"manual"`.
+  */
+  method: CopyMethod;
+  /**
+  * * ***Optional error object captured during execution.***
+  */
+  error?: unknown;
+  /** ---------------------------------------------------------
+  * * ***Optional failure or fallback reason.***
+  * ----------------------------------------------------------
+  *
+  * - **Possible values:**
+  *     - `"no-browser"`.
+  *     - `"no-clipboard"`.
+  *     - `"clipboard-error"`.
+  *     - `"timeout"`.
+  *     - `"fallback-failed"`.
+  */
+  reason?: "no-browser" | "no-clipboard" | "clipboard-error" | "timeout" | "fallback-failed";
+  /**
+  * * ***Total number of attempts performed.***
+  */
+  attempts: number;
+  /**
+  * * ***Total execution duration in milliseconds.***
+  */
+  duration: number;
+  /**
+  * * ***Unix timestamp of execution completion.***
+  */
+  timestamp: number;
+};
+/** ----------------------------------------------------------------------
+* * ***Type: `CopyOptions`.***
+* -----------------------------------------------------------------------
+* **Configuration options for the `copyText` utility.**
+*
+* ---
+* - **Behavior:**
+*     - Controls retry attempts and timeout handling.
+*     - Enables optional debug logging.
+*     - All properties are optional.
+*/
+type CopyOptions = {
+  /** -----------------------------------------------------------------------
+  * * ***Enables internal debug logging.***
+  * ------------------------------------------------------------------------
+  *
+  * @default false
+  */
+  debug?: boolean;
+  /** -----------------------------------------------------------------------
+  * * ***Number of retry attempts before fallback.***
+  * ------------------------------------------------------------------------
+  *
+  * @default 1
+  */
+  retries?: number;
+  /** -----------------------------------------------------------------------
+  * * ***Timeout duration (in milliseconds) for each Clipboard API attempt.***
+  * ------------------------------------------------------------------------
+  *
+  * @default 2000
+  */
+  timeout?: number;
+};
+/** ----------------------------------------------------------------------
+* * ***Utility: `copyText`.***
+* -----------------------------------------------------------------------
+* **Copies text to the user's clipboard with robust fallback handling.**
+*
+* ---
+* - **Behavior:**
+*     - Attempts to use the modern
+*       ***`navigator.clipboard.writeText`*** Clipboard API.
+*     - Automatically retries clipboard operations when configured.
+*     - Falls back to legacy
+*       ***`document.execCommand("copy")`***
+*       if the Clipboard API is unavailable or fails.
+*     - As a last resort, programmatically selects the text
+*       to allow manual copying by the user.
+*     - Detects non-browser environments and safely exits
+*       without accessing browser-only APIs.
+*     - Returns detailed operation metadata including method,
+*       duration, attempts, and failure reason.
+*     - Does **not throw** on copy failure;
+*       instead returns a structured
+*       ***{@link CopyResult | `CopyResult`}*** object.
+*
+* ---
+* @param {string} text
+* The text content to copy to the clipboard.
+*
+* @param {CopyOptions} [options={}]
+* Optional configuration object.
+*
+* @param {boolean} [options.debug=false]
+* Enables internal debug logging.
+*
+* @param {number} [options.retries=1]
+* Number of additional retry attempts
+* after the initial Clipboard API attempt.
+*
+* @param {number} [options.timeout=2000]
+* Timeout duration (in milliseconds)
+* for each Clipboard API attempt.
+*
+* ---
+* @returns {Promise<CopyResult>}
+* A promise resolving to a
+* ***{@link CopyResult | `CopyResult`}*** object containing:
+*  - `status` ➔ `"success"` or `"error"`.
+*  - `success` ➔ Indicates whether the operation succeeded.
+*  - `method` ➔ Copy mechanism used
+*    (`"clipboard"`, `"fallback"`, or `"manual"`).
+*  - `reason` ➔ Optional failure or fallback reason.
+*  - `error` ➔ Optional thrown error object.
+*  - `attempts` ➔ Total number of attempts performed.
+*  - `duration` ➔ Execution duration in milliseconds.
+*  - `timestamp` ➔ Unix timestamp of execution.
+*
+* ---
+* @remarks
+* - The Clipboard API requires a secure context
+*   (`HTTPS` or `localhost`).
+* - Some browsers or mobile environments may restrict
+*   clipboard access without direct user interaction.
+* - Clipboard operations may fail due to browser permission
+*   policies or missing user interaction.
+* - Manual selection mode is only triggered when all
+*   programmatic copy strategies fail.
+* - In server-side environments,
+*   the utility returns `"no-browser"`
+*   without attempting DOM access.
+*
+* ---
+* @example
+* ```ts
+* const result = await copyText("Hello world");
+*
+* if (result.success) {
+*   console.log(`Copied using ${result.method}`);
+* } else {
+*   console.error(result.reason);
+* }
+* ```
+*
+* ---
+* @example
+* ```ts
+* await copyText("Debug mode", {
+*   debug: true,
+*   retries: 2
+* });
+* ```
+*/
+declare function copyText(text: string, options?: CopyOptions): Promise<CopyResult>;
 /** ----------------------------------------------------------------------
 * * ***Utility: `findDuplicates`.***
-* ----------------------------------------------------------------------
+* -----------------------------------------------------------------------
 * **Finds duplicate values in an array by deep equality comparison.**
+*
+* ---
 * - **Behavior:**
-*    - Uses ***`isEqual` utility function*** to compare elements
-*      (handles objects, arrays, dates, NaN, etc.).
-*    - Returns a new array containing only the *first occurrences* of duplicated values.
-*    - Does **not mutate** the original array.
-*    - Throws ***{@link TypeError | `TypeError`}*** if input is not an array.
+*     - Uses ***`isEqual` utility function*** to compare elements
+*       (handles objects, arrays, dates, NaN, etc.).
+*     - Returns a new array containing only the *first occurrences* of duplicated values.
+*     - Does **not mutate** the original array.
+*     - Throws ***{@link TypeError | `TypeError`}*** if input is not an array.
+*
+* ---
 * @template T Type of elements in the input array.
+*
+* ---
 * @param {T[]} values - The array to check for duplicates.
+*
+* ---
+* @throws **{@link TypeError | `TypeError`}** if the provided `values` argument is not an array.
+*
+* ---
 * @returns {T[]} An array of the duplicate values found in the input,
 *                preserving order of their first duplicate appearance.
-* @throws **{@link TypeError | `TypeError`}** if the provided `values` argument is not an array.
+*
+* ---
 * @example
 * findDuplicates([1, 2, 2, 3, 4, 4]);
 * // ➔ [2, 4]
@@ -39,62 +233,90 @@ import { NumberRangeUnion } from "@rzl-zone/ts-types-plus";
 * // ➔ []
 */
 declare const findDuplicates: <T>(values: T[]) => T[];
-/** --------------------------------
+/** -------------------------------------------------------------------------------
 * * ***Utility: `omitKeys`.***
-* --------------------------------
+* --------------------------------------------------------------------------------
 * **This function creates a shallow copy of the given object omitting the
 *  specified keys.**
+*
+* ---
 * - **Behavior:**
-*    - It will return a new object without mutating the original.
-*    - It also validates that ***`keysToOmit`*** does not contain duplicate keys.
-* - **ℹ️ Internally:**
-*    - It uses ***`isEqual`*** to check for duplicates in
-*      the ***`keysToOmit`*** array.
+*     - It will return a new object without mutating the original.
+*     - It also validates that ***`keysToOmit`*** does not contain duplicate keys.
+*
+* ---
+* - **Internally:**
+*     - It uses ***`isEqual`*** to check for duplicates in
+*       the ***`keysToOmit`*** array.
+*
+* ---
 * @template I The type of the input object.
 * @template K The keys to omit from the object.
+*
+* ---
 * @param {I} object - The source object to omit keys from.
 * @param {K[]} keysToOmit - An array of keys to exclude from the returned object.
-* @returns {Omit<I, K>} A new object without the specified keys.
+*
+* ---
 * @throws **{@link TypeError | `TypeError`}** if `keysToOmit` is not an array.
 * @throws **{@link Error | `Error`}** if duplicate keys are found in `keysToOmit`.
+*
+* ---
+* @returns {Omit<I, K>} A new object without the specified keys.
+*
+* ---
 * @example
 * omitKeys({ a: 1, b: 2, c: 3 }, ["b", "c"]);
-* //➔ { a: 1 }
+* // ➔ { a: 1 }
 * omitKeys({ name: "John", age: 30 }, ["age"]);
-* //➔ { name: "John" }
+* // ➔ { name: "John" }
 * omitKeys({ a: 1, b: 2 }, []);
-* //➔ { a: 1, b: 2 } (no changes)
+* // ➔ { a: 1, b: 2 } (no changes)
 */
 declare const omitKeys: <I extends Record<string, unknown>, K extends keyof I>(object: I, keysToOmit: K[]) => Omit<I, K>;
 type IndexArray = NumberRangeUnion<0, 30>;
 type DotPath<T, Prev extends string = ""> = T extends Array<infer U> ? DotPath<U, `${Prev}${Prev extends "" ? "" : "."}${IndexArray}`> : T extends object ? { [K in keyof T & string]: `${Prev}${Prev extends "" ? "" : "."}${K}` | DotPath<T[K], `${Prev}${Prev extends "" ? "" : "."}${K}`> }[keyof T & string] : never;
 /** ------------------------------------------------------
 * * ***Utility: `omitKeysDeep`.***
-* ------------------------------------------------------
+* -------------------------------------------------------
 * **Recursively omits properties from an object using dot notation paths.**
+*
+* ---
 * - **Behavior:**
-*    - Removes resulting empty objects (`{}`) and arrays (`[]`), cascading upwards
-*      to remove empty parents until root if needed.
-* - **⚠️ Be careful:**
-*    - If after omission an object or array becomes empty, it will be removed entirely
-*      including all the way up to the root if necessary, resulting in `{}`.
-* - **ℹ️ Note:**
-*    - For array indices, TypeScript autocomplete only suggests `0`–`30`
-*      (to prevent editor lag on large unions).
-*      However, higher indices are still fully supported at runtime — you can
-*      manually type `"arr.99.key"` and it will work the same.
-* @template I - Type of the input object
+*     - Removes resulting empty objects (`{}`) and arrays (`[]`), cascading upwards
+*       to remove empty parents until root if needed.
+* ---
+* - **Be careful:**
+*     - If after omission an object or array becomes empty, it will be removed entirely
+*       including all the way up to the root if necessary, resulting in `{}`.
+* ---
+* - **Note:**
+*     - For array indices, TypeScript autocomplete only suggests `0`–`30`
+*       (to prevent editor lag on large unions).
+*       However, higher indices are still fully supported at runtime — you can
+*       manually type `"arr.99.key"` and it will work the same.
+*
+* ---
+* @template I - Type of the input object.
+*
+* ---
 * @param {I} object
 *  The object to process, should be a plain nested object or array structure.
 * @param {DotPath<I>[]} keysToOmit
 *  An array of string paths in dot notation indicating the properties to remove, paths
 *  can include numeric indices to target array elements, e.g. `"arr.0.x"` to
 *  remove `x` from the first object inside the `arr` array.
+*
+* ---
+* @throws **{@link TypeError | `TypeError`}** if `keysToOmit` is not an array.
+* @throws **{@link Error | `Error`}** if `keysToOmit` contains duplicate paths.
+*
+* ---
 * @returns {Partial<I>}
 *  A new deeply cloned object with the specified keys omitted, with resulting
 *  empty objects or arrays fully removed (even if it collapses to `{}`).
-* @throws **{@link TypeError | `TypeError`}** if `keysToOmit` is not an array.
-* @throws **{@link Error | `Error`}** if `keysToOmit` contains duplicate paths.
+*
+* ---
 * @example
 * omitKeysDeep({ arr: [{ a: 1 }] }, ["arr.0.a"]);
 * // ➔ {} (array becomes empty and removed)
@@ -136,4 +358,4 @@ type DotPath<T, Prev extends string = ""> = T extends Array<infer U> ? DotPath<U
 * // ➔ { mixed: { a: [1, 2, 3] } }
 */
 declare const omitKeysDeep: <I extends Record<string, unknown>>(object: I, keysToOmit: DotPath<I>[]) => Partial<I>;
-export { findDuplicates, omitKeys, omitKeysDeep };
+export { copyText, findDuplicates, omitKeys, omitKeysDeep };