promise-controller

Advanced control of JavaScript promises.

Installation

npm install promise-controller --save

Usage

import PromiseController from 'promise-controller';

const pc = new PromiseController();
const promise = pc.call(() => startAsyncProcess());
// ...when async process done
pc.resolve('done');
// or
pc.reject();

Use cases

• Easy access to resolve / reject callbacks
• Re-use of existing promise while operation is pending
• Automatically reject after timeout

Easy access to resolve / reject callbacks

With bare Promise:

let resolve, reject;

const asyncOperation = setTimeout(() => Math.random() > 0.5 ? resolve() : reject(), 100);

const promise = new Promise((_resolve, _reject) => {
   resolve = _resolve;
   reject = _reject;
   asyncOperation();
});

With PromiseController:

const pc = new PromiseController();

const asyncOperation = setTimeout(() => Math.random() > 0.5 ? pc.resolve() : pc.reject(), 100);

const promise = pc.call(asyncOperation);

Re-use of existing promise while operation is pending

With bare Promise:

let promise = null;

function connectToDb() {
    if (!promise) {
        promise = mongoClient.open();
    }

    return promise;
}

With PromiseController:

const pc = new PromiseController();

function connectToDb() {
    return pc.promise || pc.call(() => mongoClient.open());
}

Automatically reject after timeout

With bare Promise:

let resolve, timer;

const asyncOperation = setTimeout(() => {
    resolve();
    clearTimeout(timer);
}, 100);

const promise = new Promise((_resolve, _reject) => {
    resolve = _resolve;
    asyncOperation();
    timer = setTimeout(() => _reject(), 50);
});

With PromiseController:

const pc = new PromiseController({
  timeout: 50
});

const asyncOperation = setTimeout(() => resolve(), 100);

const promise = pc.call(asyncOperation);

API

Classes

PromiseController

Typedefs

Options : Object

PromiseController

Kind: global class

• PromiseController
  • new PromiseController([options])
  • instance
    • .promise ⇒ Promise
    • .value ⇒ *
    • .isPending ⇒ Boolean
    • .isFulfilled ⇒ Boolean
    • .isRejected ⇒ Boolean
    • .isSettled ⇒ Boolean
    • .call([fn]) ⇒ Promise
    • .resolve([value])
    • .reject([value])
    • .reset()
    • .configure(options)
  • static
    • .TimeoutError : TimeoutError
    • .ResetError : ResetError

new PromiseController([options])

Creates promise controller. Unlike original Promise, it does not immediately call any function. Instead it has .call() method that calls provided function and stores resolve / reject methods for future access.

Param	Type
[options]	Options

pc.promise ⇒ Promise

Returns promise itself.

Kind: instance property of PromiseController

pc.value ⇒ *

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

Kind: instance property of PromiseController

pc.isPending ⇒ Boolean

Returns true if promise is pending.

Kind: instance property of PromiseController

pc.isFulfilled ⇒ Boolean

Returns true if promise is fulfilled.

Kind: instance property of PromiseController

pc.isRejected ⇒ Boolean

Returns true if promise rejected.

Kind: instance property of PromiseController

pc.isSettled ⇒ Boolean

Returns true if promise is fulfilled or rejected.

Kind: instance property of PromiseController

pc.call([fn]) ⇒ Promise

Calls fn and returns promise OR just returns existing promise from previous call() if it is still pending. To fulfill returned promise you should use resolve / reject methods. If fn itself returns promise, then external promise is attached to it and fulfills together. If no fn passed - promiseController is initialized as well.

Kind: instance method of PromiseController

Param	Type	Description
[fn]	function	function to be called.

pc.resolve([value])

Resolves pending promise with specified value.

Kind: instance method of PromiseController

Param	Type
[value]	*

pc.reject([value])

Rejects pending promise with specified value.

Kind: instance method of PromiseController

Param	Type
[value]	*

pc.reset()

Resets to initial state. If promise is pending it will be rejected with ResetError.

Kind: instance method of PromiseController

pc.configure(options)

Re-assign one or more options.

Kind: instance method of PromiseController

Param	Type
options	Options

PromiseController.TimeoutError : TimeoutError

Error for rejection in case of timeout.

Kind: static property of PromiseController

PromiseController.ResetError : ResetError

Error for rejection in case of call .reset() while promise is pending.

Kind: static property of PromiseController

Options : Object

Kind: global typedef
Properties

Name	Type	Default	Description
[timeout]	Number	0	Timeout in ms after that promise will be rejected automatically.
[timeoutReason]	String | function		Rejection reason for timeout. Promise will be rejected with TimeoutError and this message. The message can contain placeholder {timeout} for actual timeout value. If timeoutReason is a function, it will be evaluated and returned value will be used as message.
[resetReason]	String | function		Rejection reason used when .reset() is called while promise is pending. Promise will be rejected with ResetError and this message. If resetReason is a function, it will be evaluated and returned value will be used as message.

Related projects

• event-to-promise
• promise-events

License

MIT @ Vitaliy Potapov