Event Emitter 🔊

Cross-env TypeScript Event Emitter

A cross-environment implementation of an EventEmitter that works seamlessly in Node.js, Edge Runtime (such as Next.js middleware), and browser environments.

The EventEmitter class provides a mechanism to handle events and their listeners. It allows you to register event listeners, emit events, and manage the listeners for those events.

Table of Contents

• Getting started
• API Reference
  • EventEmitter Class
    • Constructor
    • Methods
  • Types
  • Examples
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using event-emitter in your projects:

npm i @alessiofrittoli/event-emitter

or using pnpm

pnpm i @alessiofrittoli/event-emitter

API Reference

EventEmitter Class

Constructor

new EventEmitter<T>( options?: EventEmitterOptions )

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | options | EventEmitterOptions | - | Optional configuration object for the emitter instance. | | options.captureRejections | boolean | false | If set to true, captures and handles promise rejections in listeners. |

Methods

EventEmitter.emit()

Emits an event to all registered listeners.

| Parameter | Type | Description | |-----------|--------------|----------------------------------------| | event | K | The event name to emit. | | args | Args<K, T> | The arguments passed to the listeners. |

EventEmitter.on()

Adds a listener for the specified event.

| Parameter | Type | Description | |------------|------------------|---------------------------------------------------------| | event | K | The event name to listen for. | | listener | Listener<T, K> | The listener function called when the event is emitted. |

Type: EventEmitter

The current EventEmitter instance so that calls can be chained.

EventEmitter.addListener()

Alias for EventEmitter.on( event, listener ).

EventEmitter.prepend()

Adds a listener to the beginning of the listener array for the specified event.

| Parameter | Type | Description | |------------|------------------|---------------------------------------------------------| | event | K | The event name to listen for. | | listener | Listener<T, K> | The listener function called when the event is emitted. |

Type: EventEmitter

The current EventEmitter instance so that calls can be chained.

EventEmitter.prependListener()

Alias for EventEmitter.prepend( event, listener ).

EventEmitter.once()

Adds a one-time listener for the specified event. Even if the event is emitted multiple times, listeners registered with .once() method will only get called one single time.

| Parameter | Type | Description | |------------|------------------|---------------------------------------------------------| | event | K | The event name to listen for. | | listener | Listener<T, K> | The listener function called when the event is emitted. |

Type: EventEmitter

The current EventEmitter instance so that calls can be chained.

EventEmitter.prependOnce()

Adds a one-time listener to the beginning of the listener array for the specified event.

| Parameter | Type | Description | |------------|------------------|---------------------------------------------------------| | event | K | The event name to listen for. | | listener | Listener<T, K> | The listener function called when the event is emitted. |

Type: EventEmitter

The current EventEmitter instance so that calls can be chained.

EventEmitter.prependOnceListener()

Alias for EventEmitter.prependOnce( event, listener ).

EventEmitter.off()

Removes a listener for the specified event.

| Parameter | Type | Description | |------------|------------------|---------------------------------------------------------| | event | K | The event name to remove the listener from. | | listener | Listener<T, K> | The listener function to remove from the given event. |

Type: EventEmitter

The current EventEmitter instance so that calls can be chained.

EventEmitter.removeListener()

Alias for EventEmitter.off( event, listener ).

EventEmitter.removeAllListeners()

Removes all listeners for a specified event or all events.

| Parameter | Type | Description | |------------|------------------|---------------------------------------------------------| | event | K | (Optional) The event name to remove listeners from. | | listener | Listener<T, K> | (Optional) The listener function to remove. |

Type: EventEmitter

The current EventEmitter instance so that calls can be chained.

EventEmitter.getMaxListeners()

Gets the current maximum number of listeners. Default: EventEmitter.defaultMaxListeners (10).

Type number

The current maximum number of listeners.

EventEmitter.setMaxListeners()

Sets the maximum number of listeners allowed for each event.

By default, a maximum of 10 listeners can be registered for any single event. This limit can be changed for individual EventEmitter instances using the EventEmitter.setMaxListeners( n ) method.

This is not a hard limit. The EventEmitter instance will allow more listeners to be added but will output a trace warning to stderr indicating that a "possible EventEmitter memory leak" has been detected.

| Parameter | Type | Description | |-----------|----------|----------------------------------| | n | number | The maximum number of listeners. |

Type: EventEmitter

The current EventEmitter instance so that calls can be chained.

EventEmitter.listenerCount()

Gets the number of listeners for the specified event.

| Parameter | Type | Description | |------------|------------------|----------------------------------------------------------| | event | K | The event name to check the listeners for. | | listener | Listener<T, K> | (Optional) The specific listener to count (if provided). |

Type: number

The number of listeners for the specified event and optionally for the given listener.

EventEmitter.listeners()

Returns a list of listeners for the specified event.

| Parameter | Type | Description | |-----------|------|--------------------------------------| | event | K | The event name to get listeners for. |

Type: ( Listener<T, K> )[]

An array of registered listeners. Even if the listener is registered using the .once() method, the actual listener is returned instead of the OnceListenerWrapper<T, K>.

