@xylabs/promise

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Reference

@xylabs/promise

Classes

| Class | Description | | ------ | ------ | | PromiseEx | 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. |

Interfaces

| Interface | Description | | ------ | ------ | | PromiseType | An interface representing any thenable (promise-like) object. |

Type Aliases

| Type Alias | Description | | ------ | ------ | | PromiseExSubFunc | A resolve/reject callback used within PromiseEx. | | PromiseExFunc | The executor function passed to the PromiseEx constructor. | | PromiseExValueFunc | A callback that inspects the attached value and returns whether to cancel the promise. | | Promisable | A value that may be a Promise, PromiseEx, or a plain synchronous value. | | PromisableArray | A Promisable that resolves to an array. | | OptionalPromisable | A Promisable that may resolve to undefined. | | OptionalPromisableArray | A Promisable array where elements may be undefined. | | NullablePromisable | A Promisable that may resolve to null. | | NullablePromisableArray | A Promisable array where elements may be null. | | AsyncMutex | - | | AnyNonPromise | Any non-promise typed value, excluding thenables. |

Functions

| Function | Description | | ------ | ------ | | fulfilled | For use with Promise.allSettled to filter only successful results | | fulfilledValues | For use with Promise.allSettled to reduce to only successful result values | | rejected | For use with Promise.allSettled to filter only rejected results | | toPromise | Wraps a value in a Promise if it is not already one. | | isPromise | Type guard that checks whether a value is a Promise instance. |

classes

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

| Type Parameter | Default type | | ------ | ------ | | T | - | | V | void |

Constructors

Constructor

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

Parameters

| Parameter | Type | | ------ | ------ | | func | PromiseExFunc<T> | | value? | V |

Returns

PromiseEx<T, V>

Overrides

Promise<T>.constructor

Properties

| Property | Type | Description | | ------ | ------ | ------ | | cancelled? | boolean | Whether the promise has been cancelled via a value callback. |

Methods

then()

then<TResult1, TResult2>(
   onfulfilled?: (value: T) => TResult1 | PromiseLike<TResult1> | null, 
   onrejected?: 
  | (reason: unknown) => TResult2 | PromiseLike<TResult2>
  | null, 
onvalue?: (value?: V) => boolean): Promise<TResult1 | TResult2>;

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

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TResult1 | T | | TResult2 | never |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | onfulfilled? | (value: T) => TResult1 | PromiseLike<TResult1> | null | The callback to execute when the Promise is resolved. | | onrejected? | | (reason: unknown) => TResult2 | PromiseLike<TResult2> | null | The callback to execute when the Promise is rejected. | | onvalue? | (value?: V) => boolean | - |

Returns

Promise<TResult1 | TResult2>

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

Overrides

Promise.then

value()

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

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

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | onvalue? | (value?: V) => boolean | A callback that receives the attached value and returns whether to cancel. |

Returns

PromiseEx<T, V>

This instance for chaining.

functions

fulfilled

@xylabs/promise

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

For use with Promise.allSettled to filter only successful results

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | val | PromiseSettledResult<T> | - |

Returns

val is PromiseFulfilledResult<T>

fulfilledValues

@xylabs/promise

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

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

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | 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' ]

isPromise

@xylabs/promise

Call Signature

function isPromise(value: unknown): value is Promise<unknown>;

Type guard that checks whether a value is a Promise instance.

Parameters

| Parameter | Type | | ------ | ------ | | value | unknown |

Returns

value is Promise<unknown>

Call Signature

function isPromise<T>(value: T): value is Extract<T, Promise<unknown>>;

Type guard that checks whether a value is a Promise instance.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | | ------ | ------ | | value | T |

Returns

value is Extract<T, Promise<unknown>>

rejected

@xylabs/promise

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

For use with Promise.allSettled to filter only rejected results

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | val | PromiseSettledResult<T> | - |

Returns

val is PromiseRejectedResult

toPromise

@xylabs/promise

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

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

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | Promisable<T> | A value that may or may not be a Promise. |

Returns

Promise<T>

A Promise resolving to the value.

interfaces

PromiseType

@xylabs/promise

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

Properties

| Property | Type | | ------ | ------ | | then | () => unknown |

type-aliases

AnyNonPromise

@xylabs/promise

type AnyNonPromise = Exclude<TypedValue, PromiseType>;

Any non-promise typed value, excluding thenables.

AsyncMutex

@xylabs/promise

type AsyncMutex<T> = Promise<T>;

Type Parameters

| Type Parameter | | ------ | | T |

Description

Used to document promises that are being used as Mutexes

NullablePromisable

@xylabs/promise

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

A Promisable that may resolve to null.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T | - | | V | never |

NullablePromisableArray

@xylabs/promise

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

A Promisable array where elements may be null.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T | - | | V | never |

OptionalPromisable

@xylabs/promise

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

A Promisable that may resolve to undefined.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T | - | | V | never |

OptionalPromisableArray

@xylabs/promise

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

A Promisable array where elements may be undefined.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T | - | | V | never |

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

| Type Parameter | Default type | | ------ | ------ | | T | - | | V | never |

PromisableArray

@xylabs/promise

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

A Promisable that resolves to an array.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T | - | | V | never |

PromiseExFunc

@xylabs/promise

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

The executor function passed to the PromiseEx constructor.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | | ------ | ------ | | resolve? | PromiseExSubFunc<T, void> | | reject? | PromiseExSubFunc<T, void> |

Returns

void

PromiseExSubFunc

@xylabs/promise

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

A resolve/reject callback used within PromiseEx.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T | - | | TResult | T |

Parameters

| Parameter | Type | | ------ | ------ | | value | T |

Returns

TResult

PromiseExValueFunc

@xylabs/promise

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

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

Type Parameters

| Type Parameter | | ------ | | V |

Parameters

| Parameter | Type | | ------ | ------ | | value? | V |

Returns

boolean

Part of sdk-js

Maintainers

• Arie Trouw (arietrouw.com)
• Matt Jones
• Joel Carter
• Jordan Trouw

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs