promise-controller
Advanced control of JavaScript promises.
Installation
npm install promise-controller --save
Usage
; const pc = ;const promise = pc;// ...when async process donepc;// orpc;
Use cases
- Easy access to
resolve
/reject
callbacks - Re-use of existing promise while operation is pending
- Automatically reject after timeout
resolve
/ reject
callbacks
Easy access to With bare Promise:
let resolve reject; const asyncOperation = ; const promise = { resolve = _resolve; reject = _reject; ;};
With PromiseController:
const pc = ; const asyncOperation = ; const promise = pc;
Re-use of existing promise while operation is pending
With bare Promise:
let promise = null; { if !promise promise = mongoClient; return promise;}
With PromiseController:
const pc = ; { return pcpromise || pc;}
Automatically reject after timeout
With bare Promise:
let resolve timer; const asyncOperation = ; const promise = { resolve = _resolve; ; timer = ;};
With PromiseController:
const pc = timeout: 50; const asyncOperation = ; const promise = pc;
API
Classes
Typedefs
- Options :
Object
PromiseController
Kind: global class
- PromiseController
- new PromiseController([options])
- instance
- .promise ⇒
Promise
- .value ⇒
*
- .isPending ⇒
Boolean
- .isFulfilled ⇒
Boolean
- .isRejected ⇒
Boolean
- .isSettled ⇒
Boolean
- .call([fn]) ⇒
Promise
- .resolve([value])
- .reject([value])
- .reset()
- .configure(options)
- .promise ⇒
- static
new PromiseController([options])
Creates promise controller. Unlike original Promise, it does not immediately call any function.
Instead it has .call() method that calls provided function
and stores resolve / reject
methods for future access.
Param | Type |
---|---|
[options] | Options |
Promise
pc.promise ⇒ Returns promise itself.
Kind: instance property of PromiseController
*
pc.value ⇒ Returns value with that promise was settled (fulfilled or rejected).
Kind: instance property of PromiseController
Boolean
pc.isPending ⇒ Returns true if promise is pending.
Kind: instance property of PromiseController
Boolean
pc.isFulfilled ⇒ Returns true if promise is fulfilled.
Kind: instance property of PromiseController
Boolean
pc.isRejected ⇒ Returns true if promise rejected.
Kind: instance property of PromiseController
Boolean
pc.isSettled ⇒ Returns true if promise is fulfilled or rejected.
Kind: instance property of PromiseController
Promise
pc.call([fn]) ⇒ 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 / 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
Param | Type | Description |
---|---|---|
[fn] | function |
function to be called. |
pc.resolve([value])
Resolves pending promise with specified value
.
Kind: instance method of PromiseController
Param | Type |
---|---|
[value] | * |
pc.reject([value])
Rejects pending promise with specified value
.
Kind: instance method of PromiseController
Param | Type |
---|---|
[value] | * |
pc.reset()
Resets to initial state. If promise is pending it will be rejected with ResetError.
Kind: instance method of PromiseController
pc.configure(options)
Re-assign one or more options.
Kind: instance method of PromiseController
Param | Type |
---|---|
options | Options |
TimeoutError
PromiseController.TimeoutError : Error for rejection in case of timeout.
Kind: static property of PromiseController
ResetError
PromiseController.ResetError : Error for rejection in case of call .reset()
while promise is pending.
Kind: static property of PromiseController
Object
Options : 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 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 and this message. If resetReason is a function, it will be evaluated and returned value will be used as message. |
Related projects
License
MIT @ Vitaliy Potapov