src/third_party/closure_library/closure/goog/result/resultutil.js

// Copyright 2012 The Closure Library Authors. All Rights Reserved.
//
// 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.

/**
 * @fileoverview This file provides primitives and tools (wait, transform,
 *     chain, combine) that make it easier to work with Results. This section
 *     gives an overview of their functionality along with some examples and the
 *     actual definitions have detailed descriptions next to them.
 *
 *
 * NOTE: goog.result is soft deprecated - we expect to replace this and
 * goog.async.Deferred with a wrapper around W3C Promises:
 * http://dom.spec.whatwg.org/#promises.
 */

goog.provide('goog.result');

goog.require('goog.array');
goog.require('goog.result.DependentResult');
goog.require('goog.result.Result');
goog.require('goog.result.SimpleResult');


/**
 * Returns a successful result containing the provided value.
 *
 * Example:
 * <pre>
 *
 * var value = 'some-value';
 * var result = goog.result.immediateResult(value);
 * assertEquals(goog.result.Result.State.SUCCESS, result.getState());
 * assertEquals(value, result.getValue());
 *
 * </pre>
 *
 * @param {*} value The value of the result.
 * @return {!goog.result.Result} A Result object that has already been resolved
 *     to the supplied value.
 */
goog.result.successfulResult = function(value) {
  var result = new goog.result.SimpleResult();
  result.setValue(value);
  return result;
};


/**
 * Returns a failed result with the optional error slug set.
 *
 * Example:
 * <pre>
 *
 * var error = new Error('something-failed');
 * var result = goog.result.failedResult(error);
 * assertEquals(goog.result.Result.State.ERROR, result.getState());
 * assertEquals(error, result.getError());
 *
 * </pre>
 *
 * @param {*=} opt_error The error to which the result should resolve.
 * @return {!goog.result.Result} A Result object that has already been resolved
 *     to the supplied Error.
 */
goog.result.failedResult = function(opt_error) {
  var result = new goog.result.SimpleResult();
  result.setError(opt_error);
  return result;
};


/**
 * Returns a canceled result.
 * The result will be resolved to an error of type CancelError.
 *
 * Example:
 * <pre>
 *
 * var result = goog.result.canceledResult();
 * assertEquals(goog.result.Result.State.ERROR, result.getState());
 * var error = result.getError();
 * assertTrue(error instanceof goog.result.Result.CancelError);
 *
 * </pre>
 *
 * @return {!goog.result.Result} A canceled Result.
 */
goog.result.canceledResult = function() {
  var result = new goog.result.SimpleResult();
  result.cancel();
  return result;
};


/**
 * Calls the handler on resolution of the result (success or failure).
 * The handler is passed the result object as the only parameter. The call will
 * be immediate if the result is no longer pending.
 *
 * Example:
 * <pre>
 *
 * var result = xhr.get('testdata/xhr_test_text.data');
 *
 * // Wait for the result to be resolved and alert it's state.
 * goog.result.wait(result, function(result) {
 *   alert('State: ' + result.getState());
 * });
 * </pre>
 *
 * @param {!goog.result.Result} result The result to install the handlers.
 * @param {function(this:T, !goog.result.Result)} handler The handler to be
 *     called. The handler is passed the result object as the only parameter.
 * @param {T=} opt_scope Optional scope for the handler.
 * @template T
 */
goog.result.wait = function(result, handler, opt_scope) {
  result.wait(handler, opt_scope);
};


/**
 * Calls the handler if the result succeeds. The result object is the only
 * parameter passed to the handler. The call will be immediate if the result
 * has already succeeded.
 *
 * Example:
 * <pre>
 *
 * var result = xhr.get('testdata/xhr_test_text.data');
 *
 * // attach a success handler.
 * goog.result.waitOnSuccess(result, function(resultValue, result) {
 *   var datavalue = result.getvalue();
 *   alert('value: ' + datavalue + ' == ' + resultValue);
 * });
 * </pre>
 *
 * @param {!goog.result.Result} result The result to install the handlers.
 * @param {function(this:T, ?, !goog.result.Result)} handler The handler to be
 *     called. The handler is passed the result value and the result as
 *     parameters.
 * @param {T=} opt_scope Optional scope for the handler.
 * @template T
 */
