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

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' | automatically reset pending to initial state. Possible values are: never, fufilled, resolved, rejected. |

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