Superutils

Appearance

Class: PromisE<T> ​

Defined in: packages/promise/src/PromisE.ts:49

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.

Examples ​

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
)
typescript
import PromisE from '@superutils/promise'
const instance = new Promise((resolve) => setTimeout(() => resolve(1), 1000))
const p = new PromisE(instance)
console.log(p.pending)
typescript
import PromisE from '@superutils/promise'
const p = new PromisE<number>()
setTimeout(() => p.resolve(1))
p.then(console.log)
typescript
import PromisE from '@superutils/promise'
const p = PromisE.try(() => { throw new Error('I am a naughty function' ) })
p.catch(console.error)

Extends ​

Type Parameters ​

T ​

T = unknown

Constructors ​

Constructor ​

new PromisE<T>(...args): PromisE<T>

Defined in: packages/promise/src/PromisEBase.ts:18

Create a PromisE instance as a drop-in replacement for Promise

Parameters ​

args ​

...[(resolve, reject) => void]

Returns ​

PromisE<T>

Inherited from ​

PromisEBase.constructor

Constructor ​

new PromisE<T>(promise): PromisE<T>

Defined in: packages/promise/src/PromisEBase.ts:20

Extend an existing Promise instance to check status or finalize early

Parameters ​

promise ​

Promise<T>

Returns ​

PromisE<T>

Inherited from ​

PromisEBase.constructor

Constructor ​

new PromisE<T>(value): PromisE<T>

Defined in: packages/promise/src/PromisEBase.ts:22

Create a resolved promise with value

Parameters ​

value ​

T

Returns ​

PromisE<T>

Inherited from ​

PromisEBase.constructor

Constructor ​

new PromisE<T>(): PromisE<T>

Defined in: packages/promise/src/PromisEBase.ts:35

If executor function is not provided, the promise must be resolved/rejected externally.

Returns ​

PromisE<T>

Example ​

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)

Inherited from ​

PromisEBase.constructor

Properties ​

[toStringTag] ​

readonly [toStringTag]: string

Defined in: node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:176

Inherited from ​

PromisEBase.[toStringTag]

onEarlyFinalize ​

onEarlyFinalize: OnEarlyFinalize<T>[] = []

Defined in: packages/promise/src/PromisEBase.ts:15

callbacks to be invoked whenever PromisE instance is finalized early using non-static resolve()/reject() methods

Inherited from ​

PromisEBase.onEarlyFinalize

state ​

readonly state: 0 | 1 | 2 = 0

Defined in: packages/promise/src/PromisEBase.ts:9

0: pending, 1: resolved, 2: rejected

Inherited from ​

PromisEBase.state

[species] ​

readonly static [species]: PromiseConstructor

Defined in: node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:180

Inherited from ​

PromisEBase.[species]

deferred ​

static deferred: typeof deferred

Defined in: packages/promise/src/PromisE.ts:50

deferredCallback() ​

static deferredCallback: <TDefault, ThisArg, Delay, CbArgs>(callback, options) => <TResult>(...args) => IPromisE<TResult>

Defined in: packages/promise/src/PromisE.ts:52

Function

PromisE.deferredCallback

Type Parameters ​

TDefault ​

TDefault

ThisArg ​

ThisArg

Delay ​

Delay extends number = number

CbArgs ​

CbArgs extends unknown[] = unknown[]

Parameters ​

callback ​

(...args) => TDefault | Promise<TDefault>

options ​

DeferredAsyncOptions<ThisArg, Delay> = {}

Returns ​

deferred/throttled function

<TResult>(...args): IPromisE<TResult>

Type Parameters ​
TResult ​

TResult = TDefault

Parameters ​
args ​

...CbArgs

Returns ​

IPromisE<TResult>

Example ​

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

delay ​

static delay: typeof delay

Defined in: packages/promise/src/PromisE.ts:54

delayReject() ​

static delayReject: <T>(duration, reason?) => IPromisE_Delay<T>

