@superutils/promise 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Toufiqur Rahaman Chowdhury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# @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.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+    - [`new PromisE(executor)`](#promise-executor): Drop-in replacement for `Promise`
+    - [`new PromisE(promise)`](#promise-status): Check promise status
+    - [`PromisE.try()`](#static-methods): Static methods
+    - [`PromisE.delay()`](#delay): Async delay
+    - [`PromisE.deferred()`](#deferred): Async debounced/throttled callback
+    - [`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
+```
+
+## 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:
+
+```typescript
+import { PromisE } from '@superutils/promise'
+
+const p = new PromisE(resolve => setTimeout(() => resolve('done'), 1000))
+
+console.log(p.pending) // true
+
+p.then(result => {
+	console.log(result) // 'done'
+	console.log(p.resolved) // true
+	console.log(p.pending) // false
+})
+```
+
+and the ability to early finalize a 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)
+```
+
+<div id="static-methods"></div>
+
+### `PromisE.try(fn)`: Static methods
+
+Drop-in replacement for all `Promise` static methods such as `.all()`, `.race()`, `.reject`, `.resolve`, `.try()`, `.withResolvers()`....
+
+```typescript
+import { PromisE } from '@superutils/promise'
+
+const p = PromisE.try(() => {
+	throw new Error('Something went wrong')
+})
+
+p.catch(error => {
+	console.error(error.message) // 'Something went wrong'
+	console.log(p.rejected) // true
+})
+```
+
+<div id="promise-status"></div>
+
+### `new PromisE(promise)`
+
+Check status of an existing promise.
+
+```typescript
+import { PromisE } from '@superutils/promise'
+const x = Promise.resolve(1)
+const p = new PromisE(x)
+console.log(p.pending) // false
+console.log(p.resolved) // true
+console.log(p.rejected) // false
+```
+
+<div id="delay"></div>
+
+### `PromisE.delay(duration)`: Async delay
+
+Creates a promise that resolves after a specified duration, essentially a promise-based `setTimeout`.
+
+```typescript
+import PromisE from '@superutils/promise'
+// Wait until `appReady` becomes truthy but
+while (!appReady) {
+	await PromisE.delay(100)
+}
+```
+
+#### `PromisE.delay(duration, callback)`: execute after delay
+
+Creates a promise that executes a function after a specified duration and returns the value the function returns.
+
+If callback returns undefined, default value will be the duration.
+
+```typescript
+import PromisE from '@superutils/promise'
+
+const callback = () => {
+	/* do stuff here */
+}
+await PromisE.delay(100, callback)
+```
+
+<div id="deferred"></div>
+
+### `PromisE.deferred(options)`: async debounced/throttled execution
+
+Create a function that debounces or throttles promise-returning function calls. This is useful for scenarios like auto-saving user input or preventing multiple rapid API calls.
+
+```typescript
+import PromisE, { ResolveIgnored } from '@superutils/promise'
+
+// Create a deferred function that waits 300ms after the last call
+const deferredSave = PromisE.deferred({
+	defer: 300,
+	/** ignored promises will resolve with `undefined` */
+	resolveIgnored: ResolveIgnored.WITH_UNDEFINED,
+
+	/** ignored promises will NEVER be resolved/rejected
+	 * USE WITH CAUTION!
+	 */
+	resolveIgnored: ResolveIgnored.NEVER,
+
+	// ignored promises will resolve with the result of the last call
+	resolveIgnored: ResolveIgnored.WITH_LAST, // (default)
+})
+
+// Simulate rapid calls
+deferredSave(() => api.save({ text: 'first' }))
+deferredSave(() => api.save({ text: 'second' }))
+// Only the 3rd call is executed.
+// But all of them are resolved with the result of the 3rd call when `resolveIgnored` is `ResolveIgnored.WITH_LAST`
+deferredSave(() => api.save({ text: 'third' })).then(response =>
+	console.log('Saved!', response),
+)
+```
+
+<div id="deferredCallback"></div>
+
+### `PromisE.deferredCallback(callback, options)`: async debounced/throttled callbacks
+
+Same as `PromisE.deferred` but for event handlers etc.
+
+```typescript
+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,
+})
+// 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,
+	),
+)
+// Prints:
+// 200, 600, 1100
+```
+
+<div id="timeout"></div>
+
+### `PromisE.timeout(duration, ...promises)`: Reject after timeout
+
+#### Reject stuck or unexpectedly lenghthy promise(s) after a specified timeout:
+
+```typescript
+import { PromisE } from '@superutils/promise'
+
+PromisE.timeout(
+	5000, // timeout after 5000ms
+	api.save({ text: 'takes longer than 5s to finish' }),
+).catch(console.log)
+// Error: Error('Timed out after 5000ms')
+```
+
+#### Show a message when loading is too long:
+
+```typescript
+import { PromisE } from '@superutils/promise'
+
+const loadUserNProducts = () => {
+	const promise = PromisE.timeout(
+		5000, // timeout after 5000ms
+		api.getUser(),
+		api.getProducts(),
+	)
+	const [user, products] = await promise.catch(err => {
+		// promise did not time out, but was rejected
+		// because one of the data promises rejected
+		if (!promise.timedout) return Promise.reject(err)
+
+		// promise timed out >> print/update UI
+		console.log('Request is taking longer than expected......')
+		// now return the "data promise", the promise(s) provided in the PromisE.timeout()
+		// If more than one promises provided, then `promise.data` will be the combination of them all: `PromisE.all(...promises)`
+		return promise.data
+	})
+	return [user, products]
+}
+loadUserNProducts()
+```

package/dist/index.d.ts

@@ -0,0 +1,617 @@
+import * as _superutils_core from '@superutils/core';
+import { ValueOrPromise, TimeoutId, ThrottleConfig, DeferredConfig } 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>[];
+    /** Indicates if the promise is still pending/unfinalized */
+    readonly pending: boolean;
+    /** Reject pending promise early. */
+    reject: (reason: unknown) => void;
+    /** Indicates if the promise has been rejected */
+    readonly rejected: boolean;
+    /** Resovle pending promise early. */
+    resolve: (value: T | PromiseLike<T>) => void;
+    /** Indicates if the promise has been resolved */
+    readonly resolved: boolean;
+}
+interface IPromisE_Delay<T = unknown> extends 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;
+    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 DeferredReturn<TArgs extends unknown[] | [] = []> = <TResult = unknown>(promise: Promise<TResult> | ((...args: TArgs) => Promise<TResult>)) => IPromisE<TResult>;
+type DeferredOptions<ThisArg = unknown> = {
+    /** Delay in milliseconds, used for `debounce` and `throttle` modes. */
+    delayMs?: number;
+    /** Callback invoked whenever promise/function throws error */
+    onError?: (err: unknown) => ValueOrPromise<unknown>;
+    /**
+     * Whenever a promise/function is ignored when in debource/throttle mode, `onIgnored` wil be invoked.
+     * The promise/function will not be invoked, unless it's manually invoked using the `ignored` function.
+     * Use for debugging or logging purposes.
+     */
+    onIgnore?: (ignored: () => Promise<unknown>) => ValueOrPromise<unknown>;
+    /**
+     * Whenever a promise/function is executed successfully `onResult` will be called.
+     * Those that are ignored but resolve with last will not cause `onResult` to be invoked.
+     *
+     * Result can be `undefined` if `ResolveIgnored.WITH_UNDEFINED` is used.
+     */
+    onResult?: (result?: unknown) => ValueOrPromise<unknown>;
+    /**
+     * Indicates what to do when a promise in the queue is ignored.
+     * See {@link ResolveIgnored} for available options.
+     */
+    resolveIgnored?: ResolveIgnored;
+    resolveError?: ResolveError;
+    /** Enable throttle mode. Requires {@link DeferredOptions.delayMs}*/
+    throttle?: boolean;
+} & (({
+    delayMs: number;
+    throttle: true;
+} & ThrottleConfig<ThisArg>) | ({
+    delayMs?: number;
+    throttle?: false;
+} & DeferredConfig<ThisArg>));
+/** Options for what to do when deferred promise/function fails */
+declare enum ResolveError {
+    /** Neither resolve nor reject the failed */
+    NEVER = "NEVER",
+    /** (default) Reject the failed as usual */
+    REJECT = "REJECT",
+    /** Resolve (not reject) with the error/reason */
+    WITH_ERROR = "RESOLVE_ERROR",
+    /** Resolve with undefined */
+    WITH_UNDEFINED = "RESOLVE_UNDEFINED"
+}
+/** Options for what to do when a promise/callback is ignored, either because of being deferred, throttled or another been prioritized. */
+declare enum ResolveIgnored {
+    /** Never resolve ignored promises. Caution: make sure this doesn't cause any memory leaks. */
+    NEVER = "NEVER",
+    /** (default) resolve with active promise result, the one that caused the current promise/callback to be ignored).  */
+    WITH_LAST = "WITH_LAST",
+    /** resolve with `undefined` value */
+    WITH_UNDEFINED = "WITH_UNDEFINED"
+}
+
+/** Global configuration */
+declare const config: {
+    /** Default value for `options` used by `PromisE.*deferred*` functions */
+    deferOptions: DeferredOptions;
+    delayTimeoutMsg: string;
+    retryOptions: {
+        retry: number;
+        retryBackOff: "exponential";
+        retryDelay: number;
+        retryDelayJitter: true;
+        retryDelayJitterMax: number;
+        retryIf: null;
+    };
+};
+type Config = typeof config;
+
+/** Options for automatic retry mechanism */
+type RetryOptions<T = unknown> = {
+    /**
+     * Maximum number of retries.
+     *
+     * The total number of attempts will be `retry + 1`.
+     *
+     * Default: `1`
+     */
+    retry?: number;
+    /**
+     * Accepted values:
+     * - exponential: each subsequent retry delay will be doubled from the last
+     * - linear: fixed delay between retries
+     * Default: 'exponential'
+     */
+    retryBackOff?: 'exponential' | 'linear';
+    /**
+     * Delay in milliseconds between retries.
+     * Default: `300`
+     */
+    retryDelay?: number;
+    /**
+     * Add a random delay between 0ms and `retryDelayJitterMax` to the `retryDelayMs`.
+     * Default: `true`
+     */
+    retryDelayJitter?: boolean;
+    /**
+     * Maximum delay (in milliseconds) to be used when randomly generating jitter delay duration.
+     * 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.
+     */
+    retryIf?: null | ((prevResult: T | undefined, retryCount: number, error?: unknown) => boolean);
+};
+
+/**
+ * @function PromisE.deferred
+ * The adaptation of the `deferred()` function tailored for Promises.
+ *
+ * @param options           (optional) options
+ * @property options.delayMs   (optional) delay in milliseconds to be used with debounce & throttle modes. When `undefined` or `>= 0`, execution will be sequential.
+ * @property options.onError   (optional)
+ * @property options.onIgnore  (optional) invoked whenever callback invocation is ignored by a newer invocation
+ * @property options.onResult  (optional)
+ * @property options.resolveIgnored  (optional) see {@link ResolveIgnored}.
+ * Default: `PromisE.defaultResolveIgnord` (changeable)
+ *
+ * @property options.throttle  (optional) toggle to switch between debounce/deferred and throttle mode.
+ * Requires `defer`.
+ * Default: `false`
+ *
+ * @returns {Function} a callback that is invoked in one of the followin 3 methods:
+ * - sequential: when `delayMs <= 0` or `delayMs = undefined`
+ * - debounced: when `delayMs > 0` and `throttle = false`
+ * - throttled: when `delayMs > 0` and `throttle = true`
+ *
+ * The main difference is that:
+ *  - Notes:
+ *      1. A "request" simply means invokation of the returned callback function
+ *      2. By "handled" it means a "request" will be resolved or rejected.
+ *  - `PromisE.deferred` is to be used with promises/functions
+ *  - There is no specific time delay.
+ *  - The time when a request is completed is irrelevant.
+ *  - If not throttled:
+ *      1. Once a request is handled, all previous requests will be ignored and pool starts anew.
+ *      2. If a function is provided in the  returned callback, ALL of them will be invoked, regardless of pool size.
+ *      3. The last/only request in an on-going requests' pool will handled (resolve/reject).
+ *  - If throttled:
+ *      1. Once a requst starts executing, subsequent requests will be added to a queue.
+ *      2. The last/only item in the queue will be handled. Rest will be ignored.
+ *      3. If a function is provided in the returned callback, it will be invoked only if the request is handled.
+ *      Thus, improving performance by avoiding unnecessary invokations.
+ *      4. If every single request/function needs to be invoked, avoid using throttle.
+ *
+ *  - If throttled and `strict` is truthy, all subsequent request while a request is being handled will be ignored.
+ *
+ * @example Explanation & example usage:
+ * ```typescript
+ * const example = throttle => {
+ *     const df = PromisE.deferred(throttle)
+ *     df(() => PromisE.delay(5000)).then(console.log)
+ *     df(() => PromisE.delay(500)).then(console.log)
+ *     df(() => PromisE.delay(1000)).then(console.log)
+ *     // delay 2 seconds and invoke df() again
+ *     setTimeout(() => {
+ *         df(() => PromisE.delay(200)).then(console.log)
+ *     }, 2000)
+ * }
+ *
+ * // Without throttle
+ * example(false)
+ * // `1000` and `200` will be printed in the console
+ *
+ * // with throttle
+ * example(true)
+ * // `5000` and `200` will be printed in the console
+ *
+ * // with throttle with strict mode
+ * example(true)
+ * // `5000` will be printed in the console
+ * ```
+ */
+declare function deferred<T>(options?: DeferredOptions): DeferredReturn;
+
+/**
+ * @function PromisE.deferredCallback
+ *
+ * @summary a `PromisE.deferred()` wrapper for callbacks and event handlers.
+ *
+ * @returns deferred/throttled function
+ *
+ *
+ * @example Debounce/deferred event handler
+ * ```typescript
+ * const handleChange = (e: { target: { value: number }}) => console.log(e.target.value)
+ * const handleChangeDeferred = PromisE.deferredCallback(handleChange, {
+ *     delayMs: 300,
+ *     throttle: false,
+ * })
+ * // 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:
+ * // 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>;
+
+/**
+ * @function    PromisE.delay
+ * @summary Creates a promise that completes after given delay/duration.
+ *
+ * @param {Number}    duration   duration in milliseconds
+ * @param {unknown}   result    (optional) specify a value to resolve or reject with.
+ *                              Default: `delayMs` when resolved or timed out error when rejected
+ * @param {boolean}   asRejected (optional) if `true`, will reject the promise after the delay.
+ *
+ * @returns See {@link IPromisE_Delay}
+ *
+ * @example Delay before continuing execution
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * 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')
+ * ```
+ *
+ * @example Execute a function after delay.
+ * An awaitable `setTimeout()`.
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * PromisE.delay(1000, () => console.log('Prints after 1 second delay'))
+ * ```
+ */
+declare function delay<T = number, TReject extends boolean = boolean>(duration?: number, result?: T | (() => T), asRejected?: TReject): IPromisE_Delay<T>;
+
+/**
+ * @function    PromisE.delayReject
+ * @summary Creates a promise that rejects after given delay/duration.
+ *
+ * @example Create a promise that will rejectafter 3 seconds
+ * ```typescript
+ * const rejectPromise = PromisE.delayReject(
+ *     3000, // duration in milliseconds
+ *     new Error('App did not initialization on time'), // reason to reject with
+ * )
+ * await rejectPromise // throws error message after 3 seconds
+ * codeThatWillNotExecute()
+ * ```
+ *
+ * @example Prevent automated promise rejection by forcing it to resolve before timeout
+ * ```typescript
+ *
+ * const rejectPromise = PromisE.delayReject<string>(
+ *     3000,
+ *     new Error('App did not initialization on time'),
+ * )
+ * let count = 0
+ * const appReady = () => ++count >= 2 // return true on second call
+ * const intervalId = setInterval(() => {
+ *     if (!appReady()) return
+ *     rejectPromise.resolve('force resolves rejectPromise and execution continues')
+ *     clearInterval(intervalId)
+ * }, 100)
+ * await rejectPromise
+ * console.log('App is now ready')
+ * ```
+ */
+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.
+ *
+ * @param   timeout (optional) timeout duration in milliseconds.
+ *                  Default: `10000` (10 seconds)
+ * @param   values  promise/function: one or more promises as individual arguments
+ *
+ * @example Example 1: single promise - resolved
+ * ```typescript
+ * PromisE.timeout(
+ *   5000, // timeout after 5000ms
+ *   PromisE.delay(1000), // resolves after 1000ms with value 1000
+ * ).then(console.log)
+ * // Result: 1000
+ * ```
+ *
+ * @example Example 2: multiple promises - resolved
+ *
+ * ```typescript
+ * 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(3000), // resolves after 3000ms with value 3000
+ * ).then(console.log)
+ * // Result: [ 1000, 2000, 3000 ]
+ * ```
+ *
+ * @example Example 3: timed out & rejected
+ * ```typescript
+ * PromisE.timeout(
+ *     5000, // timeout after 5000ms
+ *     PromisE.delay(20000), // resolves after 20000ms with value 20000
+ * ).catch(console.error)
+ * // Error: Error('Timed out after 5000ms')
+ *```
+ *
+ * @example Example 4: timed out & but not rejected.
+ * // Eg: when API request is taking longer than expected, print a message but not reject the promise.
+ * ```typescript
+ * const promise = PromisE.timeout(
+ *     5000, // timeout after 5000ms
+ *     PromisE.delay(20000), // data promise, resolves after 20000ms with value 20000
+ * )
+ * const data = await promise.catch(err => {
+ *     // promise did not time out, but was rejected because one of the data promises rejected
+ *     if (!promise.timedout) return Promise.reject(err)
+ *
+ *     // promise timed out >> print/update UI
+ *     console.log('Request is taking longer than expected......')
+ *     // now return the data promise (the promise(s) provided in the PromisE.timeout())
+ *     return promise.data
+ * })
+ *```
+ */
+declare function timeout<T extends unknown[] | [], TOut = T['length'] extends 1 ? T[0] : T>(timeout?: number, ...values: Promise<TOut>[]): IPromisE_Timeout<TOut>;
+
+/**
+ * An attempt to solve the problem of Promise status (pending/resolved/rejected) not being easily accessible externally.
+ *
+ * For more example see static functions like `PromisE.deferred}, `PromisE.fetch}, `PromisE.timeout} etc.
+ *
+ *
+ * @example Example 1: As a drop-in replacement for Promise class
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ * const p = new PromisE((resolve, reject) => resolve('done'))
+ * console.log(
+ *  p.pending, // Indicates if promise has finalized (resolved/rejected)
+ *  p.resolved, // Indicates if the promise has resolved
+ *  p.rejected // Indicates if the promise has rejected
+ * )
+ * ```
+ *
+ * @example Example 2: Extend an existing "Proimse" instance to check status
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ * const instance = new Promise((resolve) => setTimeout(() => resolve(1), 1000))
+ * const p = new PromisE(instance)
+ * console.log(p.pending)
+ * ```
+ *
+ * @example Example 3: Create a promise to be finalized externally (an alternative to "PromisE.withResolvers()")
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ * const p = new PromisE<number>()
+ * setTimeout(() => p.resolve(1))
+ * p.then(console.log)
+ * ```
+ *
+ * @example Example 4. Invoke functions catching any error and wrapping the result in a PromisE instance
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ * const p = PromisE.try(() => { throw new Error('I am a naughty function' ) })
+ * p.catch(console.error)
+ * ```
+ */
+declare class PromisE<T = unknown> extends PromisEBase<T> {
+    /** Global configuration & default values */
+    static config: {
+        deferOptions: DeferredOptions;
+        delayTimeoutMsg: string;
+        retryOptions: {
+            retry: number;
+            retryBackOff: "exponential";
+            retryDelay: number;
+            retryDelayJitter: true;
+            retryDelayJitterMax: number;
+            retryIf: null;
+        };
+    };
+    static deferred: typeof deferred;
+    static deferredCallback: typeof deferredCallback;
+    static delay: typeof delay;
+    static delayReject: typeof delayReject;
+    static retry: <T_1>(func: () => _superutils_core.ValueOrPromise<T_1>, options?: RetryOptions<T_1>) => Promise<T_1>;
+    static timeout: typeof timeout;
+}
+
+/**
+ * Executes a function and retries it on failure or until a specific condition is met.
+ *
+ * The function will be re-executed if:
+ * 1. The `func` promise rejects or the function throws an error.
+ * 2. The optional `retryIf` function returns `true`.
+ * 3. `retry > 0`
+ *
+ * Retries will stop when the `retry` count is exhausted, or when `func` executes successfully
+ * (resolves without error) AND the `retryIf` (if provided) returns `false`.
+ *
+ * @template T The type of the value that the `func` returns/resolves to.
+ * @param {() => ValueOrPromise<T>}	func The function to execute. It can be synchronous or asynchronous.
+ * @param {RetryOptions} [options={}] (optional) Options for configuring the retry mechanism.
+ * @property {number} [options.retry=1] (optional) The maximum number of retries.
+ * @property {number} [options.retryDelayMs=300] The base delay in milliseconds between retries.
+ * @property {'exponential' | 'fixed'} [options.retryBackOff='exponential'] The backoff strategy. 'exponential' doubles the delay for each subsequent retry. 'fixed' uses a constant delay.
+ * @property {boolean} [options.retryDelayJitter=true] If true, adds a random jitter to the delay to prevent thundering herd problem.
+ * @property {number} [options.retryDelayJitterMax=100] The maximum jitter in milliseconds to add to the delay.
+ * @property {(result: T | undefined, retryCount: number) => boolean} [options.retryIf] A function that is called after a successful execution of `func`. If it returns `true`, a retry is triggered. It receives the result and the current retry count.
+ * @returns {Promise<T | undefined>} A promise that resolves with the result of the last successful execution of `func`.
+ * If all retries fail (either by throwing an error or by the condition function always returning true),
+ * it resolves with `undefined`. Errors thrown by `func` are caught and handled internally, not re-thrown.
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,408 @@
+// src/types/deferred.ts
+var ResolveError = /* @__PURE__ */ ((ResolveError2) => {
+  ResolveError2["NEVER"] = "NEVER";
+  ResolveError2["REJECT"] = "REJECT";
+  ResolveError2["WITH_ERROR"] = "RESOLVE_ERROR";
+  ResolveError2["WITH_UNDEFINED"] = "RESOLVE_UNDEFINED";
+  return ResolveError2;
+})(ResolveError || {});
+var ResolveIgnored = /* @__PURE__ */ ((ResolveIgnored2) => {
+  ResolveIgnored2["NEVER"] = "NEVER";
+  ResolveIgnored2["WITH_LAST"] = "WITH_LAST";
+  ResolveIgnored2["WITH_UNDEFINED"] = "WITH_UNDEFINED";
+  return ResolveIgnored2;
+})(ResolveIgnored || {});
+
+// src/config.ts
+var config = {
+  /** Default value for `options` used by `PromisE.*deferred*` functions */
+  deferOptions: {
+    delayMs: 100,
+    resolveError: "REJECT" /* REJECT */,
+    resolveIgnored: "WITH_LAST" /* WITH_LAST */,
+    throttle: false
+  },
+  delayTimeoutMsg: "Timed out after",
+  retryOptions: {
+    retry: 1,
+    retryBackOff: "exponential",
+    retryDelay: 300,
+    retryDelayJitter: true,
+    retryDelayJitterMax: 100,
+    retryIf: null
+  }
+};
+var config_default = config;
+
+// src/deferred.ts
+import {
+  deferred as deferredCore,
+  fallbackIfFails as fallbackIfFails2,
+  forceCast,
+  isFn as isFn2,
+  isPositiveNumber,
+  throttled as throttledCore
+} from "@superutils/core";
+
+// src/PromisEBase.ts
+import { asAny, 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) => {
+        asAny(this).state = 2;
+        reject(reason);
+      };
+      _resolve = (value) => {
+        asAny(this).state = 1;
+        resolve(value);
+      };
+      input != null ? input : input = () => {
+      };
+      const promise = isPromise(input) ? input : isFn(input) ? new globalThis.Promise(input) : Promise.resolve(input);
+      promise.then(_resolve, _reject);
+    });
+    this.state = 0;
+    /**
+     * callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods */
+    this.onEarlyFinalize = [];
+    //
+    //
+    // --------------------------- Early resolve/reject ---------------------------
+    //
+    //
+    /** Resovle pending promise early. */
+    this.resolve = (value) => {
+      var _a, _b;
+      if (!this.pending) return;
+      (_a = this._resolve) == null ? void 0 : _a.call(this, value);
+      (_b = this.onEarlyFinalize) == null ? void 0 : _b.forEach((fn) => {
+        fallbackIfFails(fn, [true, value], void 0);
+      });
+    };
+    /** Reject pending promise early. */
+    this.reject = (reason) => {
+      var _a, _b;
+      if (!this.pending) return;
+      (_a = this._reject) == null ? void 0 : _a.call(this, reason);
+      (_b = this.onEarlyFinalize) == null ? void 0 : _b.forEach((fn) => {
+        fallbackIfFails(fn, [false, reason], void 0);
+      });
+    };
+    this._resolve = _resolve;
+    this._reject = _reject;
+  }
+  //
+  //
+  //-------------------- Status related read-only attributes --------------------
+  //
+  //
+  /** Indicates if the promise is still pending/unfinalized */
+  get pending() {
+    return this.state === 0;
+  }
+  /** Indicates if the promise has been rejected */
+  get rejected() {
+    return this.state === 2;
+  }
+  /** Indicates if the promise has been resolved */
+  get resolved() {
+    return this.state === 1;
+  }
+  // static withResolvers = <T = unknown>() => {
+  // 	const pwr = globalThis.Promise.withResolvers<T>()
+  // 	const promise = new PromisEBase<T>(pwr.promise) as IPromisE<T>
+  // 	return { ...pwr, promise }
+  // }
+};
+//
+//
+// Extend all static `Promise` methods
+//
+//
+/** Sugar for `new PromisE(Promise.all(...))` */
+_PromisEBase.all = (values) => new _PromisEBase(globalThis.Promise.all(values));
+/** Sugar for `new PromisE(Promise.allSettled(...))` */
+_PromisEBase.allSettled = (values) => new _PromisEBase(globalThis.Promise.allSettled(values));
+/** Sugar for `new PromisE(Promise.any(...))` */
+_PromisEBase.any = (values) => new _PromisEBase(globalThis.Promise.any(values));
+/** Sugar for `new PromisE(Promise.race(..))` */
+_PromisEBase.race = (values) => new _PromisEBase(globalThis.Promise.race(values));
+/** Extends Promise.reject */
+_PromisEBase.reject = (reason) => {
+  const { promise, reject } = _PromisEBase.withResolvers();
+  queueMicrotask(() => reject(reason));
+  return promise;
+};
+/** Sugar for `new PromisE(Promise.resolve(...))` */
+_PromisEBase.resolve = (value) => new _PromisEBase(
+  globalThis.Promise.resolve(value)
+);
+/** Sugar for `new PromisE(Promise.try(...))` */
+_PromisEBase.try = (callbackFn, ...args) => new _PromisEBase(
+  (resolve) => resolve(
+    // Promise.try is not supported in Node < 23.
+    fallbackIfFails(
+      callbackFn,
+      args,
+      // rethrow error to ensure the returned promise is rejected
+      (err) => globalThis.Promise.reject(err)
+    )
+  )
+);
+/**
+ * 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)
+ * ```
+ */
+_PromisEBase.withResolvers = () => {
+  const promise = new _PromisEBase();
+  return { promise, reject: promise.reject, resolve: promise.resolve };
+};
+var PromisEBase = _PromisEBase;
+var PromisEBase_default = PromisEBase;
+
+// src/deferred.ts
+function deferred(options = {}) {
+  const defaults = config_default.deferOptions;
+  let { onError, onIgnore, onResult } = options;
+  const {
+    delayMs = defaults.delayMs,
+    resolveError = defaults.resolveError,
+    // by default reject on error
+    resolveIgnored = defaults.resolveIgnored,
+    thisArg,
+    throttle = defaults.throttle
+  } = options;
+  let lastPromisE = null;
+  const queue = /* @__PURE__ */ new Map();
+  const gotDelay = isPositiveNumber(delayMs);
+  if (thisArg !== void 0) {
+    onError = onError == null ? void 0 : onError.bind(thisArg);
+    onIgnore = onIgnore == null ? void 0 : onIgnore.bind(thisArg);
+    onResult = onResult == null ? void 0 : onResult.bind(thisArg);
+  }
+  const ignoreOrProceed = (currentId, qItem) => {
+    lastPromisE = null;
+    if (!gotDelay) {
+      queue.delete(currentId);
+      const [nextId, nextItem] = [...queue.entries()][0] || [];
+      return nextId && nextItem && execute(nextId, nextItem);
+    }
+    const items = [...queue.entries()];
+    const currentIndex = items.findIndex(([id]) => id === currentId);
+    for (let i = 0; i <= currentIndex; i++) {
+      const [iId, iItem] = items[i];
+      queue.delete(iId);
+      if (iItem == void 0 || iItem.started) continue;
+      onIgnore && fallbackIfFails2(onIgnore, [iItem.getPromise], void 0);
+      switch (resolveIgnored) {
+        case "WITH_UNDEFINED" /* WITH_UNDEFINED */:
+          iItem.resolve(void 0);
+          break;
+        case "WITH_LAST" /* WITH_LAST */:
+          qItem == null ? void 0 : qItem.then(iItem.resolve, iItem.reject);
+          break;
+        case "NEVER" /* NEVER */:
+          break;
+      }
+    }
+  };
+  const finalizeCb = (resolve, id, qItem) => (resultOrErr) => {
+    ignoreOrProceed(id, qItem);
+    if (resolve) {
+      qItem.resolve(resultOrErr);
+      onResult && fallbackIfFails2(onResult, [resultOrErr], void 0);
+      return;
+    }
+    onError && fallbackIfFails2(onError, [resultOrErr], void 0);
+    switch (resolveError) {
+      case "REJECT" /* REJECT */:
+        qItem.reject(resultOrErr);
+      // eslint-disable-next-line no-fallthrough
+      case "NEVER" /* NEVER */:
+        break;
+      case "RESOLVE_UNDEFINED" /* WITH_UNDEFINED */:
+        resultOrErr = void 0;
+      // eslint-disable-next-line no-fallthrough
+      case "RESOLVE_ERROR" /* WITH_ERROR */:
+        qItem.resolve(resultOrErr);
+        break;
+    }
+  };
+  const execute = (() => {
+    const execute2 = (id, qItem) => {
+      qItem.started = true;
+      lastPromisE = new PromisEBase_default(qItem.getPromise());
+      lastPromisE.then(
+        finalizeCb(true, id, qItem),
+        finalizeCb(false, id, qItem)
+      );
+    };
+    if (!gotDelay) return execute2;
+    const deferFn = throttle ? throttledCore : deferredCore;
+    return deferFn(execute2, delayMs, options);
+  })();
+  const deferredFunc = (promise) => {
+    const id = Symbol("deferred-queue-item-id");
+    const qItem = new PromisEBase_default();
+    qItem.getPromise = isFn2(promise) ? promise : () => promise;
+    qItem.started = false;
+    queue.set(id, qItem);
+    if (gotDelay || !lastPromisE) execute(id, qItem);
+    return forceCast(qItem);
+  };
+  return deferredFunc;
+}
+var deferred_default = deferred;
+
+// src/deferredCallback.ts
+function deferredCallback(callback, options = {}) {
+  const { thisArg } = options;
+  if (thisArg !== void 0) callback = callback.bind(thisArg);
+  const deferPromise = deferred_default(options);
+  return (...args) => deferPromise(() => callback(...args));
+}
+var deferredCallback_default = deferredCallback;
+
+// src/delay.ts
+import { fallbackIfFails as fallbackIfFails3, isFn as isFn3 } from "@superutils/core";
+function delay(duration = 100, result = duration, asRejected = false) {
+  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(
+      result2 != null ? result2 : new Error(`${config_default.delayTimeoutMsg} ${duration}ms`)
+    );
+  };
+  promise.timeoutId = setTimeout(() => finalize(result), duration);
+  promise.pause = () => clearTimeout(promise.timeoutId);
+  promise.catch(() => {
+  }).finally(() => promise.pause());
+  return promise;
+}
+var delay_default = delay;
+
+// src/delayReject.ts
+function delayReject(duration, reason) {
+  return delay_default(duration, reason, true);
+}
+var delayReject_default = delayReject;
+
+// src/retry.ts
+import { isPositiveInteger } from "@superutils/core";
+var retry = async (func, options = {}) => {
+  const d = config_default.retryOptions;
+  const {
+    retryIf,
+    retryBackOff = d.retryBackOff,
+    retryDelayJitter = d.retryDelayJitter
+  } = options;
+  let {
+    retry: maxRetries = 1,
+    retryDelay: delayMs,
+    retryDelayJitterMax: jitterMax
+  } = options;
+  maxRetries = maxRetries >= 0 ? maxRetries : d.retry;
+  delayMs = isPositiveInteger(delayMs) ? delayMs : d.retryDelay;
+  jitterMax = isPositiveInteger(jitterMax) ? jitterMax : d.retryDelayJitterMax;
+  let retryCount = -1;
+  let result;
+  let error;
+  let shouldRetry = false;
+  do {
+    retryCount++;
+    if (retryBackOff === "exponential" && retryCount > 1) delayMs *= 2;
+    if (retryDelayJitter) delayMs += Math.floor(Math.random() * jitterMax);
+    retryCount > 0 && await delay_default(delayMs);
+    try {
+      error = void 0;
+      result = await func();
+    } catch (err) {
+      error = err;
+    }
+    shouldRetry = maxRetries > 0 && (!!error || !!(retryIf == null ? void 0 : retryIf(result, retryCount, error))) && retryCount < maxRetries;
+  } while (shouldRetry);
+  if (error !== void 0) return Promise.reject(error);
+  return result;
+};
+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);
+  const timeoutPromise = delayReject_default(
+    timeout2,
+    new Error(`Timed out after ${timeout2}ms`)
+  );
+  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;
+}
+var timeout_default = timeout;
+
+// src/PromisE.ts
+var PromisE = class extends PromisEBase_default {
+};
+/** Global configuration & default values */
+PromisE.config = config_default;
+PromisE.deferred = deferred_default;
+PromisE.deferredCallback = deferredCallback_default;
+PromisE.delay = delay_default;
+PromisE.delayReject = delayReject_default;
+PromisE.retry = retry_default;
+PromisE.timeout = timeout_default;
+var PromisE_default = PromisE;
+
+// src/index.ts
+var index_default = PromisE_default;
+export {
+  PromisE,
+  PromisEBase,
+  ResolveError,
+  ResolveIgnored,
+  config,
+  index_default as default,
+  deferred,
+  deferredCallback,
+  delay,
+  delayReject,
+  retry,
+  timeout
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+	"author": "Toufiqur Rahaman Chowdhury",
+	"bugs": {
+		"url": "https://github.com/alien45/superutils/issues"
+	},
+	"dependencies": {
+		"@superutils/core": "^1.0.1"
+	},
+	"description": "An extended Promise class with extra features and utilities.",
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"homepage": "https://github.com/alien45/superutils/#readme",
+	"keywords": [
+		"promise",
+		"async",
+		"util",
+		"typescript"
+	],
+	"license": "MIT",
+	"main": "dist/index.js",
+	"name": "@superutils/promise",
+	"peerDpendencies": {
+		"@superutils/core": "^1.0.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/alien45/superutils.git"
+	},
+	"scripts": {
+		"_build": "tsc -p tsconfig.json",
+		"_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"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"types": "dist/index.d.ts",
+	"version": "1.0.1"
+}