pendings

Pendings

Better control of pending Promises

Pendings is a library for control of pending promises. It manages resolve / reject callbacks and provides convenient access to them for promise fulfillment.

Installation

npm install pendings --save

Example

When working with events in promise-based code we need to manually 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);
    }
}

Pendings allows to reduce boilerplate code:

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);
    }
}

This is even more useful for list of pending promises. Each promise automatically gets unique id that allows to fulfill it later:

const Pendings = require('pendings');

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

    sendDataAndWaitResponse(data) { 
        return this.pendings.add(id => { // `id` is generated by Pendings
            data.id = id;
            this.send(data);
        });
    }
    
    onEvent(event) {
        const data = event.data;
        this.pendings.resolve(data.id, data); // response event should contain `id` property
    }
    
    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])
  • .fulfill(id, [value], [reason])
  • .tryResolve(id, [value])
  • .tryReject(id, [reason])
  • .tryFulfill(id, [value], [reason])
  • .rejectAll([reason])
  • .getPromise(id) ⇒ Promise | undefined
  • .generateId() ⇒ String

new Pendings([options])

Constructor.

Param	Type	Default	Description
[options]	Object
[options.idPrefix]	String	''	prefix for generated IDs
[options.timeout]	Number	0	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
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

pendings.resolve(id, [value])

Resolves pending promise by id with specified value. Throws if promise does not exist.

Kind: instance method of Pendings

Param	Type
id	String
[value]	*

pendings.reject(id, [reason])

Rejects pending promise by id with specified reason. Throws if promise does not exist.

Kind: instance method of Pendings

Param	Type
id	String
[reason]	*

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

Rejects pending promise by id if reason is truthy, otherwise resolves with value. Throws if promise does not exist.

Kind: instance method of Pendings

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

pendings.tryResolve(id, [value])

Resolves pending promise by id with specified value if it exists.

Kind: instance method of Pendings

Param	Type
id	String
[value]	*

pendings.tryReject(id, [reason])

Rejects pending promise by id with specified reason if it exists.

Kind: instance method of Pendings

Param	Type
id	String
[reason]	*

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

Rejects pending promise by id if reason is truthy, otherwise resolves with value.

Kind: instance method of Pendings

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

pendings.rejectAll([reason])

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

Kind: instance method of Pendings

Param	Type
[reason]	*

pendings.getPromise(id) ⇒ Promise | undefined

Returns promise of pending object with specified id.

Kind: instance method of Pendings

Param	Type
id	String

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