Defined in: packages/promise/src/PromisE.ts:56

Function

PromisE.delayReject

Type Parameters ​

T ​

T = never

Parameters ​

duration ​

number

reason? ​

unknown

Returns ​

IPromisE_Delay<T>

Examples ​

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()
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')

retry ​

static retry: {<T>(func, options?): Promise<T>; defaults: object; }

Defined in: packages/promise/src/PromisE.ts:58

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.

Type Parameters ​

T ​

T

The type of the value that the func returns/resolves to.

Parameters ​

func ​

() => ValueOrPromise<T>

The function to execute. It can be synchronous or asynchronous.

options? ​

RetryOptions<T>

(optional) Options for configuring the retry mechanism.

Returns ​

Promise<T>

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.

defaults ​

defaults: object

defaults.retry ​

retry: number = 1

defaults.retryBackOff ​

retryBackOff: "exponential" = 'exponential'

defaults.retryDelay ​

retryDelay: number = 300

defaults.retryDelayJitter ​

retryDelayJitter: true = true

defaults.retryDelayJitterMax ​

retryDelayJitterMax: number = 100

timeout ​

static timeout: typeof timeout

Defined in: packages/promise/src/PromisE.ts:60

Accessors ​

pending ​

Get Signature ​

get pending(): boolean

Defined in: packages/promise/src/PromisEBase.ts:72

Indicates if the promise is still pending/unfinalized

Returns ​

boolean

Indicates if the promise is still pending/unfinalized

Inherited from ​

PromisEBase.pending

rejected ​

Get Signature ​

get rejected(): boolean

Defined in: packages/promise/src/PromisEBase.ts:77

Indicates if the promise has been rejected

Returns ​

boolean

Indicates if the promise has been rejected

Inherited from ​

PromisEBase.rejected

resolved ​

Get Signature ​

get resolved(): boolean

Defined in: packages/promise/src/PromisEBase.ts:82

Indicates if the promise has been resolved

Returns ​

boolean

Indicates if the promise has been resolved

Inherited from ​

PromisEBase.resolved

Methods ​

catch() ​

catch<TResult>(onrejected?): Promise<T | TResult>

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1564

Attaches a callback for only the rejection of the Promise.

Type Parameters ​

TResult ​

TResult = never

Parameters ​

onrejected? ​

The callback to execute when the Promise is rejected.

null | (reason) => TResult | PromiseLike<TResult>

Returns ​

Promise<T | TResult>

A Promise for the completion of the callback.

Inherited from ​

PromisEBase.catch

finally() ​

finally(onfinally?): Promise<T>

Defined in: node_modules/typescript/lib/lib.es2018.promise.d.ts:29

Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.

Parameters ​

onfinally? ​

The callback to execute when the Promise is settled (fulfilled or rejected).

null | () => void

Returns ​

Promise<T>

A Promise for the completion of the callback.

Inherited from ​

PromisEBase.finally

reject() ​

reject(reason): void

Defined in: packages/promise/src/PromisEBase.ts:103

Reject pending promise early.

Parameters ​

reason ​

unknown

Returns ​

void

Inherited from ​

PromisEBase.reject

resolve() ​

resolve(value): void

Defined in: packages/promise/src/PromisEBase.ts:93

Resovle pending promise early.

Parameters ​

value ​

T | PromiseLike<T>

Returns ​

void

Inherited from ​

PromisEBase.resolve

then() ​

then<TResult1, TResult2>(onfulfilled?, onrejected?): Promise<TResult1 | TResult2>

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1557

Attaches callbacks for the resolution and/or rejection of the Promise.

Type Parameters ​

TResult1 ​

TResult1 = T

TResult2 ​

TResult2 = never

Parameters ​

onfulfilled? ​

The callback to execute when the Promise is resolved.

null | (value) => TResult1 | PromiseLike<TResult1>

onrejected? ​

The callback to execute when the Promise is rejected.

