Skip to content

vitalets/promise-controller

Repository files navigation

promise-controller

Build Status npm license

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

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

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

License

MIT @ Vitaliy Potapov

Sponsor this project

 

Packages

No packages published