@superutils/promise 1.1.6 → 1.2.1

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import * as _superutils_core from '@superutils/core';
-import { ValueOrPromise, TimeoutId, PositiveNumber, 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 */
     readonly state: 0 | 1 | 2;
     /** callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve/reject methods */
     onEarlyFinalize: OnEarlyFinalize<T>[];
+    onFinalize: OnFinalize<T>[];
     /** Indicates if the promise is still pending/unfinalized */
     readonly pending: boolean;
     /** Reject pending promise early. */
@@ -17,64 +18,8 @@ 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 OnFinalize<T> = (result?: T | PromiseLike<T>, error?: unknown) => ValueOrPromise<void>;
 type PromiseParams<T = unknown> = ConstructorParameters<typeof Promise<T>>;
 
 /** Return type of `PromisE.deferred()` */
@@ -96,7 +41,7 @@ type DeferredAsyncOptions<ThisArg = unknown, Delay = unknown> = {
     delayMs?: 0 | 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,
+     * In debounce/throttle mode, when an older promise is resolved after a newly resolved promise,
      * the older one is considered stale.
      *
      * Default: `false`
@@ -125,17 +70,13 @@ type DeferredAsyncOptions<ThisArg = unknown, Delay = unknown> = {
      * See {@link ResolveError} for available options.
      */
     resolveError?: ResolveError;
-} & (({
-    delayMs: 0;
-} & {
+} & (Delay extends 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;
-}) | ({
-    delayMs?: PositiveNumber<Delay>;
-} & DeferredOptions<ThisArg>));
+} : DeferredOptions<ThisArg>);
 /** Determines what to do when deferred promise/function fails */
 declare enum ResolveError {
     /** Neither resolve nor reject the failed */
@@ -160,6 +101,51 @@ 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 */
@@ -225,6 +211,7 @@ declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T>
     /**
      * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
     onEarlyFinalize: OnEarlyFinalize<T>[];
+    onFinalize: OnFinalize<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 */
@@ -273,7 +260,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(...))` */
@@ -310,25 +297,94 @@ 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 abortCtrl?: AbortController;
+    /** Read-only property indicating if the promise rejected because of external abort. */
+    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[], BatchFunc extends keyof BatchFuncs<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<BatchFuncs<Values>[BatchFunc]>>;
+/** Suported function names for batch operations */
+type BatchFuncs<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[] = [], BatchFuncName extends string = 'all'> = {
+    /**
+     * An `AbortController` instance.
+     *
+     * If provided:
+     * - It will be aborted automatically when the timeout occurs.
+     * - If it is aborted externally, the promise will be rejected and the timeout will be cleared.
+     */
+    abortCtrl?: AbortController;
+    /**
+     * Whether to call `abortCtrl.abort()` if the promise is finalized externally
+     * (resolved or rejected before timeout or abort).
+     *
+     * Default: `true`
+     */
+    abortOnEarlyFinalize?: boolean;
+    /**
+     * The name of the `PromisEBase` static method to use for resolving multiple promises/functions.
+     *
+     * Only applicable when more than one promise/function is provided.
+     */
+    batchFunc?: T['length'] extends 0 ? never : T['length'] extends 1 ? never : BatchFuncName;
+    /**
+     * Callback invoked when the promise is rejected due to an abort signal.
+     *
+     * Can be used to transform the abort error by returning a custom `Error` object.
+     */
+    onAbort?: () => ValueOrPromise<void | Error>;
+    /**
+     * Callback invoked when the promise times out.
+     *
+     * Can be used to transform the timeout error by returning a custom `Error` object.
+     */
+    onTimeout?: () => ValueOrPromise<void | Error>;
+    /**
+     * An `AbortSignal` to listen to.
+     *
+     * If aborted:
+     * - The promise will be rejected.
+     * - The `abortCtrl` (if provided and distinct) will be aborted.
+     * - The timeout will be cleared.
+     */
+    signal?: AbortSignal;
+    /** Timeout duration in milliseconds. */
     timeout?: number;
-    timeoutMsg?: string;
 };
+/** Default options for `PromisE.timeout()` */
+type TimeoutOptionsDefault = Required<Omit<TimeoutOptions<unknown[], keyof BatchFuncs>, 'abortCtrl' | 'signal'>>;
 
 /**
  * @function PromisE.deferred
@@ -521,7 +577,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 */
@@ -571,12 +627,14 @@ declare function delayReject<T = never>(duration: number, reason?: unknown): IPr
  *  `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
@@ -584,8 +642,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
@@ -593,13 +664,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 ]
@@ -608,6 +681,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
@@ -622,46 +697,49 @@ 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.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.onAbort (optional) 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.
+ * @param options.onTimeout (optional) Callback invoked when the promise times out.
+ * Optionally, return an `Error` object to reject the promise with a custom error.
+ * @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 values Mix of promises, values and/or functions
  *
