fix: rename event emitter class (#2173)

We add types to a `EventEmitter` class which extends the plain js `EventTarget`.

The name is chosen to give familiarity to node developers but it's not generally a good idea.

This refactor:

1. Exports a new `TypedEventTarget` interface which adds types to `EventTarget`
2. Renames `EventEmitter` to `TypedEventEmitter` to draw a distinction between them
3. Re-exports `TypedEventEmitter` as `EventEmitter` to preserve backwards compatibility

In the future all consuming code should rely on the `TypedEventTarget` interface while implementing code uses `TypedEventEmitter` as an implementation of a `TypedEventEmitter`.

By depending on the interface and not the implementation consuming code is isolated from problems that arise when two versions of `@libp2p/interface` is in the dependency tree and the event subsystems would otherwise be compatible due to type overlap.

This manifests as an error message about incompatible implementations of the private `#listeners` field in EventEmitter.

Backwards compatibility is achieved by exporting the `TypedEventEmitter` class as the older `EventEmitter` name.  This should be removed in a future PR to the v1.0 branch once external modules (e.g. Gossipsub) have been updated to use the new `TypedEventEmitter` symbol.

## Change checklist

- [x] I have performed a self-review of my own code
- [ ] I have made corresponding changes to the documentation if necessary (this includes comments as well)
- [ ] I have added tests that prove my fix is effective or that my feature works

Author: achingbrain

packages/interface-compliance-tests/src/mocks/connection-manager.ts

@@ -6,7 +6,7 @@ import { isMultiaddr, type Multiaddr } from '@multiformats/multiaddr'
 import { connectionPair } from './connection.js'
 import type { Libp2pEvents, PendingDial } from '@libp2p/interface'
 import type { Connection } from '@libp2p/interface/connection'
-import type { EventEmitter } from '@libp2p/interface/events'
+import type { TypedEventTarget } from '@libp2p/interface/events'
 import type { PubSub } from '@libp2p/interface/pubsub'
 import type { Startable } from '@libp2p/interface/startable'
 import type { ConnectionManager } from '@libp2p/interface-internal/connection-manager'
@@ -16,7 +16,7 @@ export interface MockNetworkComponents {
   peerId: PeerId
   registrar: Registrar
   connectionManager: ConnectionManager
-  events: EventEmitter<Libp2pEvents>
+  events: TypedEventTarget<Libp2pEvents>
   pubsub?: PubSub
 }
 
@@ -51,7 +51,7 @@ export const mockNetwork = new MockNetwork()
 export interface MockConnectionManagerComponents {
   peerId: PeerId
   registrar: Registrar
-  events: EventEmitter<Libp2pEvents>
+  events: TypedEventTarget<Libp2pEvents>
 }
 
 class MockConnectionManager implements ConnectionManager, Startable {

packages/interface-compliance-tests/src/mocks/peer-discovery.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from '@libp2p/interface/events'
+import { TypedEventEmitter } from '@libp2p/interface/events'
 import { peerDiscovery } from '@libp2p/interface/peer-discovery'
 import * as PeerIdFactory from '@libp2p/peer-id-factory'
 import { multiaddr } from '@multiformats/multiaddr'
@@ -12,7 +12,7 @@ interface MockDiscoveryInit {
 /**
  * Emits 'peer' events on discovery.
  */
-export class MockDiscovery extends EventEmitter<PeerDiscoveryEvents> implements PeerDiscovery {
+export class MockDiscovery extends TypedEventEmitter<PeerDiscoveryEvents> implements PeerDiscovery {
   public readonly options: MockDiscoveryInit
   private _isRunning: boolean
   private _timer: any

packages/interface-compliance-tests/src/mocks/upgrader.ts

@@ -1,18 +1,18 @@
 import { mockConnection } from './connection.js'
 import type { Libp2pEvents } from '@libp2p/interface'
 import type { Connection, MultiaddrConnection } from '@libp2p/interface/connection'
-import type { EventEmitter } from '@libp2p/interface/events'
+import type { TypedEventTarget } from '@libp2p/interface/events'
 import type { Upgrader, UpgraderOptions } from '@libp2p/interface/transport'
 import type { Registrar } from '@libp2p/interface-internal/registrar'
 
 export interface MockUpgraderInit {
   registrar?: Registrar
-  events?: EventEmitter<Libp2pEvents>
+  events?: TypedEventTarget<Libp2pEvents>
 }
 
 class MockUpgrader implements Upgrader {
   private readonly registrar?: Registrar
-  private readonly events?: EventEmitter<Libp2pEvents>
+  private readonly events?: TypedEventTarget<Libp2pEvents>
 
   constructor (init: MockUpgraderInit) {
     this.registrar = init.registrar

packages/interface-compliance-tests/src/pubsub/utils.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from '@libp2p/interface/events'
+import { TypedEventEmitter } from '@libp2p/interface/events'
 import { createEd25519PeerId } from '@libp2p/peer-id-factory'
 import { pEvent } from 'p-event'
 import pWaitFor from 'p-wait-for'
@@ -19,7 +19,7 @@ export async function createComponents (): Promise<MockNetworkComponents> {
   const components: any = {
     peerId: await createEd25519PeerId(),
     registrar: mockRegistrar(),
-    events: new EventEmitter()
+    events: new TypedEventEmitter()
   }
   components.connectionManager = mockConnectionManager(components)
 

packages/interface-compliance-tests/src/transport/dial-test.ts

@@ -1,5 +1,5 @@
 import { AbortError } from '@libp2p/interface/errors'
-import { EventEmitter } from '@libp2p/interface/events'
+import { TypedEventEmitter } from '@libp2p/interface/events'
 import { expect } from 'aegir/chai'
 import all from 'it-all'
 import drain from 'it-drain'
@@ -27,7 +27,7 @@ export default (common: TestSetup<TransportTestFixtures>): void => {
       registrar = mockRegistrar()
       upgrader = mockUpgrader({
         registrar,
-        events: new EventEmitter()
+        events: new TypedEventEmitter()
       });
 
       ({ addrs, transport, connector } = await common.setup())

packages/interface-compliance-tests/src/transport/listen-test.ts

@@ -1,5 +1,5 @@
 /* eslint max-nested-callbacks: ["error", 8] */
-import { CustomEvent, EventEmitter } from '@libp2p/interface/events'
+import { CustomEvent, TypedEventEmitter } from '@libp2p/interface/events'
 import { expect } from 'aegir/chai'
 import drain from 'it-drain'
 import { pipe } from 'it-pipe'
@@ -27,7 +27,7 @@ export default (common: TestSetup<TransportTestFixtures>): void => {
       registrar = mockRegistrar()
       upgrader = mockUpgrader({
         registrar,
-        events: new EventEmitter()
+        events: new TypedEventEmitter()
       });
 
       ({ transport, addrs } = await common.setup())

packages/interface/src/events.ts

@@ -15,7 +15,23 @@ interface Listener {
  * https://github.com/microsoft/TypeScript/issues/299
  * etc
  */
-export class EventEmitter<EventMap extends Record<string, any>> extends EventTarget {
+export interface TypedEventTarget <EventMap extends Record<string, any>> extends EventTarget {
+  addEventListener<K extends keyof EventMap>(type: K, listener: EventHandler<EventMap[K]> | null, options?: boolean | AddEventListenerOptions): void
+
+  listenerCount (type: string): number
+
+  removeEventListener<K extends keyof EventMap>(type: K, listener?: EventHandler<EventMap[K]> | null, options?: boolean | EventListenerOptions): void
+
+  removeEventListener (type: string, listener?: EventHandler<Event>, options?: boolean | EventListenerOptions): void
+
+  safeDispatchEvent<Detail>(type: keyof EventMap, detail: CustomEventInit<Detail>): boolean
+}
+
+/**
+ * An implementation of a typed event target
+ * etc
+ */
+export class TypedEventEmitter<EventMap extends Record<string, any>> extends EventTarget implements TypedEventTarget<EventMap> {
   #listeners = new Map<any, Listener[]>()
 
   listenerCount (type: string): number {
@@ -98,3 +114,6 @@ class CustomEventPolyfill<T = any> extends Event {
 }
 
 export const CustomEvent = globalThis.CustomEvent ?? CustomEventPolyfill
+
+// TODO: remove this in v1
+export { TypedEventEmitter as EventEmitter }

packages/interface/src/index.ts

@@ -16,7 +16,7 @@
 
 import type { Connection, NewStreamOptions, Stream } from './connection/index.js'
 import type { ContentRouting } from './content-routing/index.js'
-import type { EventEmitter } from './events.js'
+import type { TypedEventTarget } from './events.js'
 import type { KeyChain } from './keychain/index.js'
 import type { Metrics } from './metrics/index.js'
 import type { PeerId } from './peer-id/index.js'
@@ -303,7 +303,7 @@ export interface PendingDial {
 /**
  * Libp2p nodes implement this interface.
  */
-export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, EventEmitter<Libp2pEvents<T>> {
+export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, TypedEventTarget<Libp2pEvents<T>> {
   /**
    * The PeerId is a unique identifier for a node on the network.
    *

packages/interface/src/peer-discovery/index.ts

@@ -1,4 +1,4 @@
-import type { EventEmitter } from '../events.js'
+import type { TypedEventTarget } from '../events.js'
 import type { PeerInfo } from '../peer-info/index.js'
 
 /**
@@ -26,4 +26,4 @@ export interface PeerDiscoveryEvents {
   'peer': CustomEvent<PeerInfo>
 }
 
-export interface PeerDiscovery extends EventEmitter<PeerDiscoveryEvents> {}
+export interface PeerDiscovery extends TypedEventTarget<PeerDiscoveryEvents> {}

packages/interface/src/pubsub/index.ts

@@ -1,5 +1,5 @@
 import type { Stream } from '../connection/index.js'
-import type { EventEmitter } from '../events.js'
+import type { TypedEventTarget } from '../events.js'
 import type { PeerId } from '../peer-id/index.js'
 import type { Pushable } from 'it-pushable'
 import type { Uint8ArrayList } from 'uint8arraylist'
@@ -65,7 +65,7 @@ export interface PubSubRPC {
   messages: PubSubRPCMessage[]
 }
 
-export interface PeerStreams extends EventEmitter<PeerStreamEvents> {
+export interface PeerStreams extends TypedEventTarget<PeerStreamEvents> {
   id: PeerId
   protocol: string
   outboundStream?: Pushable<Uint8ArrayList>
@@ -152,7 +152,7 @@ export interface TopicValidatorFn {
   (peer: PeerId, message: Message): TopicValidatorResult | Promise<TopicValidatorResult>
 }
 
-export interface PubSub<Events extends Record<string, any> = PubSubEvents> extends EventEmitter<Events> {
+export interface PubSub<Events extends Record<string, any> = PubSubEvents> extends TypedEventTarget<Events> {
   /**
    * The global signature policy controls whether or not we sill send and receive
    * signed or unsigned messages.