|
| 1 | +/** |
| 2 | + * Copyright (c) 2015, Facebook, Inc. All rights reserved. |
| 3 | + * |
| 4 | + * Facebook, Inc. ("Facebook") owns all right, title and interest, including |
| 5 | + * all intellectual property and other proprietary rights, in and to the React |
| 6 | + * Native CustomComponents software (the "Software"). Subject to your |
| 7 | + * compliance with these terms, you are hereby granted a non-exclusive, |
| 8 | + * worldwide, royalty-free copyright license to (1) use and copy the Software; |
| 9 | + * and (2) reproduce and distribute the Software as part of your own software |
| 10 | + * ("Your Software"). Facebook reserves all rights not expressly granted to |
| 11 | + * you in this license agreement. |
| 12 | + * |
| 13 | + * THE SOFTWARE AND DOCUMENTATION, IF ANY, ARE PROVIDED "AS IS" AND ANY EXPRESS |
| 14 | + * OR IMPLIED WARRANTIES (INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| 15 | + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE) ARE DISCLAIMED. |
| 16 | + * IN NO EVENT SHALL FACEBOOK OR ITS AFFILIATES, OFFICERS, DIRECTORS OR |
| 17 | + * EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| 18 | + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 19 | + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; |
| 20 | + * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, |
| 21 | + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR |
| 22 | + * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE SOFTWARE, EVEN IF |
| 23 | + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 24 | + * |
| 25 | + * @noflow |
| 26 | + * @typecheck |
| 27 | + */ |
| 28 | +'use strict'; |
| 29 | + |
| 30 | +const EmitterSubscription = require('./EmitterSubscription'); |
| 31 | +const EventSubscriptionVendor = require('./EventSubscriptionVendor'); |
| 32 | + |
| 33 | +const emptyFunction = require('fbjs/lib/emptyFunction'); |
| 34 | +const invariant = require('fbjs/lib/invariant'); |
| 35 | + |
| 36 | +/** |
| 37 | + * @class EventEmitter |
| 38 | + * @description |
| 39 | + * An EventEmitter is responsible for managing a set of listeners and publishing |
| 40 | + * events to them when it is told that such events happened. In addition to the |
| 41 | + * data for the given event it also sends a event control object which allows |
| 42 | + * the listeners/handlers to prevent the default behavior of the given event. |
| 43 | + * |
| 44 | + * The emitter is designed to be generic enough to support all the different |
| 45 | + * contexts in which one might want to emit events. It is a simple multicast |
| 46 | + * mechanism on top of which extra functionality can be composed. For example, a |
| 47 | + * more advanced emitter may use an EventHolder and EventFactory. |
| 48 | + */ |
| 49 | +class EventEmitter { |
| 50 | + |
| 51 | + _subscriber: EventSubscriptionVendor; |
| 52 | + _currentSubscription: ?EmitterSubscription; |
| 53 | + |
| 54 | + /** |
| 55 | + * @constructor |
| 56 | + * |
| 57 | + * @param {EventSubscriptionVendor} subscriber - Optional subscriber instance |
| 58 | + * to use. If omitted, a new subscriber will be created for the emitter. |
| 59 | + */ |
| 60 | + constructor(subscriber: ?EventSubscriptionVendor) { |
| 61 | + this._subscriber = subscriber || new EventSubscriptionVendor(); |
| 62 | + } |
| 63 | + |
| 64 | + /** |
| 65 | + * Adds a listener to be invoked when events of the specified type are |
| 66 | + * emitted. An optional calling context may be provided. The data arguments |
| 67 | + * emitted will be passed to the listener function. |
| 68 | + * |
| 69 | + * TODO: Annotate the listener arg's type. This is tricky because listeners |
| 70 | + * can be invoked with varargs. |
| 71 | + * |
| 72 | + * @param {string} eventType - Name of the event to listen to |
| 73 | + * @param {function} listener - Function to invoke when the specified event is |
| 74 | + * emitted |
| 75 | + * @param {*} context - Optional context object to use when invoking the |
| 76 | + * listener |
| 77 | + */ |
| 78 | + addListener( |
| 79 | + eventType: string, listener: Function, context: ?Object): EmitterSubscription { |
| 80 | + |
| 81 | + return (this._subscriber.addSubscription( |
| 82 | + eventType, |
| 83 | + new EmitterSubscription(this, this._subscriber, listener, context) |
| 84 | + ) : any); |
| 85 | + } |
| 86 | + |
| 87 | + /** |
| 88 | + * Similar to addListener, except that the listener is removed after it is |
| 89 | + * invoked once. |
| 90 | + * |
| 91 | + * @param {string} eventType - Name of the event to listen to |
| 92 | + * @param {function} listener - Function to invoke only once when the |
| 93 | + * specified event is emitted |
| 94 | + * @param {*} context - Optional context object to use when invoking the |
| 95 | + * listener |
| 96 | + */ |
| 97 | + once(eventType: string, listener: Function, context: ?Object): EmitterSubscription { |
| 98 | + return this.addListener(eventType, (...args) => { |
| 99 | + this.removeCurrentListener(); |
| 100 | + listener.apply(context, args); |
| 101 | + }); |
| 102 | + } |
| 103 | + |
| 104 | + /** |
| 105 | + * Removes all of the registered listeners, including those registered as |
| 106 | + * listener maps. |
| 107 | + * |
| 108 | + * @param {?string} eventType - Optional name of the event whose registered |
| 109 | + * listeners to remove |
| 110 | + */ |
| 111 | + removeAllListeners(eventType: ?string) { |
| 112 | + this._subscriber.removeAllSubscriptions(eventType); |
| 113 | + } |
| 114 | + |
| 115 | + /** |
| 116 | + * Provides an API that can be called during an eventing cycle to remove the |
| 117 | + * last listener that was invoked. This allows a developer to provide an event |
| 118 | + * object that can remove the listener (or listener map) during the |
| 119 | + * invocation. |
| 120 | + * |
| 121 | + * If it is called when not inside of an emitting cycle it will throw. |
| 122 | + * |
| 123 | + * @throws {Error} When called not during an eventing cycle |
| 124 | + * |
| 125 | + * @example |
| 126 | + * var subscription = emitter.addListenerMap({ |
| 127 | + * someEvent: function(data, event) { |
| 128 | + * console.log(data); |
| 129 | + * emitter.removeCurrentListener(); |
| 130 | + * } |
| 131 | + * }); |
| 132 | + * |
| 133 | + * emitter.emit('someEvent', 'abc'); // logs 'abc' |
| 134 | + * emitter.emit('someEvent', 'def'); // does not log anything |
| 135 | + */ |
| 136 | + removeCurrentListener() { |
| 137 | + invariant( |
| 138 | + !!this._currentSubscription, |
| 139 | + 'Not in an emitting cycle; there is no current subscription' |
| 140 | + ); |
| 141 | + this.removeSubscription(this._currentSubscription); |
| 142 | + } |
| 143 | + |
| 144 | + /** |
| 145 | + * Removes a specific subscription. Called by the `remove()` method of the |
| 146 | + * subscription itself to ensure any necessary cleanup is performed. |
| 147 | + */ |
| 148 | + removeSubscription(subscription: EmitterSubscription) { |
| 149 | + invariant( |
| 150 | + subscription.emitter === this, |
| 151 | + 'Subscription does not belong to this emitter.' |
| 152 | + ); |
| 153 | + this._subscriber.removeSubscription(subscription); |
| 154 | + } |
| 155 | + |
| 156 | + /** |
| 157 | + * Returns an array of listeners that are currently registered for the given |
| 158 | + * event. |
| 159 | + * |
| 160 | + * @param {string} eventType - Name of the event to query |
| 161 | + * @returns {array} |
| 162 | + */ |
| 163 | + listeners(eventType: string): [EmitterSubscription] { |
| 164 | + const subscriptions: ?[EmitterSubscription] = (this._subscriber.getSubscriptionsForType(eventType): any); |
| 165 | + return subscriptions |
| 166 | + ? subscriptions.filter(emptyFunction.thatReturnsTrue).map( |
| 167 | + function(subscription) { |
| 168 | + return subscription.listener; |
| 169 | + }) |
| 170 | + : []; |
| 171 | + } |
| 172 | + |
| 173 | + /** |
| 174 | + * Emits an event of the given type with the given data. All handlers of that |
| 175 | + * particular type will be notified. |
| 176 | + * |
| 177 | + * @param {string} eventType - Name of the event to emit |
| 178 | + * @param {...*} Arbitrary arguments to be passed to each registered listener |
| 179 | + * |
| 180 | + * @example |
| 181 | + * emitter.addListener('someEvent', function(message) { |
| 182 | + * console.log(message); |
| 183 | + * }); |
| 184 | + * |
| 185 | + * emitter.emit('someEvent', 'abc'); // logs 'abc' |
| 186 | + */ |
| 187 | + emit(eventType: string) { |
| 188 | + const subscriptions: ?[EmitterSubscription] = (this._subscriber.getSubscriptionsForType(eventType): any); |
| 189 | + if (subscriptions) { |
| 190 | + for (let i = 0, l = subscriptions.length; i < l; i++) { |
| 191 | + const subscription = subscriptions[i]; |
| 192 | + |
| 193 | + // The subscription may have been removed during this event loop. |
| 194 | + if (subscription) { |
| 195 | + this._currentSubscription = subscription; |
| 196 | + subscription.listener.apply( |
| 197 | + subscription.context, |
| 198 | + Array.prototype.slice.call(arguments, 1) |
| 199 | + ); |
| 200 | + } |
| 201 | + } |
| 202 | + this._currentSubscription = null; |
| 203 | + } |
| 204 | + } |
| 205 | + |
| 206 | + /** |
| 207 | + * Removes the given listener for event of specific type. |
| 208 | + * |
| 209 | + * @param {string} eventType - Name of the event to emit |
| 210 | + * @param {function} listener - Function to invoke when the specified event is |
| 211 | + * emitted |
| 212 | + * |
| 213 | + * @example |
| 214 | + * emitter.removeListener('someEvent', function(message) { |
| 215 | + * console.log(message); |
| 216 | + * }); // removes the listener if already registered |
| 217 | + * |
| 218 | + */ |
| 219 | + removeListener(eventType: String, listener) { |
| 220 | + const subscriptions: ?[EmitterSubscription] = (this._subscriber.getSubscriptionsForType(eventType): any); |
| 221 | + if (subscriptions) { |
| 222 | + for (let i = 0, l = subscriptions.length; i < l; i++) { |
| 223 | + const subscription = subscriptions[i]; |
| 224 | + |
| 225 | + // The subscription may have been removed during this event loop. |
| 226 | + // its listener matches the listener in method parameters |
| 227 | + if (subscription && subscription.listener === listener) { |
| 228 | + subscription.remove(); |
| 229 | + } |
| 230 | + } |
| 231 | + } |
| 232 | + } |
| 233 | +} |
| 234 | + |
| 235 | +module.exports = EventEmitter; |
0 commit comments