@superutils/promise 1.0.5 → 1.0.7

package/README.md

@@ -2,7 +2,7 @@
 
 An extended `Promise` implementation, named `PromisE`, that provides additional features and utilities for easier asynchronous flow control in JavaScript and TypeScript applications.
 
-This package offers a drop-in replacement for the native `Promise` that includes status tracking (`.pending`, `.resolved`, `.rejected`) and a suite of powerful static methods for common asynchronous patterns like deferred execution, throttling, and cancellable fetches.
+This package offers a drop-in replacement for the native `Promise` that includes status tracking (`.pending`, `.resolved`, `.rejected`) and a suite of practical static methods for common asynchronous patterns like deferred execution, throttling, and cancellable fetches.
 
 <div v-if="false">
 

package/dist/index.d.ts

@@ -17,7 +17,7 @@ interface IPromisE<T = unknown> extends Promise<T> {
     /** Indicates if the promise has been resolved */
     readonly resolved: boolean;
 }
-interface IPromisE_Delay<T = unknown> extends IPromisE<T> {
+interface IPromisE_Delay<T = unknown> extends Promise<T>, IPromisE<T> {
     /**
      * Caution: pausing will prevent the promise from resolving/rejeting automatically.
      *
@@ -58,6 +58,7 @@ interface IPromisE_Delay<T = unknown> extends IPromisE<T> {
      * ```
      */
     pause: () => void;
+    /** Timeout ID */
     timeoutId: TimeoutId;
 }
 /**
@@ -184,13 +185,13 @@ type RetryOptions<T = unknown> = {
      * Additional condition/function to be used to determine whether function should be retried.
      * `retryIf` will only be executed when function execution is successful.
      */
-    retryIf?: null | ((prevResult: T | undefined, retryCount: number, error?: unknown) => boolean | Promise<boolean>);
+    retryIf?: null | ((prevResult: T | undefined, retryCount: number) => boolean | Promise<boolean>);
 };
 
 declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T> {
-    readonly state: 0 | 1 | 2;
     private _resolve?;
     private _reject?;
+    private _state;
     /**
      * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
     onEarlyFinalize: OnEarlyFinalize<T>[];
@@ -219,6 +220,8 @@ declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T>
     get rejected(): boolean;
     /** Indicates if the promise has been resolved */
     get resolved(): boolean;
+    /** Get promise status code */
+    get state(): 0 | 1 | 2;
     /** Resovle pending promise early. */
     resolve: (value: T | PromiseLike<T>) => void;
     /** Reject pending promise early. */
@@ -293,7 +296,38 @@ type TimeoutOptions<Func extends string = 'all'> = {
  * @function PromisE.deferred
  * The adaptation of the `deferred()` function tailored for Promises.
  *
- * @param options           (optional) options
+ *
+ * # Notes
+ *
+ * - A "request" simply means invokation of the returned callback function
+ * - By "handled" it means a "request" will be resolved or rejected.
+ * - `PromisE.deferred` is to be used with promises/functions.
+ * `PromisE.deferredCallback` is for use with callback functions.
+ * - There is no specific time delay.
+ * - If a request takes longer than `delayMs`, the following request will be added to queue
+ * and either be ignored or exectued based on the debounce/throttle configuration.
+ * - If not throttled:
+ *     1. Once a request is handled, all previous requests will be ignored and pool starts anew.
+ *     2. If a function is provided in the  returned callback, ALL of them will be invoked, regardless of pool size.
+ *     3. The last/only request in an on-going requests' pool will handled (resolve/reject).
+ * - If throttled:
+ *     1. Once a requst starts executing, subsequent requests will be added to a queue.
+ *     2. The last/only item in the queue will be handled. Rest will be ignored.
+ *     3. If a function is provided in the returned callback, it will be invoked only if the request is handled.
+ *     Thus, improving performance by avoiding unnecessary invokations.
+ *     4. If every single request/function needs to be invoked, avoid using throttle.
+ * - If throttled and `strict` is truthy, all subsequent request while a request is being handled will be ignored.
+ *
+ * @param options (optional) Debounce/throttle configuration.
+ *
+ * The properties' default values can be overridden to be EFFECTIVE GLOBALLY:
+ * ```typescript
+ * deferred.defaults = {
+ *     delayMs: 100,
+ *     resolveError: ResolveError.REJECT,
+ *     resolveIgnored: ResolveIgnored.WITH_LAST,
+ * }
+ * ```
  * @property options.delayMs   (optional) delay in milliseconds to be used with debounce & throttle modes. When `undefined` or `>= 0`, execution will be sequential.
  * @property options.onError   (optional)
  * @property options.onIgnore  (optional) invoked whenever callback invocation is ignored by a newer invocation
@@ -305,30 +339,11 @@ type TimeoutOptions<Func extends string = 'all'> = {
  * Requires `defer`.
  * Default: `false`
  *
- * @returns {Function} a callback that is invoked in one of the followin 3 methods:
- * - sequential: when `delayMs <= 0` or `delayMs = undefined`
+ * @returns Callback function that can be invoked in one of the followin 3 methods:
+ * - sequential: when `delayMs <= 0`
  * - debounced: when `delayMs > 0` and `throttle = false`
  * - throttled: when `delayMs > 0` and `throttle = true`
  *
- * The main difference is that:
- *  - Notes:
- *      1. A "request" simply means invokation of the returned callback function
- *      2. By "handled" it means a "request" will be resolved or rejected.
- *  - `PromisE.deferred` is to be used with promises/functions
- *  - There is no specific time delay.
- *  - The time when a request is completed is irrelevant.
- *  - If not throttled:
- *      1. Once a request is handled, all previous requests will be ignored and pool starts anew.
- *      2. If a function is provided in the  returned callback, ALL of them will be invoked, regardless of pool size.
- *      3. The last/only request in an on-going requests' pool will handled (resolve/reject).
- *  - If throttled:
- *      1. Once a requst starts executing, subsequent requests will be added to a queue.
- *      2. The last/only item in the queue will be handled. Rest will be ignored.
- *      3. If a function is provided in the returned callback, it will be invoked only if the request is handled.
- *      Thus, improving performance by avoiding unnecessary invokations.
- *      4. If every single request/function needs to be invoked, avoid using throttle.
- *
- *  - If throttled and `strict` is truthy, all subsequent request while a request is being handled will be ignored.
  *
  * @example Explanation & example usage:
  * ```typescript
@@ -400,15 +415,19 @@ declare namespace deferred {
 declare function deferredCallback<TDefault, ThisArg, Delay extends number = number, CbArgs extends unknown[] = unknown[]>(callback: (...args: CbArgs) => TDefault | Promise<TDefault>, options?: DeferredAsyncOptions<ThisArg, Delay>): <TResult = TDefault>(...args: CbArgs) => IPromisE<TResult>;
 
 /**
- * @function    PromisE.delay
- * @summary Creates a promise that completes after given delay/duration.
+ * Creates a promise that completes after given delay/duration.
+ *
+ * Also accessible from the `PromisE` class as `PromisE.delay()`.
  *
- * @param {Number}    duration   duration in milliseconds
- * @param {unknown}   result    (optional) specify a value to resolve or reject with.
- *                              Default: `delayMs` when resolved or timed out error when rejected
- * @param {boolean}   asRejected (optional) if `true`, will reject the promise after the delay.
+ * @param duration duration in milliseconds. Default: `100`
+ * @param result (optional) specify a value to resolve or error to reject with.
  *
- * @returns See {@link IPromisE_Delay}
+ * Alternatively, a function (with no arguments) can be provided that returns the result.
+ *
+ * Default: `delayMs` when resolved or timed out error when rejected
+ * @param asRejected (optional) if `true`, will reject the promise after the delay.
+ *
+ * @returns a promise
  *
  * @example Delay before continuing execution
  * ```typescript
@@ -433,7 +452,7 @@ declare namespace delay {
     var defaults: {
         /** Default delay duration in milliseconds */
         duration: number;
-        /** Default timed out message */
+        /** Default timed out message (if `result` is not provided) */
         delayTimeoutMsg: string;
     };
 }
@@ -630,7 +649,7 @@ declare class PromisE<T = unknown> extends PromisEBase<T> {
 }
 
 /**
- * Executes a function and retries it on failure or until a specific condition is met.
+ * Executes a function asynchronously and retries it on failure or until a specific condition is met.
  *
  * The function will be re-executed if:
  * 1. The `func` promise rejects or the function throws an error.
@@ -640,21 +659,56 @@ declare class PromisE<T = unknown> extends PromisEBase<T> {
  * Retries will stop when the `retry` count is exhausted, or when `func` executes successfully
  * (resolves without error) AND the `retryIf` (if provided) returns `false`.
  *
- * @template T The type of the value that the `func` returns/resolves to.
- * @param {() => ValueOrPromise<T>}	func The function to execute. It can be synchronous or asynchronous.
- * @param {RetryOptions} [options={}] (optional) Options for configuring the retry mechanism.
- * @property {number} [options.retry=1] (optional) The maximum number of retries.
- * @property {number} [options.retryDelayMs=300] The base delay in milliseconds between retries.
- * @property {'exponential' | 'fixed'} [options.retryBackOff='exponential'] The backoff strategy. 'exponential' doubles the delay for each subsequent retry. 'fixed' uses a constant delay.
- * @property {boolean} [options.retryDelayJitter=true] If true, adds a random jitter to the delay to prevent thundering herd problem.
- * @property {number} [options.retryDelayJitterMax=100] The maximum jitter in milliseconds to add to the delay.
- * @property {(result: T | undefined, retryCount: number) => boolean} [options.retryIf] A function that is called after a successful execution of `func`. If it returns `true`, a retry is triggered. It receives the result and the current retry count.
- * @returns {Promise<T | undefined>} A promise that resolves with the result of the last successful execution of `func`.
- * If all retries fail (either by throwing an error or by the condition function always returning true),
- * it resolves with `undefined`. Errors thrown by `func` are caught and handled internally, not re-thrown.
+ * @template T The type of the value that the `func` resolves to.
+ *
+ * @param func The function to execute. It can be synchronous or asynchronous.
+ * @param options (optional) Configuration of the retry mechanism.
+ *
+ * The following options' default values can be configured to be EFFECTIVE GLOBALLY.
+ *
+ * ```typescript
+ * PromisE.retry.defaults = {
+ *     retry: 1,
+ *     retryBackOff: 'exponential',
+ *     retryDelay: 300,
+ *     retryDelayJitter: true,
+ *     retryDelayJitterMax: 100,
+ * }
+ * ```
+ * @param options.retry (optional) The maximum number of retries. Default: `1`
+ * @param options.retryBackOff (optional) The backoff strategy.
+ * Accepted values:
+ * - `'exponential'` doubles the delay for each subsequent retry.
+ * - `'linear'` uses a constant delay.
+ *
+ * Default: `'exponential'`
+ * @param options.retryDelayMs (optional) The base delay in milliseconds between retries.
+ *
+ * Default: `300`
+ * @param options.retryDelayJitter (optional) If true, adds a random jitter to the delay to prevent
+ * the thundering herd problem.
+ *
+ * Default: `true`
+ * @param options.retryDelayJitterMax The maximum jitter in milliseconds to add to the delay.
+ *
+ * Default: `100`
+ * @param options.retryIf (optional) A function that is called after a successful execution of `func`.
+ * If it returns `true`, a retry is triggered.
+ *
+ * **Arguments:**
+ * - `result`: result received after the most recent `func` excution
+ * - `retryCount`: number of times the execution has been retried (`total_attemts - 1`)
+ *
+ * If `retryIf()` throws error, the are handled gracefully and it's return value defaults `false` (no further retry).
+ *
+ * @returns A promise that resolves with the result of the last successful execution of `func`.
+ * If all retries fail (either by throwing an error or when `retryIf()` returned true in every time),
+ * it resolves with the last return value of `func()`. Errors thrown by `func` are caught and handled internally,
+ * only re-thrown if no result is received after maximum retries.
  */
 declare const retry: {
     <T>(func: () => ValueOrPromise<T>, options: RetryOptions<T>): Promise<T>;
+    /** Global default values */
     defaults: {
         retry: number;
         retryBackOff: "exponential";

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 } from "@superutils/core";
 
 // src/PromisEBase.ts
-import { asAny, fallbackIfFails, isFn, isPromise } from "@superutils/core";
+import { fallbackIfFails, isFn, isPromise } from "@superutils/core";
 var _PromisEBase = class _PromisEBase extends Promise {
   constructor(input) {
     if (input instanceof _PromisEBase) return input;
@@ -17,11 +17,11 @@ var _PromisEBase = class _PromisEBase extends Promise {
     let _reject;
     super((resolve, reject) => {
       _reject = (reason) => {
-        asAny(this).state = 2;
+        this._state = 2;
         reject(reason);
       };
       _resolve = (value) => {
-        asAny(this).state = 1;
+        this._state = 1;
         resolve(value);
       };
       input != null ? input : input = () => {
@@ -29,7 +29,7 @@ var _PromisEBase = class _PromisEBase extends Promise {
       const promise = isPromise(input) ? input : isFn(input) ? new globalThis.Promise(input) : Promise.resolve(input);
       promise.then(_resolve, _reject);
     });
-    this.state = 0;
+    this._state = 0;
     /**
      * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
     this.onEarlyFinalize = [];
@@ -66,15 +66,19 @@ var _PromisEBase = class _PromisEBase extends Promise {
   //
   /** Indicates if the promise is still pending/unfinalized */
   get pending() {
-    return this.state === 0;
+    return this._state === 0;
   }
   /** Indicates if the promise has been rejected */
   get rejected() {
-    return this.state === 2;
+    return this._state === 2;
   }
   /** Indicates if the promise has been resolved */
   get resolved() {
-    return this.state === 1;
+    return this._state === 1;
+  }
+  /** Get promise status code */
+  get state() {
+    return this._state;
   }
   // static withResolvers = <T = unknown>() => {
   // 	const pwr = globalThis.Promise.withResolvers<T>()
@@ -170,7 +174,6 @@ function deferred(options) {
   options = objCopy(defaults, options, [], "empty");
   let { onError, onIgnore, onResult } = options;
   const {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     delayMs,
     resolveError,
     // by default reject on error
@@ -259,7 +262,7 @@ function deferred(options) {
   return deferredFunc;
 }
 deferred.defaults = {
-  delayMs: -100,
+  delayMs: 100,
   resolveError: "REJECT" /* REJECT */,
   resolveIgnored: "WITH_LAST" /* WITH_LAST */
 };
@@ -284,7 +287,9 @@ function delay(duration = delay.defaults.duration, result = duration, asRejected
       result2 = (_a = fallbackIfFails3(result2, [], void 0)) != null ? _a : duration;
     if (!asRejected) return promise.resolve(result2);
     promise.reject(
-      result2 != null ? result2 : new Error(`${delay.defaults.delayTimeoutMsg} ${duration}ms`)
+      duration !== result2 && result2 !== void 0 ? result2 : new Error(
+        `${delay.defaults.delayTimeoutMsg} ${duration}ms`
+      )
     );
   };
   promise.timeoutId = setTimeout(() => finalize(result), duration);
@@ -296,7 +301,7 @@ function delay(duration = delay.defaults.duration, result = duration, asRejected
 delay.defaults = {
   /** Default delay duration in milliseconds */
   duration: 100,
-  /** Default timed out message */
+  /** Default timed out message (if `result` is not provided) */
   delayTimeoutMsg: "Timed out after"
 };
 var delay_default = delay;
@@ -353,7 +358,7 @@ var retry = async (func, options) => {
     }
     shouldRetry = maxRetries > 0 && retryCount < maxRetries && (!!error || !!await fallbackIfFails4(
       options.retryIf,
-      [result, retryCount, error],
+      [result, retryCount],
       false
     ));
   } while (shouldRetry);

package/package.json

@@ -4,7 +4,7 @@
 		"url": "https://github.com/alien45/superutils/issues"
 	},
 	"dependencies": {
-		"@superutils/core": "^1.0.5"
+		"@superutils/core": "^1.0.7"
 	},
 	"description": "An extended Promise with extra features such as status tracking, deferred/throttled execution, timeout and retry mechanism.",
 	"files": [
@@ -23,7 +23,7 @@
 	"main": "dist/index.js",
 	"name": "@superutils/promise",
 	"peerDpendencies": {
-		"@superutils/core": "^1.0.5"
+		"@superutils/core": "^1.0.7"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -43,5 +43,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.5"
+	"version": "1.0.7"
 }