pendings

Pendings

Better control of pending Promises

Pendings is a library for advanced control of single promise (or list of promises) by providing direct access resolve / reject callbacks.

Installation

npm install pendings --save

Example

When working with Promises sometimes we need to store resolve / reject callbacks for future fulfillment:

class MyClass {
    waitSomeEvent() { 
        return new Promise((resolve, reject) => {
            this.resolve = resolve;
            this.reject = reject;
            this.request();
        });
    }
    
    onEvent(event) {
        this.resolve(event.data);
    }
    
    onError(event) {
        this.reject(event.data);
    }
}

This library allows to reduce boilerplate code by automatically storing resolve / reject callbacks:

const Pending = require('pendings').Pending;

class MyClass {
    constructor() {
        this.pending = new Pending();
    }    

    waitSomeEvent() { 
        return this.pending.call(() => this.request());
    }
    
    onEvent(event) {
        this.pending.resolve(event.data);
    }
    
    onError(event) {
        this.pending.reject(event.data);
    }
}

Moreover, it is useful when working with list of pending promises. The unique id is generated for each promise and allows to fulfill it later:

const Pendings = require('pendings');

class MyClass {
    constructor() {
        this.pendings = new Pendings();
    }    

    sendDataAndWaitResponse(data) { 
        return this.pendings.add(id => {
            data.id = id;
            this.send(data);
        });
    }
    
    onEvent(event) {
        const data = event.data;
        this.pendings.resolve(data.id, data);
    }
    
    onError(event) {
        const data = event.data;        
        this.pendings.reject(data.id, data);
    }
}

API

Classes

Pendings

Pending

Pendings

Kind: global class

• Pendings
  • new Pendings([options])
  • .add(fn, [options]) ⇒ Promise
  • .set(id, fn, [options]) ⇒ Promise
  • .has(id) ⇒ Boolean
  • .resolve(id, [value])
  • .reject(id, [reason])
  • .rejectAll([reason])
  • .fulfill(id, [value], [reason])
  • .getPromise(id) ⇒ Promise | undefined
  • .generateId() ⇒ String

new Pendings([options])

Constructor.

Param	Type	Description
[options]	Object
[options.timeout]	Number	default timeout for all promises

pendings.add(fn, [options]) ⇒ Promise

Calls fn and returns new promise. fn gets generated unique id as parameter.

Kind: instance method of Pendings

Param	Type	Description
fn	function
[options]	Object
[options.timeout]	Number	custom timeout for particular promise

pendings.set(id, fn, [options]) ⇒ Promise

Calls fn and returns new promise with specified id.

Kind: instance method of Pendings

Param	Type	Description
id	String | Number
fn	function
[options]	Object
[options.timeout]	Number	custom timeout for particular promise

pendings.has(id) ⇒ Boolean

Checks if pending promise with specified id exists.

Kind: instance method of Pendings

Param	Type
id	String | Number

pendings.resolve(id, [value])

Resolves pending promise by id with specified value.

Kind: instance method of Pendings

Param	Type
id	String | Number
[value]	*

pendings.reject(id, [reason])

Rejects pending promise by id with specified reason.

Kind: instance method of Pendings

Param	Type
id	String | Number
[reason]	*

pendings.rejectAll([reason])

Rejects all pending promises with specified reason. Useful for cleanup.

Kind: instance method of Pendings

Param	Type
[reason]	*

pendings.fulfill(id, [value], [reason])

Rejects if reason is truthy, otherwise resolves with value.

Kind: instance method of Pendings

Param	Type
id	String | Number
[value]	*
[reason]	*

pendings.getPromise(id) ⇒ Promise | undefined

Returns promise of pending object with specified id.

Kind: instance method of Pendings

Param	Type
id	String | Number

pendings.generateId() ⇒ String

Generates unique ID. Can be overwritten.

Kind: instance method of Pendings

Pending

Kind: global class

• Pending
  • new Pending()
  • .promise ⇒ Promise
  • .isFulfilled ⇒ Boolean
  • .call(fn, [timeout]) ⇒ Promise
  • .resolve([value])
  • .reject([reason])
  • .fulfill([value], [reason])

new Pending()

Constructor.

pending.promise ⇒ Promise

Returns promise itself.

Kind: instance property of Pending

pending.isFulfilled ⇒ Boolean

Returns is promise fulfilled or not.

Kind: instance property of Pending

pending.call(fn, [timeout]) ⇒ Promise

Calls fn, returns new promise and holds resolve / reject callbacks.

Kind: instance method of Pending

Param	Type	Default
fn	function
[timeout]	Number	0

pending.resolve([value])

Resolves pending promise with specified value.

Kind: instance method of Pending

Param	Type
[value]	*

pending.reject([reason])

Rejects pending promise with specified reason.

Kind: instance method of Pending

Param	Type
[reason]	*

pending.fulfill([value], [reason])

Rejects if reason is truthy, otherwise resolves with value.

Kind: instance method of Pending

Param	Type
[value]	*
[reason]	*

License

MIT @ Vitaliy Potapov