controlled-promise

Better control of JavaScript Promises

A Promise wrapping library for advanced control of promise lifecycle. Allows to split business logic from promise manipulation:

• promisify event-emitters: easy access to resolve / reject callbacks
• return existing promise while it is pending
• auto-reject after configured timeout
• tiny size and zero dependencies

Installation

npm install controlled-promise --save

Usage

const ControlledPromise = require('controlled-promise');

// Create controlled promise
const cp = new ControlledPromise();

// Call asynchronous function. Returns promise wich `resolve / reject` callbacks are stored in `cp`.
const promise = cp.call(() => someAsyncFn());

// Resolve promise later via cp.resolve()
cp.resolve();

// OR reject promise later via cp.reject()
cp.reject(error);

API

ControlledPromise

Controlled Promise.

Kind: global class

• ControlledPromise
  • new ControlledPromise()
  • .promise ⇒ Promise
  • .value ⇒ *
  • .isPending ⇒ Boolean
  • .isFulfilled ⇒ Boolean
  • .isRejected ⇒ Boolean
  • .isSettled ⇒ Boolean
  • .isCalled ⇒ Boolean
  • .call(fn) ⇒ Promise
  • .resolve([value])
  • .reject([value])
  • .reset()
  • .timeout(ms, [reason])

new ControlledPromise()

Creates controlled promise. In contrast to original Promise, it does not immediately call any function. Instead it has .call() method for that and resolve / reject methods for resolving promise.

controlledPromise.promise ⇒ Promise

Returns promise itself.

Kind: instance property of ControlledPromise

controlledPromise.value ⇒ *

Returns value with that promise was fulfilled (resolved or rejected).

Kind: instance property of ControlledPromise

controlledPromise.isPending ⇒ Boolean

Returns true if promise is pending.

Kind: instance property of ControlledPromise

controlledPromise.isFulfilled ⇒ Boolean

Returns true if promise is fulfilled.

Kind: instance property of ControlledPromise

controlledPromise.isRejected ⇒ Boolean

Returns true if promise rejected.

Kind: instance property of ControlledPromise

controlledPromise.isSettled ⇒ Boolean

Returns true if promise fulfilled or rejected.

Kind: instance property of ControlledPromise

controlledPromise.isCalled ⇒ Boolean

Returns true if promise already called via .call() method.

Kind: instance property of ControlledPromise

controlledPromise.call(fn) ⇒ Promise

This method executes fn and returns promise. While promise is pending all subsequent calls of .call(fn) will return the same promise. To fulfill that promise you can use .resolve() / .reject() methods.

Kind: instance method of ControlledPromise

| Param | Type | | --- | --- | | fn | function |

controlledPromise.resolve([value])

Resolves pending promise with specified value.

Kind: instance method of ControlledPromise

| Param | Type | | --- | --- | | [value] | * |

controlledPromise.reject([value])

Rejects pending promise with specified value.

Kind: instance method of ControlledPromise

| Param | Type | | --- | --- | | [value] | * |

controlledPromise.reset()

Resets to initial state.

Kind: instance method of ControlledPromise

controlledPromise.timeout(ms, [reason])

Sets timeout to reject promise automatically.

Kind: instance method of ControlledPromise

| Param | Type | Description | | --- | --- | --- | | ms | Number | delay in ms after that promise will be rejected automatically | | [reason] | String | Error | function | rejection value. If it is string or error - promise will be rejected with that error. If it is function - this function will be called after delay where you can manually resolve or reject promise via .resolve() / .reject() methods. |

Related

• event-to-promise
• promise-events

License

MIT @ Vitaliy Potapov