@superutils/promise 1.0.3 → 1.0.6

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _superutils_core from '@superutils/core';
-import { ValueOrPromise, TimeoutId, ThrottleConfig, DeferredConfig } from '@superutils/core';
+import { ValueOrPromise, TimeoutId, PositiveNumber, ThrottleOptions, DeferredOptions } from '@superutils/core';
 
 interface IPromisE<T = unknown> extends Promise<T> {
     /** 0: pending, 1: resolved, 2: rejected */
@@ -77,25 +77,32 @@ type OnEarlyFinalize<T> = <TResolved extends boolean, TValue = TResolved extends
 type PromiseParams<T = unknown> = ConstructorParameters<typeof Promise<T>>;
 
 /** Return type of `PromisE.deferred()` */
-type DeferredReturn<TArgs extends unknown[] | [] = []> = <TResult = unknown>(promise: Promise<TResult> | ((...args: TArgs) => Promise<TResult>)) => IPromisE<TResult>;
-type DeferredOptions<ThisArg = unknown> = {
-    /** Delay in milliseconds, used for `debounce` and `throttle` modes. */
-    delayMs?: number;
+type DeferredAsyncCallback<TArgs extends unknown[] | [] = []> = <TResult = unknown>(promise: Promise<TResult> | ((...args: TArgs) => Promise<TResult>)) => IPromisE<TResult>;
+type DeferredAsyncGetPromise<T> = <TResult = T>() => Promise<TResult>;
+/** Default options used by `PromisE.deferred` and related functions */
+type DeferredAsyncDefaults = Pick<Required<DeferredAsyncOptions>, 'delayMs' | 'resolveError' | 'resolveIgnored'>;
+/** Options for `PromisE.deferred` and other related functions */
+type DeferredAsyncOptions<ThisArg = unknown, DelayMs extends number = number> = {
+    /**
+     * Delay in milliseconds, used for `debounce` and `throttle` modes.
+     *
+     * Default: `100`
+     */
     /** Callback invoked whenever promise/function throws error */
-    onError?: (err: unknown) => ValueOrPromise<unknown>;
+    onError?: (this: ThisArg, err: unknown) => ValueOrPromise<unknown>;
     /**
      * Whenever a promise/function is ignored when in debource/throttle mode, `onIgnored` wil be invoked.
      * The promise/function will not be invoked, unless it's manually invoked using the `ignored` function.
      * Use for debugging or logging purposes.
      */
-    onIgnore?: (ignored: () => Promise<unknown>) => ValueOrPromise<unknown>;
+    onIgnore?: (this: ThisArg, ignored: DeferredAsyncGetPromise<unknown>) => ValueOrPromise<unknown>;
     /**
      * Whenever a promise/function is executed successfully `onResult` will be called.
      * Those that are ignored but resolve with last will not cause `onResult` to be invoked.
      *
      * Result can be `undefined` if `ResolveIgnored.WITH_UNDEFINED` is used.
      */
-    onResult?: (result?: unknown) => ValueOrPromise<unknown>;
+    onResult?: (this: ThisArg, result?: any) => ValueOrPromise<unknown>;
     /**
      * Indicates what to do when a promise in the queue is ignored.
      * See {@link ResolveIgnored} for available options.
@@ -106,16 +113,18 @@ type DeferredOptions<ThisArg = unknown> = {
      * See {@link ResolveError} for available options.
      */
     resolveError?: ResolveError;
-    /** Enable throttle mode. Requires {@link DeferredOptions.delayMs}*/
-    throttle?: boolean;
+    /** The value to be used as "thisArg" whenever any of the callbacks are invoked */
+    thisArg?: ThisArg;
 } & (({
-    delayMs: number;
+    /** Throttle duration in milliseconds */
+    delayMs?: PositiveNumber<DelayMs>;
     throttle: true;
-} & ThrottleConfig<ThisArg>) | ({
-    delayMs?: number;
-    throttle?: false;
-} & DeferredConfig<ThisArg>));
-/** Options for what to do when deferred promise/function fails */
+} & Omit<ThrottleOptions, 'onError' | 'ThisArg' | 'tid'>) | ({
+    /** Debounce/deferred duration in milliseconds */
+    delayMs?: PositiveNumber<DelayMs>;
+    throttle?: false | undefined;
+} & Omit<DeferredOptions, 'onError' | 'ThisArg' | 'tid'>));
+/** Determines what to do when deferred promise/function fails */
 declare enum ResolveError {
     /** Neither resolve nor reject the failed */
     NEVER = "NEVER",
@@ -126,7 +135,10 @@ declare enum ResolveError {
     /** Resolve with undefined */
     WITH_UNDEFINED = "RESOLVE_UNDEFINED"
 }
-/** Options for what to do when a promise/callback is ignored, either because of being deferred, throttled or another been prioritized. */
+/**
+ * Determines what to do when a promise/callback is ignored, either because of being
+ * deferred, throttled or another been prioritized.
+ */
 declare enum ResolveIgnored {
     /** Never resolve ignored promises. Caution: make sure this doesn't cause any memory leaks. */
     NEVER = "NEVER",
@@ -136,22 +148,6 @@ declare enum ResolveIgnored {
     WITH_UNDEFINED = "WITH_UNDEFINED"
 }
 
-/** Global configuration */
-declare const config: {
-    /** Default value for `options` used by `PromisE.*deferred*` functions */
-    deferOptions: DeferredOptions;
-    delayTimeoutMsg: string;
-    retryOptions: {
-        retry: number;
-        retryBackOff: "exponential";
-        retryDelay: number;
-        retryDelayJitter: true;
-        retryDelayJitterMax: number;
-        retryIf: null;
-    };
-};
-type Config = typeof config;
-
 /** Options for automatic retry mechanism */
 type RetryOptions<T = unknown> = {
     /**
@@ -188,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);
+    retryIf?: null | ((prevResult: T | undefined, retryCount: number) => boolean | Promise<boolean>);
 };
 
 declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T> {
@@ -297,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
@@ -309,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
@@ -360,7 +368,14 @@ type TimeoutOptions<Func extends string = 'all'> = {
  * // `5000` will be printed in the console
  * ```
  */
-declare function deferred<T>(options?: DeferredOptions): DeferredReturn;
+declare function deferred<T, ThisArg = unknown, Delay extends number = number>(options?: DeferredAsyncOptions<ThisArg, Delay>): DeferredAsyncCallback;
+declare namespace deferred {
+    var defaults: {
+        delayMs: number;
+        resolveError: ResolveError.REJECT;
+        resolveIgnored: ResolveIgnored.WITH_LAST;
+    };
+}
 
 /**
  * @function PromisE.deferredCallback
@@ -394,18 +409,22 @@ declare function deferred<T>(options?: DeferredOptions): DeferredReturn;
  * // 200, 600, 1100
  * ```
  */
-declare function deferredCallback<TDefault, CbArgs extends unknown[] = unknown[]>(callback: (...args: CbArgs) => TDefault | Promise<TDefault>, options?: DeferredOptions): <TResult = TDefault>(...args: CbArgs) => IPromisE<TResult>;
+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
@@ -426,6 +445,14 @@ declare function deferredCallback<TDefault, CbArgs extends unknown[] = unknown[]
  * ```
  */
 declare function delay<T = number, TReject extends boolean = boolean>(duration?: number, result?: T | (() => T), asRejected?: TReject): IPromisE_Delay<T>;
+declare namespace delay {
+    var defaults: {
+        /** Default delay duration in milliseconds */
+        duration: number;
+        /** Default timed out message (if `result` is not provided) */
+        delayTimeoutMsg: string;
+    };
+}
 
 /**
  * @function    PromisE.delayReject
@@ -462,14 +489,16 @@ declare function delay<T = number, TReject extends boolean = boolean>(duration?:
 declare function delayReject<T = never>(duration: number, reason?: unknown): IPromisE_Delay<T>;
 
 /**
- * @function    PromisE.timeout
- * @summary times out a promise after specified timeout duration.
+ * Creates a new promise that wraps one or more promises and rejects if they do not settle within a
+ * specified timeout duration. When multiple promises are provided, they can be processed using methods like
+ *  `all` (default), `race`, `any`, or `allSettled`.
+ *
+ * @param timeout (optional) timeout duration in milliseconds.
+ * Default: `10000` (10 seconds)
  *
- * @param   timeout (optional) timeout duration in milliseconds.
- *                  Default: `10000` (10 seconds)
- * @param   values  promise/function: one or more promises as individual arguments
+ * @param values rest param containing one or more promises/values
  *
- * @example Example 1: single promise - resolved
+ * @example Wokring with a single promise: resolved succesfully
  * ```typescript
  * PromisE.timeout(
  *   5000, // timeout after 5000ms
@@ -478,7 +507,16 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  * // Result: 1000
  * ```
  *
- * @example Example 2: multiple promises - resolved
+ * @example Promise times out & rejected
+ * ```typescript
+ * PromisE.timeout(
+ *     5000, // timeout after 5000ms
+ *     PromisE.delay(20000), // resolves after 20000ms with value 20000
+ * ).catch(console.error)
+ * // Error: Error('Timed out after 5000ms')
+ *```
+ *
+ * @example Working with multiple promises, resolved using "PromisE.all()"
  *
  * ```typescript
  * PromisE.timeout(
@@ -490,17 +528,8 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  * // Result: [ 1000, 2000, 3000 ]
  * ```
  *
- * @example Example 3: timed out & rejected
- * ```typescript
- * PromisE.timeout(
- *     5000, // timeout after 5000ms
- *     PromisE.delay(20000), // resolves after 20000ms with value 20000
- * ).catch(console.error)
- * // Error: Error('Timed out after 5000ms')
- *```
- *
- * @example Example 4: timed out & but not rejected.
- * // Eg: when API request is taking longer than expected, print a message but not reject the promise.
+ * @example Promise times out & but not rejected.
+ * Eg: when API request is taking longer than expected, print a message avoid rejecting the promise.
  * ```typescript
  * const promise = PromisE.timeout(
  *     5000, // timeout after 5000ms
@@ -512,13 +541,48 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  *
  *     // promise timed out >> print/update UI
  *     console.log('Request is taking longer than expected......')
- *     // now return the data promise (the promise(s) provided in the PromisE.timeout())
+ *     // Now return the data promise which is the result of `PromisE.all(promises)` (default).
  *     return promise.data
  * })
  *```
+ *
+ * @example Multiple promises resolved using "PromisE.race()"
+ *
+ * ```typescript
+ * PromisE.timeout(
+ *     { // instead of `timeout: number` an object can be used for additional options
+ *         func: 'race', // tells PromisE.timeout to use `PromisE.race(promises)`
+ *         timeout: 5000, // timeout after 5000ms
+ *         timeoutMsg: 'My custom timed out message',
+ *     },
+ *     PromisE.delay(1000), // resolves after 1000ms with value 1000
+ *     PromisE.delay(2000), // resolves after 2000ms with value 2000
+ *     PromisE.delay(3000), // resolves after 3000ms with value 3000
+ * ).then(console.log)
+ * // Result: 1000 (Result of `Promise.race(promises)`)
+ * ```
+ */
+declare function timeout<T extends [unknown, ...unknown[]], // require at least one value
+Result = T['length'] extends 1 ? Awaited<T[0]> : Awaited<T[number]>[]>(timeout: number, ...values: T): IPromisE_Timeout<Result>;
+/**
+ *
+ * @param options An options object can be passed with one or more of the following properties:
+ * @param options.func (optional) Name of the `PromisE` method to be used to combine the `values`.
+ * Only used when more than one promise is provided.
+ *
+ * Accepted values:
+ * 1. `'all'` **(default)**: for `PromisE.all`
+ * 2. `'allSettled'`: for `PromisE.allSettled`
+ * 3. `'any'`: for `PromisE.any`
+ * 4. `'race'`: for `PromisE.race`
+ *
+ * @param options.timeout (optional) timeout duration in milliseconds. Default: `10_000` (10 seconds)
+ * @param options.timeoutMsg (optional) custom error message to be used when promises timeout.
+ *
+ * @param values
  */
 declare function timeout<T extends [unknown, ...unknown[]], // require at least one value
-TFunc extends keyof TimeoutFunc<T>, Result = T['length'] extends 1 ? Awaited<T[0]> : Awaited<ReturnType<TimeoutFunc<T>[TFunc]>>>(timeout: number | TimeoutOptions<TFunc>, ...values: T): IPromisE_Timeout<Result>;
+TFunc extends keyof TimeoutFunc<T>, Result = T['length'] extends 1 ? Awaited<T[0]> : Awaited<ReturnType<TimeoutFunc<T>[TFunc]>>>(options: TimeoutOptions<TFunc>, ...values: T): IPromisE_Timeout<Result>;
 declare namespace timeout {
     var defaultOptions: Required<TimeoutOptions>;
 }
@@ -564,29 +628,25 @@ declare namespace timeout {
  * ```
  */
 declare class PromisE<T = unknown> extends PromisEBase<T> {
-    /** Global configuration & default values */
-    static config: {
-        deferOptions: DeferredOptions;
-        delayTimeoutMsg: string;
-        retryOptions: {
+    static deferred: typeof deferred;
+    static deferredCallback: typeof deferredCallback;
+    static delay: typeof delay;
+    static delayReject: typeof delayReject;
+    static retry: {
+        <T_1>(func: () => _superutils_core.ValueOrPromise<T_1>, options: RetryOptions<T_1>): Promise<T_1>;
+        defaults: {
             retry: number;
             retryBackOff: "exponential";
             retryDelay: number;
             retryDelayJitter: true;
             retryDelayJitterMax: number;
-            retryIf: null;
         };
     };
-    static deferred: typeof deferred;
-    static deferredCallback: typeof deferredCallback;
-    static delay: typeof delay;
-    static delayReject: typeof delayReject;
-    static retry: <T_1>(func: () => _superutils_core.ValueOrPromise<T_1>, options?: RetryOptions<T_1>) => Promise<T_1>;
     static timeout: typeof timeout;
 }
 
 /**
- * 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.
@@ -596,19 +656,63 @@ 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>;
+declare const retry: {
+    <T>(func: () => ValueOrPromise<T>, options: RetryOptions<T>): Promise<T>;
+    /** Global default values */
+    defaults: {
+        retry: number;
+        retryBackOff: "exponential";
+        retryDelay: number;
+        retryDelayJitter: true;
+        retryDelayJitterMax: number;
+    };
+};
 
-export { type Config, type DeferredOptions, type DeferredReturn, type IPromisE, type IPromisE_Delay, type IPromisE_Timeout, type OnEarlyFinalize, PromisE, PromisEBase, type PromiseParams, ResolveError, ResolveIgnored, type RetryOptions, type TimeoutFunc, type TimeoutOptions, config, PromisE as default, deferred, deferredCallback, delay, delayReject, retry, timeout };
+export { type DeferredAsyncCallback, type DeferredAsyncDefaults, type DeferredAsyncGetPromise, type DeferredAsyncOptions, type IPromisE, type IPromisE_Delay, type IPromisE_Timeout, type OnEarlyFinalize, PromisE, PromisEBase, type PromiseParams, ResolveError, ResolveIgnored, type RetryOptions, type TimeoutFunc, type TimeoutOptions, PromisE as default, deferred, deferredCallback, delay, delayReject, retry, timeout };

package/dist/index.js

@@ -1,46 +1,10 @@
-// src/types/deferred.ts
-var ResolveError = /* @__PURE__ */ ((ResolveError2) => {
-  ResolveError2["NEVER"] = "NEVER";
-  ResolveError2["REJECT"] = "REJECT";
-  ResolveError2["WITH_ERROR"] = "RESOLVE_ERROR";
-  ResolveError2["WITH_UNDEFINED"] = "RESOLVE_UNDEFINED";
-  return ResolveError2;
-})(ResolveError || {});
-var ResolveIgnored = /* @__PURE__ */ ((ResolveIgnored2) => {
-  ResolveIgnored2["NEVER"] = "NEVER";
-  ResolveIgnored2["WITH_LAST"] = "WITH_LAST";
-  ResolveIgnored2["WITH_UNDEFINED"] = "WITH_UNDEFINED";
-  return ResolveIgnored2;
-})(ResolveIgnored || {});
-
-// src/config.ts
-var config = {
-  /** Default value for `options` used by `PromisE.*deferred*` functions */
-  deferOptions: {
-    delayMs: 100,
-    resolveError: "REJECT" /* REJECT */,
-    resolveIgnored: "WITH_LAST" /* WITH_LAST */,
-    throttle: false
-  },
-  delayTimeoutMsg: "Timed out after",
-  retryOptions: {
-    retry: 1,
-    retryBackOff: "exponential",
-    retryDelay: 300,
-    retryDelayJitter: true,
-    retryDelayJitterMax: 100,
-    retryIf: null
-  }
-};
-var config_default = config;
-
 // src/deferred.ts
 import {
   deferred as deferredCore,
   fallbackIfFails as fallbackIfFails2,
-  forceCast,
   isFn as isFn2,
   isPositiveNumber,
+  objCopy,
   throttled as throttledCore
 } from "@superutils/core";
 
@@ -185,17 +149,33 @@ _PromisEBase.withResolvers = () => {
 var PromisEBase = _PromisEBase;
 var PromisEBase_default = PromisEBase;
 
+// src/types/deferred.ts
+var ResolveError = /* @__PURE__ */ ((ResolveError2) => {
+  ResolveError2["NEVER"] = "NEVER";
+  ResolveError2["REJECT"] = "REJECT";
+  ResolveError2["WITH_ERROR"] = "RESOLVE_ERROR";
+  ResolveError2["WITH_UNDEFINED"] = "RESOLVE_UNDEFINED";
+  return ResolveError2;
+})(ResolveError || {});
+var ResolveIgnored = /* @__PURE__ */ ((ResolveIgnored2) => {
+  ResolveIgnored2["NEVER"] = "NEVER";
+  ResolveIgnored2["WITH_LAST"] = "WITH_LAST";
+  ResolveIgnored2["WITH_UNDEFINED"] = "WITH_UNDEFINED";
+  return ResolveIgnored2;
+})(ResolveIgnored || {});
+
 // src/deferred.ts
-function deferred(options = {}) {
-  const defaults = config_default.deferOptions;
+function deferred(options) {
+  const { defaults } = deferred;
+  options = objCopy(defaults, options, [], "empty");
   let { onError, onIgnore, onResult } = options;
   const {
-    delayMs = defaults.delayMs,
-    resolveError = defaults.resolveError,
+    delayMs,
+    resolveError,
     // by default reject on error
-    resolveIgnored = defaults.resolveIgnored,
+    resolveIgnored,
     thisArg,
-    throttle = defaults.throttle
+    throttle
   } = options;
   let lastPromisE = null;
   const queue = /* @__PURE__ */ new Map();
@@ -273,10 +253,15 @@ function deferred(options = {}) {
     qItem.started = false;
     queue.set(id, qItem);
     if (gotDelay || !lastPromisE) execute(id, qItem);
-    return forceCast(qItem);
+    return qItem;
   };
   return deferredFunc;
 }
+deferred.defaults = {
+  delayMs: 100,
+  resolveError: "REJECT" /* REJECT */,
+  resolveIgnored: "WITH_LAST" /* WITH_LAST */
+};
 var deferred_default = deferred;
 
 // src/deferredCallback.ts
@@ -290,7 +275,7 @@ var deferredCallback_default = deferredCallback;
 
 // src/delay.ts
 import { fallbackIfFails as fallbackIfFails3, isFn as isFn3 } from "@superutils/core";
-function delay(duration = 100, result = duration, asRejected = false) {
+function delay(duration = delay.defaults.duration, result = duration, asRejected = false) {
   const promise = new PromisEBase_default();
   const finalize = (result2) => {
     var _a;
@@ -298,7 +283,9 @@ function delay(duration = 100, result = duration, asRejected = false) {
       result2 = (_a = fallbackIfFails3(result2, [], void 0)) != null ? _a : duration;
     if (!asRejected) return promise.resolve(result2);
     promise.reject(
-      result2 != null ? result2 : new Error(`${config_default.delayTimeoutMsg} ${duration}ms`)
+      duration !== result2 && result2 !== void 0 ? result2 : new Error(
+        `${delay.defaults.delayTimeoutMsg} ${duration}ms`
+      )
     );
   };
   promise.timeoutId = setTimeout(() => finalize(result), duration);
@@ -307,6 +294,12 @@ function delay(duration = 100, result = duration, asRejected = false) {
   }).finally(() => promise.pause());
   return promise;
 }
+delay.defaults = {
+  /** Default delay duration in milliseconds */
+  duration: 100,
+  /** Default timed out message (if `result` is not provided) */
+  delayTimeoutMsg: "Timed out after"
+};
 var delay_default = delay;
 
 // src/delayReject.ts
@@ -316,42 +309,65 @@ function delayReject(duration, reason) {
 var delayReject_default = delayReject;
 
 // src/retry.ts
-import { isPositiveInteger } from "@superutils/core";
-var retry = async (func, options = {}) => {
-  const d = config_default.retryOptions;
+import {
+  fallbackIfFails as fallbackIfFails4,
+  isEmpty,
+  isPositiveInteger,
+  objCopy as objCopy2
+} from "@superutils/core";
+var retry = async (func, options) => {
+  options = objCopy2(retry.defaults, options != null ? options : {}, [], (key, value) => {
+    switch (key) {
+      // case 'retryDelayJitter':
+      // 	return true
+      case "retry":
+      // eslint-disable-next-line no-fallthrough
+      case "retryDelay":
+      case "retryDelayJitterMax":
+        return value !== 0 && !isPositiveInteger(value);
+    }
+    return !!isEmpty(value);
+  });
   const {
-    retryIf,
-    retryBackOff = d.retryBackOff,
-    retryDelayJitter = d.retryDelayJitter
+    retry: maxRetries,
+    retryBackOff,
+    retryDelay,
+    retryDelayJitter,
+    retryDelayJitterMax
   } = options;
-  let {
-    retry: maxRetries = d.retry,
-    retryDelay: delayMs,
-    retryDelayJitterMax: jitterMax
-  } = options;
-  if (maxRetries !== 0 && !isPositiveInteger(maxRetries)) maxRetries = d.retry;
-  if (!isPositiveInteger(delayMs)) delayMs = d.retryDelay;
-  if (!isPositiveInteger(jitterMax)) jitterMax = d.retryDelayJitterMax;
+  let _retryDelay = retryDelay;
   let retryCount = -1;
   let result;
   let error;
   let shouldRetry = false;
   do {
     retryCount++;
-    if (retryBackOff === "exponential" && retryCount > 1) delayMs *= 2;
-    if (retryDelayJitter) delayMs += Math.floor(Math.random() * jitterMax);
-    retryCount > 0 && await delay_default(delayMs);
+    if (retryBackOff === "exponential" && retryCount > 1) _retryDelay *= 2;
+    if (retryDelayJitter)
+      _retryDelay += Math.floor(Math.random() * retryDelayJitterMax);
+    retryCount > 0 && await delay_default(_retryDelay);
     try {
       error = void 0;
       result = await func();
     } catch (err) {
       error = err;
     }
-    shouldRetry = maxRetries > 0 && retryCount < maxRetries && (!!error || !!(retryIf == null ? void 0 : retryIf(result, retryCount, error)));
+    shouldRetry = maxRetries > 0 && retryCount < maxRetries && (!!error || !!await fallbackIfFails4(
+      options.retryIf,
+      [result, retryCount],
+      false
+    ));
   } while (shouldRetry);
   if (error !== void 0) return Promise.reject(error);
   return result;
 };
+retry.defaults = {
+  retry: 1,
+  retryBackOff: "exponential",
+  retryDelay: 300,
+  retryDelayJitter: true,
+  retryDelayJitterMax: 100
+};
 var retry_default = retry;
 
 // src/timeout.ts
@@ -397,8 +413,6 @@ var timeout_default = timeout;
 // src/PromisE.ts
 var PromisE = class extends PromisEBase_default {
 };
-/** Global configuration & default values */
-PromisE.config = config_default;
 PromisE.deferred = deferred_default;
 PromisE.deferredCallback = deferredCallback_default;
 PromisE.delay = delay_default;
@@ -414,7 +428,6 @@ export {
   PromisEBase,
   ResolveError,
   ResolveIgnored,
-  config,
   index_default as default,
   deferred,
   deferredCallback,

package/package.json

@@ -4,9 +4,9 @@
 		"url": "https://github.com/alien45/superutils/issues"
 	},
 	"dependencies": {
-		"@superutils/core": "1.0.3"
+		"@superutils/core": "^1.0.5"
 	},
-	"description": "An extended Promise class with extra features and utilities.",
+	"description": "An extended Promise with extra features such as status tracking, deferred/throttled execution, timeout and retry mechanism.",
 	"files": [
 		"dist",
 		"README.md",
@@ -23,7 +23,7 @@
 	"main": "dist/index.js",
 	"name": "@superutils/promise",
 	"peerDpendencies": {
-		"@superutils/core": "1.0.3"
+		"@superutils/core": "^1.0.5"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -37,10 +37,11 @@
 		"_watch": "tsc -p tsconfig.json --watch",
 		"build": "tsup src/index.ts --format esm --dts --clean --config ../../tsup.config.js",
 		"dev": "npm run build -- --watch",
+		"start": "npm run build -- --watch",
 		"test": "cd ../../ && npm run test promise"
 	},
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.3"
+	"version": "1.0.6"
 }