Source: lib/polyfill/promise.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.polyfill.Promise');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.log');
  22. goog.require('shaka.polyfill.register');
  26. /**
  27.  * @summary A polyfill to implement Promises, primarily for IE.
  28.  * Only partially supports thenables, but otherwise passes the A+ conformance
  29.  * tests.
  30.  * Note that Promise.all() and Promise.race() are not tested by that suite.
  31.  *
  32.  * @constructor
  33.  * @struct
  34.  * @param {function(function(*=), function(*=))=} opt_callback
  35.  * @template T
  36.  */
  37. shaka.polyfill.Promise = function(opt_callback) {
  38.   /** @private {!Array.<shaka.polyfill.Promise.Child>} */
  39.   this.thens_ = [];
  41.   /** @private {!Array.<shaka.polyfill.Promise.Child>} */
  42.   this.catches_ = [];
  44.   /** @private {shaka.polyfill.Promise.State} */
  45.   this.state_ = shaka.polyfill.Promise.State.PENDING;
  47.   /** @private {*} */
  48.   this.value_;
  50.   // External callers must supply the callback.  Internally, we may construct
  51.   // child Promises without it, since we can directly access their resolve_ and
  52.   // reject_ methods when convenient.
  53.   if (opt_callback) {
  54.     try {
  55.       opt_callback(this.resolve_.bind(this), this.reject_.bind(this));
  56.     } catch (e) {
  57.       this.reject_(e);
  58.     }
  59.   }
  60. };
  63. /**
  64.  * @typedef {{
  65.  *   promise: !shaka.polyfill.Promise,
  66.  *   callback: (function(*)|undefined)
  67.  * }}
  68.  *
  69.  * @summary A child promise, used for chaining.
  70.  * @description
  71.  *   Only exists in the context of a then or catch chain.
  72.  * @property {!shaka.polyfill.Promise} promise
  73.  *   The child promise.
  74.  * @property {(function(*)|undefined)} callback
  75.  *   The then or catch callback to be invoked as part of this chain.
  76.  */
  77. shaka.polyfill.Promise.Child;
  80. /**
  81.  * @enum {number}
  82.  */
  83. shaka.polyfill.Promise.State = {
  84.   PENDING: 0,
  85.   RESOLVED: 1,
  86.   REJECTED: 2
  87. };
  90. /**
  91.  * Install the polyfill if needed.
  92.  * @param {boolean=} opt_force If true, force the polyfill to be installed.
  93.  *   Used in some unit tests.
  94.  */
  95. shaka.polyfill.Promise.install = function(opt_force) {
  96.   // Decide on the best way to invoke a callback as soon as possible.
  97.   // Precompute the setImmediate/clearImmediate convenience methods to avoid the
  98.   // overhead of this switch every time a callback has to be invoked.
  99.   if (window.setImmediate) {
  100.     // For IE and node.js:
  101.     shaka.polyfill.Promise.setImmediate_ = function(callback) {
  102.       return window.setImmediate(callback);
  103.     };
  104.     shaka.polyfill.Promise.clearImmediate_ = function(id) {
  105.       return window.clearImmediate(id);
  106.     };
  107.   } else {
  108.     // For everyone else:
  109.     shaka.polyfill.Promise.setImmediate_ = function(callback) {
  110.       return window.setTimeout(callback, 0);
  111.     };
  112.     shaka.polyfill.Promise.clearImmediate_ = function(id) {
  113.       return window.clearTimeout(id);
  114.     };
  115.   }
  117.   if (window.Promise && !opt_force) {
  118.     shaka.log.info('Using native Promises.');
  119.     return;
  120.   }
  122.   shaka.log.info('Using Promises polyfill.');
  123.   // Quoted to work around type-checking, since our then() signature doesn't
  124.   // exactly match that of a native Promise.
  125.   window['Promise'] = shaka.polyfill.Promise;
  127.   // Explicitly installed because the compiler won't necessarily attach them
  128.   // to the compiled constructor.  Exporting them will only attach them to
  129.   // their original namespace, which isn't the same as attaching them to the
  130.   // constructor unless you also export the constructor.
  131.   window['Promise'].resolve = shaka.polyfill.Promise.resolve;
  132.   window['Promise'].reject = shaka.polyfill.Promise.reject;
  133.   window['Promise'].all = shaka.polyfill.Promise.all;
  134.   window['Promise'].race = shaka.polyfill.Promise.race;
  136.   // These are manually exported as well, because allowing the compiler to
  137.   // export them for us will cause the polyfill to end up in our generated
  138.   // externs.  Since nobody should be accessing this directly using the
  139.   // shaka.polyfill namespace, it is okay not to @export these methods.
  140.   window['Promise']['prototype']['then'] =
  141.       shaka.polyfill.Promise.prototype.then;
  142.   window['Promise']['prototype']['catch'] =
  143.       shaka.polyfill.Promise.prototype.catch;
  144. };
  147. /**
  148.  * Uninstall the polyfill.  Used in some unit tests.
  149.  */
  150. shaka.polyfill.Promise.uninstall = function() {
  151.   // Do nothing if there is no native implementation.
  152.   if (shaka.polyfill.Promise.nativePromise_) {
  153.     shaka.log.info('Removing Promise polyfill.');
  154.     window['Promise'] = shaka.polyfill.Promise.nativePromise_;
  155.     shaka.polyfill.Promise.q_ = [];
  156.   }
  157. };
  160. /**
  161.  * @param {*=} opt_value
  162.  * @return {!shaka.polyfill.Promise}
  163.  */
  164. shaka.polyfill.Promise.resolve = function(opt_value) {
  165.   var p = new shaka.polyfill.Promise();
  166.   p.resolve_(undefined);
  167.   return p.then(function() {
  168.     return opt_value;
  169.   });
  170. };
  173. /**
  174.  * @param {*=} opt_reason
  175.  * @return {!shaka.polyfill.Promise}
  176.  */
  177. shaka.polyfill.Promise.reject = function(opt_reason) {
  178.   var p = new shaka.polyfill.Promise();
  179.   p.reject_(opt_reason);
  180.   return p;
  181. };
  184. /**
  185.  * @param {!Array.<!shaka.polyfill.Promise>} others
  186.  * @return {!shaka.polyfill.Promise}
  187.  */
  188. shaka.polyfill.Promise.all = function(others) {
  189.   var p = new shaka.polyfill.Promise();
  190.   if (!others.length) {
  191.     p.resolve_([]);
  192.     return p;
  193.   }
  195.   // The array of results must be in the same order as the array of Promises
  196.   // passed to all().  So we pre-allocate the array and keep a count of how
  197.   // many have resolved.  Only when all have resolved is the returned Promise
  198.   // itself resolved.
  199.   var count = 0;
  200.   var values = new Array(others.length);
  201.   var resolve = function(p, i, newValue) {
  202.     goog.asserts.assert(p.state_ != shaka.polyfill.Promise.State.RESOLVED,
  203.                         'Invalid Promise state in Promise.all');
  204.     // If one of the Promises in the array was rejected, this Promise was
  205.     // rejected and new values are ignored.  In such a case, the values array
  206.     // and its contents continue to be alive in memory until all of the Promises
  207.     // in the array have completed.
  208.     if (p.state_ == shaka.polyfill.Promise.State.PENDING) {
  209.       values[i] = newValue;
  210.       count++;
  211.       if (count == values.length) {
  212.         p.resolve_(values);
  213.       }
  214.     }
  215.   };
  217.   var reject = p.reject_.bind(p);
  218.   for (var i = 0; i < others.length; ++i) {
  219.     if (others[i] && others[i].then) {
  220.       others[i].then(resolve.bind(null, p, i), reject);
  221.     } else {
  222.       resolve(p, i, others[i]);
  223.     }
  224.   }
  225.   return p;
  226. };
  229. /**
  230.  * @param {!Array.<!shaka.polyfill.Promise>} others
  231.  * @return {!shaka.polyfill.Promise}
  232.  */
  233. shaka.polyfill.Promise.race = function(others) {
  234.   var p = new shaka.polyfill.Promise();
  236.   // The returned Promise is resolved or rejected as soon as one of the others
  237.   // is.
  238.   var resolve = p.resolve_.bind(p);
  239.   var reject = p.reject_.bind(p);
  240.   for (var i = 0; i < others.length; ++i) {
  241.     if (others[i] && others[i].then) {
  242.       others[i].then(resolve, reject);
  243.     } else {
  244.       resolve(others[i]);
  245.     }
  246.   }
  247.   return p;
  248. };
  251. /**
  252.  * @param {function(*)=} opt_successCallback
  253.  * @param {function(*)=} opt_failCallback
  254.  * @return {!shaka.polyfill.Promise}
  255.  */
  256. shaka.polyfill.Promise.prototype.then = function(opt_successCallback,
  257.                                                  opt_failCallback) {
  258.   // then() returns a child Promise which is chained onto this one.
  259.   var child = new shaka.polyfill.Promise();
  260.   switch (this.state_) {
  261.     case shaka.polyfill.Promise.State.RESOLVED:
  262.       // This is already resolved, so we can chain to the child ASAP.
  263.       this.schedule_(child, opt_successCallback);
  264.       break;
  265.     case shaka.polyfill.Promise.State.REJECTED:
  266.       // This is already rejected, so we can chain to the child ASAP.
  267.       this.schedule_(child, opt_failCallback);
  268.       break;
  269.     case shaka.polyfill.Promise.State.PENDING:
  270.       // This is pending, so we have to track both callbacks and the child
  271.       // in order to chain later.
  272.       this.thens_.push({ promise: child, callback: opt_successCallback});
  273.       this.catches_.push({ promise: child, callback: opt_failCallback});
  274.       break;
  275.   }
  277.   return child;
  278. };
  281. /**
  282.  * @param {function(*)=} opt_callback
  283.  * @return {!shaka.polyfill.Promise}
  284.  */
  285. shaka.polyfill.Promise.prototype.catch = function(opt_callback) {
  286.   // Devolves into a two-argument call to 'then'.
  287.   return this.then(undefined, opt_callback);
  288. };
  291. /**
  292.  * @param {*=} opt_value
  293.  * @private
  294.  */
  295. shaka.polyfill.Promise.prototype.resolve_ = function(opt_value) {
  296.   // Ignore resolve calls if we aren't still pending.
  297.   if (this.state_ == shaka.polyfill.Promise.State.PENDING) {
  298.     this.value_ = opt_value;
  299.     this.state_ = shaka.polyfill.Promise.State.RESOLVED;
  300.     // Schedule calls to all of the chained callbacks.
  301.     for (var i = 0; i < this.thens_.length; ++i) {
  302.       this.schedule_(this.thens_[i].promise, this.thens_[i].callback);
  303.     }
  304.     this.thens_ = [];
  305.     this.catches_ = [];
  306.   }
  307. };
  310. /**
  311.  * @param {*=} opt_reason
  312.  * @private
  313.  */
  314. shaka.polyfill.Promise.prototype.reject_ = function(opt_reason) {
  315.   // Ignore reject calls if we aren't still pending.
  316.   if (this.state_ == shaka.polyfill.Promise.State.PENDING) {
  317.     this.value_ = opt_reason;
  318.     this.state_ = shaka.polyfill.Promise.State.REJECTED;
  319.     // Schedule calls to all of the chained callbacks.
  320.     for (var i = 0; i < this.catches_.length; ++i) {
  321.       this.schedule_(this.catches_[i].promise, this.catches_[i].callback);
  322.     }
  323.     this.thens_ = [];
  324.     this.catches_ = [];
  325.   }
  326. };
  329. /**
  330.  * @param {!shaka.polyfill.Promise} child
  331.  * @param {function(*)|undefined} callback
  332.  * @private
  333.  */
  334. shaka.polyfill.Promise.prototype.schedule_ = function(child, callback) {
  335.   goog.asserts.assert(this.state_ != shaka.polyfill.Promise.State.PENDING,
  336.                       'Invalid Promise state in Promise.schedule_');
  337.   var Promise = shaka.polyfill.Promise;
  339.   var wrapper = function() {
  340.     if (callback && typeof callback == 'function') {
  341.       // Wrap around the callback.  Exceptions thrown by the callback are
  342.       // converted to failures.
  343.       try {
  344.         var value = callback(this.value_);
  345.       } catch (exception) {
  346.         child.reject_(exception);
  347.         return;
  348.       }
  350.       // According to the spec, 'then' in a thenable may only be accessed once
  351.       // and any thrown exceptions in the getter must cause the Promise chain
  352.       // to fail.
  353.       var then;
  354.       try {
  355.         then = value && value.then;
  356.       } catch (exception) {
  357.         child.reject_(exception);
  358.         return;
  359.       }
  361.       if (value instanceof Promise) {
  362.         // If the returned value is a Promise, we bind it's state to the child.
  363.         if (value == child) {
  364.           // Without this, a bad calling pattern can cause an infinite loop.
  365.           child.reject_(new TypeError('Chaining cycle detected'));
  366.         } else {
  367.           value.then(child.resolve_.bind(child), child.reject_.bind(child));
  368.         }
  369.       } else if (then) {
  370.         // If the returned value is thenable, chain it to the child.
  371.         Promise.handleThenable_(value, then, child);
  372.       } else {
  373.         // If the returned value is not a Promise, the child is resolved with
  374.         // that value.
  375.         child.resolve_(value);
  376.       }
  377.     } else if (this.state_ == Promise.State.RESOLVED) {
  378.       // No callback for this state, so just chain on down the line.
  379.       child.resolve_(this.value_);
  380.     } else {
  381.       // No callback for this state, so just chain on down the line.
  382.       child.reject_(this.value_);
  383.     }
  384.   };
  386.   // Enqueue a call to the wrapper.
  387.   Promise.q_.push(wrapper.bind(this));
  388.   if (Promise.flushTimer_ == null) {
  389.     Promise.flushTimer_ = Promise.setImmediate_(Promise.flush);
  390.   }
  391. };
  394. /**
  395.  * @param {!Object} thenable
  396.  * @param {Function} then
  397.  * @param {!shaka.polyfill.Promise} child
  398.  * @private
  399.  */
  400. shaka.polyfill.Promise.handleThenable_ = function(thenable, then, child) {
  401.   var Promise = shaka.polyfill.Promise;
  402.   try {
  403.     var sealed = false;
  404.     then.call(thenable, function(value) {
  405.       if (sealed) return;
  406.       sealed = true;
  408.       var nextThen;
  409.       try {
  410.         nextThen = value && value.then;
  411.       } catch (exception) {
  412.         child.reject_(exception);
  413.         return;
  414.       }
  416.       if (nextThen) {
  417.         Promise.handleThenable_(value, nextThen, child);
  418.       } else {
  419.         child.resolve_(value);
  420.       }
  421.     }, child.reject_.bind(child));
  422.   } catch (exception) {
  423.     child.reject_(exception);
  424.   }
  425. };
  428. /**
  429.  * Flush the queue of callbacks.
  430.  * Used directly by some unit tests.
  431.  */
  432. shaka.polyfill.Promise.flush = function() {
  433.   var Promise = shaka.polyfill.Promise;
  435.   // Flush as long as we have callbacks.  This means we can finish a chain more
  436.   // quickly, since we avoid the overhead of multiple calls to setTimeout, each
  437.   // of which has a minimum resolution of as much as 15ms on IE11.
  438.   // This helps to fix the out-of-order task bug on IE:
  439.   //   https://github.com/google/shaka-player/issues/251#issuecomment-178146242
  440.   while (Promise.q_.length) {
  441.     // Callbacks may enqueue other callbacks, so clear the timer ID and swap the
  442.     // queue before we do anything else.
  443.     if (Promise.flushTimer_ != null) {
  444.       Promise.clearImmediate_(Promise.flushTimer_);
  445.       Promise.flushTimer_ = null;
  446.     }
  447.     var q = Promise.q_;
  448.     Promise.q_ = [];
  450.     for (var i = 0; i < q.length; ++i) {
  451.       q[i]();
  452.     }
  453.   }
  454. };
  457. /**
  458.  * @param {function()} callback
  459.  * @return {number}
  460.  * Schedule a callback as soon as possible.
  461.  * Bound in shaka.polyfill.Promise.install() to a specific implementation.
  462.  * @private
  463.  */
  464. shaka.polyfill.Promise.setImmediate_ = function(callback) { return 0; };
  467. /**
  468.  * @param {number} id
  469.  * Clear a scheduled callback.
  470.  * Bound in shaka.polyfill.Promise.install() to a specific implementation.
  471.  * @private
  472.  */
  473. shaka.polyfill.Promise.clearImmediate_ = function(id) {};
  476. /**
  477.  * A timer ID to flush the queue.
  478.  * @private {?number}
  479.  */
  480. shaka.polyfill.Promise.flushTimer_ = null;
  483. /**
  484.  * A queue of callbacks to be invoked ASAP in the next frame.
  485.  * @private {!Array.<function()>}
  486.  */
  487. shaka.polyfill.Promise.q_ = [];
  490. /** @private {?} */
  491. shaka.polyfill.Promise.nativePromise_ = window.Promise;
  494. shaka.polyfill.register(shaka.polyfill.Promise.install);