Emittery

Emittery is an async-first event emitter designed for high performance and modern JavaScript environments. Key features include:

• Async-first: Listeners are deferred to the next microtask to prevent blocking the main thread.
• TypeScript support: Provides strongly typed events.
• Async iteration: Supports for await...of for consuming events.
• Lifecycle hooks: Supports init and deinit for lazy resource management.
• Cancellation: Built-in AbortSignal support.
• Automatic cleanup: Supports Symbol.dispose and Symbol.asyncDispose.
• Meta events: Allows observing changes to listeners.
• Debug mode: Includes customizable logging.
• Zero dependencies: Lightweight and secure.

Install the emittery package using npm to use this simple and modern async event emitter in Node.js or the browser.

npm install emittery

You can collect and log debug information using one of the following methods:

1. Environment Variable: Set the DEBUG environment variable to 'emittery' or '*'.
2. Global Static Property: Set Emittery.isDebugEnabled = true on the class.
3. Instance Property: Set myEmitter.debug.enabled = true on a specific instance.

Create a new instance of Emittery to manage asynchronous event emission. You can optionally provide a debug configuration object to enable logging.

import Emittery from 'emittery';

const emittery = new Emittery({ debug: { enabled: true } });

Emittery does not support multiple arguments in the .emit() method. To pass multiple pieces of data, wrap them in an array or object and use destructuring in your listener.

// Use destructuring to handle multiple values passed as an array
emitter.on('🦄', ({data: [foo, bar]}) => {
	console.log(foo, bar);
});

emitter.emit('🦄', [foo, bar]);

To use emittery, import the Emittery class, instantiate it, and use .on() to register listeners and .emit() to trigger events. Listeners are deferred to the next microtask, ensuring non-blocking execution. You can use strings or Symbols as event names.

import Emittery from 'emittery';

const emitter = new Emittery();

emitter.on('🦄', ({data}) => {
	console.log(data);
});

const myUnicorn = Symbol('🦄');

emitter.on(myUnicorn, ({data}) => {
	console.log(`Unicorns love ${data}`);
});

emitter.emit('🦄', '🌈'); // Will trigger printing '🌈'
emitter.emit(myUnicorn, '🦋');  // Will trigger printing 'Unicorns love 🦋'

If you need to listen to every event emitted by an instance:

• onAny(listener, options?): Subscribes to a callback that is notified of every event. Returns an unsubscribe method (also a Disposable).
• anyEvent(options?): Returns an async iterator that buffers every event object emitted. Use await using for automatic cleanup.

import Emittery from 'emittery';

const emitter = new Emittery();

// Callback approach
const off = emitter.onAny(({name, data}) => {
	console.log(name, data);
});

// Async iterator approach
for await (const {name, data} of emitter.anyEvent()) {
	console.log(name, data);
}

Use off(eventName | eventName[], listener) to remove specific event subscriptions. You can pass a single event name or an array of event names.

import Emittery from 'emittery';

const emitter = new Emittery();
const listener = ({data}) => console.log(data);

emitter.on(['🦄', '🐶', '🦊'], listener);

emitter.off('🦄', listener);
emitter.off(['🐶', '🦊'], listener);

You can globally toggle debug mode for all instances using Emittery.isDebugEnabled. By default, it is true if the DEBUG environment variable is set to emittery or *, otherwise false.

Individual instances can be configured with specific debug options via the debug property in the constructor:

• name (string): A name for the instance used in debug output.
• enabled (boolean): Toggles debug logging for just this instance.
• logger (Function): A custom function to handle debug data. It receives (type, debugName, eventName, eventData).

import Emittery from 'emittery';

Emittery.isDebugEnabled = true;

const emitter = new Emittery({
	debug: {
		name: 'myEmitter',
		enabled: true,
		logger: (type, debugName, eventName, eventData) => {
			console.log(`[${type}]: ${eventName}`);
		}
	}
});

emitter.on('test', () => {});
emitter.emit('test');