npm package: @ketch-com/future
Description: TypeScript Future object
Author: Ketch
Latest version: 1.2.14

# future

`Future` acts like a Promised value that can be fulfilled at some future and can have multiple subscribers
that can be notified when the value is fulfilled.

## Creating a future

```typescript
const f = new Future({name, timeout, emitter, maxListeners, executor})
```

Constructs a new `Future` with the given options.

* `name` - specifies a name of the `Future`. If `emitter` is also specified, this `name` will be used for the event
* `timeout` - specifies a duration within which the `Future` must be fulfilled, or an error will automatically be fulfilled
* `emitter` - an external `EventEmitter` to which additional fulfilled events are sent. The events are named after `name`.
* `maxListeners` - specifies the maximum number of listeners
* `executor` - a function taking `resolve` and `reject` functions that can be called to fulfill or reject the the value

## Getting the promised value

```typescript
const v: T = f.value
```

If the `Future` has been fulfilled, then the value is returned. If the `Future` has not been
fulfilled then an error is raised. If an error occurred during fulfilling the `Future`, then
the error raised then is returned.

## Setting the promised value

```typescript
f.value = v
f.fulfill(v)
const f = Future.resolve(v)
```

Clears any cached error. Sets the fulfilled value to the given value. Clears any timeout. If
the value is different to an existing fulfilled value then all listeners are notified (using
the `fulfilled` event) and emits the named future event to any emitter given in the options.

## Resetting the promised value

```typescript
f.reset()
```

Clears the fulfilled value. Clears any cached error. Emits the `reset` event and emits the named
future event to any emitter given in the options.

## Determining if the promised value has been fulfilled

```typescript
const fulfilled: boolean = f.isFulfilled()
```

Returns true if the `Future` has been fulfilled.

## Get a Promise of the future value

```typescript
const p: Promise<T> = f.fulfilled
```

Returns a `Promise` that will be resolved when the `Future` is fulfilled. The `Promise` will be
rejected if an error is raised.

## Set fulfillment error

```typescript
const e = new Error('')
f.error = e
f.error = undefined
```

Set the error to the given error. If an `Error` is provided, then the `error` event is emitted.
Clears any timeout.

## Get fulfillment error

```typescript
const e: Error | undefined = f.error
```

Returns any error raised during fulfillment, or `undefined` if no error occurred.

## Add a listener

```typescript
const eventName: string | symbol = ''
const listener: (...args: any[]) => void = () => {}
f.addListener(eventName, listener)
f.on(eventName, listener)
```

Adds the listener function to the end of the listeners array for the event named `eventName`.
No checks are made to see if the listener has already been added. Multiple calls passing the
same combination of `eventName` and listener will result in the listener being added, and
called, multiple times.

Valid `eventName` include:
* `fulfilled` - the future value has been fulfilled. The payload is the fulfilled value.
* `reset` - the value has been reset. The payload is undefined.
* `error` - the future value has failed to be fulfilled. The payload is the `Error`.

If the `eventName` is `fulfilled` and the value has already been fulfilled, then the
listener is called immediately. If the `eventName` is `error` and an error has already
occurred fulfilling the value, then the listener is called immediately.

## Add a listener that fires only once

```typescript
const eventName: string | symbol = ''
const listener: (...args: any[]) => void = () => {}
f.once(eventName, listener)
```

Adds a one-time listener function for the event named eventName. The next time eventName
is triggered, this listener is removed and then invoked.

Valid `eventName` include:
* `fulfilled` - the future value has been fulfilled. The payload is the fulfilled value.
* `reset` - the value has been reset. The payload is undefined.
* `error` - the future value has failed to be fulfilled. The payload is the `Error`.

If the `eventName` is `fulfilled` and the value has already been fulfilled, then the
listener is called immediately. If the `eventName` is `error` and an error has already
occurred fulfilling the value, then the listener is called immediately.

## Remove a listener

```typescript
const eventName: string | symbol = ''
const listener: (...args: any[]) => void = () => {}
f.removeListener(eventName, listener)
f.off(eventName, listener)
```

Removes the specified `listener` from the listener array for the event named `eventName`.

## Remove all listeners

```typescript
const eventName: string | symbol = ''
f.removeAllListeners(eventName)
```

Removes all listeners, or those of the specified `eventName`.

## Execute a function when the future is fulfilled

```typescript
const v = Future.resolve(5).then(x => x + 1) // v === 6
```

Future is a `PromiseLike` class that provides a `then` function that calls a function when
the future is available and returns the transformed Promise.

## Execute a function when the future errors

```typescript
const v = Future.resolve(5).catch(e => console.log(e))
```

Future is a `PromiseLike` class that provides a `catch` function that is called if the Future
errors.