tor-browser

EventEmitter.ts (5383B)

---

/**
* @license
* Copyright 2022 Google Inc.
* SPDX-License-Identifier: Apache-2.0
*/

import mitt, {type Emitter} from '../../third_party/mitt/mitt.js';
import {disposeSymbol} from '../util/disposable.js';

/**
* @public
*/
export type EventType = string | symbol;

/**
* @public
*/
export type Handler<T = unknown> = (event: T) => void;

/**
* @public
*/
export interface CommonEventEmitter<Events extends Record<EventType, unknown>> {
 on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): this;
 off<Key extends keyof Events>(
   type: Key,
   handler?: Handler<Events[Key]>,
 ): this;
 emit<Key extends keyof Events>(type: Key, event: Events[Key]): boolean;
 once<Key extends keyof Events>(
   type: Key,
   handler: Handler<Events[Key]>,
 ): this;
 listenerCount(event: keyof Events): number;

 removeAllListeners(event?: keyof Events): this;
}

/**
* @public
*/
export type EventsWithWildcard<Events extends Record<EventType, unknown>> =
 Events & {
   '*': Events[keyof Events];
 };

/**
* The EventEmitter class that many Puppeteer classes extend.
*
* @remarks
*
* This allows you to listen to events that Puppeteer classes fire and act
* accordingly. Therefore you'll mostly use {@link EventEmitter.on | on} and
* {@link EventEmitter.off | off} to bind
* and unbind to event listeners.
*
* @public
*/
export class EventEmitter<Events extends Record<EventType, unknown>>
 implements CommonEventEmitter<EventsWithWildcard<Events>>
{
 #emitter: Emitter<EventsWithWildcard<Events>> | EventEmitter<Events>;
 #handlers = new Map<keyof Events | '*', Array<Handler<any>>>();

 /**
  * If you pass an emitter, the returned emitter will wrap the passed emitter.
  *
  * @internal
  */
 constructor(
   emitter: Emitter<EventsWithWildcard<Events>> | EventEmitter<Events> = mitt(
     new Map(),
   ),
 ) {
   this.#emitter = emitter;
 }

 /**
  * Bind an event listener to fire when an event occurs.
  * @param type - the event type you'd like to listen to. Can be a string or symbol.
  * @param handler - the function to be called when the event occurs.
  * @returns `this` to enable you to chain method calls.
  */
 on<Key extends keyof EventsWithWildcard<Events>>(
   type: Key,
   handler: Handler<EventsWithWildcard<Events>[Key]>,
 ): this {
   const handlers = this.#handlers.get(type);
   if (handlers === undefined) {
     this.#handlers.set(type, [handler]);
   } else {
     handlers.push(handler);
   }

   this.#emitter.on(type, handler);
   return this;
 }

 /**
  * Remove an event listener from firing.
  * @param type - the event type you'd like to stop listening to.
  * @param handler - the function that should be removed.
  * @returns `this` to enable you to chain method calls.
  */
 off<Key extends keyof EventsWithWildcard<Events>>(
   type: Key,
   handler?: Handler<EventsWithWildcard<Events>[Key]>,
 ): this {
   const handlers = this.#handlers.get(type) ?? [];
   if (handler === undefined) {
     for (const handler of handlers) {
       this.#emitter.off(type, handler);
     }
     this.#handlers.delete(type);
     return this;
   }
   const index = handlers.lastIndexOf(handler);
   if (index > -1) {
     this.#emitter.off(type, ...handlers.splice(index, 1));
   }
   return this;
 }

 /**
  * Emit an event and call any associated listeners.
  *
  * @param type - the event you'd like to emit
  * @param eventData - any data you'd like to emit with the event
  * @returns `true` if there are any listeners, `false` if there are not.
  */
 emit<Key extends keyof EventsWithWildcard<Events>>(
   type: Key,
   event: EventsWithWildcard<Events>[Key],
 ): boolean {
   this.#emitter.emit(type, event);
   return this.listenerCount(type) > 0;
 }

 /**
  * Like `on` but the listener will only be fired once and then it will be removed.
  * @param type - the event you'd like to listen to
  * @param handler - the handler function to run when the event occurs
  * @returns `this` to enable you to chain method calls.
  */
 once<Key extends keyof EventsWithWildcard<Events>>(
   type: Key,
   handler: Handler<EventsWithWildcard<Events>[Key]>,
 ): this {
   const onceHandler: Handler<EventsWithWildcard<Events>[Key]> = eventData => {
     handler(eventData);
     this.off(type, onceHandler);
   };

   return this.on(type, onceHandler);
 }

 /**
  * Gets the number of listeners for a given event.
  *
  * @param type - the event to get the listener count for
  * @returns the number of listeners bound to the given event
  */
 listenerCount(type: keyof EventsWithWildcard<Events>): number {
   return this.#handlers.get(type)?.length || 0;
 }

 /**
  * Removes all listeners. If given an event argument, it will remove only
  * listeners for that event.
  *
  * @param type - the event to remove listeners for.
  * @returns `this` to enable you to chain method calls.
  */
 removeAllListeners(type?: keyof EventsWithWildcard<Events>): this {
   if (type !== undefined) {
     return this.off(type);
   }
   this[disposeSymbol]();
   return this;
 }

 /**
  * @internal
  */
 [disposeSymbol](): void {
   for (const [type, handlers] of this.#handlers) {
     for (const handler of handlers) {
       this.#emitter.off(type, handler);
     }
   }
   this.#handlers.clear();
 }
}