[js] Deprecate more stuff

Author: jleyba

javascript/node/selenium-webdriver/CHANGES.md

@@ -24,6 +24,8 @@
 * Added support for setting the username and password in basic auth pop-up
    dialogs (currently IE only).
 * Deprecated `WebElement#getInnerHtml()` and `WebEleemnt#getOuterHtml()`
+* Deprecated `Promise#thenCatch()` - use `Promise#catch()` instead
+* Deprecated `Promise#thenFinally()` - use `promise.thenFinally()` instead
 * FIXED: `io.findInPath()` will no longer match against directories that have
    the same basename as the target file.
 * FIXED: `phantomjs.Driver` now takes a third argument that defines the path to

javascript/node/selenium-webdriver/firefox/index.js

@@ -374,10 +374,13 @@ class Driver extends webdriver.WebDriver {
           });
 
       onQuit = function() {
-        return command.then(command => {
+        let finishCommand = command.then(command => {
           command.kill();
           return command.result();
-        }).thenFinally(() => preparedProfile.then(io.rmDir));
+        });
+        return promise.thenFinally(
+            finishCommand,
+            () => preparedProfile.then(io.rmDir));
       };
     }
 

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

@@ -918,6 +918,7 @@ class Thenable {
    *     expect a single argument: the rejection reason.
    * @return {!ManagedPromise<R>} A new promise which will be
    *     resolved wdith the result of the invoked callback.
+   * @deprecated Use {@link #catch()} instead.
    * @template R
    */
   thenCatch(errback) {}
@@ -956,6 +957,10 @@ class Thenable {
    *     to call when this promise is resolved.
    * @return {!ManagedPromise<R>} A promise that will be fulfilled
    *     with the callback result.
+   * @deprecated thenFinally has been deprecated to help make WebDriver's
+   *     managed promises API compatible with native promises. The functionality
+   *     provided by this method is now offered for any promise implementation
+   *     using the {@link thenFinally} function in the promise module.
    * @template R
    */
   thenFinally(callback) {}
@@ -1239,12 +1244,21 @@ class ManagedPromise {
         null, errback, 'catch', ManagedPromise.prototype.catch);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @deprecated Use {@link #catch()} instead.
+   */
   thenCatch(errback) {
     return this.catch(errback);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @deprecated thenFinally has been deprecated to help make WebDriver's
+   *     managed promises API compatible with native promises. The functionality
+   *     provided by this method is now offered for any promise implementation
+   *     using the {@link thenFinally} function in the promise module.
+   */
   thenFinally(callback) {
     var error;
     var mustThrow = false;
@@ -1438,6 +1452,70 @@ class Deferred {
 Thenable.addImplementation(Deferred);
 
 
+/**
+ * Registers a listener to invoke when a promise is resolved, regardless of
+ * whether the promise's value was successfully computed. This function is
+ * synonymous with the `finally` clause in a synchronous API:
+ *
+ *     // Synchronous API:
+ *     try {
+ *       doSynchronousWork();
+ *     } finally {
+ *       cleanUp();
+ *     }
+ *
+ *     // Asynchronous promise API:
+ *     promise.finally(doAsynchronousWork(), cleanUp);
+ *
+ * __Note:__ similar to the `finally` clause, if the registered callback returns
+ * a rejected promise or throws an error, that error will silently replace the
+ * rejection (if any) from the initial promise:
+ *
+ *     try {
+ *       throw Error('one');
+ *     } finally {
+ *       throw Error('two');  // Hides Error: one
+ *     }
+ *
+ *     let p = promise.rejected(Error('one'));
+ *     promise.finally(p, function() {
+ *       throw Error('two');  // Hides Error: one
+ *     });
+ *
+ * @param {PROMISE_TYPE} promise The thenable, promise-like object with which
+ *     to register the callback.
+ * @param {function(): *} callback The function to call when the promise is
+ *     resolved.
+ * @return {!PROMISE_TYPE} A new promise that is chained to the callback. This
+ *     promise will inherit the value of the original input if the callback
+ *     does not throw or return a rejected promise.
+ * @template PROMISE_TYPE
+ */
+function thenFinally(promise, callback) {
+  if (!isPromise(promise)) {
+    throw TypeError('first argument must be a promise-like object');
+  }
+
+  if (typeof callback !== 'function') {
+    throw TypeError('second argument must be a function');
+  }
+
+  let error;
+  let mustThrow = false;
+  return promise
+      .then(() => callback(), (e) => {
+        error = e;
+        mustThrow = true;
+        return callback();
+      })
+      .then(() => {
+        if (mustThrow) {
+          throw error;
+        }
+      });
+}
+
+
 /**
  * Tests if a value is an Error-like object. This is more than an straight
  * instanceof check since the value may originate from another context.
@@ -3091,6 +3169,7 @@ module.exports = {
   map: map,
   rejected: rejected,
   setDefaultFlow: setDefaultFlow,
+  thenFinally: thenFinally,
   when: when,
 
   get LONG_STACK_TRACES() { return LONG_STACK_TRACES; },

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

@@ -114,7 +114,7 @@ exports.ableToSwitchToFrame = function ableToSwitchToFrame(frame) {
  */
 exports.alertIsPresent = function alertIsPresent() {
   return new Condition('for alert to be present', function(driver) {
-    return driver.switchTo().alert().thenCatch(function(e) {
+    return driver.switchTo().alert().catch(function(e) {
       if (!(e instanceof error.NoSuchAlertError)) {
         throw e;
       }

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

@@ -373,13 +373,13 @@ class WebDriver {
     // actually executes the command. This addresses scenarios like catching
     // an element not found error in:
     //
-    //     driver.findElement(By.id('foo')).click().thenCatch(function(e) {
+    //     driver.findElement(By.id('foo')).click().catch(function(e) {
     //       if (e instanceof NoSuchElementError) {
     //         // Do something.
     //       }
     //     });
     var prepCommand = toWireValue(command.getParameters());
-    prepCommand.thenCatch(function() {});
+    prepCommand.catch(function() {});
 
     var flow = this.flow_;
     var executor = this.executor_;
@@ -447,7 +447,7 @@ class WebDriver {
         'WebDriver.quit()');
     // Delete our session ID when the quit command finishes; this will allow us to
     // throw an error when attemnpting to use a driver post-quit.
-    return result.thenFinally(() => delete this.session_);
+    return promise.thenFinally(result, () => delete this.session_);
   }
 
   /**
@@ -926,7 +926,7 @@ class WebDriver {
           setParameter('using', locator.using).
           setParameter('value', locator.value);
       let res = this.schedule(cmd, 'WebDriver.findElements(' + locator + ')');
-      return res.thenCatch(function(e) {
+      return res.catch(function(e) {
         if (e instanceof error.NoSuchElementError) {
           return [];
         }
@@ -1930,7 +1930,7 @@ class WebElement {
     }
 
     // Suppress unhandled rejection errors until the flow executes the command.
-    keys.thenCatch(function() {});
+    keys.catch(function() {});
 
     var element = this;
     return this.driver_.flow_.execute(function() {
@@ -2200,10 +2200,10 @@ class WebElementPromise extends WebElement {
     this.catch = el.catch.bind(el);
 
     /** @override */
-    this.thenCatch = el.thenCatch.bind(el);
+    this.thenCatch = el.catch.bind(el);
 
     /** @override */
-    this.thenFinally = el.thenFinally.bind(el);
+    this.thenFinally = (cb) => promise.thenFinally(el, cb);
 
     /**
      * Defers returning the element ID until the wrapped WebElement has been
@@ -2354,10 +2354,10 @@ class AlertPromise extends Alert {
     this.catch = alert.catch.bind(alert);
 
     /** @override */
-    this.thenCatch = alert.thenCatch.bind(alert);
+    this.thenCatch = alert.catch.bind(alert);
 
     /** @override */
-    this.thenFinally = alert.thenFinally.bind(alert);
+    this.thenFinally = (cb) => promise.thenFinally(alert, cb);
 
     /**
      * Defer returning text until the promised alert has been resolved.

javascript/node/selenium-webdriver/net/portprober.js

@@ -53,7 +53,7 @@ function findSystemPortRange() {
   }
   var range = process.platform === 'win32' ?
       findWindowsPortRange() : findUnixPortRange();
-  return systemRange = range.thenCatch(function() {
+  return systemRange = range.catch(function() {
     return DEFAULT_IANA_RANGE;
   });
 }
@@ -154,7 +154,7 @@ function findWindowsPortRange() {
 function isFree(port, opt_host) {
   var result = promise.defer();
 
-  result.promise.thenCatch(function(e) {
+  result.promise.catch(function(e) {
     if (e instanceof promise.CancellationError) {
       server.close();
     }

javascript/node/selenium-webdriver/remote/index.js

@@ -237,7 +237,7 @@ class DriverService {
         return new promise.Promise(function(fulfill, reject) {
           var ready = httpUtil.waitForServer(serverUrl, timeout)
               .then(fulfill, reject);
-          earlyTermination.thenCatch(function(e) {
+          earlyTermination.catch(function(e) {
             ready.cancel(/** @type {Error} */(e));
             reject(Error(e.message));
           });

javascript/node/selenium-webdriver/safari.js

@@ -414,7 +414,7 @@ class CommandExecutor {
       }));
     }
     var self = this;
-    return promise.all(tasks).thenFinally(function() {
+    return promise.thenFinally(promise.all(tasks), function() {
       self.server_ = null;
       self.socket_ = null;
       self.safari_ = null;

javascript/node/selenium-webdriver/test/execute_script_test.js

@@ -47,7 +47,7 @@ test.suite(function(env) {
     test.it('fails if script throws', function() {
       execute('throw new Error("boom")')
           .then(function() { throw shoudlHaveFailed; })
-          .thenCatch(function(e) {
+          .catch(function(e) {
             // The java WebDriver server adds a bunch of crap to error messages.
             // Error message will just be "JavaScript error" for IE.
             assert(e.message).matches(/.*(JavaScript error|boom).*/);
@@ -57,7 +57,7 @@ test.suite(function(env) {
     test.it('fails if script does not parse', function() {
       execute('throw function\\*')
           .then(function() { throw shoudlHaveFailed; })
-          .thenCatch(function(e) {
+          .catch(function(e) {
             assert(e).notEqualTo(shouldHaveFailed);
           });
     });
@@ -323,7 +323,7 @@ test.suite(function(env) {
       });
     });
   });
-  
+
   function verifyJson(expected) {
     return function(actual) {
       assert(JSON.stringify(actual)).equalTo(JSON.stringify(expected));

javascript/node/selenium-webdriver/test/lib/promise_error_test.js

@@ -362,29 +362,29 @@ describe('promise error handling', function() {
     it('start with normal promise', function() {
       var error = Error('an error');
       return promise.rejected(error).
-          thenCatch(function(e) {
+          catch(function(e) {
             assert.equal(e, error);
             throw new StubError;
           }).
-          thenCatch(assertIsStubError);
+          catch(assertIsStubError);
     });
 
     it('start with task result', function() {
       var error = Error('an error');
       return flow.execute(function() {
         throw error;
       }).
-      thenCatch(function(e) {
+      catch(function(e) {
         assert.equal(e, error);
         throw new StubError;
       }).
-      thenCatch(assertIsStubError);
+      catch(assertIsStubError);
     });
 
     it('start with normal promise; uncaught error', function() {
       var error = Error('an error');
       promise.rejected(error).
-          thenCatch(function(e) {
+          catch(function(e) {
             assert.equal(e, error);
             throw new StubError;
           });
@@ -396,7 +396,7 @@ describe('promise error handling', function() {
       flow.execute(function() {
         throw error;
       }).
-      thenCatch(function(e) {
+      catch(function(e) {
         assert.equal(e, error);
         throw new StubError;
       });
@@ -429,7 +429,7 @@ describe('promise error handling', function() {
 
     it('promise was rejected', function() {
       var toThrow = promise.rejected(new StubError);
-      toThrow.thenCatch(function() {});  // For tearDown.
+      toThrow.catch(function() {});  // For tearDown.
       flow.execute(function() {
         throw toThrow;
       }).then(assert.fail, function(e) {
@@ -756,7 +756,7 @@ describe('promise error handling', function() {
     }).then(function(error) {
       assert.ok(error instanceof promise.CancellationError);
       assert.ok(!task.isPending());
-      return task.thenCatch(function(error) {
+      return task.catch(function(error) {
         assert.ok(error instanceof promise.CancellationError);
       });
     });