EventEmitter.rawListeners()

Returns a copy of the array of listeners for the specified event, including any wrappers (such as those created by .once()).

| Parameter | Type | Description | |-----------|------|--------------------------------------| | event | K | The event name to get listeners for. |

Type: ( Listener<T, K> | OnceListenerWrapper<T, K> )[]

An array of registered listener callback.

If a listener has been registered using the .once() method a OnceListenerWrapper<T, K> is returned. In that case the original listener can be retrieved through the listener property.

EventEmitter.eventNames()

Returns a list of all event names.

Type: ( keyof T )[]

An array of registered event names.

Types

EventEmitterOptions

Options for configuring the EventEmitter.

| Proeprty | Type | Description | |---------------------|-----------|-------------| | captureRejections | boolean | If set to true, captures and handles promise rejections in listeners. |

Listener<T, K>

Defines the type of a listener function.

| Proeprty | Type | Description | |----------|--------------|-------------| | args | Args<K, T> | Arguments passed to the listener corresponding to the event key. |

OnceListenerWrapper<T, K>

A wrapper for listeners that should be invoked only once.

| Proeprty | Type | Description | |------------|------------------|-------------| | args | Args<K, T> | Arguments passed to the listener corresponding to the event key. | | listener | Listener<T, K> | The actual listener function to be invoked. |

Args<K, T>

A utility type that resolves to a specific type based on the provided keys and event map.

Examples

Defining custom types

import type { Listener } from '@alessiofrittoli/event-emitter'

// Define an event map for your EventEmitter
interface MyEvents
{
  greet     : [ name: string ]  // The 'greet' event takes a string argument
  farewell  : [ name: Error ]   // The 'farewell' event also takes a string argument
  error     : [ error: Error ]  // The 'error' event takes an Error argument
}

// Optionally define listeners types
type OnGreetEventListener     = Listener<MyEvents, 'greet'>
type OnFarewellEventListener  = Listener<MyEvents, 'farewell'>
type OnErrorEventListener     = Listener<MyEvents, 'error'>

Emitting and Listening events

const greetListener: OnGreetEventListener = name => {
  console.log( `Hello, ${ name }!` )
}


const farewellListener: OnFarewellEventListener = name => {
  console.log( `Goodbye, ${ name }!` )
}


const errorListener: OnErrorEventListener = error => {
  console.error( 'Something went wrong.', error.message )
}

import { EventEmitter } from '@alessiofrittoli/event-emitter'

const emitter = new EventEmitter<MyEvents>()

// Attach listeners
emitter.on( 'greet', greetListener )
emitter.on( 'farewell', farewellListener )
emitter.on( 'error', errorListener )

// Emit events
emitter.emit( 'greet', 'Foo' )
emitter.emit( 'farewell', 'Bar' )
emitter.emit( 'error', new Error( 'An error occured.' ) )

One-time events listeners

const emitter = new EventEmitter<MyEvents>()

// Define a listener for the 'greet' event that should only be called once
const greetOnceListener: OnGreetEventListener = name => {
  console.log( `Once Hello, ${ name }!` )
}

emitter.once( 'greet', greetOnceListener )

// Emit the event
emitter.emit( 'greet', 'Foo' )
// `greetOnceListener` won't be called anymore, as the listener was removed after the first call.
emitter.emit( 'greet', 'Bob' )

Error Handling with captureRejections

const emitter = new EventEmitter<MyEvents>( { captureRejections: true } )

const greetListener: OnGreetEventListener = name => {
  if ( name === 'He-Who-Must-Not-Be-Named' ) {
    throw new Error( 'nooose!' )
  }
  console.log( `Howdy, ${ name }!` )
}

const errorListener: OnErrorEventListener = error => {
  console.error( 'Caught your', error.message )
}


// Add listeners
emitter.on( 'greet', greetListener )
emitter.on( 'error', errorListener )

// Emit events
emitter.emit( 'greet', 'Foo' )
emitter.emit( 'greet', 'He-Who-Must-Not-Be-Named' )

Managing Max Listeners

const emitter = (
  new EventEmitter<MyEvents>()
    .setMaxListeners( 1 )
)

const greetListener1: OnGreetEventListener = name => {
  console.log( `Hello, ${ name }!` )
}


const greetListener2: OnGreetEventListener = name => {
  console.log( `Hi, ${ name }!` )
}


const greetListener3: OnGreetEventListener = name => {
  console.log( `Howdy, ${ name }!` )
}


// Attach listeners
emitter.on( 'greet', greetListener1 )
emitter.on( 'greet', greetListener2 ) // This will trigger a warning but it will get executed anyway.
emitter.on( 'greet', greetListener3 ) // This won't trigger a warning. Warnings are emitted once.

emitter.emit( 'greet', 'Foo' )
// Output: 
// Hello, Foo!
// Hi, Foo!
// Howdy, Foo!

Using prepend and prependOnce

const emitter = new EventEmitter<MyEvents>()

