event-controller

A lightweight event emitter with separation of concerns between emitter and listener, inspired by the AbortController interface.

Features

• Separation of Concerns. Separate interfaces for emitting events and listening to events.
• Supports AbortSignal. Remove event listeners using an AbortSignal.
• TypeScript Support.: Full TypeScript definitions with type safety.
• Promise Support.: Get a promise that resolves when the next event of a type is emitted.
• Lightweight.: Just a single .js file. Zero dependencies.
• Exceptions Handled. Exceptions thrown by event listeners won't prevents other listeners from being called, and emitting events will never throw exceptions. You can listen to error thrown by listeners if you want.
• Modern.: TypeScript, AbortSignal, Promises, Streams, Async Iterators.

Usage

import { EventController } from '@leonardoraele/event-controller';

// Define your event emitter interface (TypeScript only)
interface MyEvents {
  userLoggedIn: (user: { id: string; name: string }) => void;
  dataUpdated: (data: any[]) => void;
  error: (error: Error) => void;
}

// Create a controller
const controller = new EventController<MyEvents>();

// Each controller instance has an `emitter` field that can be used to listen to events emitted by the controller.
// You expose only the `emitter` to clients interested in your events.
controller.emitter.on('userLoggedIn', (user) => { // `user` is of type `{ id: string; name: string }`
  console.log(`Welcome, ${user.name}!`);
});

controller.emitter.on('error', (error) => { // `error` is of type `Error`
  console.error('An error occurred:', error.message);
});

// Emit events
controller.emit('userLoggedIn', { id: '123', name: 'John Doe' }); // Arguments are type-checked
controller.emit('error', new Error('Something went wrong'));

Installation

npm install @leonardoraele/event-controller

API Reference

See api.md file.

Advanced Uses

Remove Listenres

Using an AbortSignal:

const aborter = new AbortController();

{
	emitter.addEventListener('userLoggedIn', { signal: aborter.signal }, (user) => {
		console.log(`User ${user.name} logged in`);
	});

	emitter.addEventListener('error', { signal: aborter.signal }, (error) => {
		console.error('Error:', error.message);
	});
}

// Remove all listeners from the event emitter
aborter.abort();

Using removeEventListener():

emitter.addEventListener('userLoggedIn', function onUserLoggedIn(user) {
  console.log(`User ${user.name} logged in`);
});

emitter.addEventListener('error', function onError(error) {
  console.error('Error:', error.message);
});

emitter.removeEventListener('userLoggedIn', onUserLoggedIn);
emitter.removeEventListener('error', onError);

Async Iterators & Streams

// Transform events into an async iterator, transforms the data, then pipe into a sink stream.
emitter.observe('dataUpdated')
	.map(data => JSON.stringify(data))
	.toStream()
	.pipeTo(sinkStream);

Error Handling

Signal listeners that throw errors will have their errors logged to the console, but won't stop other listeners from executing:

/// When a listener throws an exception...
controller.emitter.addEventListener('userLoggedIn', (user) => {
  throw new Error('This will be logged but won\'t stop other listeners');
});

// This listener from the controller is called
controller.onError = (errors, eventType, args) => {
	if (eventType === 'userLoggedIn') {
		const [user] = args;
		// `errors` is an array of the errors that had been thrown for each listener that threw
		for (const error of errors) {
			console.error(
				'A listener for the event', eventType, 'threw this error:', error,
				'This happened when the event was emitted with these arguments:', args,
			);
		}
	}
}

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.