[js] Changed promise.{fulfilled, rejected, defer} to all use native p…

…romises

when the promise manager is disabled.

Deprecated promise.when()

For #2969

javascript/node/selenium-webdriver/CHANGES.md

@@ -1,6 +1,11 @@
 ## v.next
 
 * The `lib` package is once again platform agnostic (excluding `lib/devmode`).
+* Deprecated `promise.when(value, callback, errback)`.
+ Use `promise.fulfilled(value).then(callback, errback)`
+* Changed `promise.fulfilled(value)`, `promise.rejected(reason)` and
+ `promise.defer()` to all use native promises when the promise manager is
+ disabled.
 
 ## v3.0.1
 

javascript/node/selenium-webdriver/lib/promise.js

@@ -1383,6 +1383,37 @@ function isPending(promise) {
 }
 
 
+/**
+ * Structural interface for a deferred promise resolver.
+ * @record
+ * @template T
+ */
+function Resolver() {}
+
+
+/**
+ * The promised value for this resolver.
+ * @type {!Thenable<T>}
+ */
+Resolver.prototype.promise;
+
+
+/**
+ * Resolves the promised value with the given `value`.
+ * @param {T|Thenable<T>} value
+ * @return {void}
+ */
+Resolver.prototype.resolve;
+
+
+/**
+ * Rejects the promised value with the given `reason`.
+ * @param {*} reason
+ * @return {void}
+ */
+Resolver.prototype.reject;
+
+
 /**
  * Represents a value that will be resolved at some point in the future. This
  * class represents the protected "producer" half of a ManagedPromise - each Deferred
@@ -1395,6 +1426,7 @@ function isPending(promise) {
  * {@link ControlFlow} as an unhandled failure.
  *
  * @template T
+ * @implements {Resolver<T>}
  */
 class Deferred {
  /**
@@ -1421,16 +1453,24 @@ class Deferred {
  * Resolves this deferred with the given value. It is safe to call this as a
  * normal function (with no bound "this").
  * @param {(T|IThenable<T>|Thenable)=} opt_value The fulfilled value.
+ * @const
  */
- this.fulfill = function(opt_value) {
+ this.resolve = function(opt_value) {
  checkNotSelf(opt_value);
  fulfill(opt_value);
  };
 
+ /**
+ * An alias for {@link #resolve}.
+ * @const
+ */
+ this.fulfill = this.resolve;
+
  /**
  * Rejects this promise with the given reason. It is safe to call this as a
  * normal function (with no bound "this").
  * @param {*=} opt_reason The rejection reason.
+ * @const
  */
  this.reject = function(opt_reason) {
  checkNotSelf(opt_reason);
@@ -1487,36 +1527,63 @@ function delayed(ms) {
 
 
 /**
- * Creates a new deferred object.
- * @return {!Deferred<T>} The new deferred object.
+ * Creates a new deferred resolver.
+ *
+ * If the promise manager is currently enabled, this function will return a
+ * {@link Deferred} instance. Otherwise, it will return a resolver for a
+ * {@linkplain NativePromise native promise}.
+ *
+ * @return {!Resolver<T>} A new deferred resolver.
  * @template T
  */
 function defer() {
- return new Deferred();
+ if (usePromiseManager()) {
+ return new Deferred();
+ }
+ let resolve, reject;
+ let promise = new NativePromise((_resolve, _reject) => {
+ resolve = _resolve;
+ reject = _reject;
+ });
+ return {promise, resolve, reject};
 }
 
 
 /**
  * Creates a promise that has been resolved with the given value.
+ *
+ * If the promise manager is currently enabled, this function will return a
+ * {@linkplain ManagedPromise managed promise}. Otherwise, it will return a
+ * {@linkplain NativePromise native promise}.
+ *
  * @param {T=} opt_value The resolved value.
- * @return {!ManagedPromise<T>} The resolved promise.
- * @deprecated Use {@link ManagedPromise#resolve Promise.resolve(value)}.
+ * @return {!Thenable<T>} The resolved promise.
  * @template T
  */
 function fulfilled(opt_value) {
- return ManagedPromise.resolve(opt_value);
+ if (usePromiseManager()) {
+ return ManagedPromise.resolve(opt_value);
+ }
+ return NativePromise.resolve(opt_value);
 }
 
 
 /**
  * Creates a promise that has been rejected with the given reason.
+ *
+ * If the promise manager is currently enabled, this function will return a
+ * {@linkplain ManagedPromise managed promise}. Otherwise, it will return a
+ * {@linkplain NativePromise native promise}.
+ *
  * @param {*=} opt_reason The rejection reason; may be any value, but is
  * usually an Error or a string.
- * @return {!ManagedPromise<?>} The rejected promise.
- * @deprecated Use {@link ManagedPromise#reject Promise.reject(reason)}.
+ * @return {!Thenable<?>} The rejected promise.
  */
 function rejected(opt_reason) {
- return ManagedPromise.reject(opt_reason);
+ if (usePromiseManager()) {
+ return ManagedPromise.reject(opt_reason);
+ }
+ return NativePromise.reject(opt_reason);
 }
 
 
@@ -1610,21 +1677,17 @@ function thenFinally(promise, callback) {
  * @param {Function=} opt_errback The function to call when the value is
  * rejected.
  * @return {!Thenable} A new promise.
+ * @deprecated Use `promise.fulfilled(value).then(opt_callback, opt_errback)`
  */
 function when(value, opt_callback, opt_errback) {
- if (Thenable.isImplementation(value)) {
- return value.then(opt_callback, opt_errback);
- }
-
- return createPromise(resolve => resolve(value))
- .then(opt_callback, opt_errback);
+ return fulfilled(value).then(opt_callback, opt_errback);
 }
 
 
 /**
  * Invokes the appropriate callback function as soon as a promised `value` is
- * resolved. This function is similar to `when()`, except it does not return
- * a new promise.
+ * resolved.
+ *
  * @param {*} value The value to observe.
  * @param {Function} callback The function to call when the value is
  * resolved successfully.
@@ -1826,7 +1889,7 @@ function filter(arr, fn, opt_self) {
  */
 function fullyResolved(value) {
  if (isPromise(value)) {
- return when(value, fullyResolveValue);
+ return fulfilled(value).then(fullyResolveValue);
  }
  return fullyResolveValue(value);
 }
@@ -2934,7 +2997,7 @@ class TaskQueue extends events.EventEmitter {
 
  this.subQ_.once('end', () => { // On task completion.
  this.subQ_ = null;
- this.pending_ && this.pending_.task.fulfill(result);
+ this.pending_ && this.pending_.task.resolve(result);
  });
 
  this.subQ_.once('error', e => { // On task failure.
@@ -3245,6 +3308,7 @@ module.exports = {
  MultipleUnhandledRejectionError: MultipleUnhandledRejectionError,
  Thenable: Thenable,
  Promise: ManagedPromise,
+ Resolver: Resolver,
  Scheduler: Scheduler,
  all: all,
  asap: asap,