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 (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 can automatically get unique id and can be fulfilled later by that id. After fulfillment promise is removed from list.

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

API

Classes

Pending

Pendings

TimeoutError

Pending

Kind: global class

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

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.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, [timeout]) ⇒ 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 timeout is specified, the promise will be automatically rejected after timeout milliseconds 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([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])
  • .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])
  • .waitAll() ⇒ Promise
  • .generateId() ⇒ String

new Pendings([options])

Creates dynamic list of promises. When each promise if fulfilled it is remove from list.

Param	Type	Default	Description
[options]	Object
[options.idPrefix]	String	''	prefix for generated IDs
[options.timeout]	Number	0	default timeout for all promises
[options.persistent]	Number	false	should list keep promises after fulfillment

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.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 {resolved: <Array>, rejected: <Array>}

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