Debian Codegraph @

closure-library/closure/goog/promise/thenable.js

raw
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 };