Backpack

Appearance

API reference / @backpack/error-handling / async-result / AsyncResult

Class: AsyncResult<T> ​

Extension of a Promise<T>, providing some nice additional operators for improved error handling.

Extends ​

  • Promise<T>

Type Parameters ​

Type ParameterDescription
TRepresents the type of the resulting value, if successful.

Constructors ​

Constructor ​

ts
new AsyncResult<T>(executor): AsyncResult<T>;

Creates a new AsyncResult.

Parameters ​

ParameterType
executor(resolve, reject) => void

Returns ​

AsyncResult<T>

Overrides ​

ts
Promise<T>.constructor

Methods ​

asResult() ​

ts
asResult(): Promise<Result<T, unknown>>;

Converts the AsyncResult<T> into a Promise<Result<T, unknown>>.

Can be used in combination with async/await to handle the Result in a more imperative style.

Returns ​

Promise<Result<T, unknown>>

asResultCatchingOnly() ​

ts
asResultCatchingOnly<T1, T2>(e, ...exceptions): Promise<Result<T, T1 | T2 extends Class<E>[] ? E : unknown>>;

Converts the AsyncResult<T> into a Promise<Result<T, unknown>>, catching only errors that are an instance of the error classes provided.

Can be used in combination with async/await to handle the Result in a more imperative style.

Type Parameters ​

Type Parameter
T1
T2 extends Class[]

Parameters ​

ParameterType
eClass<T1>
...exceptionsT2

Returns ​

Promise<Result<T, T1 | T2 extends Class<E>[] ? E : unknown>>

map() ​

ts
map<TResult>(mapFn): AsyncResult<TResult>;

If successful, maps the value, catching any errors in the process.

Type Parameters ​

Type ParameterDefault type
TResultT

Parameters ​

ParameterType
mapFn(value) => TResult | PromiseLike<TResult>

Returns ​

AsyncResult<TResult>

match() ​

ts
match<TResult1, TResult2>(onSuccess, onError): AsyncResult<TResult1 | TResult2>;

Maps the value if successful, or else the error if failed.

For example, .match(x => 1, e => 2) would be similar to .map(x => 1).recover(e => 2)

Type Parameters ​

Type Parameter
TResult1
TResult2

Parameters ​

ParameterType
onSuccess(value) => TResult1 | PromiseLike<TResult1>
onError(error) => TResult2 | PromiseLike<TResult2>

Returns ​

AsyncResult<TResult1 | TResult2>

onFailure() ​

ts
onFailure(errorConsumer): AsyncResult<T>;

Executes the given callback if failed, letting the original error pass through.

Can be used to introduce a side effect (such as logging the error).

Parameters ​

ParameterType
errorConsumer(error) => void

Returns ​

AsyncResult<T>

onFailureIfInstanceOf() ​

ts
onFailureIfInstanceOf<TNarrowedError>(errorClass, errorConsumer): AsyncResult<T>;

Executes the given callback if failed, if the error is an instance of the class provided, letting the original error pass through.

Can be used to introduce a side effect, such as logging.

Type Parameters ​

Type Parameter
TNarrowedError

Parameters ​

ParameterType
errorClassClass<TNarrowedError>
errorConsumer(error) => void

Returns ​

AsyncResult<T>

onSuccess() ​

ts
onSuccess(consumer): AsyncResult<T>;

Executes the given callback if successful, letting the original value pass through.

Can be used to introduce a side effect.

Parameters ​

ParameterType
consumer(value) => void

Returns ​

AsyncResult<T>

orElse() ​

ts
orElse<TResult>(defaultValue): AsyncResult<T | TResult>;

If failed, maps the error to the given value, to recover into a successful AsyncResult.

Alias for .recover(() => value) to improve semantics.

Type Parameters ​

Type Parameter
TResult

Parameters ​

ParameterType
defaultValueTResult | PromiseLike<TResult>

Returns ​

AsyncResult<T | TResult>

orElseGet() ​

ts
orElseGet<TResult>(defaultValueProvider): AsyncResult<T | TResult>;

If failed, maps the error to the value returned by the given provider, to recover into a successful AsyncResult.

Alias for .recover(() => value) to improve semantics.

Type Parameters ​

Type Parameter
TResult

Parameters ​

ParameterType
defaultValueProvider(error) => TResult | PromiseLike<TResult>

Returns ​

AsyncResult<T | TResult>

recover() ​

ts
recover<TResult>(recoverFn): AsyncResult<T | TResult>;

If failed, maps the error to another value, to recover into a successful AsyncResult.

Type Parameters ​

Type Parameter
TResult

Parameters ​

