Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/vitalets/pendings

[DEPRECATED] Better control of promises
https://github.com/vitalets/pendings
promise promise-api promise-library promise-support promises
Last synced: 16 days ago
JSON representation
[DEPRECATED] Better control of promises
Host: GitHub
URL: https://github.com/vitalets/pendings
Owner: vitalets
Created: 2017-06-23T09:31:55.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2017-08-28T10:03:36.000Z (about 7 years ago)
Last Synced: 2024-10-15T00:46:02.501Z (about 1 month ago)
Topics: promise, promise-api, promise-library, promise-support, promises
Language: JavaScript
Homepage:
Size: 109 KB
Stars: 2
Watchers: 3
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

        # Pendings

[![Build Status](https://travis-ci.org/vitalets/pendings.svg?branch=master)](https://travis-ci.org/vitalets/pendings)

[![npm](https://img.shields.io/npm/v/pendings.svg)](https://www.npmjs.com/package/pendings)

[![license](https://img.shields.io/npm/l/pendings.svg)](https://www.npmjs.com/package/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

```bash

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:

```js

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](#Pending) class allows to do it simpler:   

```js

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](#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.

```js

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](#Pending)

    * [new Pending([options])](#new_Pending_new)

    * [.promise](#Pending+promise) ⇒ Promise

    * [.value](#Pending+value) ⇒ \*

    * [.isResolved](#Pending+isResolved) ⇒ Boolean

    * [.isRejected](#Pending+isRejected) ⇒ Boolean

    * [.isFulfilled](#Pending+isFulfilled) ⇒ Boolean

    * [.isPending](#Pending+isPending) ⇒ Boolean

    * [.onFulfilled](#Pending+onFulfilled)

    * [.call(fn, [options])](#Pending+call) ⇒ Promise

    * [.resolve([value])](#Pending+resolve)

    * [.reject([value])](#Pending+reject)

    * [.fulfill([resolveValue], [rejectValue])](#Pending+fulfill)

    * [.reset([error])](#Pending+reset)



### 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()](#Pending+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)  



### pending.value ⇒ \*

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

**Kind**: instance property of [Pending](#Pending)  



### pending.isResolved ⇒ Boolean

Returns true if promise resolved.

**Kind**: instance property of [Pending](#Pending)  



### pending.isRejected ⇒ Boolean

Returns true if promise rejected.

**Kind**: instance property of [Pending](#Pending)  



### pending.isFulfilled ⇒ Boolean

Returns true if promise fulfilled (resolved or rejected).

**Kind**: instance property of [Pending](#Pending)  



### pending.isPending ⇒ Boolean

Returns true if promise is pending.

**Kind**: instance property of [Pending](#Pending)  



### pending.onFulfilled

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

**Kind**: instance property of [Pending](#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](#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](#Pending)  

| Param | Type |

| --- | --- |

| [value] | \* | 



### pending.reject([value])

Rejects pending promise with specified `value`.

**Kind**: instance method of [Pending](#Pending)  

| Param | Type |

| --- | --- |

| [value] | \* | 



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

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

**Kind**: instance method of [Pending](#Pending)  

| Param | Type |

| --- | --- |

| [resolveValue] | \* | 

| [rejectValue] | \* | 



### pending.reset([error])

Resets to initial state.

**Kind**: instance method of [Pending](#Pending)  

| Param | Type | Description |

| --- | --- | --- |

| [error] | Error | custom rejection error if promise is in pending state. |



## Pendings

**Kind**: global class  

* [Pendings](#Pendings)

    * [new Pendings([options])](#new_Pendings_new)

    * [.count](#Pendings+count) ⇒ Number

    * [.add(fn, [options])](#Pendings+add) ⇒ Promise

    * [.set(id, fn, [options])](#Pendings+set) ⇒ Promise

    * [.has(id)](#Pendings+has) ⇒ Boolean

    * [.resolve(id, [value])](#Pendings+resolve)

    * [.reject(id, [value])](#Pendings+reject)

    * [.fulfill(id, [resolveValue], [rejectValue])](#Pendings+fulfill)

    * [.tryResolve(id, [value])](#Pendings+tryResolve)

    * [.tryReject(id, [value])](#Pendings+tryReject)

    * [.tryFulfill(id, [resolveValue], [rejectValue])](#Pendings+tryFulfill)

    * [.rejectAll([value])](#Pendings+rejectAll)

    * [.waitAll()](#Pendings+waitAll) ⇒ Promise

    * [.clear()](#Pendings+clear)

    * [.generateId()](#Pendings+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)  



### pendings.add(fn, [options]) ⇒ Promise

Calls `fn` and returns new promise. `fn` gets generated unique `id` as parameter.

**Kind**: instance method of [Pendings](#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](#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](#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](#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](#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](#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](#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](#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](#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](#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](#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)  



### pendings.generateId() ⇒ String

Generates unique ID. Can be overwritten.

**Kind**: instance method of [Pendings](#Pendings)  



## TimeoutError

**Kind**: global class  



### new TimeoutError(timeout)

Timeout error for pending promise.

| Param | Type |

| --- | --- |

| timeout | Number | 

## License

MIT @ [Vitaliy Potapov](https://github.com/vitalets)

[Promises]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise