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

Usage

When using promises in event-based code we need to manually store resolve / reject callbacks:

class Foo {
    asyncRequest() { 
        return new Promise((resolve, reject) => {
            this.resolve = resolve;
            this.reject = reject;
            this.send();
        });
    }
}    

and resolve later:

    onSuccess(data) {
        this.resolve(data);
    }

Pendings allows to do it simpler:

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

class Foo {
    constructor() {
        this.pending = new Pending();
    }
    asyncRequest() { 
        return this.pending.call(() => this.send());
    }
}

and resolve later:

    onSuccess(data) {
        this.pending.resolve(data);
    }

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

const Pendings = require('pendings');

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

    asyncRequest() { 
        return this.pendings.add(id => {
            this.send({id, foo: 'bar'}); // mark request with unique `id` generated by Pendings
        });
    }
    
    onSuccess(data) {
        this.pendings.resolve(data.id, data); // resolve by `id` property of event
    }
    
    onError(data) {
        this.pendings.reject(data.id, data); // reject by `id` property of event
    }
}

API

Classes

Pending

Pendings

TimeoutError

Pending

Kind: global class

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

new Pending()

Creates instance of single pending promise. It holds resolve / reject callbacks for future fulfillment.

pending.promise ⇒ Promise

Returns promise itself.

Kind: instance property of Pending

pending.isResolved ⇒ Boolean

Returns true if promise resolved.

Kind: instance property of Pending

pending.isRejected ⇒ Boolean

Returns true if promise rejected.

Kind: instance property of Pending

pending.isFulfilled ⇒ Boolean

Returns true if promise fulfilled (resolved or rejected).

Kind: instance property of Pending

pending.onFulfilled

Callback called when promise is fulfilled (resolved or rejected).

Kind: instance property of Pending

Param	Type
fn	function

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

Calls fn, returns new promise and holds resolve / reject callbacks. If timeout specified, the promise will be rejected after timeout with PendingTimeoutError.

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]	*

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])
  • .generateId() ⇒ String

new Pendings([options])

Creates list of pending promises.

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. If promise with such id already pending - it will be returned.

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 promise with specified id is pending.

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 or is already fulfilled.

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 or is already fulfilled.

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 or is already fulfilled.

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.generateId() ⇒ String

Generates unique ID. Can be overwritten.

Kind: instance method of Pendings

TimeoutError

Kind: global class

new TimeoutError(timeout)

Timeout error for pending promise.

Param	Type
timeout	Number

License

MIT @ Vitaliy Potapov