# promise-controller
[![Build Status](https://travis-ci.org/vitalets/promise-controller.svg?branch=master)](https://travis-ci.org/vitalets/promise-controller)
[![npm](https://img.shields.io/npm/v/promise-controller.svg)](https://www.npmjs.com/package/promise-controller)
[![license](https://img.shields.io/npm/l/promise-controller.svg)](https://www.npmjs.com/package/promise-controller)

Advanced control of JavaScript promises.

## Installation
```bash
npm install promise-controller --save
```

## Usage
```js
import PromiseController from 'promise-controller';

const pc = new PromiseController();
const promise = pc.call(() => startAsyncProcess());
// ...when async process done
pc.resolve('done');
// or
pc.reject();
```

## Use cases

* [Easy access to `resolve` / `reject` callbacks](#easy-access-to-resolve--reject-callbacks)
* [Re-use of existing promise while operation is pending](#re-use-of-existing-promise-while-operation-is-pending)
* [Automatically reject after timeout](#automatically-reject-after-timeout)

### Easy access to `resolve` / `reject` callbacks
With bare Promise:
```js
let resolve, reject;

const asyncOperation = setTimeout(() => Math.random() > 0.5 ? resolve() : reject(), 100);

const promise = new Promise((_resolve, _reject) => {
   resolve = _resolve;
   reject = _reject;
   asyncOperation();
});
```

With PromiseController:
```js
const pc = new PromiseController();

const asyncOperation = setTimeout(() => Math.random() > 0.5 ? pc.resolve() : pc.reject(), 100);

const promise = pc.call(asyncOperation);
```

### Re-use of existing promise while operation is pending
With bare Promise:
```js
let promise = null;

function connectToDb() {
    if (!promise) {
        promise = mongoClient.open();
    }

    return promise;
}
```

With PromiseController:
```js
const pc = new PromiseController();

function connectToDb() {
    return pc.promise || pc.call(() => mongoClient.open());
}
```

### Automatically reject after timeout
With bare Promise:
```js
let resolve, timer;

const asyncOperation = setTimeout(() => {
    resolve();
    clearTimeout(timer);
}, 100);

const promise = new Promise((_resolve, _reject) => {
    resolve = _resolve;
    asyncOperation();
    timer = setTimeout(() => _reject(), 50);
});
```

With PromiseController:
```js
const pc = new PromiseController({
  timeout: 50
});

const asyncOperation = setTimeout(() => resolve(), 100);

const promise = pc.call(asyncOperation);
```

## API

### Classes

PromiseController

### Typedefs

Options : Object

### PromiseController
**Kind**: global class  

* [PromiseController](#PromiseController)
    * [new PromiseController([options])](#new_PromiseController_new)
    * _instance_
        * [.promise](#PromiseController+promise) ⇒ Promise
        * [.value](#PromiseController+value) ⇒ \*
        * [.isPending](#PromiseController+isPending) ⇒ Boolean
        * [.isFulfilled](#PromiseController+isFulfilled) ⇒ Boolean
        * [.isRejected](#PromiseController+isRejected) ⇒ Boolean
        * [.isSettled](#PromiseController+isSettled) ⇒ Boolean
        * [.call([fn])](#PromiseController+call) ⇒ Promise
        * [.resolve([value])](#PromiseController+resolve)
        * [.reject([value])](#PromiseController+reject)
        * [.reset()](#PromiseController+reset)
        * [.configure(options)](#PromiseController+configure)
    * _static_
        * [.TimeoutError](#PromiseController.TimeoutError) : [TimeoutError](#PromiseController.TimeoutError)
        * [.ResetError](#PromiseController.ResetError) : [ResetError](#PromiseController.ResetError)

#### new PromiseController([options])
Creates promise controller. Unlike original Promise, it does not immediately call any function.
Instead it has [.call()](#PromiseController+call) method that calls provided function
and stores `resolve / reject` methods for future access.

| Param | Type |
| --- | --- |
| [options] | [Options](#Options) | 

#### pc.promise ⇒ Promise
Returns promise itself.

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

#### pc.value ⇒ \*
Returns value with that promise was settled (fulfilled or rejected).

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

#### pc.isPending ⇒ Boolean
Returns true if promise is pending.

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

#### pc.isFulfilled ⇒ Boolean
Returns true if promise is fulfilled.

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

#### pc.isRejected ⇒ Boolean
Returns true if promise rejected.

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

#### pc.isSettled ⇒ Boolean
Returns true if promise is fulfilled or rejected.

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

#### pc.call([fn]) ⇒ Promise
Calls `fn` and returns promise OR just returns existing promise from previous `call()` if it is still pending.
To fulfill returned promise you should use
[resolve](#PromiseController+resolve) / [reject](#PromiseController+reject) methods.
If `fn` itself returns promise, then external promise is attached to it and fulfills together.
If no `fn` passed - promiseController is initialized as well.

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

| Param | Type | Description |
| --- | --- | --- |
| [fn] | function | function to be called. |

#### pc.resolve([value])
Resolves pending promise with specified `value`.

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

| Param | Type |
| --- | --- |
| [value] | \* | 

#### pc.reject([value])
Rejects pending promise with specified `value`.

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

| Param | Type |
| --- | --- |
| [value] | \* | 

#### pc.reset()
Resets to initial state.
If promise is pending it will be rejected with [ResetError](#PromiseController.ResetError).

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

#### pc.configure(options)
Re-assign one or more options.

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

| Param | Type |
| --- | --- |
| options | [Options](#Options) | 

#### PromiseController.TimeoutError : [TimeoutError](#PromiseController.TimeoutError)
Error for rejection in case of timeout.

**Kind**: static property of [PromiseController](#PromiseController)  

#### PromiseController.ResetError : [ResetError](#PromiseController.ResetError)
Error for rejection in case of call `.reset()` while promise is pending.

**Kind**: static property of [PromiseController](#PromiseController)  

### Options : Object
**Kind**: global typedef  
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [timeout] | Number | 0 | Timeout in ms after that promise will be rejected automatically. |
| [timeoutReason] | String \| function |  | Rejection reason for timeout. Promise will be rejected with [TimeoutError](#PromiseController.TimeoutError) and this message. The message can contain placeholder `{timeout}` for actual timeout value. If timeoutReason is a function, it will be evaluated and returned value will be used as message. |
| [resetReason] | String \| function |  | Rejection reason used when `.reset()` is called while promise is pending. Promise will be rejected with [ResetError](#PromiseController.ResetError) and this message. If resetReason is a function, it will be evaluated and returned value will be used as message. |

## Related projects
* [event-to-promise](https://github.com/JsCommunity/event-to-promise)
* [promise-events](https://github.com/yanickrochon/promise-events)

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