tor-browser

event-emitter.js (11184B)

---

/* 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.";

const eventListeners = Symbol("EventEmitter/listeners");
const onceResolvers = Symbol("EventEmitter/once-resolvers");
loader.lazyRequireGetter(this, "flags", "resource://devtools/shared/flags.js");

class EventEmitter {
 /**
  * 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);
 }

 /**
  * Registers an event `listener` that is called every time events of
  * specified `type` is emitted on this instance.
  *
  * @param {string} type
  *    The type of event.
  * @param {Function} 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.
  */
 on(type, listener, { signal } = {}) {
   if (typeof listener !== "function") {
     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 this)) {
     this[eventListeners] = new Map();
   }

   const events = this[eventListeners];

   if (events.has(type)) {
     events.get(type).add(listener);
   } else {
     events.set(type, new Set([listener]));
   }

   const offFn = () => this.off(type, listener);

   if (signal) {
     signal.addEventListener("abort", offFn, { once: true });
   }

   return offFn;
 }

 /**
  * Removes an event `listener` for the given event `type` on this instance
  * If no `listener` is passed removes all listeners of the given
  * `type`. If `type` is not passed removes all the listeners of this instance.
  *
  * @param {string} [type]
  *    The type of event.
  * @param {Function} [listener]
  *    The listener that processes the event.
  */
 off(type, listener) {
   const length = arguments.length;
   const events = this[eventListeners];

   if (!events) {
     return;
   }

   if (length >= 2) {
     // Trying to remove from `this` 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);
       delete listener[onceResolvers];
     }
   } else if (length === 1) {
     // 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 === 0) {
     // With no parameter passed, we're removing all the listeners from this.
     events.clear();
   }
 }

 clearEvents() {
   const events = this[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 this instance.
  * It returns a Promise resolved once the specified event `type` is emitted.
  *
  * @param {string} type
  *    The type of the event.
  * @param {Function} [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.
  */
 once(type, listener = function () {}, options) {
   const { promise, resolve } = Promise.withResolvers();
   if (!listener[onceResolvers]) {
     listener[onceResolvers] = [];
   }
   listener[onceResolvers].push(resolve);
   this.on(type, listener, options);
   return promise;
 }

 emit(type, ...rest) {
   this._emit(type, false, rest);
 }

 emitAsync(type, ...rest) {
   return this._emit(type, true, rest);
 }

 emitForTests(type, ...rest) {
   if (flags.testing) {
     this.emit(type, ...rest);
   }
 }

 /**
  * Emit an event of a given `type` on this instance.
  *
  * @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;
  */
 _emit(type, async, args) {
   if (loggingEnabled) {
     logEvent(type, args);
   }

   const targetEventListeners = this[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 this)) {
       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 {
         // If this was a one-off listener (add via `EventEmitter#once`), unregister the
         // listener right away, before firing the listener, to prevent re-entry in case
         // the listener fires the same event again.
         const resolvers = listener[onceResolvers];
         if (resolvers) {
           this.off(type, listener);
         }
         const promise = listener.apply(this, args);
         // Resolve the promise returned by `EventEmitter#once` only after having called
         // the listener.
         if (resolvers) {
           for (const resolver of resolvers) {
             // Resolve with the first argument fired on the listened event
             // (`EventEmitter#once` listeners don't have access to all the other arguments).
             resolver(args[0]);
           }
         }
         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 this instance.
  *
  * @param {string} type
  *    The type of event.
  * @return {number}
  *    The number of event listeners.
  */
 count(type) {
   if (eventListeners in this) {
     const listenersForType = this[eventListeners].get(type);

     if (listenersForType) {
       return listenersForType.size;
     }
   }

   return 0;
 }
}

module.exports = EventEmitter;

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`);
 }
}