1
// Copyright 2015 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Utilities for working with promises.
17
 * Note that this file is written ES5-only.
18
 */
19

20
goog.module('goog.labs.promise');
21

22
var Promise = goog.require('goog.Promise');
23

24

25
/**
26
 * Executes an ES6 generator function that may yield Promises, blocking after
27
 * each Promise until it settles.  Within the generator, the value of each
28
 * 'yield' expression becomes the resolved value of the yielded promise.
29
 *
30
 * If the generator function throws an exception or yields a rejected promise,
31
 * execution stops, and the promise returned by this function is rejected.
32
 *
33
 * A typical call uses generator function syntax:
34
 *
35
 *   goog.labs.promise.run(function*() {
36
 *     console.log('about to start waiting');
37
 *     while (needsToWait()) {
38
 *       // Wait 10 seconds.
39
 *       yield goog.Timer.promise(10000);
40
 *       console.log('still waiting...');
41
 *     }
42
 *   }).then(() => {
43
 *     console.log('done waiting');
44
 *   });
45
 *
46
 * This function can also be used to simplify asynchronous code:
47
 *
48
 *   goog.labs.promise.run(function*()) {
49
 *     var x = yield somethingThatReturnsAPromise();
50
 *     var y = yield somethingElseThatReturnsAPromise();
51
 *     return x + y;
52
 *   }).then(sum => {
53
 *     console.log('The sum is:', sum);
54
 *   });
55
 *
56
 * @param {function(this: CONTEXT):TYPE} generatorFunc A function which is
57
 *     called immediately and returns a generator.
58
 * @param {CONTEXT=} opt_context The context in which generatorFunc should be
59
 *     called.
60
 * @return {!goog.Promise<TYPE>} A promise that is resolved when the generator
61
 *     returned from generatorFunc is exhausted, or rejected if an error occurs.
62
 *     If the generator function returns, this promise resolves to the returned
63
 *     value.
64
 * @template CONTEXT, TYPE
65
 */
66
exports.run = function(generatorFunc, opt_context) {
67
  var generator = generatorFunc.call(opt_context);
68
  /**
69
   * @param {*} previousResolvedValue
70
   * @param {boolean=} opt_isRejected
71
   */
72
  function loop(previousResolvedValue, opt_isRejected) {
73
    var gen = opt_isRejected ? generator['throw'](previousResolvedValue) :
74
                               generator.next(previousResolvedValue);
75
    if (!gen.done) {
76
      // Wrap gen.value in a promise in case it isn't a promise already.
77
      return Promise.resolve(gen.value).then(
78
          function(resolvedValue) { return loop(resolvedValue); },
79
          function(rejectValue) { return loop(rejectValue, true); });
80
    }
81
    return gen.value;
82
  }
83
  // Call loop() from then() to ensure exceptions are captured.
84
  return Promise.resolve().then(loop);
85
};
86

87