@xylabs/promise

@xylabs/promise

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Install

Using npm:

npm install {{name}}

Using yarn:

yarn add {{name}}

Using pnpm:

pnpm add {{name}}

Using bun:

bun add {{name}}

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Reference

packages

promise

### .temp-typedoc

  ### classes

    ### <a id="PromiseEx"></a>PromiseEx

@xylabs/promise

An extended Promise that carries an optional attached value and supports cancellation. The value can be inspected via the then or value methods to conditionally cancel.

Extends

• Promise<T>

Type Parameters

T

T

V

V = void

Constructors

Constructor

new PromiseEx<T, V>(func, value?): PromiseEx<T, V>;

Parameters

func

PromiseExFunc<T>

value?

V

Returns

PromiseEx<T, V>

Overrides

Promise<T>.constructor

Properties

cancelled?

optional cancelled?: boolean;

Whether the promise has been cancelled via a value callback.

Methods

then()

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

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

Type Parameters

TResult1

TResult1 = T

TResult2

TResult2 = never

Parameters

onfulfilled?

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

The callback to execute when the Promise is resolved.

onrejected?

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

The callback to execute when the Promise is rejected.

onvalue?

(value?) => boolean

Returns

Promise<TResult1 | TResult2>

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

Overrides

Promise.then

value()

value(onvalue?): PromiseEx<T, V>;

Inspects the attached value via the callback; if it returns true, marks the promise as cancelled.

Parameters

onvalue?

(value?) => boolean

A callback that receives the attached value and returns whether to cancel.

Returns

PromiseEx<T, V>

This instance for chaining.

  ### functions

    ### <a id="fulfilled"></a>fulfilled

@xylabs/promise

function fulfilled<T>(val): val is PromiseFulfilledResult<T>;

For use with Promise.allSettled to filter only successful results

Type Parameters

T

T

Parameters

val

PromiseSettledResult<T>

Returns

val is PromiseFulfilledResult<T>

    ### <a id="fulfilledValues"></a>fulfilledValues

@xylabs/promise

function fulfilledValues<T>(previousValue, currentValue): T[];

For use with Promise.allSettled to reduce to only successful result values

Type Parameters

T

T

Parameters

previousValue

T[]

currentValue

PromiseSettledResult<T>

Returns

T[]

Examples

const resolved = Promise.resolve('resolved')
const rejected = Promise.reject('rejected')
const settled = await Promise.allSettled([resolved, rejected])
const results = settled.reduce(fulfilledValues, [] as string[])
// results === [ 'resolved' ]

const resolved = Promise.resolve('resolved')
const rejected = Promise.reject('rejected')
const settled = await Promise.allSettled([resolved, rejected])
const results = settled.reduce<string[]>(fulfilledValues, [])
// results === [ 'resolved' ]

    ### <a id="rejected"></a>rejected

@xylabs/promise

function rejected<T>(val): val is PromiseRejectedResult;

For use with Promise.allSettled to filter only rejected results

Type Parameters

T

T

Parameters

val

PromiseSettledResult<T>

Returns

val is PromiseRejectedResult

    ### <a id="toPromise"></a>toPromise

@xylabs/promise

function toPromise<T>(value): Promise<T>;

Wraps a value in a Promise if it is not already one.

Type Parameters

T

T

Parameters

value

Promisable<T>

A value that may or may not be a Promise.

Returns

Promise<T>

A Promise resolving to the value.

  ### interfaces

    ### <a id="PromiseType"></a>PromiseType

@xylabs/promise

An interface representing any thenable (promise-like) object.

Properties

then

then: () => unknown;

Returns

unknown

  ### type-aliases

    ### <a id="AnyNonPromise"></a>AnyNonPromise

@xylabs/promise

type AnyNonPromise = Exclude<TypedValue, PromiseType>;

Any non-promise typed value, excluding thenables.

    ### <a id="AsyncMutex"></a>AsyncMutex

@xylabs/promise

type AsyncMutex<T> = Promise<T>;

Type Parameters

T

T

Description

Used to document promises that are being used as Mutexes

    ### <a id="NullablePromisable"></a>NullablePromisable

@xylabs/promise

type NullablePromisable<T, V> = Promisable<T | null, V>;

A Promisable that may resolve to null.

Type Parameters

T

T

V

V = never

    ### <a id="NullablePromisableArray"></a>NullablePromisableArray

@xylabs/promise

type NullablePromisableArray<T, V> = PromisableArray<T | null, V>;

A Promisable array where elements may be null.

Type Parameters

T

T

V

V = never

    ### <a id="OptionalPromisable"></a>OptionalPromisable

@xylabs/promise

type OptionalPromisable<T, V> = Promisable<T | undefined, V>;

A Promisable that may resolve to undefined.

Type Parameters

T

T

V

V = never

    ### <a id="OptionalPromisableArray"></a>OptionalPromisableArray

@xylabs/promise

type OptionalPromisableArray<T, V> = PromisableArray<T | undefined, V>;

A Promisable array where elements may be undefined.

Type Parameters

T

T

V

V = never

    ### <a id="Promisable"></a>Promisable

@xylabs/promise

type Promisable<T, V> = PromiseEx<T, V> | Promise<T> | T;

A value that may be a Promise, PromiseEx, or a plain synchronous value.

Type Parameters

T

T

V

V = never

    ### <a id="PromisableArray"></a>PromisableArray

@xylabs/promise

type PromisableArray<T, V> = Promisable<T[], V>;

A Promisable that resolves to an array.

Type Parameters

T

T

V

V = never

    ### <a id="PromiseExFunc"></a>PromiseExFunc

@xylabs/promise

type PromiseExFunc<T> = (resolve?, reject?) => void;

The executor function passed to the PromiseEx constructor.

Type Parameters

T

T

Parameters

resolve?

PromiseExSubFunc<T, void>

reject?

PromiseExSubFunc<T, void>

Returns

void

    ### <a id="PromiseExSubFunc"></a>PromiseExSubFunc

@xylabs/promise

type PromiseExSubFunc<T, TResult> = (value) => TResult;

A resolve/reject callback used within PromiseEx.

Type Parameters

T

T

TResult

TResult = T

Parameters

value

T

Returns

TResult

    ### <a id="PromiseExValueFunc"></a>PromiseExValueFunc

@xylabs/promise

type PromiseExValueFunc<V> = (value?) => boolean;

A callback that inspects the attached value and returns whether to cancel the promise.

Type Parameters

V

V

Parameters

value?

V

Returns

boolean