/**
* @license
* Copyright 2016 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
goog.provide('shaka.polyfill.Promise');
goog.require('goog.asserts');
goog.require('shaka.log');
goog.require('shaka.polyfill.register');
/**
* @summary A polyfill to implement Promises, primarily for IE.
* Only partially supports thenables, but otherwise passes the A+ conformance
* tests.
* Note that Promise.all() and Promise.race() are not tested by that suite.
*
* @constructor
* @struct
* @param {function(function(*=), function(*=))=} opt_callback
* @template T
*/
shaka.polyfill.Promise = function(opt_callback) {
/** @private {!Array.<shaka.polyfill.Promise.Child>} */
this.thens_ = [];
/** @private {!Array.<shaka.polyfill.Promise.Child>} */
this.catches_ = [];
/** @private {shaka.polyfill.Promise.State} */
this.state_ = shaka.polyfill.Promise.State.PENDING;
/** @private {*} */
this.value_;
// External callers must supply the callback. Internally, we may construct
// child Promises without it, since we can directly access their resolve_ and
// reject_ methods when convenient.
if (opt_callback) {
try {
opt_callback(this.resolve_.bind(this), this.reject_.bind(this));
} catch (e) {
this.reject_(e);
}
}
};
/**
* @typedef {{
* promise: !shaka.polyfill.Promise,
* callback: (function(*)|undefined)
* }}
*
* @summary A child promise, used for chaining.
* @description
* Only exists in the context of a then or catch chain.
* @property {!shaka.polyfill.Promise} promise
* The child promise.
* @property {(function(*)|undefined)} callback
* The then or catch callback to be invoked as part of this chain.
*/
shaka.polyfill.Promise.Child;
/**
* @enum {number}
*/
shaka.polyfill.Promise.State = {
PENDING: 0,
RESOLVED: 1,
REJECTED: 2
};
/**
* Install the polyfill if needed.
* @param {boolean=} opt_force If true, force the polyfill to be installed.
* Used in some unit tests.
*/
shaka.polyfill.Promise.install = function(opt_force) {
// Decide on the best way to invoke a callback as soon as possible.
// Precompute the setImmediate/clearImmediate convenience methods to avoid the
// overhead of this switch every time a callback has to be invoked.
if (window.setImmediate) {
// For IE and node.js:
shaka.polyfill.Promise.setImmediate_ = function(callback) {
return window.setImmediate(callback);
};
shaka.polyfill.Promise.clearImmediate_ = function(id) {
return window.clearImmediate(id);
};
} else {
// For everyone else:
shaka.polyfill.Promise.setImmediate_ = function(callback) {
return window.setTimeout(callback, 0);
};
shaka.polyfill.Promise.clearImmediate_ = function(id) {
return window.clearTimeout(id);
};
}
if (window.Promise && !opt_force) {
shaka.log.info('Using native Promises.');
return;
}
shaka.log.info('Using Promises polyfill.');
// Quoted to work around type-checking, since our then() signature doesn't
// exactly match that of a native Promise.
window['Promise'] = shaka.polyfill.Promise;
// Explicitly installed because the compiler won't necessarily attach them
// to the compiled constructor. Exporting them will only attach them to
// their original namespace, which isn't the same as attaching them to the
// constructor unless you also export the constructor.
window['Promise'].resolve = shaka.polyfill.Promise.resolve;
window['Promise'].reject = shaka.polyfill.Promise.reject;
window['Promise'].all = shaka.polyfill.Promise.all;
window['Promise'].race = shaka.polyfill.Promise.race;
// These are manually exported as well, because allowing the compiler to
// export them for us will cause the polyfill to end up in our generated
// externs. Since nobody should be accessing this directly using the
// shaka.polyfill namespace, it is okay not to @export these methods.
window['Promise']['prototype']['then'] =
shaka.polyfill.Promise.prototype.then;
window['Promise']['prototype']['catch'] =
shaka.polyfill.Promise.prototype.catch;
};
/**
* Uninstall the polyfill. Used in some unit tests.
*/
shaka.polyfill.Promise.uninstall = function() {
// Do nothing if there is no native implementation.
if (shaka.polyfill.Promise.nativePromise_) {
shaka.log.info('Removing Promise polyfill.');
window['Promise'] = shaka.polyfill.Promise.nativePromise_;
shaka.polyfill.Promise.q_ = [];
}
};
/**
* @param {*=} opt_value
* @return {!shaka.polyfill.Promise}
*/
shaka.polyfill.Promise.resolve = function(opt_value) {
var p = new shaka.polyfill.Promise();
p.resolve_(undefined);
return p.then(function() {
return opt_value;
});
};
/**
* @param {*=} opt_reason
* @return {!shaka.polyfill.Promise}
*/
shaka.polyfill.Promise.reject = function(opt_reason) {
var p = new shaka.polyfill.Promise();
p.reject_(opt_reason);
return p;
};
/**
* @param {!Array.<!shaka.polyfill.Promise>} others
* @return {!shaka.polyfill.Promise}
*/
shaka.polyfill.Promise.all = function(others) {
var p = new shaka.polyfill.Promise();
if (!others.length) {
p.resolve_([]);
return p;
}
// The array of results must be in the same order as the array of Promises
// passed to all(). So we pre-allocate the array and keep a count of how
// many have resolved. Only when all have resolved is the returned Promise
// itself resolved.
var count = 0;
var values = new Array(others.length);
var resolve = function(p, i, newValue) {
goog.asserts.assert(p.state_ != shaka.polyfill.Promise.State.RESOLVED,
'Invalid Promise state in Promise.all');
// If one of the Promises in the array was rejected, this Promise was
// rejected and new values are ignored. In such a case, the values array
// and its contents continue to be alive in memory until all of the Promises
// in the array have completed.
if (p.state_ == shaka.polyfill.Promise.State.PENDING) {
values[i] = newValue;
count++;
if (count == values.length) {
p.resolve_(values);
}
}
};
var reject = p.reject_.bind(p);
for (var i = 0; i < others.length; ++i) {
if (others[i] && others[i].then) {
others[i].then(resolve.bind(null, p, i), reject);
} else {
resolve(p, i, others[i]);
}
}
return p;
};
/**
* @param {!Array.<!shaka.polyfill.Promise>} others
* @return {!shaka.polyfill.Promise}
*/
shaka.polyfill.Promise.race = function(others) {
var p = new shaka.polyfill.Promise();
// The returned Promise is resolved or rejected as soon as one of the others
// is.
var resolve = p.resolve_.bind(p);
var reject = p.reject_.bind(p);
for (var i = 0; i < others.length; ++i) {
if (others[i] && others[i].then) {
others[i].then(resolve, reject);
} else {
resolve(others[i]);
}
}
return p;
};
/**
* @param {function(*)=} opt_successCallback
* @param {function(*)=} opt_failCallback
* @return {!shaka.polyfill.Promise}
*/
shaka.polyfill.Promise.prototype.then = function(opt_successCallback,
opt_failCallback) {
// then() returns a child Promise which is chained onto this one.
var child = new shaka.polyfill.Promise();
switch (this.state_) {
case shaka.polyfill.Promise.State.RESOLVED:
// This is already resolved, so we can chain to the child ASAP.
this.schedule_(child, opt_successCallback);
break;
case shaka.polyfill.Promise.State.REJECTED:
// This is already rejected, so we can chain to the child ASAP.
this.schedule_(child, opt_failCallback);
break;
case shaka.polyfill.Promise.State.PENDING:
// This is pending, so we have to track both callbacks and the child
// in order to chain later.
this.thens_.push({ promise: child, callback: opt_successCallback});
this.catches_.push({ promise: child, callback: opt_failCallback});
break;
}
return child;
};
/**
* @param {function(*)=} opt_callback
* @return {!shaka.polyfill.Promise}
*/
shaka.polyfill.Promise.prototype.catch = function(opt_callback) {
// Devolves into a two-argument call to 'then'.
return this.then(undefined, opt_callback);
};
/**
* @param {*=} opt_value
* @private
*/
shaka.polyfill.Promise.prototype.resolve_ = function(opt_value) {
// Ignore resolve calls if we aren't still pending.
if (this.state_ == shaka.polyfill.Promise.State.PENDING) {
this.value_ = opt_value;
this.state_ = shaka.polyfill.Promise.State.RESOLVED;
// Schedule calls to all of the chained callbacks.
for (var i = 0; i < this.thens_.length; ++i) {
this.schedule_(this.thens_[i].promise, this.thens_[i].callback);
}
this.thens_ = [];
this.catches_ = [];
}
};
/**
* @param {*=} opt_reason
* @private
*/
shaka.polyfill.Promise.prototype.reject_ = function(opt_reason) {
// Ignore reject calls if we aren't still pending.
if (this.state_ == shaka.polyfill.Promise.State.PENDING) {
this.value_ = opt_reason;
this.state_ = shaka.polyfill.Promise.State.REJECTED;
// Schedule calls to all of the chained callbacks.
for (var i = 0; i < this.catches_.length; ++i) {
this.schedule_(this.catches_[i].promise, this.catches_[i].callback);
}
this.thens_ = [];
this.catches_ = [];
}
};
/**
* @param {!shaka.polyfill.Promise} child
* @param {function(*)|undefined} callback
* @private
*/
shaka.polyfill.Promise.prototype.schedule_ = function(child, callback) {
goog.asserts.assert(this.state_ != shaka.polyfill.Promise.State.PENDING,
'Invalid Promise state in Promise.schedule_');
var Promise = shaka.polyfill.Promise;
var wrapper = function() {
if (callback && typeof callback == 'function') {
// Wrap around the callback. Exceptions thrown by the callback are
// converted to failures.
try {
var value = callback(this.value_);
} catch (exception) {
child.reject_(exception);
return;
}
// According to the spec, 'then' in a thenable may only be accessed once
// and any thrown exceptions in the getter must cause the Promise chain
// to fail.
var then;
try {
then = value && value.then;
} catch (exception) {
child.reject_(exception);
return;
}
if (value instanceof Promise) {
// If the returned value is a Promise, we bind it's state to the child.
if (value == child) {
// Without this, a bad calling pattern can cause an infinite loop.
child.reject_(new TypeError('Chaining cycle detected'));
} else {
value.then(child.resolve_.bind(child), child.reject_.bind(child));
}
} else if (then) {
// If the returned value is thenable, chain it to the child.
Promise.handleThenable_(value, then, child);
} else {
// If the returned value is not a Promise, the child is resolved with
// that value.
child.resolve_(value);
}
} else if (this.state_ == Promise.State.RESOLVED) {
// No callback for this state, so just chain on down the line.
child.resolve_(this.value_);
} else {
// No callback for this state, so just chain on down the line.
child.reject_(this.value_);
}
};
// Enqueue a call to the wrapper.
Promise.q_.push(wrapper.bind(this));
if (Promise.flushTimer_ == null) {
Promise.flushTimer_ = Promise.setImmediate_(Promise.flush);
}
};
/**
* @param {!Object} thenable
* @param {Function} then
* @param {!shaka.polyfill.Promise} child
* @private
*/
shaka.polyfill.Promise.handleThenable_ = function(thenable, then, child) {
var Promise = shaka.polyfill.Promise;
try {
var sealed = false;
then.call(thenable, function(value) {
if (sealed) return;
sealed = true;
var nextThen;
try {
nextThen = value && value.then;
} catch (exception) {
child.reject_(exception);
return;
}
if (nextThen) {
Promise.handleThenable_(value, nextThen, child);
} else {
child.resolve_(value);
}
}, child.reject_.bind(child));
} catch (exception) {
child.reject_(exception);
}
};
/**
* Flush the queue of callbacks.
* Used directly by some unit tests.
*/
shaka.polyfill.Promise.flush = function() {
var Promise = shaka.polyfill.Promise;
// Flush as long as we have callbacks. This means we can finish a chain more
// quickly, since we avoid the overhead of multiple calls to setTimeout, each
// of which has a minimum resolution of as much as 15ms on IE11.
// This helps to fix the out-of-order task bug on IE:
// https://github.com/google/shaka-player/issues/251#issuecomment-178146242
while (Promise.q_.length) {
// Callbacks may enqueue other callbacks, so clear the timer ID and swap the
// queue before we do anything else.
if (Promise.flushTimer_ != null) {
Promise.clearImmediate_(Promise.flushTimer_);
Promise.flushTimer_ = null;
}
var q = Promise.q_;
Promise.q_ = [];
for (var i = 0; i < q.length; ++i) {
q[i]();
}
}
};
/**
* @param {function()} callback
* @return {number}
* Schedule a callback as soon as possible.
* Bound in shaka.polyfill.Promise.install() to a specific implementation.
* @private
*/
shaka.polyfill.Promise.setImmediate_ = function(callback) { return 0; };
/**
* @param {number} id
* Clear a scheduled callback.
* Bound in shaka.polyfill.Promise.install() to a specific implementation.
* @private
*/
shaka.polyfill.Promise.clearImmediate_ = function(id) {};
/**
* A timer ID to flush the queue.
* @private {?number}
*/
shaka.polyfill.Promise.flushTimer_ = null;
/**
* A queue of callbacks to be invoked ASAP in the next frame.
* @private {!Array.<function()>}
*/
shaka.polyfill.Promise.q_ = [];
/** @private {?} */
shaka.polyfill.Promise.nativePromise_ = window.Promise;
shaka.polyfill.register(shaka.polyfill.Promise.install);