Pendings

Better control of Promises

Pendings is a wrapping library over Promises providing flexible control of promise lifecycle. It is useful for event-based code where you need to manually store resolve / reject callbacks for later fulfillment. It reduces boilerplate code and allows to split business logic from promise manipulation.

Installation

npm install pendings --save

Features

• automatically store resolve / reject callbacks for later fulfillment
• automatically return existing promise for all calls until promise is fulfilled
• automatic reject promise after configured timeout
• flexible manipulation with list of promises: dynamic insert and waitAll() method

Usage (single promise)

Typical situation with promises in event-based code:

class Foo {
    constructor() {
      this.promise = null;
      this.resolve = null;
      this.reject = null;
    }
    asyncRequest() {
        if (this.promise) { // if promise already exists - return it
            return this.promise;
        }
        this.promise = new Promise((resolve, reject) => {
            this.resolve = resolve;
            this.reject = reject;
            this.send();
        });
        return this.promise;
    }
    onSuccess(data) {
        this.resolve(data);
    }
}    

Pending class allows to do it simpler:

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

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

Usage (list of promises)

Pendings class is useful for dynamic list of promises. Each promise gets unique id (manually or auto-generated) and can be resolved later by that id.

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 generated `id`
        });
    }
    
    onSuccess(data) {
        this.pendings.resolve(data.id, data); // resolve by `id`
    }
    
    onError(data) {
        this.pendings.reject(data.id, data); // reject by `id`
    }
}

API

Classes

Pending

Pendings

TimeoutError

Pending

Kind: global class

• Pending
  • new Pending([options])
  • .promise ⇒ Promise
  • .value ⇒ *
  • .isResolved ⇒ Boolean
  • .isRejected ⇒ Boolean
  • .isFulfilled ⇒ Boolean
  • .isPending ⇒ Boolean
  • .onFulfilled
  • .call(fn, [options]) ⇒ Promise
  • .resolve([value])
  • .reject([value])
  • .fulfill([resolveValue], [rejectValue])
  • .reset([error])

new Pending([options])

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

Param	Type	Default	Description
[options]	Object
[options.timeout]	Number	0
[options.autoReset]	String	'never'	Condition for auto-reset. It is important for the result of .call() method: never: never reset, so .call() always returns existing promise while it is pending and when fulfilled fufilled: reset when fulfilled, so .call() returns existing promise while it is pending and creates new promise when fulfilled rejected: reset only rejected, so .call() returns existing promise while it is pending or when resolved and creates new promise when rejected resolved: reset only resolved, so .call() returns existing promise while it is pending or when rejected and creates new promise when resolved

pending.promise ⇒ Promise

Returns promise itself.

Kind: instance property of Pending

pending.value ⇒ *

Returns value with that promise was fulfilled (resolved or rejected).

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.isPending ⇒ Boolean

Returns true if promise is pending.

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, [options]) ⇒ Promise

For the first time this method calls fn and returns new promise. Also holds resolve / reject callbacks to allow fulfill promise via pending.resolve() and pending.reject(). All subsequent calls of .call(fn) will return the same promise, which can be still pending or already fulfilled. To reset this behavior use .reset(). If options.timeout is specified, the promise will be automatically rejected after timeout milliseconds with TimeoutError.

Kind: instance method of Pending

Param	Type	Default	Description
fn	function
[options]	Object
[options.timeout]	Number	0	timeout after which promise will be automatically rejected

pending.resolve([value])

Resolves pending promise with specified value.

Kind: instance method of Pending

Param	Type
[value]	*

pending.reject([value])

Rejects pending promise with specified value.

Kind: instance method of Pending

Param	Type
[value]	*

pending.fulfill([resolveValue], [rejectValue])

Helper method: rejects if rejectValue is truthy, otherwise resolves with resolveValue.

Kind: instance method of Pending

Param	Type
[resolveValue]	*
[rejectValue]	*

pending.reset([error])

Resets to initial state.

Kind: instance method of Pending

Param	Type	Description
[error]	Error	custom rejection error if promise is in pending state.

Pendings

Kind: global class

• Pendings
  • new Pendings([options])
  • .count ⇒ Number
  • .add(fn, [options]) ⇒ Promise
  • .set(id, fn, [options]) ⇒ Promise
  • .has(id) ⇒ Boolean
  • .resolve(id, [value])
  • .reject(id, [value])
  • .fulfill(id, [resolveValue], [rejectValue])
  • .tryResolve(id, [value])
  • .tryReject(id, [value])
  • .tryFulfill(id, [resolveValue], [rejectValue])
  • .rejectAll([value])
  • .waitAll() ⇒ Promise
  • .clear()
  • .generateId() ⇒ String

new Pendings([options])

Manipulation of list of promises.

Param	Type	Default	Description
[options]	Object
[options.autoRemove]	Number	false	automatically remove fulfilled promises from list
[options.timeout]	Number	0	default timeout for all promises
[options.idPrefix]	String	''	prefix for generated promise IDs

pendings.count ⇒ Number

Returns count of pending / fulfilled promises in the list.

Kind: instance property of Pendings

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	Default	Description
id	String
fn	function
[options]	Object
[options.timeout]	Number	0	custom timeout for particular promise

pendings.has(id) ⇒ Boolean

Checks if promise with specified id is exists in the list.

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, [value])

Rejects 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.fulfill(id, [resolveValue], [rejectValue])

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
[resolveValue]	*
[rejectValue]	*

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, [value])

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

Kind: instance method of Pendings

Param	Type
id	String
[value]	*

pendings.tryFulfill(id, [resolveValue], [rejectValue])

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

Kind: instance method of Pendings

Param	Type
id	String
[resolveValue]	*
[rejectValue]	*

pendings.rejectAll([value])

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

Kind: instance method of Pendings

Param	Type
[value]	*

pendings.waitAll() ⇒ Promise

Waits for all promises to fulfill and returns object with resolved/rejected values.

Kind: instance method of Pendings
Returns: Promise - promise resolved with object {resolved: {id: value, ...}, rejected: {id: value, ...}}

pendings.clear()

Removes all items from list. If there is waitAll promise - it will be resolved with empty results.

Kind: instance method of Pendings

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