null | (reason) => TResult2 | PromiseLike<TResult2>

Returns ​

Promise<TResult1 | TResult2>

A Promise for the completion of which ever callback is executed.

Inherited from ​

PromisEBase.then

all() ​

static all<T>(values): IPromisE<{ -readonly [P in string | number | symbol]: Awaited<T[P<P>]> }>

Defined in: packages/promise/src/PromisEBase.ts:121

Sugar for new PromisE(Promise.all(...))

Type Parameters ​

T ​

T extends unknown[]

Parameters ​

values ​

T

Returns ​

IPromisE<{ -readonly [P in string | number | symbol]: Awaited<T[P<P>]> }>

Inherited from ​

PromisEBase.all

allSettled() ​

static allSettled<T>(values): IPromisE<PromiseSettledResult<Awaited<T[number]>>[]>

Defined in: packages/promise/src/PromisEBase.ts:127

Sugar for new PromisE(Promise.allSettled(...))

Type Parameters ​

T ​

T extends unknown[]

Parameters ​

values ​

T

Returns ​

IPromisE<PromiseSettledResult<Awaited<T[number]>>[]>

Inherited from ​

PromisEBase.allSettled

any() ​

static any<T>(values): IPromisE<Awaited<T[number]>>

Defined in: packages/promise/src/PromisEBase.ts:133

Sugar for new PromisE(Promise.any(...))

Type Parameters ​

T ​

T extends unknown[]

Parameters ​

values ​

T

Returns ​

IPromisE<Awaited<T[number]>>

Inherited from ​

PromisEBase.any

race() ​

static race<T>(values): IPromisE<Awaited<T[number]>>

Defined in: packages/promise/src/PromisEBase.ts:139

Sugar for new PromisE(Promise.race(..))

Type Parameters ​

T ​

T extends unknown[]

Parameters ​

values ​

T

Returns ​

IPromisE<Awaited<T[number]>>

Inherited from ​

PromisEBase.race

reject() ​

static reject<T>(reason): IPromisE<T>

Defined in: packages/promise/src/PromisEBase.ts:145

Extends Promise.reject

Type Parameters ​

T ​

T = never

Parameters ​

reason ​

unknown

Returns ​

IPromisE<T>

Inherited from ​

PromisEBase.reject

resolve() ​

static resolve<T>(value?): IPromisE<T>

Defined in: packages/promise/src/PromisEBase.ts:152

Sugar for new PromisE(Promise.resolve(...))

Type Parameters ​

T ​

T

Parameters ​

value? ​

T | PromiseLike<T>

Returns ​

IPromisE<T>

Inherited from ​

PromisEBase.resolve

try() ​

static try<T, U>(callbackFn, ...args): IPromisE<Awaited<T>>

Defined in: packages/promise/src/PromisEBase.ts:158

Sugar for new PromisE(Promise.try(...))

Type Parameters ​

T ​

T

U ​

U extends unknown[]

Parameters ​

callbackFn ​

(...args) => T | PromiseLike<T>

args ​

...U

Returns ​

IPromisE<Awaited<T>>

Inherited from ​

PromisEBase.try

withResolvers() ​

static withResolvers<T>(): object

Defined in: packages/promise/src/PromisEBase.ts:199

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.

Type Parameters ​

T ​

T = unknown

Returns ​

object

promise ​

promise: IPromisE<T>

reject() ​

reject: (reason) => void = promise.reject

Parameters ​
reason ​

unknown

Returns ​

void

resolve() ​

resolve: (value) => void = promise.resolve

Parameters ​
value ​

T | PromiseLike<T>

Returns ​

void

Examples ​

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)

Using withResolvers

typescript
import PromisE from '@superutils/promise'
const pwr = PromisE.withResolvers<number>()
setTimeout(() => pwr.resolve(1), 1000)
pwr.promise.then(console.log)

Inherited from ​

PromisEBase.withResolvers