https://github.com/vitalets/promise-controller
Advanced control of JavaScript promises
https://github.com/vitalets/promise-controller
promise promise-api promise-library promise-wrapper
Last synced: 6 months ago
JSON representation
Advanced control of JavaScript promises
- Host: GitHub
- URL: https://github.com/vitalets/promise-controller
- Owner: vitalets
- Created: 2018-07-03T15:22:56.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-03-02T01:56:51.000Z (over 2 years ago)
- Last Synced: 2024-05-09T19:26:24.087Z (over 1 year ago)
- Topics: promise, promise-api, promise-library, promise-wrapper
- Language: JavaScript
- Size: 399 KB
- Stars: 13
- Watchers: 3
- Forks: 1
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# promise-controller
[](https://travis-ci.org/vitalets/promise-controller)
[](https://www.npmjs.com/package/promise-controller)
[](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
### 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)