1
// Copyright 2013 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
goog.provide('goog.Thenable');
16

17
/** @suppress {extraRequire} */
18
goog.forwardDeclare('goog.Promise'); // for the type reference.
19

20

21

22
/**
23
 * Provides a more strict interface for Thenables in terms of
24
 * http://promisesaplus.com for interop with {@see goog.Promise}.
25
 *
26
 * @interface
27
 * @extends {IThenable<TYPE>}
28
 * @template TYPE
29
 */
30
goog.Thenable = function() {};
31

32

33
/**
34
 * Adds callbacks that will operate on the result of the Thenable, returning a
35
 * new child Promise.
36
 *
37
 * If the Thenable is fulfilled, the {@code onFulfilled} callback will be
38
 * invoked with the fulfillment value as argument, and the child Promise will
39
 * be fulfilled with the return value of the callback. If the callback throws
40
 * an exception, the child Promise will be rejected with the thrown value
41
 * instead.
42
 *
43
 * If the Thenable is rejected, the {@code onRejected} callback will be invoked
44
 * with the rejection reason as argument, and the child Promise will be rejected
45
 * with the return value of the callback or thrown value.
46
 *
47
 * @param {?(function(this:THIS, TYPE): VALUE)=} opt_onFulfilled A
48
 *     function that will be invoked with the fulfillment value if the Promise
49
 *     is fulfilled.
50
 * @param {?(function(this:THIS, *): *)=} opt_onRejected A function that will
51
 *     be invoked with the rejection reason if the Promise is rejected.
52
 * @param {THIS=} opt_context An optional context object that will be the
53
 *     execution context for the callbacks. By default, functions are executed
54
 *     with the default this.
55
 *
56
 * @return {RESULT} A new Promise that will receive the result
57
 *     of the fulfillment or rejection callback.
58
 * @template VALUE
59
 * @template THIS
60
 *
61
 * When a Promise (or thenable) is returned from the fulfilled callback,
62
 * the result is the payload of that promise, not the promise itself.
63
 *
64
 * @template RESULT := type('goog.Promise',
65
 *     cond(isUnknown(VALUE), unknown(),
66
 *       mapunion(VALUE, (V) =>
67
 *         cond(isTemplatized(V) && sub(rawTypeOf(V), 'IThenable'),
68
 *           templateTypeOf(V, 0),
69
 *           cond(sub(V, 'Thenable'),
70
 *              unknown(),
71
 *              V)))))
72
 *  =:
73
 *
74
 */
75
goog.Thenable.prototype.then = function(
76
    opt_onFulfilled, opt_onRejected, opt_context) {};
77

78

79
/**
80
 * An expando property to indicate that an object implements
81
 * {@code goog.Thenable}.
82
 *
83
 * {@see addImplementation}.
84
 *
85
 * @const
86
 */
87
goog.Thenable.IMPLEMENTED_BY_PROP = '$goog_Thenable';
88

89

90
/**
91
 * Marks a given class (constructor) as an implementation of Thenable, so
92
 * that we can query that fact at runtime. The class must have already
93
 * implemented the interface.
94
 * Exports a 'then' method on the constructor prototype, so that the objects
95
 * also implement the extern {@see goog.Thenable} interface for interop with
96
 * other Promise implementations.
97
 * @param {function(new:goog.Thenable,...?)} ctor The class constructor. The
98
 *     corresponding class must have already implemented the interface.
99
 */
100
goog.Thenable.addImplementation = function(ctor) {
101
  // Use bracket notation instead of goog.exportSymbol() so that the compiler
102
  // won't create a 'var ctor;' extern when the "create externs from exports"
103
  // mode is enabled.
104
  ctor.prototype['then'] = ctor.prototype.then;
105
  if (COMPILED) {
106
    ctor.prototype[goog.Thenable.IMPLEMENTED_BY_PROP] = true;
107
  } else {
108
    // Avoids dictionary access in uncompiled mode.
109
    ctor.prototype.$goog_Thenable = true;
110
  }
111
};
112

113

114
/**
115
 * @param {?} object
116
 * @return {boolean} Whether a given instance implements {@code goog.Thenable}.
117
 *     The class/superclass of the instance must call {@code addImplementation}.
118
 */
119
goog.Thenable.isImplementedBy = function(object) {
120
  if (!object) {
121
    return false;
122
  }
123
  try {
124
    if (COMPILED) {
125
      return !!object[goog.Thenable.IMPLEMENTED_BY_PROP];
126
    }
127
    return !!object.$goog_Thenable;
128
  } catch (e) {
129
    // Property access seems to be forbidden.
130
    return false;
131
  }
132
};
133

134