goog.result.waitOnSuccess = function(result, handler, opt_scope) {
  goog.result.wait(result, function(res) {
    if (res.getState() == goog.result.Result.State.SUCCESS) {
      // 'this' refers to opt_scope
      handler.call(this, res.getValue(), res);
    }
  }, opt_scope);
};


/**
 * Calls the handler if the result action errors. The result object is passed as
 * the only parameter to the handler. The call will be immediate if the result
 * object has already resolved to an error.
 *
 * Example:
 *
 * <pre>
 *
 * var result = xhr.get('testdata/xhr_test_text.data');
 *
 * // Attach a failure handler.
 * goog.result.waitOnError(result, function(error) {
 *  // Failed asynchronous call!
 * });
 * </pre>
 *
 * @param {!goog.result.Result} result The result to install the handlers.
 * @param {function(this:T, ?, !goog.result.Result)} handler The handler to be
 *     called. The handler is passed the error and the result object as
 *     parameters.
 * @param {T=} opt_scope Optional scope for the handler.
 * @template T
 */
goog.result.waitOnError = function(result, handler, opt_scope) {
  goog.result.wait(result, function(res) {
    if (res.getState() == goog.result.Result.State.ERROR) {
      // 'this' refers to opt_scope
      handler.call(this, res.getError(), res);
    }
  }, opt_scope);
};


/**
 * Given a result and a transform function, returns a new result whose value,
 * on success, will be the value of the given result after having been passed
 * through the transform function.
 *
 * If the given result is an error, the returned result is also an error and the
 * transform will not be called.
 *
 * Example:
 * <pre>
 *
 * var result = xhr.getJson('testdata/xhr_test_json.data');
 *
 * // Transform contents of returned data using 'processJson' and create a
 * // transformed result to use returned JSON.
 * var transformedResult = goog.result.transform(result, processJson);
 *
 * // Attach success and failure handlers to the tranformed result.
 * goog.result.waitOnSuccess(transformedResult, function(resultValue, result) {
 *   var jsonData = resultValue;
 *   assertEquals('ok', jsonData['stat']);
 * });
 *
 * goog.result.waitOnError(transformedResult, function(error) {
 *   // Failed getJson call
 * });
 * </pre>
 *
 * @param {!goog.result.Result} result The result whose value will be
 *     transformed.
 * @param {function(?):?} transformer The transformer
 *     function. The return value of this function will become the value of the
 *     returned result.
 *
 * @return {!goog.result.DependentResult} A new Result whose eventual value will
 *     be the returned value of the transformer function.
 */
goog.result.transform = function(result, transformer) {
  var returnedResult = new goog.result.DependentResultImpl_([result]);

  goog.result.wait(result, function(res) {
    if (res.getState() == goog.result.Result.State.SUCCESS) {
      returnedResult.setValue(transformer(res.getValue()));
    } else {
      returnedResult.setError(res.getError());
    }
  });

  return returnedResult;
};


/**
 * The chain function aids in chaining of asynchronous Results. This provides a
 * convenience for use cases where asynchronous operations must happen serially
 * i.e. subsequent asynchronous operations are dependent on data returned by
 * prior asynchronous operations.
 *
 * It accepts a result and an action callback as arguments and returns a
 * result. The action callback is called when the first result succeeds and is
 * supposed to return a second result. The returned result is resolved when one
 * of both of the results resolve (depending on their success or failure.) The
 * state and value of the returned result in the various cases is documented
 * below:
 * <pre>
 *
 * First Result State:    Second Result State:    Returned Result State:
 * SUCCESS                SUCCESS                 SUCCESS
 * SUCCESS                ERROR                   ERROR
 * ERROR                  Not created             ERROR
 * </pre>
 *
 * The value of the returned result, in the case both results succeed, is the
 * value of the second result (the result returned by the action callback.)
 *
 * Example:
 * <pre>
 *
 * var testDataResult = xhr.get('testdata/xhr_test_text.data');
 *
 * // Chain this result to perform another asynchronous operation when this
 * // Result is resolved.
 * var chainedResult = goog.result.chain(testDataResult,
 *     function(testDataResult) {
 *
 *       // The result value of testDataResult is the URL for JSON data.
 *       var jsonDataUrl = testDataResult.getValue();
 *
 *       // Create a new Result object when the original result is resolved.
 *       var jsonResult = xhr.getJson(jsonDataUrl);
 *
 *       // Return the newly created Result.
 *       return jsonResult;
 *     });
 *
 * // The chained result resolves to success when both results resolve to
 * // success.
 * goog.result.waitOnSuccess(chainedResult, function(resultValue, result) {
 *
 *   // At this point, both results have succeeded and we can use the JSON
 *   // data returned by the second asynchronous call.
 *   var jsonData = resultValue;
 *   assertEquals('ok', jsonData['stat']);
 * });
 *
 * // Attach the error handler to be called when either Result fails.
 * goog.result.waitOnError(chainedResult, function(result) {
 *   alert('chained result failed!');
 * });
 * </pre>
 *
 * @param {!goog.result.Result} result The result to chain.
 * @param {function(this:T, !goog.result.Result):!goog.result.Result}
 *     actionCallback The callback called when the result is resolved. This
 *     callback must return a Result.
 * @param {T=} opt_scope Optional scope for the action callback.
 * @return {!goog.result.DependentResult} A result that is resolved when both
 *     the given Result and the Result returned by the actionCallback have
 *     resolved.
 * @template T
 */
