diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 17:32:43 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 17:32:43 +0000 |
commit | 6bf0a5cb5034a7e684dcc3500e841785237ce2dd (patch) | |
tree | a68f146d7fa01f0134297619fbe7e33db084e0aa /devtools/shared/event-emitter.js | |
parent | Initial commit. (diff) | |
download | thunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.tar.xz thunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.zip |
Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | devtools/shared/event-emitter.js | 470 |
1 files changed, 470 insertions, 0 deletions
diff --git a/devtools/shared/event-emitter.js b/devtools/shared/event-emitter.js new file mode 100644 index 0000000000..2ba4ae927b --- /dev/null +++ b/devtools/shared/event-emitter.js @@ -0,0 +1,470 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +"use strict"; + +const BAD_LISTENER = + "The event listener must be a function, or an object that has " + + "`EventEmitter.handler` Symbol."; + +const eventListeners = Symbol("EventEmitter/listeners"); +const onceOriginalListener = Symbol("EventEmitter/once-original-listener"); +const handler = Symbol("EventEmitter/event-handler"); +loader.lazyRequireGetter(this, "flags", "resource://devtools/shared/flags.js"); + +class EventEmitter { + /** + * Registers an event `listener` that is called every time events of + * specified `type` is emitted on the given event `target`. + * + * @param {Object} target + * Event target object. + * @param {String} type + * The type of event. + * @param {Function|Object} listener + * The listener that processes the event. + * @param {Object} options + * @param {AbortSignal} options.signal + * The listener will be removed when linked AbortController’s abort() method is called + * @returns {Function} + * A function that removes the listener when called. + */ + static on(target, type, listener, { signal } = {}) { + if (typeof listener !== "function" && !isEventHandler(listener)) { + throw new Error(BAD_LISTENER); + } + + if (signal?.aborted === true) { + // The signal is already aborted so don't setup the listener. + // We return an empty function as it's the expected returned value. + return () => {}; + } + + if (!(eventListeners in target)) { + target[eventListeners] = new Map(); + } + + const events = target[eventListeners]; + + if (events.has(type)) { + events.get(type).add(listener); + } else { + events.set(type, new Set([listener])); + } + + const offFn = () => EventEmitter.off(target, type, listener); + + if (signal) { + signal.addEventListener("abort", offFn, { once: true }); + } + + return offFn; + } + + /** + * Removes an event `listener` for the given event `type` on the given event + * `target`. If no `listener` is passed removes all listeners of the given + * `type`. If `type` is not passed removes all the listeners of the given + * event `target`. + * @param {Object} target + * The event target object. + * @param {String} [type] + * The type of event. + * @param {Function|Object} [listener] + * The listener that processes the event. + */ + static off(target, type, listener) { + const length = arguments.length; + const events = target[eventListeners]; + + if (!events) { + return; + } + + if (length >= 3) { + // Trying to remove from the `target` the `listener` specified for the + // event's `type` given. + const listenersForType = events.get(type); + + // If we don't have listeners for the event's type, we bail out. + if (!listenersForType) { + return; + } + + // If the listeners list contains the listener given, we just remove it. + if (listenersForType.has(listener)) { + listenersForType.delete(listener); + } else { + // If it's not present, there is still the possibility that the listener + // have been added using `once`, since the method wraps the original listener + // in another function. + // So we iterate all the listeners to check if any of them is a wrapper to + // the `listener` given. + for (const value of listenersForType.values()) { + if ( + onceOriginalListener in value && + value[onceOriginalListener] === listener + ) { + listenersForType.delete(value); + break; + } + } + } + } else if (length === 2) { + // No listener was given, it means we're removing all the listeners from + // the given event's `type`. + if (events.has(type)) { + events.delete(type); + } + } else if (length === 1) { + // With only the `target` given, we're removing all the listeners from the object. + events.clear(); + } + } + + static clearEvents(target) { + const events = target[eventListeners]; + if (!events) { + return; + } + events.clear(); + } + + /** + * Registers an event `listener` that is called only the next time an event + * of the specified `type` is emitted on the given event `target`. + * It returns a Promise resolved once the specified event `type` is emitted. + * + * @param {Object} target + * Event target object. + * @param {String} type + * The type of the event. + * @param {Function|Object} [listener] + * The listener that processes the event. + * @param {Object} options + * @param {AbortSignal} options.signal + * The listener will be removed when linked AbortController’s abort() method is called + * @return {Promise} + * The promise resolved once the event `type` is emitted. + */ + static once(target, type, listener, options) { + return new Promise(resolve => { + // This is the actual listener that will be added to the target's listener, it wraps + // the call to the original `listener` given. + const newListener = (first, ...rest) => { + // To prevent side effects we're removing the listener upfront. + EventEmitter.off(target, type, newListener); + + let rv; + if (listener) { + if (isEventHandler(listener)) { + // if the `listener` given is actually an object that handles the events + // using `EventEmitter.handler`, we want to call that function, passing also + // the event's type as first argument, and the `listener` (the object) as + // contextual object. + rv = listener[handler](type, first, ...rest); + } else { + // Otherwise we'll just call it + rv = listener.call(target, first, ...rest); + } + } + + // We resolve the promise once the listener is called. + resolve(first); + + // Listeners may return a promise, so pass it along + return rv; + }; + + newListener[onceOriginalListener] = listener; + EventEmitter.on(target, type, newListener, options); + }); + } + + static emit(target, type, ...rest) { + EventEmitter._emit(target, type, false, rest); + } + + static emitAsync(target, type, ...rest) { + return EventEmitter._emit(target, type, true, rest); + } + + /** + * Emit an event of a given `type` on a given `target` object. + * + * @param {Object} target + * Event target object. + * @param {String} type + * The type of the event. + * @param {Boolean} async + * If true, this function will wait for each listener completion. + * Each listener has to return a promise, which will be awaited for. + * @param {Array} args + * The arguments to pass to each listener function. + * @return {Promise|undefined} + * If `async` argument is true, returns the promise resolved once all listeners have resolved. + * Otherwise, this function returns undefined; + */ + static _emit(target, type, async, args) { + if (loggingEnabled) { + logEvent(type, args); + } + + const targetEventListeners = target[eventListeners]; + if (!targetEventListeners) { + return undefined; + } + + const listeners = targetEventListeners.get(type); + if (!listeners?.size) { + return undefined; + } + + const promises = async ? [] : null; + + // Creating a temporary Set with the original listeners, to avoiding side effects + // in emit. + for (const listener of new Set(listeners)) { + // If the object was destroyed during event emission, stop emitting. + if (!(eventListeners in target)) { + break; + } + + // If listeners were removed during emission, make sure the + // event handler we're going to fire wasn't removed. + if (listeners && listeners.has(listener)) { + try { + let promise; + if (isEventHandler(listener)) { + promise = listener[handler](type, ...args); + } else { + promise = listener.apply(target, args); + } + if (async) { + // Assert the name instead of `constructor != Promise` in order + // to avoid cross compartment issues where Promise can be multiple. + if (!promise || promise.constructor.name != "Promise") { + console.warn( + `Listener for event '${type}' did not return a promise.` + ); + } else { + promises.push(promise); + } + } + } catch (ex) { + // Prevent a bad listener from interfering with the others. + console.error(ex); + const msg = ex + ": " + ex.stack; + dump(msg + "\n"); + } + } + } + + if (async) { + return Promise.all(promises); + } + + return undefined; + } + + /** + * Returns a number of event listeners registered for the given event `type` + * on the given event `target`. + * + * @param {Object} target + * Event target object. + * @param {String} type + * The type of event. + * @return {Number} + * The number of event listeners. + */ + static count(target, type) { + if (eventListeners in target) { + const listenersForType = target[eventListeners].get(type); + + if (listenersForType) { + return listenersForType.size; + } + } + + return 0; + } + + /** + * Decorate an object with event emitter functionality; basically using the + * class' prototype as mixin. + * + * @param Object target + * The object to decorate. + * @return Object + * The object given, mixed. + */ + static decorate(target) { + const descriptors = Object.getOwnPropertyDescriptors(this.prototype); + delete descriptors.constructor; + return Object.defineProperties(target, descriptors); + } + + static get handler() { + return handler; + } + + on(...args) { + return EventEmitter.on(this, ...args); + } + + off(...args) { + EventEmitter.off(this, ...args); + } + + clearEvents() { + EventEmitter.clearEvents(this); + } + + once(...args) { + return EventEmitter.once(this, ...args); + } + + emit(...args) { + EventEmitter.emit(this, ...args); + } + + emitAsync(...args) { + return EventEmitter.emitAsync(this, ...args); + } + + emitForTests(...args) { + if (flags.testing) { + EventEmitter.emit(this, ...args); + } + } + + count(...args) { + return EventEmitter.count(this, ...args); + } +} + +module.exports = EventEmitter; + +const isEventHandler = listener => + listener && handler in listener && typeof listener[handler] === "function"; + +const { + getNthPathExcluding, +} = require("resource://devtools/shared/platform/stack.js"); +let loggingEnabled = false; + +if (!isWorker) { + loggingEnabled = Services.prefs.getBoolPref("devtools.dump.emit", false); + const observer = { + observe: () => { + loggingEnabled = Services.prefs.getBoolPref("devtools.dump.emit"); + }, + }; + Services.prefs.addObserver("devtools.dump.emit", observer); + + // Also listen for Loader unload to unregister the pref observer and + // prevent leaking + const unloadObserver = function (subject) { + if (subject.wrappedJSObject == require("@loader/unload")) { + Services.prefs.removeObserver("devtools.dump.emit", observer); + Services.obs.removeObserver(unloadObserver, "devtools:loader:destroy"); + } + }; + Services.obs.addObserver(unloadObserver, "devtools:loader:destroy"); +} + +function serialize(target) { + const MAXLEN = 60; + + // Undefined + if (typeof target === "undefined") { + return "undefined"; + } + + if (target === null) { + return "null"; + } + + // Number / String + if (typeof target === "string" || typeof target === "number") { + return truncate(target, MAXLEN); + } + + // HTML Node + if (target.nodeName) { + let out = target.nodeName; + + if (target.id) { + out += "#" + target.id; + } + if (target.className) { + out += "." + target.className; + } + + return out; + } + + // Array + if (Array.isArray(target)) { + return truncate(target.toSource(), MAXLEN); + } + + // Function + if (typeof target === "function") { + return `function ${target.name ? target.name : "anonymous"}()`; + } + + // Window + if (target?.constructor?.name === "Window") { + return `window (${target.location.origin})`; + } + + // Object + if (typeof target === "object") { + let out = "{"; + + const entries = Object.entries(target); + for (let i = 0; i < Math.min(10, entries.length); i++) { + const [name, value] = entries[i]; + + if (i > 0) { + out += ", "; + } + + out += `${name}: ${truncate(value, MAXLEN)}`; + } + + return out + "}"; + } + + // Other + return truncate(target.toSource(), MAXLEN); +} + +function truncate(value, maxLen) { + // We don't use value.toString() because it can throw. + const str = String(value); + return str.length > maxLen ? str.substring(0, maxLen) + "..." : str; +} + +function logEvent(type, args) { + let argsOut = ""; + + // We need this try / catch to prevent any dead object errors. + try { + argsOut = `${args.map(serialize).join(", ")}`; + } catch (e) { + // Object is dead so the toolbox is most likely shutting down, + // do nothing. + } + + const path = getNthPathExcluding(0, "devtools/shared/event-emitter.js"); + + if (args.length) { + dump(`EMITTING: emit(${type}, ${argsOut}) from ${path}\n`); + } else { + dump(`EMITTING: emit(${type}) from ${path}\n`); + } +} |