@superutils/promise 1.1.5 → 1.2.0

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 practical 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, auto-retry and timeout.
 
 <div v-if="false">
 
@@ -16,39 +16,52 @@ For full API reference check out the [docs page](https://alien45.github.io/super
 - [Installation](#installation)
 - [Usage](#usage)
     - [`new PromisE(executor)`](#promise-executor): Drop-in replacement for `Promise`
-    - [`new PromisE(promise)`](#promise-status): Check promise status
+        - [Status tracking](#status-tracking)
+        - [Early Finalization](#early-finalization)
+    - [`new PromisE(promise)`](#promise-status): Check status of an existing promise.
     - [`PromisE.try()`](#static-methods): Static methods
     - [`PromisE.delay()`](#delay): Async delay
     - [`PromisE.deferred()`](#deferred): Async debounced/throttled callback
+        - [Debounce Example](#debounce-example)
+        - [Throttle Example](#throttle-example)
+        - [Behavior with different `options`](#behavior-with-different-options)
     - [`PromisE.timeout()`](#timeout): Reject after timeout
 
 ## Features
 
 - **Promise Status**: Easily check if a promise is `pending`, `resolved`, or `rejected`.
 - **Deferred Execution**: Defer or throttle promise-based function calls with `PromisE.deferred()`.
-- **Auto-cancellable Fetch**: Automatically abort pending requests when subsequent requests are made using `PromisE.deferredFetch()` and `PromisE.deferredPost()`.
-- **Auto-cancellable Fetch**: The `PromisE.deferredFetch` and `PromisE.deferredPost` utilities automatically abort pending requests when a new deferred/throttled call is made.
 - **Timeouts**: Wrap any promise with a timeout using `PromisE.timeout()`.
 - **Rich Utilities**: A collection of static methods like `.all()`, `.race()`, `.delay()`, and more, all returning `PromisE` instances.
 
 ## Installation
 
 ```bash
-npm install @superutils/core @superutils/promise
+npm install @superutils/promise
 ```
 
+Dependency: `@superutils/core` will be automatically installed by NPM
+
 ## Usage
 
 <div id="promise-executor"></div>
 
 ### `new PromisE(executor)`: Drop-in replacement for `Promise`
 
-The `PromisE` class can be used just like the native `Promise`. The key difference is the addition of status properties:
+The `PromisE` class is an extension of the built-in `Promise` class and can be used as a drop-in replacement. It is fully compatible with async/await and `Promise` static methods.
 
-```typescript
-import { PromisE } from '@superutils/promise'
+A `PromisE` instance has the following additional features in comparison to `Promise`:
+
+#### Status tracking:
+
+All instances come with `.pending`, `.resolved` and `.rejected` read-only properties that indicate the current state of the promise.
 
-const p = new PromisE(resolve => setTimeout(() => resolve('done'), 1000))
+```javascript
+import Promise from '@superutils/promise'
+
+// Importing `PromisE` as "Promise" allows it to be used as a drop-in replacement without changing existing code
+
+const p = new Promise(resolve => setTimeout(() => resolve('done'), 1000))
 
 console.log(p.pending) // true
 
@@ -59,24 +72,33 @@ p.then(result => {
 })
 ```
 
-and the ability to early finalize a promise:
+#### Early finalization:
+
+All `PromisE` instances expose `.resolve()` and `.reject()` methods that allow early finalization and `.onEarlyFinalize` array that allows adding callbacks to be executed when the promise is finalized externally using these methods.
+
+```javascript
+import PromisE from '@superutils/promise'
 
-```typescript
-import { PromisE } from '@superutils/promise'
 const p = new PromisE(resolve => setTimeout(() => resolve('done'), 10000))
 p.then(result => console.log(result))
 // resolve the promise early
 setTimeout(() => p.resolve('finished early'), 500)
+
+// Add a callback to do stuff whenever promise is finalized externally.
+// This will not be invoked if promise finalized naturally using the Promise executor.
+p.onEarlyFinalize.push(((resolved, valueOrReason) =>
+	console.log('Promise finalized externally:', { resolved, valueOrReason }),
+))
 ```
 
 <div id="static-methods"></div>
 
-### `PromisE.try(fn)`: Static methods
+### Static methods
 
 Drop-in replacement for all `Promise` static methods such as `.all()`, `.race()`, `.reject`, `.resolve`, `.try()`, `.withResolvers()`....
 
-```typescript
-import { PromisE } from '@superutils/promise'
+```javascript
+import PromisE from '@superutils/promise'
 
 const p = PromisE.try(() => {
 	throw new Error('Something went wrong')
@@ -90,12 +112,11 @@ p.catch(error => {
 
 <div id="promise-status"></div>
 
-### `new PromisE(promise)`
+### `new PromisE(promise)`: Check status of an existing promise.
 
-Check status of an existing promise.
+```javascript
+import PromisE from '@superutils/promise'
 
-```typescript
-import { PromisE } from '@superutils/promise'
 const x = Promise.resolve(1)
 const p = new PromisE(x)
 console.log(p.pending) // false
@@ -109,8 +130,9 @@ console.log(p.rejected) // false
 
 Creates a promise that resolves after a specified duration, essentially a promise-based `setTimeout`.
 
-```typescript
+```javascript
 import PromisE from '@superutils/promise'
+
 // Wait until `appReady` becomes truthy but
 while (!appReady) {
 	await PromisE.delay(100)
@@ -123,16 +145,13 @@ Creates a promise that executes a function after a specified duration and return
 
 If callback returns undefined, default value will be the duration.
 
-```typescript
+```javascript
 import PromisE from '@superutils/promise'
 
-const func = async () => {
-	console.log('Waiting for app initialization or something else to be ready')
-	// wait 3 seconds before proceeding
-	await PromisE.delay(3000)
-	console.log('App ready')
-}
-func()
+console.log('Waiting for app initialization or something else to be ready')
+const onReady = () => console.log('App ready')
+
+PromisE.delay(3000, onReady)
 ```
 
 <div id="deferred"></div>
@@ -144,6 +163,8 @@ Create a function that debounces or throttles promise-returning function calls.
 #### Debounce example:
 
 ```typescript
+import PromisE from '@superutils/promise'
+
 const example = async (options = {}) => {
 	const df = PromisE.deferred({
 		delayMs: 100,
@@ -165,7 +186,10 @@ example({ ignoreStale: true, throttle: false })
 
 #### Throttle example:
 
-```typescript
+```javascript
+import PromisE from '@superutils/promise'
+
+// Simulate an example scenario
 const example = async (options = {}) => {
 	const df = PromisE.deferred({
 		delayMs: 100,
@@ -185,6 +209,22 @@ example({ ignoreStale: false, throttle: true })
 // `200` and `5000` will be printed in the console
 ```
 
+#### Behavior with different `options`:
+
+- **`delayMs: PositiveNumber, throttle: false`**: (default) Debounce mode.
+- **`throttle: true`**: Switches from debounce to throttle mode.
+- **`delayMs: 0`**: Disables debouncing and throttling, enabling sequential/queue mode. Requests are executed one after the other. Any failed promise does not affect subsequent promises.
+- **`resolveIgnored` (enum)**: Controls how an ignored promises is handled.
+    1. `ResolveIgnored.WITH_UNDEFINED`: The promise for the ignored request resolves with `undefined`.
+    2. `ResolveIgnored.WITH_LAST`: The promise for the ignored request waits (if needed) and resolves with the last/most-recent finalized promise.
+    3. `ResolveIgnored.NEVER`: The promise for the ignored request is neither resolved nor rejected. It will remain pending indefinitely.
+        > **Warning:** Use with caution, as this may lead to memory leaks if not handled properly.
+- **`resolveError` (enum)**: Controls how failed requests are handled.
+    1.  `ResolveError.NEVER`: The promise for a failed request will neither resolve nor reject, causing it to remain pending indefinitely.
+        > **Warning:** Use with caution, as this may lead to memory leaks if not handled properly.
+    2.  `ResolveError.WITH_ERROR`: The promise resolves with the error object instead of being rejected.
+    3.  `ResolveError.WITH_UNDEFINED`: The promise resolves with an `undefined` value upon failure.
+
 <div id="deferredCallback"></div>
 
 ### `PromisE.deferredCallback(callback, options)`: async debounced/throttled callbacks
@@ -221,7 +261,7 @@ delays.forEach(timeout =>
 #### Reject stuck or unexpectedly lenghthy promise(s) after a specified timeout:
 
 ```typescript
-import { PromisE } from '@superutils/promise'
+import PromisE from '@superutils/promise'
 
 PromisE.timeout(
 	5000, // timeout after 5000ms
@@ -233,13 +273,13 @@ PromisE.timeout(
 #### Show a message when loading is too long:
 
 ```typescript
-import { PromisE } from '@superutils/promise'
+import PromisE from '@superutils/promise'
 
-const loadUserNProducts = () => {
+const loadUserNProducts = async () => {
 	const promise = PromisE.timeout(
 		5000, // timeout after 5000ms
-		api.getUser(),
-		api.getProducts(),
+		fetch('https://dummyjson.com/users/1'), // fetch user
+		fetch('https://dummyjson.com/products'), // fetch products
 	)
 	const [user, products] = await promise.catch(err => {
 		// promise did not time out, but was rejected
@@ -254,5 +294,5 @@ const loadUserNProducts = () => {
 	})
 	return [user, products]
 }
-loadUserNProducts()
+loadUserNProducts().catch(console.warn)
 ```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _superutils_core from '@superutils/core';
-import { ValueOrPromise, TimeoutId, PositiveNumber, ThrottleOptions, DeferredOptions } from '@superutils/core';
+import { ValueOrPromise, PositiveNumber, DeferredOptions, TimeoutId } from '@superutils/core';
 
 interface IPromisE<T = unknown> extends Promise<T> {
     /** 0: pending, 1: resolved, 2: rejected */
@@ -17,73 +17,18 @@ interface IPromisE<T = unknown> extends Promise<T> {
     /** Indicates if the promise has been resolved */
     readonly resolved: boolean;
 }
-interface IPromisE_Delay<T = unknown> extends Promise<T>, IPromisE<T> {
-    /**
-     * Caution: pausing will prevent the promise from resolving/rejeting automatically.
-     *
-     * In order to finalize the promise either the `resolve()` or the `reject()` method must be invoked manually.
-     *
-     * An never-finalized promise may cause memory leak and will leave it at the mercry of the garbage collector.
-     * Use `pause()` only if you are sure.
-     *
-     * @example
-     * ```typescript
-     * // Example 1: SAFE => no memory leak, because no reference to the promise is stored and no suspended code
-     * <button onClick={() => {
-     *     const promise = PromisE.delay(1000).then(... do stuff ....)
-     *     setTimeout(() => promise.pause(), 300)
-     * }}>Click Me</button>
-     * ```
-     *
-     * @example UNSAFE => potential memory leak, because of suspended code
-     * ```typescript
-     * <button onClick={() => {
-     *     const promise = PromisE.delay(1000)
-     *     setTimeout(() => promise.pause(), 300)
-     *     await promise // suspended code
-     *     //... do stuff ....
-     * }}>Click Me</button>
-     * ```
-     *
-     * @example UNSAFE => potential memory leak, because of preserved reference.
-     * ```typescript
-     * // Until the reference to promises is collected by the garbage collector,
-     * // reference to the unfinished promise will remain in memory.
-     * const promises = []
-     * <button onClick={() => {
-     *     const promise = PromisE.delay(1000)
-     *     setTimeout(() => promise.pause(), 300)
-     *     promises.push(promise)
-     * }}>Click Me</button>
-     * ```
-     */
-    pause: () => void;
-    /** Timeout ID */
-    timeoutId: TimeoutId;
-}
-/**
- * Descibes a timeout PromisE and it's additional properties.
- */
-type IPromisE_Timeout<T = unknown> = IPromisE<T> & {
-    /** Clearing the timeout will prevent it from timing out */
-    clearTimeout: () => void;
-    /** The result/data promise. If more than one supplied in `args` result promise will be a combined `PromisE.all` */
-    data: IPromisE<T>;
-    /** A shorthand getter to check if the promise has timed out. Same as `promise.timeout.rejected`. */
-    readonly timedout: boolean;
-    /** The timeout promise */
-    timeout: IPromisE_Delay<T>;
-};
 type OnEarlyFinalize<T> = <TResolved extends boolean, TValue = TResolved extends true ? T : unknown>(resolved: TResolved, resultOrReason: TValue) => ValueOrPromise<unknown>;
 type PromiseParams<T = unknown> = ConstructorParameters<typeof Promise<T>>;
 
 /** Return type of `PromisE.deferred()` */
 type DeferredAsyncCallback<TArgs extends unknown[] | [] = []> = <TResult = unknown>(promise: Promise<TResult> | ((...args: TArgs) => Promise<TResult>)) => IPromisE<TResult>;
-type DeferredAsyncGetPromise<T> = <TResult = T>() => Promise<TResult>;
+type GetPromiseFunc<T> = <TResult = T>() => Promise<TResult>;
 /** Default options used by `PromisE.deferred` and related functions */
-type DeferredAsyncDefaults<ThisArg = unknown, Delay = unknown> = Pick<Required<DeferredAsyncOptions<ThisArg, Delay>>, 'delayMs' | 'resolveError' | 'resolveIgnored'>;
+type DeferredAsyncDefaults<ThisArg = unknown, Delay = unknown> = Pick<Required<DeferredAsyncOptions<ThisArg, Delay>>, 'resolveError' | 'resolveIgnored'> & {
+    delayMs: number;
+};
 /** Options for `PromisE.deferred` and other related functions */
-type DeferredAsyncOptions<ThisArg = unknown, Delay = unknown> = {
+type DeferredAsyncOptions<ThisArg = unknown, Delay = number> = {
     /**
      * Delay in milliseconds, used for `debounce` and `throttle` modes. Use `0` for sequential execution.
      *
@@ -91,7 +36,7 @@ type DeferredAsyncOptions<ThisArg = unknown, Delay = unknown> = {
      *
      * Default: `100` (or whatever is set in `PromisE.deferred.defaults.delayMs`)
      */
-    delayMs?: 0 | PositiveNumber<Delay>;
+    delayMs?: number | PositiveNumber<Delay>;
     /**
      * Whether to ignore (based on `resolveIgnored` settings) stale promises.
      * In debouce/throttle mode, when an older promise is resolved after a newly resolved promise,
@@ -100,14 +45,12 @@ type DeferredAsyncOptions<ThisArg = unknown, Delay = unknown> = {
      * Default: `false`
      */
     ignoreStale?: boolean;
-    /** Callback invoked whenever promise/function throws error */
-    onError?: (this: ThisArg, err: unknown) => ValueOrPromise<unknown>;
     /**
      * Whenever a promise/function is ignored when in debounce/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?: (this: ThisArg, ignored: DeferredAsyncGetPromise<unknown>) => ValueOrPromise<unknown>;
+    onIgnore?: (this: ThisArg, ignored: GetPromiseFunc<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.
@@ -125,18 +68,17 @@ type DeferredAsyncOptions<ThisArg = unknown, Delay = unknown> = {
      * See {@link ResolveError} for available options.
      */
     resolveError?: ResolveError;
-    /** The value to be used as "thisArg" whenever any of the callbacks are invoked */
-    thisArg?: ThisArg;
 } & (({
-    delayMs: PositiveNumber<Delay>;
-    throttle: true;
-} & Pick<ThrottleOptions, 'trailing'>) | ({
     delayMs?: PositiveNumber<Delay>;
-    throttle?: false;
-} & Pick<DeferredOptions, 'leading'>) | {
+} & DeferredOptions<ThisArg>) | ({
     delayMs: 0;
+} & {
     throttle?: false;
-});
+    /** Callback invoked whenever promise/function throws error */
+    onError?: (this: ThisArg, err: unknown) => ValueOrPromise<unknown>;
+    /** The value to be used as "thisArg" whenever any of the callbacks are invoked */
+    thisArg?: ThisArg;
+}));
 /** Determines what to do when deferred promise/function fails */
 declare enum ResolveError {
     /** Neither resolve nor reject the failed */
@@ -161,6 +103,53 @@ declare enum ResolveIgnored {
     WITH_UNDEFINED = "WITH_UNDEFINED"
 }
 
+interface IPromisE_Delay<T = unknown> extends Promise<T>, IPromisE<T> {
+    /**
+     * Caution: pausing will prevent the promise from resolving/rejeting automatically.
+     *
+     * In order to finalize the promise either the `resolve()` or the `reject()` method must be invoked manually.
+     *
+     * An never-finalized promise may cause memory leak and will leave it at the mercry of the garbage collector.
+     * Use `pause()` only if you are sure.
+     *
+     * @example
+     * ```typescript
+     * // Example 1: SAFE => no memory leak, because no reference to the promise is stored and no suspended code
+     * <button onClick={() => {
+     *     const promise = PromisE.delay(1000).then(... do stuff ....)
+     *     setTimeout(() => promise.pause(), 300)
+     * }}>Click Me</button>
+     * ```
+     *
+     * @example UNSAFE => potential memory leak, because of suspended code
+     * ```typescript
+     * <button onClick={() => {
+     *     const promise = PromisE.delay(1000)
+     *     setTimeout(() => promise.pause(), 300)
+     *     await promise // suspended code
+     *     //... do stuff ....
+     * }}>Click Me</button>
+     * ```
+     *
+     * @example UNSAFE => potential memory leak, because of preserved reference.
+     * ```typescript
+     * // Until the reference to promises is collected by the garbage collector,
+     * // reference to the unfinished promise will remain in memory.
+     * const promises = []
+     * <button onClick={() => {
+     *     const promise = PromisE.delay(1000)
+     *     setTimeout(() => promise.pause(), 300)
+     *     promises.push(promise)
+     * }}>Click Me</button>
+     * ```
+     */
+    pause: () => void;
+    /** Timeout ID */
+    timeoutId: TimeoutId;
+}
+
+/** Function to determine whether retry should be attempted based on previous result/error */
+type RetryIfFunc<T = unknown> = (prevResult: T | undefined, retryCount: number, error?: unknown) => ValueOrPromise<boolean | void>;
 /** Options for automatic retry mechanism */
 type RetryOptions<T = unknown> = {
     /**
@@ -179,30 +168,47 @@ type RetryOptions<T = unknown> = {
      */
     retryBackOff?: 'exponential' | 'linear';
     /**
-     * Delay in milliseconds between retries.
+     * Minimum delay in milliseconds between retries.
      * Default: `300`
      */
     retryDelay?: number;
     /**
-     * Add a random delay between 0ms and `retryDelayJitterMax` to the `retryDelay`.
+     * Whether to add a random delay between 0ms and `retryDelayJitterMax` to the `retryDelay`.
+     *
+     * This helps to avoid "thundering herd" problem when multiple retries are attempted simultaneously.
+     *
      * Default: `true`
      */
     retryDelayJitter?: boolean;
     /**
-     * Maximum delay (in milliseconds) to be used when randomly generating jitter delay duration.
+     * Maximum jitter delay (in milliseconds) to be added to the `retryDelay` when `retryDelayJitter` is `true`.
+     *
+     * A random value between `0` and `retryDelayJitterMax` will be added to the base `retryDelay`.
+     *
      * Default: `100`
      */
     retryDelayJitterMax?: number;
     /**
-     * Additional condition/function to be used to determine whether function should be retried.
-     * `retryIf` will only be executed when function execution is successful.
+     * Additional condition to be used to determine whether function should be retried.
+     *
+     * If `retryIf` not provided, execution will be retried on any error until the retry limit is reached
+     * or a result is received without an exception.
+     *
+     * @param prevResult The result from the previous attempt, if any.
+     * @param retryCount The number of retries that have been attempted so far.
+     * @param error The error from the previous attempt, if any.
+     *
+     * Expected return values:
+     * - `true`: retry will be attempted regardless of error.
+     * - `false`: no further retry will be attempted and the last error/result will be returned.
+     * - `void | undefined`: retry will be attempted only if there was an error.
      */
-    retryIf?: null | ((prevResult: T | undefined, retryCount: number) => boolean | Promise<boolean>);
+    retryIf?: RetryIfFunc<T>;
 };
 
 declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T> {
-    private _resolve?;
-    private _reject?;
+    private _resolve;
+    private _reject;
     private _state;
     /**
      * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
@@ -213,6 +219,8 @@ declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T>
     constructor(promise: Promise<T>);
     /** Create a resolved promise with value */
     constructor(value: T);
+    /** Create a promise to be resolved externally using `.resolve()` and `.reject()` methods */
+    constructor(value: undefined);
     /**
      * If executor function is not provided, the promise must be resolved/rejected externally.
      *
@@ -253,7 +261,7 @@ declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T>
     /** 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>;
+    static reject: <T_1 = never>(reason: unknown) => PromisEBase<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(...))` */
@@ -290,29 +298,67 @@ declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T>
     };
 }
 
-type TimeoutFunc<T extends unknown[]> = {
+/**
+ * Descibes a timeout PromisE and it's additional properties.
+ */
+type IPromisE_Timeout<T = unknown> = IPromisE<T> & {
+    readonly aborted: boolean;
+    /**
+     * Removes `abortCtrl/signal` listeners, effectively disabling external cancellation via AbortController.
+     */
+    cancelAbort: () => void;
+    /**
+     * Clears the timeout timer, preventing the promise from being rejected due to a timeout.
+     */
+    clearTimeout: () => void;
+    /** The underlying data promise. If multiple promises were passed to `timeout`, this represents the combined result (defaulting to `PromisE.all`). */
+    data: IPromisE<T>;
+    /** Read-only property indicating if the promise timed out. Equivalent to checking `promise.timeout.rejected`. */
+    readonly timedout: boolean;
+    /** The internal promise that handles the timeout logic. It rejects when the duration expires. */
+    timeout: IPromisE_Delay<T>;
+};
+type TimeoutResult<T extends unknown[], TFunc extends keyof TimeoutFunc<T>, Values extends unknown[] = {
+    -readonly [P in keyof T]: T[P] extends (...args: unknown[]) => infer ReturnType ? ReturnType : T[P];
+}> = Awaited<T['length'] extends 1 ? Values[0] : ReturnType<TimeoutFunc<Values>[TFunc]>>;
+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
+ * Options for `PromisE.timeout()`
  *
- * @param func (optional) name of the supported `PromieBase` static method. Default: `"all"`
+ * @param func (optional) name of the supported `PromiEBase` static method to be used to resolve
+ * when more than one promise/function is provided. 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;
+type TimeoutOptions<T extends unknown[] = [], Func extends string = 'all'> = {
+    abortCtrl?: AbortController;
+    func?: T['length'] extends 0 ? never : T['length'] extends 1 ? never : Func;
+    /**
+     * Callback invoked when the promise is rejected due to an abort signal.
+     * Optionally, return an `Error` object to reject the promise with a custom error.
+     */
+    onAbort?: () => ValueOrPromise<void | Error>;
+    /**
+     * Callback invoked when the promise times out.
+     * Optionally, return an `Error` object to reject the promise with a custom error.
+     */
+    onTimeout?: () => ValueOrPromise<void | Error>;
+    signal?: AbortSignal;
     timeout?: number;
-    timeoutMsg?: string;
 };
+/** Default options for `PromisE.timeout()` */
+type TimeoutOptionsDefault = Required<Omit<TimeoutOptions<unknown[], keyof TimeoutFunc>, 'abortCtrl' | 'signal'>>;
 
 /**
  * @function PromisE.deferred
- * The adaptation of the `deferred()` function tailored for Promises.
+ *
+ * The adaptation of the `deferred()` function from `@superutils/core` tailored for Promises.
  *
  *
  * # Notes
@@ -500,7 +546,7 @@ declare function deferredCallback<TDefault = unknown, ThisArg = unknown, Delay =
  * func()
  * ```
  */
-declare function delay<T = number, TReject extends boolean = boolean>(duration?: number, result?: T | (() => T), asRejected?: TReject): IPromisE_Delay<T>;
+declare function delay<T = number, TReject extends boolean = boolean>(duration?: number, result?: T | (() => T | Promise<T>), asRejected?: TReject): IPromisE_Delay<T>;
 declare namespace delay {
     var defaults: {
         /** Default delay duration in milliseconds */
@@ -544,18 +590,22 @@ declare namespace delay {
  */
 declare function delayReject<T = never>(duration: number, reason?: unknown): IPromisE_Delay<T>;
 
+/** Timeout duration (in milliseconds) used as a fallback when positive number is not provided to {@link timeout} */
+declare const FALLBACK_TIMEOUT = 10000;
 /**
  * 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)
+ * Default: `10_000` (10 seconds)
  *
  * @param values rest param containing one or more promises/values
  *
- * @example Wokring with a single promise: resolved succesfully
+ * @example Working with a single promise
  * ```typescript
+ * import PromisE from '@supertuils/promise'
+ *
  * PromisE.timeout(
  *   5000, // timeout after 5000ms
  *   PromisE.delay(1000), // resolves after 1000ms with value 1000
@@ -563,8 +613,21 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  * // Result: 1000
  * ```
  *
+ * @example Working with a single function
+ * ```typescript
+ * import PromisE from '@supertuils/promise'
+ *
+ * PromisE.timeout(
+ *   5000, // timeout after 5000ms
+ *   () => PromisE.delay(1000), // function resolves after 1000ms with value 1000
+ * ).then(console.log)
+ * // Result: 1000
+ * ```
+ *
  * @example Promise times out & rejected
  * ```typescript
+ * import PromisE from '@supertuils/promise'
+ *
  * PromisE.timeout(
  *     5000, // timeout after 5000ms
  *     PromisE.delay(20000), // resolves after 20000ms with value 20000
@@ -572,13 +635,15 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  * // Error: Error('Timed out after 5000ms')
  *```
  *
- * @example Working with multiple promises, resolved using "PromisE.all()"
+ * @example Working with multiple promises/functions, resolved using "PromisE.all()"
  *
  * ```typescript
+ * import PromisE from '@supertuils/promise'
+ *
  * PromisE.timeout(
  *     5000, // timeout after 5000ms
  *     PromisE.delay(1000), // resolves after 1000ms with value 1000
- *     PromisE.delay(2000), // resolves after 2000ms with value 2000
+ *     () => PromisE.delay(2000), // resolves after 2000ms with value 2000
  *     PromisE.delay(3000), // resolves after 3000ms with value 3000
  * ).then(console.log)
  * // Result: [ 1000, 2000, 3000 ]
@@ -587,6 +652,8 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  * @example Promise times out & but not rejected.
  * Eg: when API request is taking longer than expected, print a message avoid rejecting the promise.
  * ```typescript
+ * import PromisE from '@supertuils/promise'
+ *
  * const promise = PromisE.timeout(
  *     5000, // timeout after 5000ms
  *     PromisE.delay(20000), // data promise, resolves after 20000ms with value 20000
@@ -601,10 +668,32 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  *     return promise.data
  * })
  *```
+ */
+declare function timeout<T extends [unknown, ...unknown[]]>(timeout: number, ...values: T): IPromisE_Timeout<TimeoutResult<T, 'all'>>;
+/**
+ *
+ * @param options An options object can be passed with one or more of the following properties:
+ * @param options.abortCtrl (optional) AbortController to manually reject promise externally and/or to sync abort with timeout rejection
+ * @param options.abortMsg (optional) error message when promise is rejected by abort controller/signal
+ * @param options.func (optional) Name of the `PromisE` static method to be used to combine the `values`.
+ * Only used when more than one promise is provided. Default: `"all"`
+ *
+ * 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.signal (optional) AbortSignal to manually reject promise externally
+ * @param options.timeout (optional) timeout duration in milliseconds. If positive number is not provided, the default value will be used. Default: `10_000` (10 seconds)
+ * @param options.timeoutMsg (optional) custom error message to be used when promises timeout.
  *
- * @example Multiple promises resolved using "PromisE.race()"
+ * @param values Mix of promises, values and/or functions
+ *
+ * @example Working with multiple promises/functions resolved using "PromisE.race()"
  *
  * ```typescript
+ * import PromisE from '@supertuils/promise'
+ *
  * PromisE.timeout(
  *     { // instead of `timeout: number` an object can be used for additional options
  *         func: 'race', // tells PromisE.timeout to use `PromisE.race(promises)`
@@ -612,35 +701,15 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  *         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(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]>>>(options: TimeoutOptions<TFunc>, ...values: T): IPromisE_Timeout<Result>;
+declare function timeout<T extends unknown[], TFunc extends keyof TimeoutFunc<T> = keyof TimeoutFunc<T>>(options: TimeoutOptions<T, TFunc>, ...values: T): IPromisE_Timeout<TimeoutResult<T, TFunc>>;
 declare namespace timeout {
-    var defaultOptions: Required<TimeoutOptions>;
+    var defaults: Required<Omit<TimeoutOptions<unknown[], keyof TimeoutFunc<[]>>, "abortCtrl" | "signal">>;
 }
 
 /**
@@ -771,4 +840,4 @@ declare const retry: {
     };
 };
 
-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 };
+export { type DeferredAsyncCallback, type DeferredAsyncDefaults, type DeferredAsyncOptions, FALLBACK_TIMEOUT, type GetPromiseFunc, type IPromisE, type IPromisE_Delay, type IPromisE_Timeout, type OnEarlyFinalize, PromisE, PromisEBase, type PromiseParams, ResolveError, ResolveIgnored, type RetryIfFunc, type RetryOptions, type TimeoutFunc, type TimeoutOptions, type TimeoutOptionsDefault, type TimeoutResult, PromisE as default, deferred, deferredCallback, delay, delayReject, retry, timeout };

package/dist/index.js

@@ -1,33 +1,34 @@
 // src/deferred.ts
 import {
-  deferred as deferredCore,
+  deferred as deferredSync,
   fallbackIfFails as fallbackIfFails2,
   isFn as isFn2,
   isPositiveNumber,
-  objCopy,
-  throttled as throttledCore
+  objCopy
 } from "@superutils/core";
 
 // src/PromisEBase.ts
 import { fallbackIfFails, isFn, isPromise } from "@superutils/core";
 var _PromisEBase = class _PromisEBase extends Promise {
   constructor(input) {
-    if (input instanceof _PromisEBase) return input;
     let _resolve;
     let _reject;
     super((resolve, reject) => {
       _reject = (reason) => {
-        this._state = 2;
         reject(reason);
+        this._state = 2;
       };
       _resolve = (value) => {
-        this._state = 1;
         resolve(value);
+        this._state = 1;
       };
-      input != null ? input : input = () => {
-      };
-      const promise = isPromise(input) ? input : isFn(input) ? new globalThis.Promise(input) : Promise.resolve(input);
-      promise.then(_resolve, _reject);
+      if (isFn(input)) {
+        fallbackIfFails(input, [_resolve, _reject], _reject);
+      } else if (isPromise(input)) {
+        input.then(_resolve, _reject);
+      } else if (input !== void 0) {
+        _resolve(input);
+      }
     });
     this._state = 0;
     /**
@@ -66,15 +67,15 @@ 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:
@@ -86,11 +87,6 @@ var _PromisEBase = class _PromisEBase extends Promise {
   get state() {
     return this._state;
   }
-  // static withResolvers = <T = unknown>() => {
-  // 	const pwr = globalThis.Promise.withResolvers<T>()
-  // 	const promise = new PromisEBase<T>(pwr.promise) as IPromisE<T>
-  // 	return { ...pwr, promise }
-  // }
 };
 //
 //
@@ -107,8 +103,8 @@ _PromisEBase.any = (values) => new _PromisEBase(globalThis.Promise.any(values));
 _PromisEBase.race = (values) => new _PromisEBase(globalThis.Promise.race(values));
 /** Extends Promise.reject */
 _PromisEBase.reject = (reason) => {
-  const { promise, reject } = _PromisEBase.withResolvers();
-  queueMicrotask(() => reject(reason));
+  const promise = new _PromisEBase();
+  queueMicrotask(() => promise.reject(reason));
   return promise;
 };
 /** Sugar for `new PromisE(Promise.resolve(...))` */
@@ -186,12 +182,14 @@ function deferred(options = {}) {
   let { onError, onIgnore, onResult } = options;
   const {
     delayMs = 0,
+    ignoreStale,
     resolveError,
     resolveIgnored,
     thisArg,
     throttle
   } = options;
-  let prevQItem = null;
+  let lastInSeries = null;
+  let lastExecuted;
   const queue = /* @__PURE__ */ new Map();
   const isSequential = !isPositiveNumber(delayMs);
   if (thisArg !== void 0) {
@@ -199,17 +197,21 @@ function deferred(options = {}) {
     onIgnore = onIgnore == null ? void 0 : onIgnore.bind(thisArg);
     onResult = onResult == null ? void 0 : onResult.bind(thisArg);
   }
-  const handleIgnore = (items, prevQItem2) => {
+  const handleIgnore = (items) => {
     for (const [iId, iItem] of items) {
       queue.delete(iId);
-      if (iItem === void 0 || iItem.started) continue;
-      onIgnore && fallbackIfFails2(onIgnore, [iItem.getPromise], 0);
+      const isStale = ignoreStale && iItem.sequence < lastExecuted.sequence;
+      if (iItem.resolved || iItem.started && !isStale) continue;
+      if (iItem.started) {
+        iItem.getPromise = (() => iItem.result);
+      }
+      fallbackIfFails2(onIgnore, [iItem.getPromise], 0);
       switch (resolveIgnored) {
         case "WITH_UNDEFINED" /* WITH_UNDEFINED */:
           iItem.resolve(void 0);
           break;
         case "WITH_LAST" /* WITH_LAST */:
-          prevQItem2 == null ? void 0 : prevQItem2.then(iItem.resolve, iItem.reject);
+          lastExecuted == null ? void 0 : lastExecuted.then(iItem.resolve, iItem.reject);
           break;
         case "NEVER" /* NEVER */:
           break;
@@ -218,33 +220,32 @@ function deferred(options = {}) {
     if (!queue.size) sequence = 0;
   };
   const handleRemaining = (currentId) => {
-    const _prevQItem = prevQItem;
-    prevQItem = null;
+    lastInSeries = null;
     if (isSequential) {
       queue.delete(currentId);
       const [nextId, nextItem] = [...queue.entries()][0] || [];
       return nextId && nextItem && handleItem(nextId, nextItem);
     }
     let items = [...queue.entries()];
-    if (throttle && options.trailing) {
+    if (throttle === true && options.trailing) {
       const currentIndex = items.findIndex(([id]) => id === currentId);
       items = items.slice(0, currentIndex);
     } else if (!throttle) {
       items = items.slice(0, -1);
     }
-    handleIgnore(items, _prevQItem);
+    handleIgnore(items);
+    queue.delete(currentId);
   };
-  let prevSeq = 0;
   const executeItem = async (id, qItem) => {
     var _a;
-    qItem.started = true;
-    const _prevQItem = prevQItem;
-    prevQItem = qItem;
-    prevSeq = (_a = prevQItem == null ? void 0 : prevQItem.sequence) != null ? _a : 0;
     try {
-      const result = await PromisEBase_default.try(qItem.getPromise);
-      const ignore = !isSequential && options.ignoreStale && prevSeq > qItem.sequence;
-      if (ignore) return handleIgnore([[id, qItem]], _prevQItem);
+      qItem.started = true;
+      lastExecuted = qItem;
+      lastInSeries = qItem;
+      (_a = qItem.result) != null ? _a : qItem.result = PromisEBase_default.try(qItem.getPromise);
+      const result = await qItem.result;
+      const isStale = !!ignoreStale && qItem.sequence < lastExecuted.sequence;
+      if (isStale) return handleIgnore([[id, qItem]]);
       qItem.resolve(result);
       onResult && fallbackIfFails2(onResult, [result], void 0);
     } catch (err) {
@@ -265,22 +266,21 @@ function deferred(options = {}) {
     }
     handleRemaining(id);
   };
-  const handleItem = isSequential ? executeItem : (throttle ? throttledCore : deferredCore)(
+  const handleItem = isSequential ? executeItem : deferredSync(
     executeItem,
     delayMs,
     options
   );
-  const deferredFunc = (promise) => {
+  return (promise) => {
     const id = /* @__PURE__ */ Symbol("deferred-queue-item-id");
     const qItem = new PromisEBase_default();
     qItem.getPromise = isFn2(promise) ? promise : () => promise;
     qItem.started = false;
     qItem.sequence = ++sequence;
     queue.set(id, qItem);
-    if (!prevQItem || !isSequential) handleItem(id, qItem);
+    if (!lastInSeries || !isSequential) handleItem(id, qItem);
     return qItem;
   };
-  return deferredFunc;
 }
 deferred.defaults = {
   /**
@@ -307,23 +307,28 @@ var deferredCallback_default = deferredCallback;
 
 // src/delay.ts
 import { fallbackIfFails as fallbackIfFails3, isFn as isFn3 } from "@superutils/core";
-function delay(duration = delay.defaults.duration, result = duration, asRejected = false) {
+function delay(duration = delay.defaults.duration, result, asRejected = false) {
   const promise = new PromisEBase_default();
   const finalize = (result2) => {
-    var _a;
-    if (isFn3(result2))
-      result2 = (_a = fallbackIfFails3(result2, [], void 0)) != null ? _a : duration;
-    if (!asRejected) return promise.resolve(result2);
-    promise.reject(
-      duration !== result2 && result2 !== void 0 ? result2 : new Error(
-        `${delay.defaults.delayTimeoutMsg} ${duration}ms`
-      )
+    const _result = fallbackIfFails3(
+      async () => {
+        const _result2 = await (isFn3(result2) ? result2() : result2);
+        return !asRejected ? _result2 != null ? _result2 : duration : _result2 != null ? _result2 : new Error(
+          `${delay.defaults.delayTimeoutMsg} ${duration}ms`
+        );
+      },
+      [],
+      // when result is a function and it fails/rejects,
+      // promise will reject even if `asRejected = false`
+      (err) => Promise.reject(err)
     );
+    !asRejected ? promise.resolve(_result) : _result.then(promise.reject, promise.reject);
   };
   promise.timeoutId = setTimeout(() => finalize(result), duration);
   promise.pause = () => clearTimeout(promise.timeoutId);
   promise.catch(() => {
   }).finally(() => promise.pause());
+  promise.onEarlyFinalize.push(() => promise.pause());
   return promise;
 }
 delay.defaults = {
@@ -348,6 +353,7 @@ import {
   objCopy as objCopy2
 } from "@superutils/core";
 var retry = async (func, options) => {
+  var _a, _b;
   options = objCopy2(retry.defaults, options != null ? options : {}, [], (key, value) => {
     switch (key) {
       // case 'retryDelayJitter':
@@ -377,18 +383,21 @@ var retry = async (func, options) => {
     if (retryBackOff === "exponential" && retryCount > 1) _retryDelay *= 2;
     if (retryDelayJitter)
       _retryDelay += Math.floor(Math.random() * retryDelayJitterMax);
-    retryCount > 0 && await delay_default(_retryDelay);
+    if (retryCount > 0) await delay_default(_retryDelay);
     try {
       error = void 0;
       result = await func();
     } catch (err) {
       error = err;
     }
-    shouldRetry = maxRetries > 0 && retryCount < maxRetries && (!!error || !!await fallbackIfFails4(
-      options.retryIf,
-      [result, retryCount],
-      false
-    ));
+    if (maxRetries === 0 || retryCount >= maxRetries) break;
+    shouldRetry = !!((_b = await fallbackIfFails4(
+      (_a = options.retryIf) != null ? _a : error,
+      // if `retryIf` not provided, retry on error
+      [result, retryCount, error],
+      error
+      // if `retryIf` throws error, default to retry on error
+    )) != null ? _b : error);
   } while (shouldRetry);
   if (error !== void 0) return Promise.reject(error);
   return result;
@@ -403,44 +412,116 @@ retry.defaults = {
 var retry_default = retry;
 
 // src/timeout.ts
-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(timeoutMsg || `Timed out after ${timeout2}ms`)
+import {
+  arrUnique,
+  fallbackIfFails as fallbackIfFails5,
+  isFn as isFn4,
+  isObj,
+  isPositiveNumber as isPositiveNumber2,
+  noop,
+  objCopy as objCopy3
+} from "@superutils/core";
+var FALLBACK_TIMEOUT = 1e4;
+function timeout(timeoutOrOptions, ...values) {
+  const options = objCopy3(
+    timeout.defaults,
+    isObj(timeoutOrOptions) ? timeoutOrOptions : { timeout: timeoutOrOptions },
+    [],
+    "empty"
+  );
+  const { func, onTimeout } = options;
+  const duration = isPositiveNumber2(options.timeout) ? options.timeout : FALLBACK_TIMEOUT;
+  const arrPromises = values.map((v) => isFn4(v) ? PromisEBase_default.try(v) : v);
+  const dataPromise = arrPromises.length <= 1 ? (
+    // single promise resolves to a single result
+    arrPromises[0] instanceof PromisEBase_default ? arrPromises[0] : new PromisEBase_default(arrPromises[0])
+  ) : (
+    // multiple promises resolve to an array of results
+    (isFn4(PromisEBase_default[func]) ? PromisEBase_default[func] : PromisEBase_default.all)(
+      arrPromises
+    )
   );
+  const timeoutPromise = delayReject_default(duration, onTimeout);
   const promise = PromisEBase_default.race([
     dataPromise,
     timeoutPromise
   ]);
-  promise.clearTimeout = () => clearTimeout(timeoutPromise.timeoutId);
-  promise.data = dataPromise;
-  promise.timeout = timeoutPromise;
-  Object.defineProperty(promise, "timedout", {
-    get: () => promise.timeout.rejected
-  });
-  dataPromise.catch(() => {
-  }).finally(() => {
-    promise.clearTimeout();
-  });
+  addPropsNListeners(promise, dataPromise, timeoutPromise, options);
   return promise;
 }
-timeout.defaultOptions = {
+timeout.defaults = {
   func: "all",
-  timeout: 1e4
+  timeout: FALLBACK_TIMEOUT
 };
 var timeout_default = timeout;
+var addPropsNListeners = (promise, dataPromise, timeoutPromise, options) => {
+  const { abortCtrl, onAbort, signal } = options;
+  const signals = arrUnique([abortCtrl == null ? void 0 : abortCtrl.signal, signal].filter(Boolean));
+  Object.defineProperties(promise, {
+    aborted: {
+      get() {
+        return promise.rejected && !!signals.find((s) => s.aborted);
+      }
+    },
+    cancelAbort: {
+      get() {
+        return () => {
+          signals == null ? void 0 : signals.forEach(
+            (signal2) => signal2.removeEventListener("abort", handleAbort)
+          );
+        };
+      }
+    },
+    clearTimeout: {
+      get() {
+        return () => clearTimeout(timeoutPromise.timeoutId);
+      }
+    },
+    data: {
+      get() {
+        return dataPromise;
+      }
+    },
+    timeout: {
+      get() {
+        return timeoutPromise;
+      }
+    },
+    timedout: {
+      get() {
+        return promise.rejected && timeoutPromise.rejected;
+      }
+    }
+  });
+  const cleanup = () => {
+    promise.cancelAbort();
+    promise.clearTimeout();
+  };
+  promise.onEarlyFinalize.push(cleanup);
+  promise.catch(() => {
+    var _a;
+    if (!timeoutPromise.rejected && !signals.find((x) => x.aborted))
+      return;
+    ((_a = abortCtrl == null ? void 0 : abortCtrl.signal) == null ? void 0 : _a.aborted) === false && abortCtrl.abort();
+  }).finally(cleanup);
+  if (!signals.length) return;
+  const started = /* @__PURE__ */ new Date();
+  function handleAbort() {
+    if (!promise.pending) return;
+    fallbackIfFails5(async () => await (onAbort == null ? void 0 : onAbort()), [], void 0).then(
+      (err) => {
+        var _a;
+        err != null ? err : err = new Error(
+          `Aborted after ${(/* @__PURE__ */ new Date()).getTime() - started.getTime()}ms`
+        );
+        (_a = err.name) != null ? _a : err.name = "AbortError";
+        promise.reject(err);
+      },
+      noop
+    );
+  }
+  signals.forEach((signal2) => signal2.addEventListener("abort", handleAbort));
+};
 
 // src/PromisE.ts
 var PromisE = class extends PromisEBase_default {
@@ -456,6 +537,7 @@ var PromisE_default = PromisE;
 // src/index.ts
 var index_default = PromisE_default;
 export {
+  FALLBACK_TIMEOUT,
   PromisE,
   PromisEBase,
   ResolveError,

package/package.json

@@ -4,9 +4,9 @@
 		"url": "https://github.com/alien45/superutils/issues"
 	},
 	"dependencies": {
-		"@superutils/core": "^1.1.5"
+		"@superutils/core": "^1.1.8"
 	},
-	"description": "An extended Promise with extra features such as status tracking, deferred/throttled execution, timeout and retry mechanism.",
+	"description": "An extended Promise with additional 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.1.5"
+		"@superutils/core": "^1.2.0"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -43,5 +43,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.1.5"
+	"version": "1.2.0"
 }