Source: promise.js

  1. /*global process*/
  3. 'use strict';
  5. var _ = require('lodash/core');
  7. /**
  8.  * @callback ResolvedCallback
  9.  * @param {T} result - Resolved value
  10.  * @returns {S}
  11.  * @template T,S
  12.  */
  14. /**
  15.  * @callback RejectedCallback
  16.  * @param {Error} reason - Rejected reason
  17.  * @returns {S}
  18.  * @template S
  19.  */
  21. /**
  22.  * @callback ResolveCallback
  23.  * @param {T} result
  24.  * @template T
  25.  */
  27. /**
  28.  * @callback RejectedCallback
  29.  * @param {Error} reason - Rejected reason
  30.  * @returns {S}
  31.  * @template S
  32.  */
  34. /**
  35.  * @callback PromiseCallback
  36.  * @param {ResolveCallback.<T>} resolve
  37.  * @param {RejectCallback} reject
  38.  * @template T
  39.  */
  41. /**
  42.  * Promise class with a little extension
  43.  *
  44.  * @class Promise
  45.  * @constructor
  46.  * @param {PromiseCallback.<T>}
  47.  * @template T
  48.  */
  49. var Promise = require('promise/lib/es6-extensions');
  51. /**
  52.  * The "then" method from the Promises/A+ specification
  53.  *
  54.  * @method Promise#then
  55.  * @param {FulfilledCallback.<T, S1>} [onFulfilled]
  56.  * @param {RejectedCallback.<S2>} [onRejected]
  57.  * @returns {Promise.<S1|S2>}
  58.  */
  60. /**
  61.  * Call "then" using given node-style callback function.
  62.  * This is basically same as "nodeify" except that it always return the original promise
  63.  *
  64.  * @method Promise#thenCall
  65.  * @param {Callback.<T>} [callback] - Callback function
  66.  * @returns {Promise}
  67.  */
  68. Promise.prototype.thenCall = function(callback) {
  69.   if (_.isFunction(callback)) {
  70.     this.then(function(res) {
  71.       process.nextTick(function() {
  72.         callback(null, res);
  73.       });
  74.     }, function(err) {
  75.       process.nextTick(function() {
  76.         callback(err);
  77.       });
  78.     });
  79.   }
  80.   return this;
  81. };
  83. /**
  84.  * A sugar method, equivalent to promise.then(undefined, onRejected).
  85.  *
  86.  * @method Promise#catch
  87.  * @param {RejectedCallback.<S>} onRejected
  88.  * @returns {Promise.<S>}
  89.  */
  91. /**
  92.  * Synonym of Promise#catch
  93.  *
  94.  * @method Promise#fail
  95.  * @param {RejectedCallback.<S>} onRejected
  96.  * @returns {Promise.<S>}
  97.  */
  98. Promise.prototype.fail = Promise.prototype['catch'];
  100. /**
  101.  * Returns resolving promise with given reason
  102.  *
  103.  * @method Promise.resolve
  104.  * @param {*} result - Resolved value
  105.  * @returns {Promise}
  106.  */
  108. /**
  109.  * Returns rejecting promise with given reason
  110.  *
  111.  * @method Promise.reject
  112.  * @param {Error} reason - Rejecting reason
  113.  * @returns {Promise}
  114.  */
  116. /**
  117.  * Returns a promise that is fulfilled with an array containing the fulfillment value of each promise,
  118.  * or is rejected with the same rejection reason as the first promise to be rejected.
  119.  *
  120.  * @method Promise.all
  121.  * @param {Array.<Promise.<*>|*>} promises
  122.  * @returns {Promise.<Array.<*>>}
  123.  */
  125. /**
  126.  * Returns a deferred object
  127.  *
  128.  * @method Promise.defer
  129.  * @returns {Deferred}
  130.  */
  131. Promise.defer = function() {
  132.   return new Deferred();
  133. };
  135. /**
  136.  * Deferred object
  137.  *
  138.  * @protected
  139.  * @constructor
  140.  */
  141. var Deferred = function() {
  142.   var self = this;
  143.   this.promise = new Promise(function(resolve, reject) {
  144.     self.resolve = resolve;
  145.     self.reject = reject;
  146.   });
  147. };
  149. /**
  150.  * Resolve promise
  151.  * @method Deferred#resolve
  152.  * @param {*} result - Resolving result
  153.  */
  155. /**
  156.  * Reject promise
  157.  * @method Deferred#reject
  158.  * @param {Error} error - Rejecting reason
  159.  */
  161. /**
  162.  *
  163.  */
  164. module.exports = Promise;