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

package/dist/promises/index.cjs

@@ -1,25 +1,77 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.12.0.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-'use strict';
-
-var chunk7B76BSNK_cjs = require('../chunk-7B76BSNK.cjs');
-require('../chunk-DVMHRLKP.cjs');
-require('../chunk-TQPGXGKB.cjs');
-require('../chunk-UDA26MCU.cjs');
-require('../chunk-GKC3UDMC.cjs');
-
-Object.defineProperty(exports, "CustomPromise", {
-  enumerable: true,
-  get: function () { return chunk7B76BSNK_cjs.CustomPromise; }
-});
-Object.defineProperty(exports, "delay", {
-  enumerable: true,
-  get: function () { return chunk7B76BSNK_cjs.delay; }
-});
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  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`
+* ========================================================================
+*/
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_assertIsBoolean = require('../assertIsBoolean-C8WEXVr2.cjs');
+const require_safeStableStringify = require('../safeStableStringify-CJtP89qn.cjs');
+const require_isInteger = require('../isInteger-Caeuz0rB.cjs');
+var CustomPromise = class extends Promise {
+	_value;
+	_error;
+	_finish = [];
+	constructor(executor) {
+		let resolveOuter;
+		let rejectOuter;
+		super((resolve, reject) => {
+			resolveOuter = resolve;
+			rejectOuter = reject;
+		});
+		executor((v) => {
+			this._value = v;
+			resolveOuter(v);
+			this._finish.forEach((f) => f(v, void 0));
+		}, (e) => {
+			this._error = e;
+			rejectOuter(e);
+			this._finish.forEach((f) => f(void 0, e));
+		});
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	then(onfulfilled, onrejected) {
+		return super.then(onfulfilled, onrejected);
+	}
+	catch(onrejected) {
+		return super.catch(onrejected);
+	}
+	finish(cb) {
+		if (this._value !== void 0 || this._error !== void 0) cb(this._value, this._error);
+		else this._finish.push(cb);
+		return this;
+	}
+};
+var AbortError = class extends Error {
+	constructor(message = "The operation was aborted", name = "AbortError") {
+		super(message);
+		this.name = name;
+	}
+};
+const delay = (milliSeconds = 1e3, signal) => {
+	if (!require_isInteger.isInteger(milliSeconds) || milliSeconds <= 0) throw new TypeError(`First parameter (\`milliSeconds\`) must be of type \`number\` and value must be a \`non-zero\`, \`non-NaN\`, \`non-negative\`, and \`integer-number\`, but received: \`${require_assertIsBoolean.getPreciseType(milliSeconds)}\`, with value: \`${require_safeStableStringify.safeStableStringify(milliSeconds, { keepUndefined: true })}\`.`);
+	if (require_assertIsBoolean.isNull(signal) || signal && !(signal instanceof AbortSignal)) throw new TypeError("Second parameter (`signal`) must be an `instance of AbortSignal` if provided.");
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, milliSeconds);
+		const cleanup = () => {
+			clearTimeout(timer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+		};
+		const onAbort = () => {
+			cleanup();
+			reject(new AbortError("Function `delay` from `@rzl-zone/utils-js` was aborted.", "AbortError"));
+		};
+		if (signal) if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	});
+};
+exports.CustomPromise = CustomPromise;
+exports.delay = delay;
+//# sourceMappingURL=index.cjs.map

package/dist/promises/index.cjs.map

@@ -0,0 +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,EAAE;CAE7D,YACE,UAIA;EACA,IAAI;EACJ,IAAI;EAEJ,OAAO,SAAS,WAAW;GACzB,eAAe;GACf,cAAc;IACd;EAEF,UACG,MAAM;GACL,KAAK,SAAS;GACd,aAAa,EAAE;GACf,KAAK,QAAQ,SAAS,MAAM,EAAE,GAAG,OAAU,CAAC;MAE7C,MAAM;GACL,KAAK,SAAS;GACd,YAAY,EAAE;GACd,KAAK,QAAQ,SAAS,MAAM,EAAE,QAAW,EAAE,CAAC;IAE/C;EAED,OAAO,eAAe,MAAM,IAAI,OAAO,UAAU;;CAGnD,AAAS,KACP,aACA,YAC2C;EAC3C,OAAO,MAAM,KAAK,aAAa,WAAW;;CAM5C,AAAS,MACP,YACyC;EACzC,OAAO,MAAM,MAAM,WAAW;;;;;;;;;;;;;CAiBhC,OAAO,IAAgD;EACrD,IAAI,KAAK,WAAW,UAAa,KAAK,WAAW,QAC/C,GAAG,KAAK,QAAQ,KAAK,OAAO;OAE5B,KAAK,QAAQ,KAAK,GAAG;EAEvB,OAAO;;;;;;;;;;AClIX,IAAM,aAAN,cAAyB,MAAM;CAC7B,YACE,UAAkB,6BAClB,OAAe,cACf;EACA,MAAM,QAAQ;EACd,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiChB,MAAa,SACX,eAAuB,KACvB,WACkB;CAClB,IAAI,CAACA,4BAAU,aAAa,IAAI,gBAAgB,GAC9C,MAAM,IAAI,UACR,0KAA0KC,uCACxK,aACD,CAAC,oBAAoBC,gDAAoB,cAAc,EACtD,eAAe,MAChB,CAAC,CAAC,KACJ;CAGH,IAAIC,+BAAO,OAAO,IAAK,UAAU,EAAE,kBAAkB,cACnD,MAAM,IAAI,UACR,gFACD;CAGH,OAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,MAAM,QAAQ,iBAAiB;GAC7B,SAAS;GACT,SAAS;KACR,aAAa;EAEhB,MAAM,gBAAgB;GACpB,aAAa,MAAM;GACnB,IAAI,QAAQ,OAAO,oBAAoB,SAAS,QAAQ;;EAG1D,MAAM,gBAAgB;GACpB,SAAS;GACT,OACE,IAAI,WACF,2DACA,aACD,CACF;;EAGH,IAAI,QACF,IAAI,OAAO,SACT,SAAS;OAET,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;GAG7D"}

