@ketch-com/future v1.2.7

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

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

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

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

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

const fulfilled: boolean = f.isFulfilled()

Returns true if the Future has been fulfilled.

Get a Promise of the future value

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

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

const e: Error | undefined = f.error

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

Add a listener

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

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

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

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

Removes all listeners, or those of the specified eventName.

Execute a function when the future is fulfilled

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

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.