Deferred
The fastest implementation of Deferred pattern with synchronous calls and context support.
12 times less and 5 times faster than Bluebird.
Features
- Cross-browser
- Sync calls when it's possible
- Support context for the handlers
- Small size: 2.1 KB (minified and gzipped)
- No dependencies
- Performance
Browser support
Any ES3 compliant browser.
Table of content
Install
npm install deferred2
Usage
As a script tag:
As a CommonJS module:
const Deferred = ; // Deferred is available here
As an AMD module:
;
As an ES2015 module:
// Deferred is available here
API
Deferred
A new instance of Deferred can be created by calling Deferred as a constructor
(e.g. with a new
keyword):
const dfd = ;
Static methods
Deferred.resolve()
Returns a Promise object that is resolved with the given value.
If the value is a thenable (i.e. has a then method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value.
Params
Parameter | Type | Description |
---|---|---|
value | *|Promise|Deferred|Thenable |
Any value. Optional. |
Returns: Promise
.
Examples
Resolving with value:
Deferred ;
Resolving with another deferred:
const dfd = ;Deferred ==== dfdpromise; // true
Resolving with promise:
const dfd = ;Deferred === dfdpromise; // true
Resolving with thenable:
const thenable = { ; }; Deferred ;
Deferred.reject()
Returns a Promise object that is rejected with the given reason.
Params
Parameter | Type | Description |
---|---|---|
reason | * |
Any value. Optional. |
Returns: Promise
.
Examples
Rejection with value:
Deferred ;
Deferred.all()
Returns a promise that resolves when all of the promises in the given array have resolved, or rejects with the reason of the first passed promise that rejects.
Params
Parameter | Type | Description |
---|---|---|
promises | Array|ArrayLike |
Array or ArrayLike object of promises. |
Returns: Promise
.
Examples
const dfdA = ;const dfdB = ;const dfdC = ; DeferredalldfdApromise dfdBpromise dfdCpromise ; dfdA;dfdB;dfdC; // ["foo", "bar", "xyz"]
Deferred.race()
Returns a promise that resolves or rejects as soon as one of the promises in the given array resolves or rejects, with the value or reason from that promise.
Params
Parameter | Type | Description |
---|---|---|
promises | Array|ArrayLike |
Array or ArrayLike object of promises. |
Returns: Promise
.
Examples
const dfdA = ;const dfdB = ;const dfdC = ; Deferred ; ; ;
Deferred.isDeferred()
Returns true
if the given argument is an instance of Deferred, false
if it is not.
Params
Parameter | Type | Description |
---|---|---|
arg | * |
The argument to be checked. |
Returns: Boolean
.
Examples
const dfd = ; Deferred; // trueDeferred; // falseDeferred; // falseDeferred; // false
Deferred.isPromise()
Returns true
if the given argument is an instance of Promise, produced by Deferred,
false
if it is not.
Params
Parameter | Type | Description |
---|---|---|
arg | * |
The argument to be checked. |
Returns: Boolean
.
Examples
const dfd = ; Deferred; // falseDeferred; // trueDeferred; // falseDeferred; // falseDeferred; // false
Deferred.isThenable()
Returns true
if the given argument is a thenable object (has then
method),
false
if it is not.
Params
Parameter | Type | Description |
---|---|---|
arg | * |
The argument to be checked. |
Returns: Boolean
.
Examples
const dfd = ; Deferred; // falseDeferred; // trueDeferred; // trueDeferred; // falseDeferred; // true
Deferred instance
.resolve()
Resolves the promise with the given value.
If the value is a thenable (i.e. has a then method), the promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value.
Params
Parameter | Type | Description |
---|---|---|
value | *|Promise|Deferred|Thenable |
Any value. Optional. |
Returns: Deferred
– the same deferred instance for the chaining.
Examples
Resolving with value:
const dfd = ; dfdpromise ; dfd; // 2
Resolving with another deferred:
const dfdA = ;const dfdB = ; dfdApromise ; dfdA; dfdB; // "foo"
Resolving with promise:
const dfdA = ;const dfdB = ; dfdApromise ; dfdA; dfdB; // "foo"
Resolving with thenable:
const dfd = ; dfdpromise ; const thenable = { ; }; dfd;
.reject()
Rejects the promise with the given reason.
Params
Parameter | Type | Description |
---|---|---|
reason | * |
Any value. |
Returns: Deferred
– the same deferred instance for the chaining.
Examples
const dfd = ; dfdpromise ; dfd; // "Error"
.promise
Promise instance associated with this deferred. See Promise instance API.
Examples
const dfd = ; dfdpromise;
Promise instance
Promise cannot be instantiated directly. Instead you need to create an instance of Deferred and get the associated promise from it:
const dfd = ;const promise = dfdpromise; promise
Promise instance methods
.then()
Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled (i.e. if the relevant handler onFulfilled or onRejected is undefined).
See Promises/A+ for details.
Params
Parameter | Type | Description |
---|---|---|
onResolve | Function |
A function, which is called when the promise is resolved. Optional. |
onReject | Function |
A function, which is called when the promise is rejected. Optional. |
ctx | Object |
The context for the handlers. Optional. |
Returns: Promise
– a new promise based on the value, returned by the handler.
Examples
Handle resolve:
const dfd = ; dfdpromise ; dfd; // "foo"
Handle reject:
const dfd = ; dfdpromise ; dfd; // "Error"
Pass only onResolve
:
const dfd = ; dfdpromise ; dfd; // "bar"
Pass only onReject
:
const dfd = ; dfdpromise ; dfd; // "Error"
Pass the context:
{ this } { console; // true } { console; // true }
Pass only onResolve
and the context:
{ this ; } { console; // true }
.catch()
Adds the given handler to be called when the promise is reject.
Creates a new promise and returns it.
Alias for .then(null, onReject)
.
Params
Parameter | Type | Description |
---|---|---|
onReject | Function |
A function, which is called when the promise is rejected. |
ctx | Object |
The context for the handler. Optional. |
Examples
const dfd = ; dfdpromise ; dfd; // "Error"
.done()
Adds the given handler to be called when the promise is resolved.
The main difference from .then
method is that .done
only adds a handler and doesn't create
a new promise. Instead it returns the current promise for the chaining.
Params
Parameter | Type | Description |
---|---|---|
onResolve | Function |
A function, which is called when the promise is resolved. |
ctx | Object |
The context for the handler. Optional. |
Returns: Promise
– the same promise for the chaining.
Examples
const dfd = ; dfdpromise ; dfd; // "foo"
Context for the handler:
{ this ; } { console; // true } { const dfd = ; return dfdpromise; }
.fail()
Adds the given handler to be called when the promise is rejected.
The main difference from .catch
method is that .fail
only adds a handler and doesn't create
a new promise. Instead it returns the current promise for the chaining.
Params
Parameter | Type | Description |
---|---|---|
onReject | Function |
A function, which is called when the promise is rejected. |
ctx | Object |
The context for the handler. Optional. |
Returns: Promise
– the same promise for the chaining.
Examples
const dfd = ; dfdpromise ; dfd; // "foo"
Context for the handler:
{ this ; } { console; // true } { const dfd = ; return dfdpromise; }
.always()
Adds the given handler to be called when the promise is either resolved or rejected.
Params
Parameter | Type | Description |
---|---|---|
onSettle | Function |
A function, which is called when the promise is resolved or rejected. |
ctx | Object |
The context for the handler. Optional. |
Returns: Promise
– the same promise for the chaining.
Examples
const dfdA = ;const dfdB = ; dfdApromise ; dfdBpromise ; dfdA; // "foo"dfdB; // "bar"
The always
method is useful when you need to run some code regardless to the result of
the async call.
Consider you want to load some data and while the data is loading you want to display a progress indicator. In this case you need to show the progress indicator before the request for the data and hide when the request is completed regardless to whether it was successful or not:
; ;
NOTE: Most descriptions here are taken from MDN.
Performance
In the benchmark suite I create an instance of the Deferred.
Then I create a new promise by calling .then
method on the initial one.
And then I resolve the deferred with plain value.
Since native promises don't provide a deferred implementation, the suite for the ES6 Promise is slightly different.
The code of the benchmark suite can be found in benchmark/suite directory.
Start benchmark:
npm run bench
If you get out of memory
error, try to run the suites separately one by one by commenting out
all the suites and keeping uncommented only one of them.
On Macbook Pro 2015 with NodeJS v4.0.0
I got the following result:
Library | Ops/sec |
---|---|
Deferred | 1,754,069 |
Bluebird | 913,827 |
ES6 promise | 724,337 |
RSVP | 590,330 |
vow | 365,653 |
kew | 171,724 |
Q | 57,255 |
jQuery | 41,247 |
License
MIT