package/dist/promises/index.d.cts

@@ -0,0 +1,123 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  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`
+* ========================================================================
+*/
+
+import { CustomPromiseType } from "@rzl-zone/ts-types-plus";
+/** -------------------------------------------------------------
+* * ***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
+*      it can be retrieved by a custom `finish` handler.
+*  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.
+* @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";
+*
+* 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
+*     );
+*   });
+* }
+*
+* 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.
+*/
+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)`.
+  * @returns `this` for fluent chaining.
+  */
+  finish(cb: (val?: Success, err?: Error) => 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.
+* @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);
+*
+* // Delay with AbortSignal
+* const controller = new AbortController();
+* delay(5000, controller.signal).catch(err => console.log(err.name)); // "AbortError"
+* controller.abort();
+*/
+declare const delay: (milliSeconds?: number, signal?: AbortSignal) => Promise<void>;
+export { CustomPromise, type CustomPromiseType, delay };

package/dist/promises/index.d.ts

@@ -1,126 +1,123 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.12.0.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-import { CustomPromiseType } from '@rzl-zone/ts-types-plus';
-export { CustomPromiseType } from '@rzl-zone/ts-types-plus';
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  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`
+* ========================================================================
+*/
 
+import { CustomPromiseType } from "@rzl-zone/ts-types-plus";
 /** -------------------------------------------------------------
- * * ***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
- *      it can be retrieved by a custom `finish` handler.
- *  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.
- * @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";
- *
- * 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
- *     );
- *   });
- * }
- *
- * 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.
- */
+* * ***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
+*      it can be retrieved by a custom `finish` handler.
+*  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.
+* @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";
+*
+* 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
+*     );
+*   });
+* }
+*
+* 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.
+*/
 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);
-    then<TResult1 = Success, TResult2 = never>(onfulfilled?: ((value: Success) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null): CustomPromise<TResult1 | TResult2, Error>;
-    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)`.
-     * @returns `this` for fluent chaining.
-     */
-    finish(cb: (val?: Success, err?: Error) => void): this;
+  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)`.
+  * @returns `this` for fluent chaining.
+  */
+  finish(cb: (val?: Success, err?: Error) => 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.
- * @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);
- *
- * // Delay with AbortSignal
- * const controller = new AbortController();
- * delay(5000, controller.signal).catch(err => console.log(err.name)); // "AbortError"
- * controller.abort();
- */
+* * ***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.
+* @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);
+*
+* // Delay with AbortSignal
+* const controller = new AbortController();
+* delay(5000, controller.signal).catch(err => console.log(err.name)); // "AbortError"
+* controller.abort();
+*/
 declare const delay: (milliSeconds?: number, signal?: AbortSignal) => Promise<void>;
-
-export { CustomPromise, delay };
+export { CustomPromise, type CustomPromiseType, delay };

package/dist/promises/index.js

@@ -1,14 +1,74 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.12.0.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-export { CustomPromise, delay } from '../chunk-SYNL5IKP.js';
-import '../chunk-WVSPXFTY.js';
-import '../chunk-6VUXD3CF.js';
-import '../chunk-QNKGP5DY.js';
-import '../chunk-CSG4SCL3.js';
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  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`
+* ========================================================================
+*/
+import { E as isNull, r as getPreciseType } from "../assertIsBoolean-DR1SaXPD.js";
+import { t as safeStableStringify } from "../safeStableStringify-CXOZ9Ub8.js";
+import { t as isInteger } from "../isInteger-naMbJsxJ.js";
+var CustomPromise = class extends Promise {
+	_value;
+	_error;
+	_finish = [];
+	constructor(executor) {
+		let resolveOuter;
+		let rejectOuter;
+		super((resolve, reject) => {
+			resolveOuter = resolve;
+			rejectOuter = reject;
+		});
+		executor((v) => {
+			this._value = v;
+			resolveOuter(v);
+			this._finish.forEach((f) => f(v, void 0));
+		}, (e) => {
+			this._error = e;
+			rejectOuter(e);
+			this._finish.forEach((f) => f(void 0, e));
+		});
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	then(onfulfilled, onrejected) {
+		return super.then(onfulfilled, onrejected);
+	}
+	catch(onrejected) {
+		return super.catch(onrejected);
+	}
+	finish(cb) {
+		if (this._value !== void 0 || this._error !== void 0) cb(this._value, this._error);
+		else this._finish.push(cb);
+		return this;
+	}
+};
+var AbortError = class extends Error {
+	constructor(message = "The operation was aborted", name = "AbortError") {
+		super(message);
+		this.name = name;
+	}
+};
+const delay = (milliSeconds = 1e3, signal) => {
+	if (!isInteger(milliSeconds) || milliSeconds <= 0) throw new TypeError(`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(milliSeconds)}\`, with value: \`${safeStableStringify(milliSeconds, { keepUndefined: true })}\`.`);
+	if (isNull(signal) || signal && !(signal instanceof AbortSignal)) throw new TypeError("Second parameter (`signal`) must be an `instance of AbortSignal` if provided.");
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, milliSeconds);
+		const cleanup = () => {
+			clearTimeout(timer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+		};
+		const onAbort = () => {
+			cleanup();
+			reject(new AbortError("Function `delay` from `@rzl-zone/utils-js` was aborted.", "AbortError"));
+		};
+		if (signal) if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	});
+};
+export { CustomPromise, delay };
+//# sourceMappingURL=index.js.map