goog.result.chain = function(result, actionCallback, opt_scope) {
  var dependentResult = new goog.result.DependentResultImpl_([result]);

  // Wait for the first action.
  goog.result.wait(result, function(result) {
    if (result.getState() == goog.result.Result.State.SUCCESS) {

      // The first action succeeded. Chain the contingent action.
      var contingentResult = actionCallback.call(opt_scope, result);
      dependentResult.addParentResult(contingentResult);
      goog.result.wait(contingentResult, function(contingentResult) {

        // The contingent action completed. Set the dependent result based on
        // the contingent action's outcome.
        if (contingentResult.getState() ==
            goog.result.Result.State.SUCCESS) {
          dependentResult.setValue(contingentResult.getValue());
        } else {
          dependentResult.setError(contingentResult.getError());
        }
      });
    } else {
      // First action failed, the dependent result should also fail.
      dependentResult.setError(result.getError());
    }
  });

  return dependentResult;
};


/**
 * Returns a result that waits on all given results to resolve. Once all have
 * resolved, the returned result will succeed (and never error).
 *
 * Example:
 * <pre>
 *
 * var result1 = xhr.get('testdata/xhr_test_text.data');
 *
 * // Get a second independent Result.
 * var result2 = xhr.getJson('testdata/xhr_test_json.data');
 *
 * // Create a Result that resolves when both prior results resolve.
 * var combinedResult = goog.result.combine(result1, result2);
 *
 * // Process data after resolution of both results.
 * goog.result.waitOnSuccess(combinedResult, function(results) {
 *   goog.array.forEach(results, function(result) {
 *       alert(result.getState());
 *   });
 * });
 * </pre>
 *
 * @param {...!goog.result.Result} var_args The results to wait on.
 *
 * @return {!goog.result.DependentResult} A new Result whose eventual value will
 *     be the resolved given Result objects.
 */
goog.result.combine = function(var_args) {
  /** @type {!Array<!goog.result.Result>} */
  var results = goog.array.clone(arguments);
  var combinedResult = new goog.result.DependentResultImpl_(results);

  var isResolved = function(res) {
    return res.getState() != goog.result.Result.State.PENDING;
  };

  var checkResults = function() {
    if (combinedResult.getState() == goog.result.Result.State.PENDING &&
        goog.array.every(results, isResolved)) {
      combinedResult.setValue(results);
    }
  };

  goog.array.forEach(results, function(result) {
    goog.result.wait(result, checkResults);
  });

  return combinedResult;
};


