# @xylabs/promise

[![npm][npm-badge]][npm-link]
[![license][license-badge]][license-link]

> Base functionality used throughout XY Labs TypeScript/JavaScript libraries

## Install

Using npm:

```sh
npm install {{name}}
```

Using yarn:

```sh
yarn add {{name}}
```

Using pnpm:

```sh
pnpm add {{name}}
```

Using bun:

```sh
bun add {{name}}
```


## License

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

## Reference

### packages

  ### promise

    ### .temp-typedoc

      ### classes

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

[**@xylabs/promise**](#../README)

***

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

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

### Parameters

#### func

[`PromiseExFunc`](#../type-aliases/PromiseExFunc)\<`T`\>

#### value?

`V`

### Returns

`PromiseEx`\<`T`, `V`\>

### Overrides

```ts
Promise<T>.constructor
```

## Properties

### cancelled?

```ts
optional cancelled?: boolean;
```

Whether the promise has been cancelled via a value callback.

## Methods

### then()

```ts
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

```ts
Promise.then
```

***

### value()

```ts
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**](#../README)

***

```ts
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**](#../README)

***

```ts
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

```ts
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' ]
```

```ts
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**](#../README)

***

```ts
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**](#../README)

***

```ts
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`](#../type-aliases/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**](#../README)

***

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

## Properties

### then

```ts
then: () => unknown;
```

### Returns

`unknown`

      ### type-aliases

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

[**@xylabs/promise**](#../README)

***

```ts
type AnyNonPromise = Exclude<TypedValue, PromiseType>;
```

Any non-promise typed value, excluding thenables.

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

[**@xylabs/promise**](#../README)

***

```ts
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**](#../README)

***

```ts
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**](#../README)

***

```ts
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**](#../README)

***

```ts
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**](#../README)

***

```ts
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**](#../README)

***

```ts
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**](#../README)

***

```ts
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**](#../README)

***

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

The executor function passed to the PromiseEx constructor.

## Type Parameters

### T

`T`

## Parameters

### resolve?

[`PromiseExSubFunc`](#PromiseExSubFunc)\<`T`, `void`\>

### reject?

[`PromiseExSubFunc`](#PromiseExSubFunc)\<`T`, `void`\>

## Returns

`void`

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

[**@xylabs/promise**](#../README)

***

```ts
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**](#../README)

***

```ts
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`


[npm-badge]: https://img.shields.io/npm/v/@xylabs/promise.svg
[npm-link]: https://www.npmjs.com/package/@xylabs/promise
[license-badge]: https://img.shields.io/npm/l/@xylabs/promise.svg
[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE