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

Typedefs

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