@superutils/promise 1.0.1 → 1.0.3

package/README.md

@@ -1,9 +1,15 @@
-# @superutils/promise
+# [@superutils/promise](https://www.npmjs.com/package/@superutils/promise)
 
 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.
 
+<div v-if="false">
+
+For full API reference check out the [docs page](https://alien45.github.io/superutils/packages/@superutils/promise/).
+
+</div>
+
 ## Table of Contents
 
 - [Features](#features)

package/dist/index.d.ts

@@ -101,6 +101,10 @@ type DeferredOptions<ThisArg = unknown> = {
      * See {@link ResolveIgnored} for available options.
      */
     resolveIgnored?: ResolveIgnored;
+    /**
+     * What do to when an executed function/promise throws error
+     * See {@link ResolveError} for available options.
+     */
     resolveError?: ResolveError;
     /** Enable throttle mode. Requires {@link DeferredOptions.delayMs}*/
     throttle?: boolean;
@@ -187,6 +191,108 @@ type RetryOptions<T = unknown> = {
     retryIf?: null | ((prevResult: T | undefined, retryCount: number, error?: unknown) => boolean);
 };
 
+declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T> {
+    readonly state: 0 | 1 | 2;
+    private _resolve?;
+    private _reject?;
+    /**
+     * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
+    onEarlyFinalize: OnEarlyFinalize<T>[];
+    /** Create a PromisE instance as a drop-in replacement for Promise */
+    constructor(...args: PromiseParams<T>);
+    /** Extend an existing Promise instance to check status or finalize early */
+    constructor(promise: Promise<T>);
+    /** Create a resolved promise with value */
+    constructor(value: T);
+    /**
+     * If executor function is not provided, the promise must be resolved/rejected externally.
+     *
+     * @example An alternative to "Promise.withResolvers()"
+     * ```typescript
+     * // create a promise that will NEVER finalize automatically
+     * const p = new PromisE<number>()
+     * // resolve it manually
+     * setTimeout(() => p.resolve(1), 1000)
+     * p.then(console.log)
+     * ```
+     */
+    constructor();
+    /** Indicates if the promise is still pending/unfinalized */
+    get pending(): boolean;
+    /** Indicates if the promise has been rejected */
+    get rejected(): boolean;
+    /** Indicates if the promise has been resolved */
+    get resolved(): boolean;
+    /** Resovle pending promise early. */
+    resolve: (value: T | PromiseLike<T>) => void;
+    /** Reject pending promise early. */
+    reject: (reason: unknown) => void;
+    /** Sugar for `new PromisE(Promise.all(...))` */
+    static all: <T_1 extends unknown[]>(values: T_1) => IPromisE<{ -readonly [P in keyof T_1]: Awaited<T_1[P]>; }>;
+    /** Sugar for `new PromisE(Promise.allSettled(...))` */
+    static allSettled: <T_1 extends unknown[]>(values: T_1) => IPromisE<PromiseSettledResult<Awaited<T_1[number]>>[]>;
+    /** Sugar for `new PromisE(Promise.any(...))` */
+    static any: <T_1 extends unknown[]>(values: T_1) => IPromisE<Awaited<T_1[number]>>;
+    /** Sugar for `new PromisE(Promise.race(..))` */
+    static race: <T_1 extends unknown[]>(values: T_1) => IPromisE<Awaited<T_1[number]>>;
+    /** Extends Promise.reject */
+    static reject: <T_1 = never>(reason: unknown) => IPromisE<T_1>;
+    /** Sugar for `new PromisE(Promise.resolve(...))` */
+    static resolve: <T_1>(value?: T_1 | PromiseLike<T_1>) => IPromisE<T_1>;
+    /** Sugar for `new PromisE(Promise.try(...))` */
+    static try: <T_1, U extends unknown[]>(callbackFn: (...args: U) => T_1 | PromiseLike<T_1>, ...args: U) => IPromisE<Awaited<T_1>>;
+    /**
+     * Creates a `PromisE` instance and returns it in an object, along with its `resolve` and `reject` functions.
+     *
+     * NB: this function is technically no longer needed because the `PromisE` class already comes with the resolvers.
+     *
+     * ---
+     * @example
+     * Using `PromisE` directly: simply provide an empty function as the executor
+     *
+     * ```typescript
+     * import PromisE from '@superutils/promise'
+     * const promisE = new PromisE<number>(() => {})
+     * setTimeout(() => promisE.resolve(1), 1000)
+     * promisE.then(console.log)
+     * ```
+     *
+     * @example
+     * Using `withResolvers`
+     * ```typescript
+     * import PromisE from '@superutils/promise'
+     * const pwr = PromisE.withResolvers<number>()
+     * setTimeout(() => pwr.resolve(1), 1000)
+     * pwr.promise.then(console.log)
+     * ```
+     */
+    static withResolvers: <T_1 = unknown>() => {
+        promise: IPromisE<T_1>;
+        reject: (reason: unknown) => void;
+        resolve: (value: T_1 | PromiseLike<T_1>) => void;
+    };
+}
+
+type TimeoutFunc<T extends unknown[]> = {
+    all: typeof PromisEBase.all<T>;
+    allSettled: typeof PromisEBase.allSettled<T>;
+    any: typeof PromisEBase.any<T>;
+    race: typeof PromisEBase.race<T>;
+};
+/**
+ * `PromisE.timeout` options
+ *
+ * @param func (optional) name of the supported `PromieBase` static method. Default: `"all"`
+ * @param timeout (optional) timeout duration in milliseconds. Default: `10_000` (10 seconds)
+ * @param timeoutMsg (optional) timeout error message. Default: `"Timed out after 10000ms"`
+ *
+ */
+type TimeoutOptions<Func extends string = 'all'> = {
+    func: Func;
+    timeout?: number;
+    timeoutMsg?: string;
+};
+
 /**
  * @function PromisE.deferred
  * The adaptation of the `deferred()` function tailored for Promises.
@@ -266,58 +372,27 @@ declare function deferred<T>(options?: DeferredOptions): DeferredReturn;
  *
  * @example Debounce/deferred event handler
  * ```typescript
- * const handleChange = (e: { target: { value: number }}) => console.log(e.target.value)
+ * import PromisE from '@superutils/promise'
+ *
+ * // Input change handler
+ * const handleChange = (e: { target: { value: number } }) =>
+ * 	   console.log(e.target.value)
+ * // Change handler with `PromisE.deferred()`
  * const handleChangeDeferred = PromisE.deferredCallback(handleChange, {
- *     delayMs: 300,
- *     throttle: false,
+ * 	   delayMs: 300,
+ * 	   throttle: false,
  * })
- * // simulate click events call after prespecified delay
- * const delays = [
- *     100,
- *     150,
- *     200,
- *     550,
- *     580,
- *     600,
- *     1000,
- *     1100,
- * ]
+ * // Simulate input change events after prespecified delays
+ * const delays = [100, 150, 200, 550, 580, 600, 1000, 1100]
  * delays.forEach(timeout =>
- *     setTimeout(() => handleChangeDeferred({
- *        target: { value: timeout }
- *     }), timeout)
+ * 	   setTimeout(
+ * 	   	   () => handleChangeDeferred({ target: { value: timeout } }),
+ * 	   	   timeout,
+ * 	   ),
  * )
- *
- *
  * // Prints:
  * // 200, 600, 1100
  * ```
- *
- * @example  Throttled event handler
- * ```typescript
- * const handleChange = (e: { target: { value: number }}) => console.log(e.target.value)
- * const handleChangeDeferred = PromisE.deferredCallback(handleChange, {
- *     delayMs: 300,
- *     throttle: true,
- * })
- * // simulate click events call after prespecified delay
- * const delays = [
- *     100,
- *     150,
- *     200,
- *     550,
- *     580,
- *     600,
- *     1000,
- *     1100,
- * ]
- * delays.forEach(timeout =>
- *     setTimeout(() => handleChangeDeferred({
- *        target: { value: timeout }
- *     }), timeout)
- * )
- * // Prints: 100, 550, 1100
- * ```
  */
 declare function deferredCallback<TDefault, CbArgs extends unknown[] = unknown[]>(callback: (...args: CbArgs) => TDefault | Promise<TDefault>, options?: DeferredOptions): <TResult = TDefault>(...args: CbArgs) => IPromisE<TResult>;
 
@@ -386,88 +461,6 @@ declare function delay<T = number, TReject extends boolean = boolean>(duration?:
  */
 declare function delayReject<T = never>(duration: number, reason?: unknown): IPromisE_Delay<T>;
 
-declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T> {
-    readonly state: 0 | 1 | 2;
-    private _resolve?;
-    private _reject?;
-    /**
-     * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
-    onEarlyFinalize: OnEarlyFinalize<T>[];
-    /** Create a PromisE instance as a drop-in replacement for Promise */
-    constructor(...args: PromiseParams<T>);
-    /** Extend an existing Promise instance to check status or finalize early */
-    constructor(promise: Promise<T>);
-    /** Create a resolved promise with value */
-    constructor(value: T);
-    /**
-     * If executor function is not provided, the promise must be resolved/rejected externally.
-     *
-     * @example An alternative to "Promise.withResolvers()"
-     * ```typescript
-     * // create a promise that will NEVER finalize automatically
-     * const p = new PromisE<number>()
-     * // resolve it manually
-     * setTimeout(() => p.resolve(1), 1000)
-     * p.then(console.log)
-     * ```
-     */
-    constructor();
-    /** Indicates if the promise is still pending/unfinalized */
-    get pending(): boolean;
-    /** Indicates if the promise has been rejected */
-    get rejected(): boolean;
-    /** Indicates if the promise has been resolved */
-    get resolved(): boolean;
-    /** Resovle pending promise early. */
-    resolve: (value: T | PromiseLike<T>) => void;
-    /** Reject pending promise early. */
-    reject: (reason: unknown) => void;
-    /** Sugar for `new PromisE(Promise.all(...))` */
-    static all: <T_1 extends readonly unknown[] | []>(values: T_1) => IPromisE<{ -readonly [P in keyof T_1]: Awaited<T_1[P]>; }>;
-    /** Sugar for `new PromisE(Promise.allSettled(...))` */
-    static allSettled: <T_1 extends unknown[]>(values: T_1) => IPromisE<PromiseSettledResult<Awaited<T_1[number]>>[]>;
-    /** Sugar for `new PromisE(Promise.any(...))` */
-    static any: <T_1 extends unknown[]>(values: T_1) => IPromisE<T_1[number]>;
-    /** Sugar for `new PromisE(Promise.race(..))` */
-    static race: <T_1>(values: T_1[]) => IPromisE<Awaited<T_1>>;
-    /** Extends Promise.reject */
-    static reject: <T_1 = never>(reason: unknown) => IPromisE<T_1>;
-    /** Sugar for `new PromisE(Promise.resolve(...))` */
-    static resolve: <T_1>(value?: T_1 | PromiseLike<T_1>) => IPromisE<T_1>;
-    /** Sugar for `new PromisE(Promise.try(...))` */
-    static try: <T_1, U extends unknown[]>(callbackFn: (...args: U) => T_1 | PromiseLike<T_1>, ...args: U) => IPromisE<Awaited<T_1>>;
-    /**
-     * Creates a `PromisE` instance and returns it in an object, along with its `resolve` and `reject` functions.
-     *
-     * NB: this function is technically no longer needed because the `PromisE` class already comes with the resolvers.
-     *
-     * ---
-     * @example
-     * Using `PromisE` directly: simply provide an empty function as the executor
-     *
-     * ```typescript
-     * import PromisE from '@superutils/promise'
-     * const promisE = new PromisE<number>(() => {})
-     * setTimeout(() => promisE.resolve(1), 1000)
-     * promisE.then(console.log)
-     * ```
-     *
-     * @example
-     * Using `withResolvers`
-     * ```typescript
-     * import PromisE from '@superutils/promise'
-     * const pwr = PromisE.withResolvers<number>()
-     * setTimeout(() => pwr.resolve(1), 1000)
-     * pwr.promise.then(console.log)
-     * ```
-     */
-    static withResolvers: <T_1 = unknown>() => {
-        promise: IPromisE<T_1>;
-        reject: (reason: unknown) => void;
-        resolve: (value: T_1 | PromiseLike<T_1>) => void;
-    };
-}
-
 /**
  * @function    PromisE.timeout
  * @summary times out a promise after specified timeout duration.
@@ -524,7 +517,11 @@ declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T>
  * })
  *```
  */
-declare function timeout<T extends unknown[] | [], TOut = T['length'] extends 1 ? T[0] : T>(timeout?: number, ...values: Promise<TOut>[]): IPromisE_Timeout<TOut>;
+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>;
+declare namespace timeout {
+    var defaultOptions: Required<TimeoutOptions>;
+}
 
 /**
  * An attempt to solve the problem of Promise status (pending/resolved/rejected) not being easily accessible externally.
@@ -614,4 +611,4 @@ declare class PromisE<T = unknown> extends PromisEBase<T> {
  */
 declare const retry: <T>(func: () => ValueOrPromise<T>, options?: RetryOptions<T>) => Promise<T>;
 
-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, config, PromisE as default, deferred, deferredCallback, delay, delayReject, retry, timeout };
+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 };

package/dist/index.js

@@ -325,13 +325,13 @@ var retry = async (func, options = {}) => {
     retryDelayJitter = d.retryDelayJitter
   } = options;
   let {
-    retry: maxRetries = 1,
+    retry: maxRetries = d.retry,
     retryDelay: delayMs,
     retryDelayJitterMax: jitterMax
   } = options;
-  maxRetries = maxRetries >= 0 ? maxRetries : d.retry;
-  delayMs = isPositiveInteger(delayMs) ? delayMs : d.retryDelay;
-  jitterMax = isPositiveInteger(jitterMax) ? jitterMax : d.retryDelayJitterMax;
+  if (maxRetries !== 0 && !isPositiveInteger(maxRetries)) maxRetries = d.retry;
+  if (!isPositiveInteger(delayMs)) delayMs = d.retryDelay;
+  if (!isPositiveInteger(jitterMax)) jitterMax = d.retryDelayJitterMax;
   let retryCount = -1;
   let result;
   let error;
@@ -347,7 +347,7 @@ var retry = async (func, options = {}) => {
     } catch (err) {
       error = err;
     }
-    shouldRetry = maxRetries > 0 && (!!error || !!(retryIf == null ? void 0 : retryIf(result, retryCount, error))) && retryCount < maxRetries;
+    shouldRetry = maxRetries > 0 && retryCount < maxRetries && (!!error || !!(retryIf == null ? void 0 : retryIf(result, retryCount, error)));
   } while (shouldRetry);
   if (error !== void 0) return Promise.reject(error);
   return result;
@@ -355,11 +355,22 @@ var retry = async (func, options = {}) => {
 var retry_default = retry;
 
 // src/timeout.ts
-function timeout(timeout2 = 1e4, ...values) {
-  const dataPromise = values.length === 1 ? new PromisEBase_default(values[0]) : PromisEBase_default.all(values);
+import { isFn as isFn4, isObj, isPositiveNumber as isPositiveNumber2 } from "@superutils/core";
+function timeout(timeout2, ...values) {
+  var _a, _b;
+  let funcName = "all";
+  let timeoutMsg = "";
+  if (isObj(timeout2)) {
+    funcName = timeout2.func;
+    timeoutMsg = (_a = timeout2.timeoutMsg) != null ? _a : "";
+    timeout2 = (_b = timeout2.timeout) != null ? _b : 1e4;
+  }
+  timeout2 = isPositiveNumber2(timeout2) && timeout2 || 1e4;
+  const func = isFn4(PromisEBase_default[funcName]) ? PromisEBase_default[funcName] : PromisEBase_default.all;
+  const dataPromise = values.length <= 1 ? new PromisEBase_default(values == null ? void 0 : values[0]) : func(values);
   const timeoutPromise = delayReject_default(
     timeout2,
-    new Error(`Timed out after ${timeout2}ms`)
+    new Error(timeoutMsg || `Timed out after ${timeout2}ms`)
   );
   const promise = PromisEBase_default.race([
     dataPromise,
@@ -372,9 +383,15 @@ function timeout(timeout2 = 1e4, ...values) {
     get: () => promise.timeout.rejected
   });
   dataPromise.catch(() => {
-  }).finally(promise.clearTimeout);
+  }).finally(() => {
+    promise.clearTimeout();
+  });
   return promise;
 }
+timeout.defaultOptions = {
+  func: "all",
+  timeout: 1e4
+};
 var timeout_default = timeout;
 
 // src/PromisE.ts

package/package.json

@@ -4,7 +4,7 @@
 		"url": "https://github.com/alien45/superutils/issues"
 	},
 	"dependencies": {
-		"@superutils/core": "^1.0.1"
+		"@superutils/core": "1.0.3"
 	},
 	"description": "An extended Promise class with extra features and utilities.",
 	"files": [
@@ -12,7 +12,7 @@
 		"README.md",
 		"LICENSE"
 	],
-	"homepage": "https://github.com/alien45/superutils/#readme",
+	"homepage": "https://alien45.github.io/superutils/packages/@superutils/promise/",
 	"keywords": [
 		"promise",
 		"async",
@@ -23,7 +23,7 @@
 	"main": "dist/index.js",
 	"name": "@superutils/promise",
 	"peerDpendencies": {
-		"@superutils/core": "^1.0.1"
+		"@superutils/core": "1.0.3"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -37,10 +37,10 @@
 		"_watch": "tsc -p tsconfig.json --watch",
 		"build": "tsup src/index.ts --format esm --dts --clean --config ../../tsup.config.js",
 		"dev": "npm run build -- --watch",
-		"test": "vitest"
+		"test": "cd ../../ && npm run test promise"
 	},
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.1"
+	"version": "1.0.3"
 }