package/dist/promises/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"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,EAAE;CAE7D,YACE,UAIA;EACA,IAAI;EACJ,IAAI;EAEJ,OAAO,SAAS,WAAW;GACzB,eAAe;GACf,cAAc;IACd;EAEF,UACG,MAAM;GACL,KAAK,SAAS;GACd,aAAa,EAAE;GACf,KAAK,QAAQ,SAAS,MAAM,EAAE,GAAG,OAAU,CAAC;MAE7C,MAAM;GACL,KAAK,SAAS;GACd,YAAY,EAAE;GACd,KAAK,QAAQ,SAAS,MAAM,EAAE,QAAW,EAAE,CAAC;IAE/C;EAED,OAAO,eAAe,MAAM,IAAI,OAAO,UAAU;;CAGnD,AAAS,KACP,aACA,YAC2C;EAC3C,OAAO,MAAM,KAAK,aAAa,WAAW;;CAM5C,AAAS,MACP,YACyC;EACzC,OAAO,MAAM,MAAM,WAAW;;;;;;;;;;;;;CAiBhC,OAAO,IAAgD;EACrD,IAAI,KAAK,WAAW,UAAa,KAAK,WAAW,QAC/C,GAAG,KAAK,QAAQ,KAAK,OAAO;OAE5B,KAAK,QAAQ,KAAK,GAAG;EAEvB,OAAO;;;;;;;;;;AClIX,IAAM,aAAN,cAAyB,MAAM;CAC7B,YACE,UAAkB,6BAClB,OAAe,cACf;EACA,MAAM,QAAQ;EACd,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiChB,MAAa,SACX,eAAuB,KACvB,WACkB;CAClB,IAAI,CAAC,UAAU,aAAa,IAAI,gBAAgB,GAC9C,MAAM,IAAI,UACR,0KAA0K,eACxK,aACD,CAAC,oBAAoB,oBAAoB,cAAc,EACtD,eAAe,MAChB,CAAC,CAAC,KACJ;CAGH,IAAI,OAAO,OAAO,IAAK,UAAU,EAAE,kBAAkB,cACnD,MAAM,IAAI,UACR,gFACD;CAGH,OAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,MAAM,QAAQ,iBAAiB;GAC7B,SAAS;GACT,SAAS;KACR,aAAa;EAEhB,MAAM,gBAAgB;GACpB,aAAa,MAAM;GACnB,IAAI,QAAQ,OAAO,oBAAoB,SAAS,QAAQ;;EAG1D,MAAM,gBAAgB;GACpB,SAAS;GACT,OACE,IAAI,WACF,2DACA,aACD,CACF;;EAGH,IAAI,QACF,IAAI,OAAO,SACT,SAAS;OAET,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;GAG7D"}