/**
 * Returns a result that waits on all given results to resolve. Once all have
 * resolved, the returned result will succeed if and only if all given results
 * succeeded. Otherwise it will error.
 *
 * Example:
 * <pre>
 *
 * var result1 = xhr.get('testdata/xhr_test_text.data');
 *
 * // Get a second independent Result.
 * var result2 = xhr.getJson('testdata/xhr_test_json.data');
 *
 * // Create a Result that resolves when both prior results resolve.
 * var combinedResult = goog.result.combineOnSuccess(result1, result2);
 *
 * // Process data after successful resolution of both results.
 * goog.result.waitOnSuccess(combinedResult, function(results) {
 *   var textData = results[0].getValue();
 *   var jsonData = results[1].getValue();
 *   assertEquals('Just some data.', textData);
 *   assertEquals('ok', jsonData['stat']);
 * });
 *
 * // Handle errors when either or both results failed.
 * goog.result.waitOnError(combinedResult, function(combined) {
 *   var results = combined.getError();
 *
 *   if (results[0].getState() == goog.result.Result.State.ERROR) {
 *     alert('result1 failed');
 *   }
 *
 *   if (results[1].getState() == goog.result.Result.State.ERROR) {
 *     alert('result2 failed');
 *   }
 * });
 * </pre>
 *
 * @param {...!goog.result.Result} var_args The results to wait on.
 *
 * @return {!goog.result.DependentResult} A new Result whose eventual value will
 *     be an array of values of the given Result objects.
 */
goog.result.combineOnSuccess = function(var_args) {
  var results = goog.array.clone(arguments);
  var combinedResult = new goog.result.DependentResultImpl_(results);

  var resolvedSuccessfully = function(res) {
    return res.getState() == goog.result.Result.State.SUCCESS;
  };

  goog.result.wait(
      goog.result.combine.apply(goog.result.combine, results),
      // The combined result never ERRORs
      function(res) {
        var results = /** @type {Array<!goog.result.Result>} */ (
            res.getValue());
        if (goog.array.every(results, resolvedSuccessfully)) {
          combinedResult.setValue(results);
        } else {
          combinedResult.setError(results);
        }
      });

  return combinedResult;
};


/**
 * Given a DependentResult, cancels the Results it depends on (that is, the
 * results returned by getParentResults). This function does not recurse,
 * so e.g. parents of parents are not canceled; only the immediate parents of
 * the given Result are canceled.
 *
 * Example using @see goog.result.combine:
 * <pre>
 * var result1 = xhr.get('testdata/xhr_test_text.data');
 *
 * // Get a second independent Result.
 * var result2 = xhr.getJson('testdata/xhr_test_json.data');
 *
 * // Create a Result that resolves when both prior results resolve.
 * var combinedResult = goog.result.combineOnSuccess(result1, result2);
 *
 * combinedResult.wait(function() {
 *   if (combinedResult.isCanceled()) {
 *     goog.result.cancelParentResults(combinedResult);
 *   }
 * });
 *
 * // Now, canceling combinedResult will cancel both result1 and result2.
 * combinedResult.cancel();
 * </pre>
 * @param {!goog.result.DependentResult} dependentResult A Result that is
 *     dependent on the values of other Results (for example the Result of a
 *     goog.result.combine, goog.result.chain, or goog.result.transform call).
 * @return {boolean} True if any results were successfully canceled; otherwise
 *     false.
 * TODO(user): Implement a recursive version of this that cancels all
 * ancestor results.
 */
goog.result.cancelParentResults = function(dependentResult) {
  var anyCanceled = false;
  var results = dependentResult.getParentResults();
  for (var n = 0; n < results.length; n++) {
    anyCanceled |= results[n].cancel();
  }
  return !!anyCanceled;
};



/**
 * A DependentResult represents a Result whose eventual value depends on the
 * value of one or more other Results. For example, the Result returned by
 * @see goog.result.chain or @see goog.result.combine is dependent on the
 * Results given as arguments.
 *
 * @param {!Array<!goog.result.Result>} parentResults A list of Results that
 *     will affect the eventual value of this Result.
 * @constructor
 * @implements {goog.result.DependentResult}
 * @extends {goog.result.SimpleResult}
 * @private
 */
goog.result.DependentResultImpl_ = function(parentResults) {
  goog.result.DependentResultImpl_.base(this, 'constructor');
  /**
   * A list of Results that will affect the eventual value of this Result.
   * @type {!Array<!goog.result.Result>}
   * @private
   */
  this.parentResults_ = parentResults;
};
goog.inherits(goog.result.DependentResultImpl_, goog.result.SimpleResult);


/**
 * Adds a Result to the list of Results that affect this one.
 * @param {!goog.result.Result} parentResult A result whose value affects the
 *     value of this Result.
 */
goog.result.DependentResultImpl_.prototype.addParentResult = function(
    parentResult) {
  this.parentResults_.push(parentResult);
};


/** @override */
goog.result.DependentResultImpl_.prototype.getParentResults = function() {
  return this.parentResults_;
};