@metamask/safe-event-emitter

What is @metamask/safe-event-emitter?

@metamask/safe-event-emitter is a lightweight event emitter library designed to be a safer alternative to the Node.js EventEmitter. It provides a simple API for emitting and listening to events, with additional safety checks to prevent common issues such as memory leaks and unhandled errors.

What are @metamask/safe-event-emitter's main functionalities?

Basic Event Emission

This feature allows you to emit and listen to events. The code sample demonstrates how to create an instance of SafeEventEmitter, set up an event listener, and emit an event.

const SafeEventEmitter = require('@metamask/safe-event-emitter');
const emitter = new SafeEventEmitter();
emitter.on('event', (message) => {
  console.log(message);
});
emitter.emit('event', 'Hello, world!');

Error Handling

This feature provides built-in error handling. The code sample shows how to listen for 'error' events and handle them appropriately.

const SafeEventEmitter = require('@metamask/safe-event-emitter');
const emitter = new SafeEventEmitter();
emitter.on('error', (err) => {
  console.error('An error occurred:', err);
});
emitter.emit('error', new Error('Something went wrong!'));

Removing Listeners

This feature allows you to remove event listeners. The code sample demonstrates how to add a listener, remove it, and then emit an event that will not be logged because the listener has been removed.

const SafeEventEmitter = require('@metamask/safe-event-emitter');
const emitter = new SafeEventEmitter();
function listener(message) {
  console.log(message);
}
emitter.on('event', listener);
emitter.removeListener('event', listener);
emitter.emit('event', 'This will not be logged.');

Other packages similar to @metamask/safe-event-emitter

events

The 'events' package is the standard Node.js EventEmitter implementation. It provides a similar API for emitting and listening to events but lacks some of the safety features of @metamask/safe-event-emitter, such as built-in error handling and memory leak prevention.

eventemitter3

eventemitter3 is a high-performance event emitter for Node.js and the browser. It offers a similar API to @metamask/safe-event-emitter but focuses more on performance and less on safety features.

mitt

mitt is a tiny (~200 bytes) functional event emitter. It provides a minimal API for emitting and listening to events, making it a lightweight alternative to @metamask/safe-event-emitter, though it lacks some of the built-in safety features.

README

safe-event-emitter

An EventEmitter that isolates the emitter from errors in handlers. If an error is thrown in a handler it is caught and re-thrown inside of a setTimeout so as to not interrupt the emitter's code flow.

The API is the same as a core EventEmitter.

Install

$ yarn add '@metamask/safe-event-emitter'

Usage

import SafeEventEmitter from '@metamask/safe-event-emitter';

const ee = new SafeEventEmitter();
ee.on('boom', () => { throw new Error(); });
ee.emit('boom'); // No error here

// Error is thrown after setTimeout

Release & Publishing

The project follows the same release process as the other libraries in the MetaMask organization:

1. Create a release branch
   • For a typical release, this would be based on master
   • To update an older maintained major version, base the release branch on the major version branch (e.g. 1.x)
2. Update the changelog
3. Update version in package.json file (e.g. yarn version --minor --no-git-tag-version)
4. Create a pull request targeting the base branch (e.g. master or 1.x)
5. Code review and QA
6. Once approved, the PR is squashed & merged
7. The commit on the base branch is tagged
8. The tag can be published as needed

Running tests

yarn test

Changelog

[3.1.0] - 2024-03-08

Added

• Add ESM build (#141)