Nourishing Pizza Microservice

    deferred2

    1.4.0 • Public • Published

    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:

    <script src="path/to/deferred.js"></script>
    <script>
      // window.Deferred is available here
    </script> 

    As a CommonJS module:

    const Deferred = require('deferred2');
     
    // Deferred is available here

    As an AMD module:

    define(['Deferred'], function (Deferred) {
      // Deferred is available here
    });

    As an ES2015 module:

    import {Deferred} from 'deferred2'
     
    // 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):

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();

    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:

    import {Deferred} from 'deferred2'
     
    Deferred.resolve(2)
      .then(function(val) {
        console.log(val); // 2
      });

    Resolving with another deferred:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
    Deferred.resolve(dfd) ==== dfd.promise; // true

    Resolving with promise:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
    Deferred.resolve(dfd.promise) === dfd.promise; // true

    Resolving with thenable:

    import {Deferred} from 'deferred2'
     
    const thenable = {
      then: function (onResolve, onReject) {
        setTimeout(function () {
          onResolve(2);
        }, 1000);
      }
    };
     
    Deferred.resolve(thenable)
      .then(function (val) {
        console.log(val); // 2
      });

    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:

    import {Deferred} from 'deferred2'
     
    Deferred.reject('Some error')
      .catch(function(val) {
        console.log(val); // "Some error"
      });

    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
    import {Deferred} from 'deferred'
     
    const dfdA = new Deferred();
    const dfdB = new Deferred();
    const dfdC = new Deferred();
     
    Deferred.all([dfdA.promise, dfdB.promise, dfdC.promise])
      .then(function onResolve (values) {
        console.log(values);
      })
      .catch(function onReject (reason) {
        console.log(reason);
      });
     
    dfdA.resolve('foo');
    dfdB.resolve('bar');
    dfdC.resolve('xyz'); // ["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
    import {Deferred} from 'deferred'
     
    const dfdA = new Deferred();
    const dfdB = new Deferred();
    const dfdC = new Deferred();
     
    Deferred.race([dfdA.promise, dfdB.promise, dfdC.promise])
      .then(function onResolve (value) {
        console.log(value);
      })
      .catch(function onReject (reason) {
        console.log(reason);
      });
     
    setTimeout(() => {
      dfdA.resolve('foo');
    }, 1000);
     
    setTimeout(() => {
      dfdA.resolve('bar'); // "bar"
    }, 500);

    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
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    Deferred.isDeferred(dfd);                      // true
    Deferred.isDeferred(dfd.promise);              // false
    Deferred.isDeferred({ then: function () {} }); // false
    Deferred.isDeferred('foo');                    // 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
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    Deferred.isPromise(dfd);                      // false
    Deferred.isPromise(dfd.promise);              // true
    Deferred.isPromise({ then: function () {} }); // false
    Deferred.isPromise('foo');                    // false
    Deferred.isPromise((new Promise(function (resolve, reject) {}))); // 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
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    Deferred.isThenable(dfd);                      // false
    Deferred.isThenable(dfd.promise);              // true
    Deferred.isThenable({ then: function () {} }); // true
    Deferred.isThenable('foo');                    // false
    Deferred.isThenable((new Promise(function (resolve, reject) {}))); // 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:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .then(function(val) {
        console.log(val);
      });
     
    dfd.resolve(2); // 2

    Resolving with another deferred:

    import {Deferred} from 'deferred2'
     
    const dfdA = new Deferred();
    const dfdB = new Deferred();
     
    dfdA.promise
      .then(function onResolve (value) {
        console.log(value);
      });
     
    dfdA.resolve(dfdB);
     
    dfdB.resolve('foo'); // "foo"

    Resolving with promise:

    import {Deferred} from 'deferred2'
     
    const dfdA = new Deferred();
    const dfdB = new Deferred();
     
    dfdA.promise
      .then(function onResolve (value) {
        console.log(value);
      });
     
    dfdA.resolve(dfdB.promise);
     
    dfdB.resolve('foo'); // "foo"

    Resolving with thenable:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .then(function onResolve (value) {
        console.log(value);
      });
     
    const thenable = {
      then: function (onResolve, onReject) {
        setTimeout(function () {
          onResolve('foo'); // "foo"
        }, 1000);
      }
    };
     
    dfd.resolve(thenable);

    .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
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .catch(function(reason) {
        console.log(reason);
      });
     
    dfd.reject('Error'); // "Error"

    .promise

    Promise instance associated with this deferred. See Promise instance API.

    Examples
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise.then(onResolve, onReject);

    Promise instance

    Promise cannot be instantiated directly. Instead you need to create an instance of Deferred and get the associated promise from it:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
    const promise = dfd.promise;
     
    promise.then(/*...*/)

    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:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .then(function onResolve (value) {
        console.log(value);
      }, function onReject (reason) {
        console.log(reason);
      });
     
    dfd.resolve('foo'); // "foo"

    Handle reject:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .then(function onResolve (value) {
        console.log(value);
      }, function onReject (reason) {
        console.log(reason);
      });
     
    dfd.reject('Error'); // "Error"

    Pass only onResolve:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .then(function onResolve (value) {
        console.log(value);
      });
     
    dfd.resolve('bar'); // "bar"

    Pass only onReject:

    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .then(null, function onReject (value) {
        console.log(value);
      });
     
    dfd.reject('Error'); // "Error"

    Pass the context:

    import {Deferred} from 'deferred2'
     
    class Component {
      constructor () {
        this.load()
          .then(
            this.onLoad,
            this.onFail,
            this
          )
      }
     
      onLoad () {
        console.log(this instanceof Component); // true
      }
     
      onFail () {
        console.log(this instanceof Component); // true
      }
    }

    Pass only onResolve and the context:

    import {Deferred} from 'deferred2'
     
    class Component {
      constructor () {
        this.load()
        .then(this.onLoad, this);
      }
     
      onLoad () {
        console.log(this instanceof Component); // 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
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .catch(function onReject (reason) {
        console.log(reason);
      });
     
    dfd.reject('Error'); // "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
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .done(function (value) {
        console.log(value);
      });
     
    dfd.resolve('foo'); // "foo"

    Context for the handler:

    import {Deferred} from 'deferred2'
     
    class Component {
      constructor () {
        this.loadData()
          .done(this.onLoad, this);
      }
     
      onLoad () {
        console.log(this instanceof Component); // true
      }
     
      load () {
        const dfd = new Deferred();
        return dfd.promise;
      }
    }

    .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
    import {Deferred} from 'deferred2'
     
    const dfd = new Deferred();
     
    dfd.promise
      .fail(function (value) {
        console.log(value);
      });
     
    dfd.reject('foo'); // "foo"

    Context for the handler:

    import {Deferred} from 'deferred2'
     
    class Component {
      constructor () {
        this.loadData()
          .fail(this.onFail, this);
      }
     
      onFail () {
        console.log(this instanceof Component); // true
      }
     
      load () {
        const dfd = new Deferred();
        return dfd.promise;
      }
    }

    .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
    import {Deferred} from 'deferred2'
     
    const dfdA = new Deferred();
    const dfdB = new Deferred();
     
    dfdA.promise
      .always(function (value) {
        console.log(value);
      });
     
    dfdB.promise
      .always(function (value) {
        console.log(value);
      });
     
    dfdA.resolve('foo'); // "foo"
    dfdB.reject('bar');  // "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:

    showSpinner();
     
    loadData()
      .done(renderData)
      .fail(displayError)
      .always(hideSpinner);

    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

    Install

    npm i deferred2

    DownloadsWeekly Downloads

    0

    Version

    1.4.0

    License

    MIT

    Last publish

    Collaborators

    • dmitryshimkin