// Attach listeners
emitter.on( 'greet', name => {
  console.log( `A: Hello! Better late than never ${ name }.` )
} )
emitter.prepend( 'greet', name => {
  console.log( `B: Hello, ${ name }!` )
} )
emitter.prependOnce( 'greet', name => {
  console.log( `C: Once Hello, ${ name }! I won't say hello to you, Bar.` )
} )

// Emit events
emitter.emit( 'greet', 'Foo' )
emitter.emit( 'greet', 'Bar' )
// Outputs:
// C: Once Hello, Foo! I won't say hello to you, Bar.
// B: Hello, Foo!
// A: Hello! Better late than never Foo.
// B: Hello, Bar!
// A: Hello! Better late than never Bar.

Retrieve listeners count

const emitter = (
  new EventEmitter<MyEvents>()
    .on( 'greet', () => {} )
    .on( 'greet', () => {} )
    .on( 'farewell', () => {} )
)

console.log( emitter.listenerCount( 'greet' ) )     // Outputs: `2`
console.log( emitter.listenerCount( 'farewell' ) )  // Outputs: `1`
console.log( emitter.listenerCount( 'error' ) )     // Outputs: `0`

const callback1 = () => {}
const callback2 = () => {}

const emitter = (
  new EventEmitter<MyEvents>()
    .on( 'greet', callback1 )
    .on( 'greet', callback1 )
    .on( 'greet', callback2 )
)

console.log( emitter.listenerCount( 'greet', callback1 ) ) // Outputs: `2`
console.log( emitter.listenerCount( 'greet', callback2 ) ) // Outputs: `1`

Retrieve registered listeners

We register callback2 with EventEmitter.once() to verify that we correctly get the original callback2 instead of the onceWrapper function in the returning array.

const callback1 = () => {}
const callback2 = () => {}

const emitter = (
  new EventEmitter<MyEvents>()
    .on( 'greet', callback1 )
    .once( 'greet', callback2 )
    .on( 'farewell', callback1 )
)
const functions = emitter.listeners( 'greet' ) // Listener<MyEvents, 'greet'>[]

console.log( functions )
// Outputs: `[ [Function: callback1], [Function: callback2] ]`

functions.map( listener => {
  listener() // manually execute the listener.
} )

Again we register callback2 with EventEmitter.once() to verify that we correctly get the onceWrapper function instead of the original callback2 listener in the returning array.

const callback1 = () => {}
const callback2 = () => {}

const emitter = (
  new EventEmitter<MyEvents>()
    .on( 'greet', callback1 )
    .once( 'greet', callback2 )
    .on( 'farewell', callback1 )
)

const functions = emitter.rawListeners( 'greet' ) // ( Listener<MyEvents, 'greet'> | OnceListenerWrapper<MyEvents, 'greet'> )[]

console.log( functions )
// Outputs: `[ [Function: callback1], [Function: onceWrapper] { listener: [Function: callback2] } ]`

functions.map( callback => {
  /** Manually execute the listener. If this is a `onceWrapper` function, it will remove the listener from the listeners array and then execute the original listener function. */
  callback()

  /** Or execute the original listener without removing it from the listeners array. */
  if ( 'listener' in callback ) {
    callback.listener()
  }
} )

Batch removing listeners

const emitter = (
  new EventEmitter<MyEvents>()
    .on( 'greet', () => {} )
    .once( 'greet', () => {} )
    .on( 'farewell', () => {} )
)

console.log( emitter.listenerCount( 'greet' ) )     // Outputs: `2`
console.log( emitter.listenerCount( 'farewell' ) )  // Outputs: `1`
console.log( emitter.listenerCount( 'error' ) )     // Outputs: `0`

emitter.removeAllListeners()

console.log( emitter.listenerCount( 'greet' ) )     // Outputs: `0`
console.log( emitter.listenerCount( 'farewell' ) )  // Outputs: `0`
console.log( emitter.listenerCount( 'error' ) )     // Outputs: `0`

const emitter = (
  new EventEmitter<MyEvents>()
    .on( 'greet', () => {} )
    .once( 'greet', () => {} )
    .on( 'farewell', () => {} )
    .removeAllListeners( 'greet' )
)

console.log( emitter.listenerCount( 'greet' ) )     // Outputs: `0`
console.log( emitter.listenerCount( 'farewell' ) )  // Outputs: `1`
console.log( emitter.listenerCount( 'error' ) )     // Outputs: `0`

const callback1 = () => {}
const callback2 = () => {}

const emitter = (
  new EventEmitter<MyEvents>()
    .on( 'greet', callback1 )
    .once( 'greet', callback1 )
    .once( 'greet', callback2 )
    .on( 'farewell', callback1 )
    .removeAllListeners( 'greet', callback1 )
)

console.log( emitter.listenerCount( 'greet' ) )     // Outputs: `1`
console.log( emitter.listenerCount( 'farewell' ) )  // Outputs: `1`
console.log( emitter.listenerCount( 'error' ) )     // Outputs: `0`

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email [email protected] to disclose any security vulnerabilities.

Made with ☕