ParameterType
recoverFn(error) => TResult | PromiseLike<TResult>

Returns ​

AsyncResult<T | TResult>

recoverIf() ​

Call Signature ​

ts
recoverIf<TResult, TNarrowedError>(predicate, recoverFn): AsyncResult<TResult>;

If failed, maps the error to another value if it matches the given type guard, to recover into a successful AsyncResult.

Type Parameters ​
Type Parameter
TResult
TNarrowedError
Parameters ​
ParameterType
predicate(error) => error is TNarrowedError
recoverFn(error) => TResult | PromiseLike<TResult>
Returns ​

AsyncResult<TResult>

Call Signature ​

ts
recoverIf<TResult>(predicate, recoverFn): AsyncResult<TResult>;

If failed, maps the error to another value if it matches the given predicate, to recover into a successful AsyncResult.

Type Parameters ​
Type Parameter
TResult
Parameters ​
ParameterType
predicate(error) => boolean
recoverFn(error) => TResult | PromiseLike<TResult>
Returns ​

AsyncResult<TResult>

recoverIfInstanceOf() ​

ts
recoverIfInstanceOf<TResult, TNarrowedError>(errorClass, recoverFn): AsyncResult<T | TResult>;

If failed, maps the error to a value if it is an instance of the provided error class, to recover into a successful AsyncResult.

Type Parameters ​

Type Parameter
TResult
TNarrowedError

Parameters ​

ParameterType
errorClassClass<TNarrowedError>
recoverFn(error) => TResult | PromiseLike<TResult>

Returns ​

AsyncResult<T | TResult>

failure() ​

ts
static failure<T>(error): AsyncResult<Awaited<T>>;

Creates an AsyncResult representing a failure.

Alias for AsyncResult.reject(error), to improve semantics.

Type Parameters ​

Type ParameterDefault type
Tnever

Parameters ​

ParameterType
errorunknown

Returns ​

AsyncResult<Awaited<T>>

fromPromise() ​

ts
static fromPromise<T>(value): AsyncResult<T>;

Creates an AsyncResult<T> out of an existing Promise<T>.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
valuePromiseLike<T>

Returns ​

AsyncResult<T>

reject() ​

ts
static reject<T>(error): AsyncResult<Awaited<T>>;

Type Parameters ​

Type ParameterDefault type
Tnever

Parameters ​

ParameterType
errorunknown

Returns ​

AsyncResult<Awaited<T>>

Inherit Doc ​

Overrides ​

ts
Promise.reject

resolve() ​

Call Signature ​

ts
static resolve(): AsyncResult<void>;
Returns ​

AsyncResult<void>

Inherit Doc ​
Overrides ​
ts
Promise.resolve

Call Signature ​

ts
static resolve<T>(value): AsyncResult<Awaited<T>>;

Creates a new resolved promise for the provided value.

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterTypeDescription
valueTA promise.
Returns ​

AsyncResult<Awaited<T>>

A promise whose internal state matches the provided promise.

Overrides ​
ts
Promise.resolve

Call Signature ​

ts
static resolve<T>(value): AsyncResult<Awaited<T>>;

Creates a new resolved promise for the provided value.

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterTypeDescription
valueT | PromiseLike<T>A promise.
Returns ​

AsyncResult<Awaited<T>>

A promise whose internal state matches the provided promise.

Overrides ​
ts
Promise.resolve

success() ​

Call Signature ​

ts
static success(): AsyncResult<void>;

Creates an AsyncResult representing a successful value.

Alias for AsyncResult.resolve(value), to improve semantics.

Returns ​

AsyncResult<void>

Call Signature ​

ts
static success<T>(value): AsyncResult<Awaited<T>>;

Creates an AsyncResult representing a successful value.

Alias for AsyncResult.resolve(value), to improve semantics.

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
valueT
Returns ​

AsyncResult<Awaited<T>>

Call Signature ​

ts
static success<T>(value): AsyncResult<Awaited<T>>;

Creates an AsyncResult representing a successful value.

Alias for AsyncResult.resolve(value), to improve semantics.

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
valueT | PromiseLike<T>
Returns ​

AsyncResult<Awaited<T>>

try() ​

ts
static try<T>(block): AsyncResult<T>;

Executes a callback, wrapping its result in a AsyncResult<T>.

Similar to Promise.try() (currently stage 3).

Type Parameters ​

Type ParameterDescription
TRepresents the type of the resulting value, if successful.

Parameters ​

ParameterTypeDescription
block() => T | PromiseLike<T>The callback to execute. Any synchronous or asynchronous error will result in a rejected AsyncResult.

Returns ​

AsyncResult<T>

See ​

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/try