Deprecated. Use
@ariestools/sdkinstead. This package is a backward-compatibility re-export shim.
@xylabs/promise
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Install
Using npm:
npm install @xylabs/promiseUsing yarn:
yarn add @xylabs/promiseUsing pnpm:
pnpm add @xylabs/promiseUsing bun:
bun add @xylabs/promiseLicense
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
Reference
packages
promise
### .temp-typedoc
### classes
### <a id="PromiseEx"></a>PromiseExAn 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
value?
V
Returns
PromiseEx<T, V>
Overrides
Promise<T>.constructorProperties
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.thenvalue()
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>fulfilledfunction 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>fulfilledValuesfunction 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>rejectedfunction 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>toPromisefunction 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>PromiseTypeAn interface representing any thenable (promise-like) object.
Properties
then
then: () => unknown;Returns
unknown
### type-aliases
### <a id="AnyNonPromise"></a>AnyNonPromisetype AnyNonPromise = Exclude<TypedValue, PromiseType>;Any non-promise typed value, excluding thenables.
### <a id="AsyncMutex"></a>AsyncMutextype AsyncMutex<T> = Promise<T>;Type Parameters
T
T
Description
Used to document promises that are being used as Mutexes
### <a id="NullablePromisable"></a>NullablePromisabletype 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>NullablePromisableArraytype 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>OptionalPromisabletype 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>OptionalPromisableArraytype 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>Promisabletype 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>PromisableArraytype PromisableArray<T, V> = Promisable<T[], V>;A Promisable that resolves to an array.
Type Parameters
T
T
V
V = never
### <a id="PromiseExFunc"></a>PromiseExFunctype 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>PromiseExSubFunctype 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>PromiseExValueFunctype 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