@rzl-zone/utils-js 3.13.1 → 3.14.0-beta.0

package/dist/promises/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["isInteger","getPreciseType","safeStableStringify","isNull"],"sources":["../../src/promises/CustomPromise.ts","../../src/promises/delay.ts"],"sourcesContent":["import type { CustomPromiseType } from \"@rzl-zone/ts-types-plus\";\n\nexport type { CustomPromiseType };\n\n/** -------------------------------------------------------------\n * * ***Utility Class: `CustomPromise`.***\n * -------------------------------------------------------------\n * **A strongly typed extension of the native {@link Promise | **`Promise`**}.**\n *  1. **Behaves exactly like a normal Promise** for `then`/`catch`\n *      and `await` semantics.\n *  2. **Stores the final resolution or rejection internally** so\n *      it can be retrieved by a custom `finish` handler.\n *  3. **Adds a `finish` method** which runs once after settlement\n *      with access to both the fulfilled value *and* the rejection\n *      reason (only one will be defined).\n * - **Key Differences from a Native `Promise`:**\n *    - Every call to `then`/`catch` returns **`CustomPromise`**\n *      again, so the `finish` method remains available on the\n *      entire chain.\n *    - `finish` provides a tuple-like callback:\n *      - `val`  → defined when fulfilled.\n *      - `err`  → defined when rejected.\n * @template Success  Type of the resolved value.\n * @template Error    Type of the rejection reason (default `unknown`).\n * @example\n * ```ts\n * import { CustomPromise, type CustomPromiseType } from \"@rzl-zone/utils-js/promises\";\n *\n * type User = { id: number; name: string };\n * type ApiError = { message: string };\n *\n * function fetchUser(): CustomPromiseType<User, ApiError> {\n *   return new CustomPromise<User, ApiError>((resolve, reject) => {\n *     setTimeout(\n *       () =>\n *         void (Math.random() > 0.5\n *           ? resolve({ id: 1, name: \"Alice\" })\n *           : reject({ message: \"Random failure\" })),\n *       500\n *     );\n *   });\n * }\n *\n * fetchUser()\n *   .then(user => {\n *      console.log(\"SUCCESS:\", user);\n *      return user;\n *    })\n *   .catch(err => {\n *      console.error(\"ERROR:\", err);\n *      throw err;\n *    })\n *   .finish((val, err) => {\n *     // Runs once after settle, regardless of outcome\n *     console.log(\"FINISH:\", { val, err });\n *   });\n * ```\n * ---\n * - **Implementation Notes:**\n *    - Uses `Object.setPrototypeOf` to preserve the prototype chain\n *      for environments targeting ES5 or when subclassing Promise.\n *    - Internal `_value` and `_error` are updated as soon as the\n *      executor resolves or rejects, guaranteeing `finish` receives\n *      the final state even when added after settlement.\n */\nexport class CustomPromise<Success, Error = unknown>\n  extends Promise<Success>\n  implements CustomPromiseType<Success, Error>\n{\n  private _value?: Success;\n  private _error?: Error;\n  private _finish: Array<(v?: Success, e?: Error) => void> = [];\n\n  constructor(\n    executor: (\n      resolve: (v: Success) => void,\n      reject: (e: Error) => void\n    ) => void\n  ) {\n    let resolveOuter!: (v: Success) => void;\n    let rejectOuter!: (e: Error) => void;\n\n    super((resolve, reject) => {\n      resolveOuter = resolve;\n      rejectOuter = reject;\n    });\n\n    executor(\n      (v) => {\n        this._value = v;\n        resolveOuter(v);\n        this._finish.forEach((f) => f(v, undefined));\n      },\n      (e) => {\n        this._error = e;\n        rejectOuter(e);\n        this._finish.forEach((f) => f(undefined, e));\n      }\n    );\n\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  override then<TResult1 = Success, TResult2 = never>(\n    onfulfilled?: ((value: Success) => TResult1 | PromiseLike<TResult1>) | null,\n    onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null\n  ): CustomPromise<TResult1 | TResult2, Error> {\n    return super.then(onfulfilled, onrejected) as unknown as CustomPromise<\n      TResult1 | TResult2,\n      Error\n    >;\n  }\n\n  override catch<TResult = never>(\n    onrejected?: ((reason: Error) => TResult | PromiseLike<TResult>) | null\n  ): CustomPromise<Success | TResult, Error> {\n    return super.catch(onrejected) as unknown as CustomPromise<\n      Success | TResult,\n      Error\n    >;\n  }\n\n  /**\n   * Registers a callback to be invoked **exactly once** when the\n   * promise settles, with access to both the resolved value and\n   * the rejection reason.\n   *\n   * If the promise is already settled when `finish` is called,\n   * the callback executes immediately on the same tick.\n   *\n   * @param cb Callback receiving the final `(value, error)`.\n   * @returns `this` for fluent chaining.\n   */\n  finish(cb: (val?: Success, err?: Error) => void): this {\n    if (this._value !== undefined || this._error !== undefined) {\n      cb(this._value, this._error);\n    } else {\n      this._finish.push(cb);\n    }\n    return this;\n  }\n}\n","import { isNull } from \"@/predicates/is/isNull\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** -------------------------------------------------------------------\n * * ***Custom `AbortError` for cross-runtime delay cancellation.***\n * -------------------------------------------------------------------\n */\nclass AbortError extends Error {\n  constructor(\n    message: string = \"The operation was aborted\",\n    name: string = \"AbortError\"\n  ) {\n    super(message);\n    this.name = name;\n  }\n}\n\n/** ------------------------------------------------------------\n * * ***Utility: `delay`.***\n * ------------------------------------------------------------\n * **Creates a Promise-based delay that resolves after a given number\n * of milliseconds, optionally supports cancellation with `AbortSignal`.**\n * - **Behavior:**\n *    - Validates `milliSeconds` is a non-zero, non-negative integer.\n *    - Validates `signal` is an `AbortSignal` instance when provided.\n *    - Cleans up event listeners and timers properly.\n * @param {number} [milliSeconds=1000]\n *  The duration of the delay in milliseconds, default is `1000`.\n * @param {AbortSignal} [signal]\n *  An optional `AbortSignal` that can cancel the delay.\n * @returns {Promise<void>}\n *  A promise that resolves after the specified delay or\n *  rejects with an `AbortError` if aborted.\n * @throws **{@link TypeError | `TypeError`}** while validates `milliSeconds` and `signal`:\n *  - If `milliSeconds` **is not a valid** an `integer-number`, `NaN`, `negative-number`, or `≤ 0`.\n *  - If `signal` **is not a valid** an`AbortSignal`.\n * @throws **{@link DOMException | `DOMException`}** if the delay is aborted using the signal, rejects with `AbortError`.\n * @example\n * // Waits for 2 seconds\n * await delay(2000);\n *\n * // Delay with AbortSignal\n * const controller = new AbortController();\n * delay(5000, controller.signal).catch(err => console.log(err.name)); // \"AbortError\"\n * controller.abort();\n */\nexport const delay = (\n  milliSeconds: number = 1000,\n  signal?: AbortSignal\n): Promise<void> => {\n  if (!isInteger(milliSeconds) || milliSeconds <= 0) {\n    throw new TypeError(\n      `First parameter (\\`milliSeconds\\`) must be of type \\`number\\` and value must be a \\`non-zero\\`, \\`non-NaN\\`, \\`non-negative\\`, and \\`integer-number\\`, but received: \\`${getPreciseType(\n        milliSeconds\n      )}\\`, with value: \\`${safeStableStringify(milliSeconds, {\n        keepUndefined: true\n      })}\\`.`\n    );\n  }\n\n  if (isNull(signal) || (signal && !(signal instanceof AbortSignal))) {\n    throw new TypeError(\n      \"Second parameter (`signal`) must be an `instance of AbortSignal` if provided.\"\n    );\n  }\n\n  return new Promise<void>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      cleanup();\n      resolve();\n    }, milliSeconds);\n\n    const cleanup = () => {\n      clearTimeout(timer);\n      if (signal) signal.removeEventListener(\"abort\", onAbort);\n    };\n\n    const onAbort = () => {\n      cleanup();\n      reject(\n        new AbortError(\n          \"Function `delay` from `@rzl-zone/utils-js` was aborted.\",\n          \"AbortError\"\n        )\n      );\n    };\n\n    if (signal) {\n      if (signal.aborted) {\n        onAbort();\n      } else {\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n      }\n    }\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,IAAa,gBAAb,cACU,QAEV;CACE,AAAQ;CACR,AAAQ;CACR,AAAQ,UAAmD,CAAC;CAE5D,YACE,UAIA;EACA,IAAI;EACJ,IAAI;EAEJ,OAAO,SAAS,WAAW;GACzB,eAAe;GACf,cAAc;EAChB,CAAC;EAED,UACG,MAAM;GACL,KAAK,SAAS;GACd,aAAa,CAAC;GACd,KAAK,QAAQ,SAAS,MAAM,EAAE,GAAG,MAAS,CAAC;EAC7C,IACC,MAAM;GACL,KAAK,SAAS;GACd,YAAY,CAAC;GACb,KAAK,QAAQ,SAAS,MAAM,EAAE,QAAW,CAAC,CAAC;EAC7C,CACF;EAEA,OAAO,eAAe,MAAM,IAAI,OAAO,SAAS;CAClD;CAEA,AAAS,KACP,aACA,YAC2C;EAC3C,OAAO,MAAM,KAAK,aAAa,UAAU;CAI3C;CAEA,AAAS,MACP,YACyC;EACzC,OAAO,MAAM,MAAM,UAAU;CAI/B;;;;;;;;;;;;CAaA,OAAO,IAAgD;EACrD,IAAI,KAAK,WAAW,UAAa,KAAK,WAAW,QAC/C,GAAG,KAAK,QAAQ,KAAK,MAAM;OAE3B,KAAK,QAAQ,KAAK,EAAE;EAEtB,OAAO;CACT;AACF;;;;;;;;ACpIA,IAAM,aAAN,cAAyB,MAAM;CAC7B,YACE,UAAkB,6BAClB,OAAe,cACf;EACA,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,SACX,eAAuB,KACvB,WACkB;CAClB,IAAI,CAACA,4BAAU,YAAY,KAAK,gBAAgB,GAC9C,MAAM,IAAI,UACR,0KAA0KC,uCACxK,YACF,EAAE,oBAAoBC,gDAAoB,cAAc,EACtD,eAAe,KACjB,CAAC,EAAE,IACL;CAGF,IAAIC,+BAAO,MAAM,KAAM,UAAU,EAAE,kBAAkB,cACnD,MAAM,IAAI,UACR,+EACF;CAGF,OAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,MAAM,QAAQ,iBAAiB;GAC7B,QAAQ;GACR,QAAQ;EACV,GAAG,YAAY;EAEf,MAAM,gBAAgB;GACpB,aAAa,KAAK;GAClB,IAAI,QAAQ,OAAO,oBAAoB,SAAS,OAAO;EACzD;EAEA,MAAM,gBAAgB;GACpB,QAAQ;GACR,OACE,IAAI,WACF,2DACA,YACF,CACF;EACF;EAEA,IAAI,QACF,IAAI,OAAO,SACT,QAAQ;OAER,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAG9D,CAAC;AACH"}
+{"version":3,"file":"index.cjs","names":["isInteger","getPreciseType","safeStableStringify","isNull","AbortError","createMessage"],"sources":["../../src/promises/CustomPromise.ts","../../src/promises/delay.ts"],"sourcesContent":["import type { CustomPromiseType } from \"@rzl-zone/ts-types-plus\";\n\nexport type { CustomPromiseType };\n\n/** -------------------------------------------------------------\n * * ***Utility Class: `CustomPromise`.***\n * --------------------------------------------------------------\n * **A strongly typed extension of the native {@link Promise | **`Promise`**}.**\n *\n * ---\n *  1. **Behaves exactly like a normal Promise** for `then`/`catch`\n *      and `await` semantics.\n *  2. **Stores the final resolution or rejection internally** so\n *      it can be retrieved by a custom `finish` handler.\n *  3. **Adds a `finish` method** which runs once after settlement\n *      with access to both the fulfilled value *and* the rejection\n *      reason (only one will be defined).\n *\n * ---\n * - **Key Differences from a Native `Promise`:**\n *     - Every call to `then`/`catch` returns **`CustomPromise`**\n *       again, so the `finish` method remains available on the\n *       entire chain.\n *     - `finish` provides a tuple-like callback:\n *        - `val`  ➔ defined when fulfilled.\n *        - `err`  ➔ defined when rejected.\n *\n * ---\n * @template Success  Type of the resolved value.\n * @template Error    Type of the rejection reason (default `unknown`).\n *\n * ---\n * @example\n *  ```ts\n *  import { CustomPromise, type CustomPromiseType } from \"@rzl-zone/utils-js/promises\";\n *\n *  type User = { id: number; name: string };\n *  type ApiError = { message: string };\n *\n *  function fetchUser(): CustomPromiseType<User, ApiError> {\n *    return new CustomPromise<User, ApiError>((resolve, reject) => {\n *      setTimeout(\n *        () =>\n *          void (Math.random() > 0.5\n *            ? resolve({ id: 1, name: \"Alice\" })\n *            : reject({ message: \"Random failure\" })),\n *        500\n *      );\n *    });\n *  }\n *\n *  fetchUser()\n *    .then(user => {\n *       console.log(\"SUCCESS:\", user);\n *       return user;\n *     })\n *    .catch(err => {\n *       console.error(\"ERROR:\", err);\n *       throw err;\n *     })\n *    .finish((val, err) => {\n *      // Runs once after settle, regardless of outcome\n *      console.log(\"FINISH:\", { val, err });\n *    });\n *  ```\n * ---\n * - **Implementation Notes:**\n *     - Uses `Object.setPrototypeOf` to preserve the prototype chain\n *       for environments targeting ES5 or when subclassing Promise.\n *     - Internal settlement state is tracked automatically,\n *       allowing `finish` to access the final result even\n *       when registered after settlement.\n */\nexport class CustomPromise<Success, Failure = unknown>\n  extends Promise<Success>\n  implements CustomPromiseType<Success, Failure>\n{\n  /** ------------------------------------------------------------\n   *\n   * @internal\n   * Stores the resolved value after promise settlement.\n   *\n   * -------------------------------------------------------------\n   */\n  private _value?: Success;\n  /** ------------------------------------------------------------\n   *\n   * @internal\n   * Stores the rejection reason after promise settlement.\n   *\n   * -------------------------------------------------------------\n   */\n  private _error?: Failure;\n  /** ------------------------------------------------------------\n   *\n   * @internal\n   * Stores registered `finish` callbacks until the\n   * promise settles.\n   *\n   * -------------------------------------------------------------\n   */\n  private _finish: Array<(v?: Success, e?: Failure) => void> = [];\n\n  /** ------------------------------------------------------------\n   * * ***Constructor: `CustomPromise`.***\n   * -------------------------------------------------------------\n   * **Creates a new `CustomPromise` instance using a custom executor.**\n   *\n   * ---\n   * - **Behavior:**\n   *     - Behaves similarly to the native\n   *       ***`Promise`*** constructor.\n   *     - Receives custom `resolve` and `reject`\n   *       functions through the executor callback.\n   *     - Stores the resolved value or rejection reason\n   *       internally for use by `finish`.\n   *     - Preserves the `CustomPromise` prototype chain\n   *       for subclassed promise behavior.\n   *     - Ensures chained `then` and `catch`\n   *       operations continue returning\n   *       ***`CustomPromise`*** instances.\n   *\n   * ---\n   * @param {(resolve, reject) => void} executor\n   * ***Executor function responsible for controlling the asynchronous operation lifecycle.***\n   *\n   * @param {(value: Success) => void} executor.resolve\n   * ***Function used to resolve the promise with a value.***\n   *\n   * @param {(error: Error) => void} executor.reject\n   * ***Function used to reject the promise with an error.***\n   *\n   * ---\n   * @throws **{@link Error | `Error`}**\n   * Any uncaught exception thrown inside the executor\n   * automatically rejects the promise.\n   *\n   * ---\n   * @example\n   * ```ts\n   * const promise = new CustomPromise<string>(\n   *   (resolve) => {\n   *     setTimeout(\n   *       () => resolve(\"Done\"),\n   *       1000\n   *     );\n   *   }\n   * );\n   * ```\n   * ---\n   * @example\n   * ```ts\n   * const promise = new CustomPromise<\n   *   string,\n   *   Error\n   * >((resolve, reject) => {\n   *   Math.random() > 0.5\n   *     ? resolve(\"Success\")\n   *     : reject(\n   *         new Error(\"Failed\")\n   *       );\n   * });\n   * ```\n   */\n  constructor(\n    executor: (\n      /**\n       * * ***Function used to resolve the promise with a value.***\n       */\n      resolve: (value: Success) => void,\n\n      /**\n       * * ***Function used to reject the promise with an error.***\n       */\n      reject: (error: Failure) => void\n    ) => void\n  ) {\n    let resolveOuter: (v: Success) => void;\n    let rejectOuter: (e: Failure) => void;\n\n    super((resolve, reject) => {\n      resolveOuter = resolve;\n      rejectOuter = reject;\n    });\n\n    executor(\n      async (val) => {\n        this._value = await val;\n        resolveOuter(val);\n        this._finish.forEach(async (fn) => fn(await val, undefined));\n      },\n      async (err) => {\n        this._error = await err;\n        rejectOuter(err);\n        this._finish.forEach(async (fn) => fn(undefined, await err));\n      }\n    );\n\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  /** ---------------------------------------------------------------\n   * * ***Overrides `Promise.then()` while preserving the\n   * `CustomPromise` prototype chain.***\n   * ----------------------------------------------------------------\n   * **Registers callbacks for both fulfillment and rejection.**\n   *\n   * ---\n   * Unlike the native `Promise`, this override ensures the returned\n   * value remains a ***`CustomPromise`*** so additional methods\n   * such as `finish()` continue to be available throughout the chain.\n   *\n   * ---\n   * @template TResult1\n   * ***Result type returned by the fulfillment handler.***\n   *\n   * @template TResult2\n   * ***Result type returned by the rejection handler.***\n   *\n   * ---\n   * @param onfulfilled\n   * ***Callback executed when the promise resolves successfully.***\n   *\n   * @param onfulfilled.value\n   * ***Resolved value from the current promise.***\n   *\n   * @param onrejected\n   * ***Callback executed when the promise is rejected.***\n   *\n   * @param onrejected.reason\n   * ***Rejection reason from the current promise.***\n   *\n   * ---\n   * @returns A new ***`CustomPromise`*** containing the transformed result.\n   */\n  override then<TResult1 = Success, TResult2 = never>(\n    onfulfilled?:\n      | ((\n          /**\n           * * ***Resolved value from the current promise.***\n           */\n          value: Success\n        ) => TResult1 | PromiseLike<TResult1>)\n      | null,\n    onrejected?:\n      | ((\n          /**\n           * * ***Rejection reason from the current promise.***\n           */\n          reason: Failure\n        ) => TResult2 | PromiseLike<TResult2>)\n      | null\n  ): CustomPromise<TResult1 | TResult2, Failure> {\n    return super.then(onfulfilled, onrejected) as unknown as CustomPromise<\n      TResult1 | TResult2,\n      Failure\n    >;\n  }\n\n  /** ---------------------------------------------------------------\n   * * ***Overrides `Promise.catch()` while preserving the\n   * `CustomPromise` prototype chain.***\n   * ----------------------------------------------------------------\n   * **Registers a callback for promise rejection handling.**\n   *\n   * ---\n   * Unlike the native `Promise`, this override ensures the returned\n   * value remains a ***`CustomPromise`*** so additional methods\n   * such as `finish()` continue to be available throughout the chain.\n   *\n   * ---\n   * @template TResult\n   * ***Result type returned by the rejection handler.***\n   *\n   * ---\n   * @param onrejected\n   * ***Callback executed when the promise is rejected.***\n   *\n   * @param onrejected.reason\n   * ***Rejection reason from the current promise.***\n   *\n   * ---\n   * @returns A new ***`CustomPromise`*** containing either the\n   * original success value or the transformed rejection result.\n   */\n  override catch<TResult = never>(\n    onrejected?:\n      | ((\n          /**\n           * * ***Rejection reason from the current promise.***\n           */\n          reason: Failure\n        ) => TResult | PromiseLike<TResult>)\n      | null\n  ): CustomPromise<Success | TResult, Failure> {\n    return super.catch(onrejected) as unknown as CustomPromise<\n      Success | TResult,\n      Failure\n    >;\n  }\n\n  /** ---------------------------------------------------------------\n   * * ***Registers a callback to be invoked exactly once when the\n   * promise settles.***\n   * ----------------------------------------------------------------\n   * *If the promise is already settled when `finish()` is called,\n   * the callback executes immediately on the same tick.*\n   *\n   * ---\n   * @param callback\n   * ***Callback receiving the final settlement result.***\n   *\n   * @param callback.value\n   * ***Resolved value when the promise is fulfilled.***\n   *\n   * @param callback.error\n   * ***Rejection reason when the promise is rejected.***\n   *\n   * ---\n   * @returns `this` for fluent chaining.\n   */\n  finish(\n    callback: (\n      /**\n       * * ***Resolved value when the promise is fulfilled.***\n       */\n      value?: Success,\n\n      /**\n       * * ***Rejection reason when the promise is rejected.***\n       */\n      error?: Failure\n    ) => void\n  ): this {\n    if (this._value !== undefined || this._error !== undefined) {\n      callback(this._value, this._error);\n    } else {\n      this._finish.push(callback);\n    }\n    return this;\n  }\n}\n","import { createMessage } from \"@/_private/logger\";\n\nimport { AbortError } from \"@/errors/AbortError\";\nimport { isNull } from \"@/predicates/is/isNull\";\nimport { isInteger } from \"@/predicates/is/isInteger\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\n/** ------------------------------------------------------------\n * * ***Utility: `delay`.***\n * -------------------------------------------------------------\n * **Creates a Promise-based delay that resolves after a given number\n * of milliseconds, optionally supports cancellation with `AbortSignal`.**\n *\n * ---\n * - **Behavior:**\n *     - Validates `milliSeconds` is a non-zero, non-negative integer.\n *     - Validates `signal` is an `AbortSignal` instance when provided.\n *     - Cleans up event listeners and timers properly.\n *\n * ---\n * @param {number} [milliSeconds=1000]\n *  The duration of the delay in milliseconds, default is `1000`.\n * @param {AbortSignal} [signal]\n *  An optional `AbortSignal` that can cancel the delay.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** while validates `milliSeconds` and `signal`:\n *  - If `milliSeconds` **is not a valid** an `integer-number`, `NaN`, `negative-number`, or `≤ 0`.\n *  - If `signal` **is not a valid** an`AbortSignal`.\n * @throws **{@link AbortError | `AbortError`}** if the delay is aborted using the provided signal.\n *\n * ---\n * @returns {Promise<void>}\n *  A promise that resolves after the specified delay or\n *  rejects with an `AbortError` if aborted.\n *\n * ---\n * @example\n * 1. #### Waits for 2 seconds:\n *    ```ts\n *    await delay(2000);\n *    ```\n *    ---\n * 2. #### Delay with AbortSignal:\n *    ```ts\n *    const controller = new AbortController();\n *    delay(5000, controller.signal).catch(err => {\n *     console.log(err.name)\n *     // ➔ \"AbortError:['@rzl-zone/utils-js/promises:delay']\"\n *    });\n *    controller.abort();\n *    ```\n */\nexport const delay = (\n  milliSeconds: number = 1000,\n  signal?: AbortSignal\n): Promise<void> => {\n  if (!isInteger(milliSeconds) || milliSeconds <= 0) {\n    throw new TypeError(\n      errorMsg(\n        `First parameter (\\`milliSeconds\\`) must be of type \\`number\\` and value must be a \\`non-zero\\`, \\`non-NaN\\`, \\`non-negative\\`, and \\`integer-number\\`, but received: \\`${getPreciseType(\n          milliSeconds\n        )}\\`, with value: \\`${safeStableStringify(milliSeconds, {\n          keepUndefined: true\n        })}\\`.`\n      )\n    );\n  }\n\n  if (isNull(signal) || (signal && !(signal instanceof AbortSignal))) {\n    throw new TypeError(\n      errorMsg(\n        \"Second parameter (`signal`) must be an `instance of AbortSignal` if provided.\"\n      )\n    );\n  }\n\n  return new Promise<void>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      cleanup();\n      resolve();\n    }, milliSeconds);\n\n    const cleanup = () => {\n      clearTimeout(timer);\n      if (signal) signal.removeEventListener(\"abort\", onAbort);\n    };\n\n    const onAbort = () => {\n      cleanup();\n      reject(\n        new AbortError(\n          \"Function `delay` from `@rzl-zone/utils-js` was aborted.\",\n          {\n            suffix: \":['@rzl-zone/utils-js/promises:delay']\"\n          }\n        )\n      );\n    };\n\n    if (signal) {\n      if (signal.aborted) {\n        onAbort();\n        return;\n      }\n\n      signal.addEventListener(\"abort\", onAbort, { once: true });\n    }\n  });\n};\n\n/**\n * @internal ***`Not part of the public API.`***\n */\nconst errorMsg = (msg: string) => createMessage(\"delay\", msg);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyEA,IAAa,gBAAb,cACU,QAEV;;;;;;;;CAQE,AAAQ;;;;;;;;CAQR,AAAQ;;;;;;;;;CASR,AAAQ,UAAqD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+D9D,YACE,UAWA;EACA,IAAI;EACJ,IAAI;EAEJ,OAAO,SAAS,WAAW;GACzB,eAAe;GACf,cAAc;EAChB,CAAC;EAED,SACE,OAAO,QAAQ;GACb,KAAK,SAAS,MAAM;GACpB,aAAa,GAAG;GAChB,KAAK,QAAQ,QAAQ,OAAO,OAAO,GAAG,MAAM,KAAK,MAAS,CAAC;EAC7D,GACA,OAAO,QAAQ;GACb,KAAK,SAAS,MAAM;GACpB,YAAY,GAAG;GACf,KAAK,QAAQ,QAAQ,OAAO,OAAO,GAAG,QAAW,MAAM,GAAG,CAAC;EAC7D,CACF;EAEA,OAAO,eAAe,MAAM,IAAI,OAAO,SAAS;CAClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCA,AAAS,KACP,aAQA,YAQ6C;EAC7C,OAAO,MAAM,KAAK,aAAa,UAAU;CAI3C;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BA,AAAS,MACP,YAQ2C;EAC3C,OAAO,MAAM,MAAM,UAAU;CAI/B;;;;;;;;;;;;;;;;;;;;;CAsBA,OACE,UAWM;EACN,IAAI,KAAK,WAAW,UAAa,KAAK,WAAW,QAC/C,SAAS,KAAK,QAAQ,KAAK,MAAM;OAEjC,KAAK,QAAQ,KAAK,QAAQ;EAE5B,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/RA,MAAa,SACX,eAAuB,KACvB,WACkB;CAClB,IAAI,CAACA,4BAAU,YAAY,KAAK,gBAAgB,GAC9C,MAAM,IAAI,UACR,SACE,0KAA0KC,8BACxK,YACF,EAAE,oBAAoBC,gDAAoB,cAAc,EACtD,eAAe,KACjB,CAAC,EAAE,IACL,CACF;CAGF,IAAIC,sBAAO,MAAM,KAAM,UAAU,EAAE,kBAAkB,cACnD,MAAM,IAAI,UACR,SACE,+EACF,CACF;CAGF,OAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,MAAM,QAAQ,iBAAiB;GAC7B,QAAQ;GACR,QAAQ;EACV,GAAG,YAAY;EAEf,MAAM,gBAAgB;GACpB,aAAa,KAAK;GAClB,IAAI,QAAQ,OAAO,oBAAoB,SAAS,OAAO;EACzD;EAEA,MAAM,gBAAgB;GACpB,QAAQ;GACR,OACE,IAAIC,8BACF,2DACA,EACE,QAAQ,yCACV,CACF,CACF;EACF;EAEA,IAAI,QAAQ;GACV,IAAI,OAAO,SAAS;IAClB,QAAQ;IACR;GACF;GAEA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D;CACF,CAAC;AACH;;;;AAKA,MAAM,YAAY,QAAgBC,6BAAc,SAAS,GAAG"}

package/dist/promises/index.d.cts

@@ -2,17 +2,19 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1`
+*  Version: `3.14.0-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
 */
 
-import { CustomPromiseType } from "@rzl-zone/ts-types-plus";
+import { o as CustomPromiseType } from "../index-DZHiYYR7.cjs";
 /** -------------------------------------------------------------
 * * ***Utility Class: `CustomPromise`.***
-* -------------------------------------------------------------
+* --------------------------------------------------------------
 * **A strongly typed extension of the native {@link Promise | **`Promise`**}.**
+*
+* ---
 *  1. **Behaves exactly like a normal Promise** for `then`/`catch`
 *      and `await` semantics.
 *  2. **Stores the final resolution or rejection internally** so
@@ -20,104 +22,254 @@ import { CustomPromiseType } from "@rzl-zone/ts-types-plus";
 *  3. **Adds a `finish` method** which runs once after settlement
 *      with access to both the fulfilled value *and* the rejection
 *      reason (only one will be defined).
+*
+* ---
 * - **Key Differences from a Native `Promise`:**
-*    - Every call to `then`/`catch` returns **`CustomPromise`**
-*      again, so the `finish` method remains available on the
-*      entire chain.
-*    - `finish` provides a tuple-like callback:
-*      - `val`  → defined when fulfilled.
-*      - `err`  → defined when rejected.
+*     - Every call to `then`/`catch` returns **`CustomPromise`**
+*       again, so the `finish` method remains available on the
+*       entire chain.
+*     - `finish` provides a tuple-like callback:
+*        - `val`  ➔ defined when fulfilled.
+*        - `err`  ➔ defined when rejected.
+*
+* ---
 * @template Success  Type of the resolved value.
 * @template Error    Type of the rejection reason (default `unknown`).
+*
+* ---
 * @example
-* ```ts
-* import { CustomPromise, type CustomPromiseType } from "@rzl-zone/utils-js/promises";
+*  ```ts
+*  import { CustomPromise, type CustomPromiseType } from "@rzl-zone/utils-js/promises";
 *
-* type User = { id: number; name: string };
-* type ApiError = { message: string };
+*  type User = { id: number; name: string };
+*  type ApiError = { message: string };
 *
-* function fetchUser(): CustomPromiseType<User, ApiError> {
-*   return new CustomPromise<User, ApiError>((resolve, reject) => {
-*     setTimeout(
-*       () =>
-*         void (Math.random() > 0.5
-*           ? resolve({ id: 1, name: "Alice" })
-*           : reject({ message: "Random failure" })),
-*       500
-*     );
-*   });
-* }
+*  function fetchUser(): CustomPromiseType<User, ApiError> {
+*    return new CustomPromise<User, ApiError>((resolve, reject) => {
+*      setTimeout(
+*        () =>
+*          void (Math.random() > 0.5
+*            ? resolve({ id: 1, name: "Alice" })
+*            : reject({ message: "Random failure" })),
+*        500
+*      );
+*    });
+*  }
 *
-* fetchUser()
-*   .then(user => {
-*      console.log("SUCCESS:", user);
-*      return user;
-*    })
-*   .catch(err => {
-*      console.error("ERROR:", err);
-*      throw err;
-*    })
-*   .finish((val, err) => {
-*     // Runs once after settle, regardless of outcome
-*     console.log("FINISH:", { val, err });
-*   });
-* ```
+*  fetchUser()
+*    .then(user => {
+*       console.log("SUCCESS:", user);
+*       return user;
+*     })
+*    .catch(err => {
+*       console.error("ERROR:", err);
+*       throw err;
+*     })
+*    .finish((val, err) => {
+*      // Runs once after settle, regardless of outcome
+*      console.log("FINISH:", { val, err });
+*    });
+*  ```
 * ---
 * - **Implementation Notes:**
-*    - Uses `Object.setPrototypeOf` to preserve the prototype chain
-*      for environments targeting ES5 or when subclassing Promise.
-*    - Internal `_value` and `_error` are updated as soon as the
-*      executor resolves or rejects, guaranteeing `finish` receives
-*      the final state even when added after settlement.
+*     - Uses `Object.setPrototypeOf` to preserve the prototype chain
+*       for environments targeting ES5 or when subclassing Promise.
+*     - Internal settlement state is tracked automatically,
+*       allowing `finish` to access the final result even
+*       when registered after settlement.
 */
-declare class CustomPromise<Success, Error = unknown> extends Promise<Success> implements CustomPromiseType<Success, Error> {
-  private _value?;
-  private _error?;
-  private _finish;
-  constructor(executor: (resolve: (v: Success) => void, reject: (e: Error) => void) => void);
-  override then<TResult1 = Success, TResult2 = never>(onfulfilled?: ((value: Success) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null): CustomPromise<TResult1 | TResult2, Error>;
-  override catch<TResult = never>(onrejected?: ((reason: Error) => TResult | PromiseLike<TResult>) | null): CustomPromise<Success | TResult, Error>;
-  /**
-  * Registers a callback to be invoked **exactly once** when the
-  * promise settles, with access to both the resolved value and
-  * the rejection reason.
-  *
-  * If the promise is already settled when `finish` is called,
-  * the callback executes immediately on the same tick.
-  *
-  * @param cb Callback receiving the final `(value, error)`.
+declare class CustomPromise<Success, Failure = unknown> extends Promise<Success> implements CustomPromiseType<Success, Failure> {
+  /** ------------------------------------------------------------
+  * * ***Constructor: `CustomPromise`.***
+  * -------------------------------------------------------------
+  * **Creates a new `CustomPromise` instance using a custom executor.**
+  *
+  * ---
+  * - **Behavior:**
+  *     - Behaves similarly to the native
+  *       ***`Promise`*** constructor.
+  *     - Receives custom `resolve` and `reject`
+  *       functions through the executor callback.
+  *     - Stores the resolved value or rejection reason
+  *       internally for use by `finish`.
+  *     - Preserves the `CustomPromise` prototype chain
+  *       for subclassed promise behavior.
+  *     - Ensures chained `then` and `catch`
+  *       operations continue returning
+  *       ***`CustomPromise`*** instances.
+  *
+  * ---
+  * @param {(resolve, reject) => void} executor
+  * ***Executor function responsible for controlling the asynchronous operation lifecycle.***
+  *
+  * @param {(value: Success) => void} executor.resolve
+  * ***Function used to resolve the promise with a value.***
+  *
+  * @param {(error: Error) => void} executor.reject
+  * ***Function used to reject the promise with an error.***
+  *
+  * ---
+  * @throws **{@link Error | `Error`}**
+  * Any uncaught exception thrown inside the executor
+  * automatically rejects the promise.
+  *
+  * ---
+  * @example
+  * ```ts
+  * const promise = new CustomPromise<string>(
+  *   (resolve) => {
+  *     setTimeout(
+  *       () => resolve("Done"),
+  *       1000
+  *     );
+  *   }
+  * );
+  * ```
+  * ---
+  * @example
+  * ```ts
+  * const promise = new CustomPromise<
+  *   string,
+  *   Error
+  * >((resolve, reject) => {
+  *   Math.random() > 0.5
+  *     ? resolve("Success")
+  *     : reject(
+  *         new Error("Failed")
+  *       );
+  * });
+  * ```
+  */
+  constructor(executor: (resolve: (value: Success) => void, reject: (error: Failure) => void) => void);
+  /** ---------------------------------------------------------------
+  * * ***Overrides `Promise.then()` while preserving the
+  * `CustomPromise` prototype chain.***
+  * ----------------------------------------------------------------
+  * **Registers callbacks for both fulfillment and rejection.**
+  *
+  * ---
+  * Unlike the native `Promise`, this override ensures the returned
+  * value remains a ***`CustomPromise`*** so additional methods
+  * such as `finish()` continue to be available throughout the chain.
+  *
+  * ---
+  * @template TResult1
+  * ***Result type returned by the fulfillment handler.***
+  *
+  * @template TResult2
+  * ***Result type returned by the rejection handler.***
+  *
+  * ---
+  * @param onfulfilled
+  * ***Callback executed when the promise resolves successfully.***
+  *
+  * @param onfulfilled.value
+  * ***Resolved value from the current promise.***
+  *
+  * @param onrejected
+  * ***Callback executed when the promise is rejected.***
+  *
+  * @param onrejected.reason
+  * ***Rejection reason from the current promise.***
+  *
+  * ---
+  * @returns A new ***`CustomPromise`*** containing the transformed result.
+  */
+  override then<TResult1 = Success, TResult2 = never>(onfulfilled?: ((value: Success) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: Failure) => TResult2 | PromiseLike<TResult2>) | null): CustomPromise<TResult1 | TResult2, Failure>;
+  /** ---------------------------------------------------------------
+  * * ***Overrides `Promise.catch()` while preserving the
+  * `CustomPromise` prototype chain.***
+  * ----------------------------------------------------------------
+  * **Registers a callback for promise rejection handling.**
+  *
+  * ---
+  * Unlike the native `Promise`, this override ensures the returned
+  * value remains a ***`CustomPromise`*** so additional methods
+  * such as `finish()` continue to be available throughout the chain.
+  *
+  * ---
+  * @template TResult
+  * ***Result type returned by the rejection handler.***
+  *
+  * ---
+  * @param onrejected
+  * ***Callback executed when the promise is rejected.***
+  *
+  * @param onrejected.reason
+  * ***Rejection reason from the current promise.***
+  *
+  * ---
+  * @returns A new ***`CustomPromise`*** containing either the
+  * original success value or the transformed rejection result.
+  */
+  override catch<TResult = never>(onrejected?: ((reason: Failure) => TResult | PromiseLike<TResult>) | null): CustomPromise<Success | TResult, Failure>;
+  /** ---------------------------------------------------------------
+  * * ***Registers a callback to be invoked exactly once when the
+  * promise settles.***
+  * ----------------------------------------------------------------
+  * *If the promise is already settled when `finish()` is called,
+  * the callback executes immediately on the same tick.*
+  *
+  * ---
+  * @param callback
+  * ***Callback receiving the final settlement result.***
+  *
+  * @param callback.value
+  * ***Resolved value when the promise is fulfilled.***
+  *
+  * @param callback.error
+  * ***Rejection reason when the promise is rejected.***
+  *
+  * ---
   * @returns `this` for fluent chaining.
   */
-  finish(cb: (val?: Success, err?: Error) => void): this;
+  finish(callback: (value?: Success, error?: Failure) => void): this;
 }
 /** ------------------------------------------------------------
 * * ***Utility: `delay`.***
-* ------------------------------------------------------------
+* -------------------------------------------------------------
 * **Creates a Promise-based delay that resolves after a given number
 * of milliseconds, optionally supports cancellation with `AbortSignal`.**
+*
+* ---
 * - **Behavior:**
-*    - Validates `milliSeconds` is a non-zero, non-negative integer.
-*    - Validates `signal` is an `AbortSignal` instance when provided.
-*    - Cleans up event listeners and timers properly.
+*     - Validates `milliSeconds` is a non-zero, non-negative integer.
+*     - Validates `signal` is an `AbortSignal` instance when provided.
+*     - Cleans up event listeners and timers properly.
+*
+* ---
 * @param {number} [milliSeconds=1000]
 *  The duration of the delay in milliseconds, default is `1000`.
 * @param {AbortSignal} [signal]
 *  An optional `AbortSignal` that can cancel the delay.
-* @returns {Promise<void>}
-*  A promise that resolves after the specified delay or
-*  rejects with an `AbortError` if aborted.
+*
+* ---
 * @throws **{@link TypeError | `TypeError`}** while validates `milliSeconds` and `signal`:
 *  - If `milliSeconds` **is not a valid** an `integer-number`, `NaN`, `negative-number`, or `≤ 0`.
 *  - If `signal` **is not a valid** an`AbortSignal`.
-* @throws **{@link DOMException | `DOMException`}** if the delay is aborted using the signal, rejects with `AbortError`.
-* @example
-* // Waits for 2 seconds
-* await delay(2000);
+* @throws **{@link AbortError | `AbortError`}** if the delay is aborted using the provided signal.
 *
-* // Delay with AbortSignal
-* const controller = new AbortController();
-* delay(5000, controller.signal).catch(err => console.log(err.name)); // "AbortError"
-* controller.abort();
+* ---
+* @returns {Promise<void>}
+*  A promise that resolves after the specified delay or
+*  rejects with an `AbortError` if aborted.
+*
+* ---
+* @example
+* 1. #### Waits for 2 seconds:
+*    ```ts
+*    await delay(2000);
+*    ```
+*    ---
+* 2. #### Delay with AbortSignal:
+*    ```ts
+*    const controller = new AbortController();
+*    delay(5000, controller.signal).catch(err => {
+*     console.log(err.name)
+*     // ➔ "AbortError:['@rzl-zone/utils-js/promises:delay']"
+*    });
+*    controller.abort();
+*    ```
 */
 declare const delay: (milliSeconds?: number, signal?: AbortSignal) => Promise<void>;
 export { CustomPromise, type CustomPromiseType, delay };