- * @example Multiple promises resolved using "PromisE.race()"
+ * @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)`
  *         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(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 BatchFuncs<T> = keyof BatchFuncs<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 BatchFuncs<[]>>, "abortCtrl" | "signal">>;
 }
 
 /**
@@ -792,4 +870,27 @@ declare const retry: {
     };
 };
 
-export { type DeferredAsyncCallback, type DeferredAsyncDefaults, type DeferredAsyncOptions, 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, PromisE as default, deferred, deferredCallback, delay, delayReject, retry, timeout };
+/** Timeout duration (in milliseconds) used as a fallback when positive number is not provided to {@link timeout} */
+declare const TIMEOUT_FALLBACK = 10000;
+/** Node.js setTimeout limit is 2147483647 (2^31-1). Larger values fire immediately. */
+declare const TIMEOUT_MAX = 2147483647;
+declare class TimeoutPromise<T> extends PromisEBase<T> implements IPromisE_Timeout<T> {
+    readonly data: IPromisE<T>;
+    readonly options: TimeoutOptions;
+    readonly timeout: IPromisE_Delay<T>;
+    readonly started: Date;
+    private _signals?;
+    constructor(data: IPromisE<T>, timeout: IPromisE_Delay<T>, options: TimeoutOptions, _signals?: AbortSignal[]);
+    get abortCtrl(): AbortController | undefined;
+    get aborted(): boolean;
+    cancelAbort(): void;
+    clearTimeout(): void;
+    get timedout(): boolean;
+    private _setup;
+    private _handleAbort;
+    private _handleEarlyFinalize;
+    private _handleFinalize;
+    static defaults: TimeoutOptionsDefault;
+}
+
+export { type BatchFuncs, type DeferredAsyncCallback, type DeferredAsyncDefaults, type DeferredAsyncOptions, type GetPromiseFunc, type IPromisE, type IPromisE_Delay, type IPromisE_Timeout, type OnEarlyFinalize, type OnFinalize, PromisE, PromisEBase, type PromiseParams, ResolveError, ResolveIgnored, type RetryIfFunc, type RetryOptions, TIMEOUT_FALLBACK, TIMEOUT_MAX, type TimeoutOptions, type TimeoutOptionsDefault, TimeoutPromise, type TimeoutResult, PromisE as default, deferred, deferredCallback, delay, delayReject, retry, timeout };

package/dist/index.js

@@ -17,10 +17,16 @@ var _PromisEBase = class _PromisEBase extends Promise {
       _reject = (reason) => {
         reject(reason);
         this._state = 2;
+        this.onFinalize.forEach(
+          (fn) => fallbackIfFails(fn, [void 0, reason], void 0)
+        );
       };
       _resolve = (value) => {
         resolve(value);
         this._state = 1;
+        this.onFinalize.forEach(
+          (fn) => fallbackIfFails(fn, [value, void 0], void 0)
+        );
       };
       if (isFn(input)) {
         fallbackIfFails(input, [_resolve, _reject], _reject);
@@ -34,6 +40,7 @@ var _PromisEBase = class _PromisEBase extends Promise {
     /**
      * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
     this.onEarlyFinalize = [];
+    this.onFinalize = [];
     //
     //
     // --------------------------- Early resolve/reject ---------------------------
@@ -87,11 +94,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 }
-  // }
 };
 //
 //
@@ -108,8 +110,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(...))` */
@@ -312,23 +314,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 = {
@@ -411,45 +418,141 @@ 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;
+// src/TimeoutPromise.ts
+import { arrUnique, fallbackIfFails as fallbackIfFails5, isObj } from "@superutils/core";
+var TIMEOUT_FALLBACK = 1e4;
+var TIMEOUT_MAX = 2147483647;
+var TimeoutPromise = class extends PromisEBase_default {
+  constructor(data, timeout2, options, _signals) {
+    super(data);
+    this.started = /* @__PURE__ */ new Date();
+    this._setup = () => {
+      var _a, _b, _c, _d;
+      this._signals = arrUnique(
+        [(_b = (_a = this.options) == null ? void 0 : _a.abortCtrl) == null ? void 0 : _b.signal, (_c = this.options) == null ? void 0 : _c.signal].filter(
+          Boolean
+        )
+      );
+      !this.onEarlyFinalize.includes(this._handleEarlyFinalize) && this.onEarlyFinalize.push(this._handleEarlyFinalize);
+      !this.onFinalize.includes(this._handleFinalize) && this.onFinalize.push(this._handleFinalize);
+      (_d = this._signals) == null ? void 0 : _d.forEach(
+        (signal) => signal == null ? void 0 : signal.addEventListener(
+          "abort",
+          this._handleAbort
+        )
+      );
+    };
+    this._handleAbort = async () => {
+      var _a, _b, _c;
+      if (!((_a = this._signals) == null ? void 0 : _a.length) || !this.pending) return;
+      let err = await fallbackIfFails5((_b = this.options) == null ? void 0 : _b.onAbort, [], void 0);
+      err != null ? err : err = new Error(
+        `Aborted after ${(/* @__PURE__ */ new Date()).getTime() - this.started.getTime()}ms`
+      );
+      (_c = err.name) != null ? _c : err.name = "AbortError";
+      this.reject(err);
+    };
+    this._handleEarlyFinalize = () => {
+      var _a, _b, _c, _d;
+      ((_a = this.options) == null ? void 0 : _a.abortOnEarlyFinalize) && ((_d = (_c = (_b = this.options) == null ? void 0 : _b.abortCtrl) == null ? void 0 : _c.abort) == null ? void 0 : _d.call(_c));
+    };
+    // cleanup after execution
+    this._handleFinalize = ((_, err) => {
+      var _a, _b, _c, _d, _e;
+      const failed = !this.timeout.rejected && !((_a = this._signals) == null ? void 0 : _a.find((x) => x == null ? void 0 : x.aborted));
+      if (failed) return;
+      ((_d = (_c = (_b = this.options) == null ? void 0 : _b.abortCtrl) == null ? void 0 : _c.signal) == null ? void 0 : _d.aborted) === false && ((_e = this.options) == null ? void 0 : _e.abortCtrl.abort(err));
+      this.cancelAbort();
+      this.clearTimeout();
+    });
+    this.data = data;
+    this.options = isObj(options) ? options : {};
+    this.timeout = timeout2;
+    this._signals = _signals;
+    this._setup();
+  }
+  get abortCtrl() {
+    return this.options.abortCtrl;
+  }
+  get aborted() {
+    var _a;
+    return this.rejected && !this.timeout.rejected && !!((_a = this._signals) == null ? void 0 : _a.find((s) => s == null ? void 0 : s.aborted));
+  }
+  cancelAbort() {
+    var _a;
+    (_a = this._signals) == null ? void 0 : _a.forEach(
+      (signal) => signal == null ? void 0 : signal.removeEventListener(
+        "abort",
+        this._handleAbort
+      )
+    );
+  }
+  clearTimeout() {
+    clearTimeout(this.timeout.timeoutId);
+  }
+  get timedout() {
+    return this.rejected && this.timeout.rejected;
   }
-  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`)
+};
+TimeoutPromise.defaults = {
+  abortOnEarlyFinalize: true,
+  batchFunc: "all",
+  timeout: TIMEOUT_FALLBACK
+};
+var TimeoutPromise_default = TimeoutPromise;
+
+// src/timeout.ts
+import {
+  arrUnique as arrUnique2,
+  isFn as isFn4,
+  isNumber,
+  isObj as isObj2,
+  isPositiveNumber as isPositiveNumber2,
+  objCopy as objCopy3
+} from "@superutils/core";
+function timeout(options, ...values) {
+  var _a;
+  const opts = objCopy3(
+    timeout.defaults,
+    isNumber(options) ? { timeout: options } : isObj2(options) ? options : {},
+    [],
+    "empty"
+  );
+  opts.timeout = Math.min(
+    isPositiveNumber2(opts.timeout) ? opts.timeout : TIMEOUT_FALLBACK,
+    TIMEOUT_MAX
+  );
+  const promises = values.map(
+    (v) => isFn4(v) ? PromisEBase_default.try(v) : v
+  );
+  const dataPromise = promises.length <= 1 ? (
+    // single promise resolves to a single result
+    promises[0] instanceof PromisEBase_default ? promises[0] : new PromisEBase_default(promises[0])
+  ) : (
+    // multiple promises resolve to an array of results
+    (isFn4(PromisEBase_default[opts.batchFunc]) ? PromisEBase_default[opts.batchFunc] : PromisEBase_default.all)(promises)
+  );
+  const timeoutPromise = delayReject_default(opts.timeout, opts.onTimeout);
+  const promise = new TimeoutPromise_default(
+    PromisEBase_default.race([dataPromise, timeoutPromise]),
+    timeoutPromise,
+    opts,
+    arrUnique2(
+      [(_a = opts.abortCtrl) == null ? void 0 : _a.signal, opts.signal].filter(Boolean)
+    )
   );
-  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();
-  });
   return promise;
 }
-timeout.defaultOptions = {
-  func: "all",
-  timeout: 1e4
-};
 var timeout_default = timeout;
+timeout.defaults = TimeoutPromise_default.defaults;
+Object.defineProperty(timeout, "defaults", {
+  get() {
+    return TimeoutPromise_default.defaults;
+  },
+  set(newDefaults) {
+    TimeoutPromise_default.defaults = newDefaults;
+  }
+});
 
 // src/PromisE.ts
 var PromisE = class extends PromisEBase_default {
@@ -469,6 +572,9 @@ export {
   PromisEBase,
   ResolveError,
   ResolveIgnored,
+  TIMEOUT_FALLBACK,
+  TIMEOUT_MAX,
+  TimeoutPromise,
   index_default as default,
   deferred,
   deferredCallback,

package/package.json

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