@superutils/promise 1.0.5 → 1.0.6

package/dist/index.d.ts

@@ -184,7 +184,7 @@ 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> {
@@ -293,7 +293,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 +336,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 +412,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 duration duration in milliseconds. Default: `100`
+ * @param result (optional) specify a value to resolve or error to reject with.
  *
- * @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.
+ * Alternatively, a function (with no arguments) can be provided that returns the result.
  *
- * @returns See {@link IPromisE_Delay}
+ * 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 +449,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 +646,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 +656,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

@@ -170,7 +170,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 +258,7 @@ function deferred(options) {
   return deferredFunc;
 }
 deferred.defaults = {
-  delayMs: -100,
+  delayMs: 100,
   resolveError: "REJECT" /* REJECT */,
   resolveIgnored: "WITH_LAST" /* WITH_LAST */
 };
@@ -284,7 +283,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 +297,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 +354,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

@@ -43,5 +43,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.5"
+	"version": "1.0.6"
 }