emittery 1.2.0 → 2.0.0

package/index.d.ts

@@ -5,6 +5,31 @@ Symbol event names are preferred given that they can be used to avoid name colli
 */
 export type EventName = PropertyKey;
 
+/**
+The object passed to every event listener. Always includes `name`. Includes `data` only when the event was emitted with data.
+
+@example
+```
+import Emittery from 'emittery';
+
+const emitter = new Emittery<{unicorn: string; close: undefined}>();
+
+emitter.on('unicorn', ({name, data}) => {
+	console.log(name); //=> 'unicorn'
+	console.log(data); //=> '🌈'
+});
+
+emitter.on('close', ({name}) => {
+	console.log(name); //=> 'close'
+});
+```
+*/
+export type EmitteryEvent<Name extends EventName, Data> = [Data] extends [undefined]
+	? {readonly name: Name; readonly data?: undefined}
+	: {readonly name: Name; readonly data: Data};
+
+type EventDataPair<EventData, Name extends keyof EventData> = Name extends keyof EventData ? EmitteryEvent<Name, EventData[Name]> : never;
+
 // Helper type for turning the passed `EventData` type map into a list of string keys that don't require data alongside the event name when emitting. Uses the same trick that `Omit` does internally to filter keys by building a map of keys to keys we want to keep, and then accessing all the keys to return just the list of keys we want to keep.
 type DatalessEventNames<EventData> = {
 	[Key in keyof EventData]: EventData[Key] extends undefined ? Key : never;
@@ -21,7 +46,7 @@ To enable this feature set the `DEBUG` environment variable to `emittery` or `*`
 
 See API for more information on how debugging works.
 */
-export type DebugLogger<EventData, Name extends keyof EventData> = (type: string, debugName: string, eventName?: Name, eventData?: EventData[Name]) => void;
+export type DebugLogger<EventData, Name extends keyof EventData> = (type: string, debugName?: string, eventName?: Name, eventData?: EventData[Name]) => void;
 
 /**
 Configure debug options of an instance.
@@ -40,7 +65,7 @@ export type DebugOptions<EventData> = {
 
 	const emitter = new Emittery({debug: {name: 'myEmitter'}});
 
-	emitter.on('test', data => {
+	emitter.on('test', () => {
 		// …
 	});
 
@@ -49,7 +74,7 @@ export type DebugOptions<EventData> = {
 	//	data: undefined
 	```
 	*/
-	readonly name: string;
+	readonly name?: string;
 
 	/**
 	Toggle debug logging just for this instance.
@@ -63,11 +88,11 @@ export type DebugOptions<EventData> = {
 	const emitter1 = new Emittery({debug: {name: 'emitter1', enabled: true}});
 	const emitter2 = new Emittery({debug: {name: 'emitter2'}});
 
-	emitter1.on('test', data => {
+	emitter1.on('test', () => {
 		// …
 	});
 
-	emitter2.on('test', data => {
+	emitter2.on('test', () => {
 		// …
 	});
 
@@ -86,7 +111,11 @@ export type DebugOptions<EventData> = {
 	@default
 	```
 	(type, debugName, eventName, eventData) => {
-		eventData = JSON.stringify(eventData);
+		try {
+			eventData = JSON.stringify(eventData);
+		} catch {
+			eventData = `Object with the following keys failed to stringify: ${Object.keys(eventData).join(',')}`;
+		}
 
 		if (typeof eventName === 'symbol' || typeof eventName === 'number') {
 			eventName = eventName.toString();
@@ -114,7 +143,7 @@ export type DebugOptions<EventData> = {
 		}
 	});
 
-	emitter.on('test', data => {
+	emitter.on('test', () => {
 		// …
 	});
 
@@ -141,8 +170,24 @@ export type EmitteryOncePromise<T> = {
 
 /**
 Removes an event subscription.
+
+Can be used with the `using` keyword for automatic cleanup:
+
+@example
+```
+import Emittery from 'emittery';
+
+const emitter = new Emittery();
+
+{
+	using off = emitter.on('event', ({data}) => {
+		console.log(data);
+	});
+	// auto-unsubscribes when leaving scope
+}
+```
 */
-export type UnsubscribeFunction = () => void;
+export type UnsubscribeFunction = (() => void) & Disposable;
 
 /**
 The data provided as `eventData` when listening for `Emittery.listenerAdded` or `Emittery.listenerRemoved`.
@@ -151,7 +196,7 @@ export type ListenerChangedData = {
 	/**
 	The listener that was added or removed.
 	*/
-	listener: (eventData?: unknown) => (void | Promise<void>);
+	listener: (event: unknown) => (void | Promise<void>);
 
 	/**
 	The name of the event that was added or removed if `.on()` or `.off()` was used, or `undefined` if `.onAny()` or `.offAny()` was used.
@@ -191,8 +236,7 @@ emitter.emit('other');
 ```
 */
 export default class Emittery<
-	EventData = Record<EventName, any>, // TODO: Use `unknown` instead of `any`.
-	AllEventData = EventData & OmnipresentEventData,
+	EventData = Record<EventName, unknown>, AllEventData = EventData & OmnipresentEventData,
 	DatalessEvents = DatalessEventNames<EventData>,
 > {
 	/**
@@ -209,11 +253,11 @@ export default class Emittery<
 	const emitter1 = new Emittery({debug: {name: 'myEmitter1'}});
 	const emitter2 = new Emittery({debug: {name: 'myEmitter2'}});
 
-	emitter1.on('test', data => {
+	emitter1.on('test', () => {
 		// …
 	});
 
-	emitter2.on('otherTest', data => {
+	emitter2.on('otherTest', () => {
 		// …
 	});
 
@@ -239,15 +283,15 @@ export default class Emittery<
 
 	const emitter = new Emittery();
 
-	emitter.on(Emittery.listenerAdded, ({listener, eventName}) => {
+	emitter.on(Emittery.listenerAdded, ({data: {listener, eventName}}) => {
 		console.log(listener);
-		//=> data => {}
+		//=> ({data}) => {}
 
 		console.log(eventName);
 		//=> '🦄'
 	});
 
-	emitter.on('🦄', data => {
+	emitter.on('🦄', ({data}) => {
 		// Handle data
 	});
 	```
@@ -265,13 +309,13 @@ export default class Emittery<
 
 	const emitter = new Emittery();
 
-	const off = emitter.on('🦄', data => {
+	const off = emitter.on('🦄', ({data}) => {
 		// Handle data
 	});
 
-	emitter.on(Emittery.listenerRemoved, ({listener, eventName}) => {
+	emitter.on(Emittery.listenerRemoved, ({data: {listener, eventName}}) => {
 		console.log(listener);
-		//=> data => {}
+		//=> ({data}) => {}
 
 		console.log(eventName);
 		//=> '🦄'
@@ -300,7 +344,7 @@ export default class Emittery<
 	static mixin(
 		emitteryPropertyName: string | symbol,
 		methodNames?: readonly string[]
-	): <T extends {new (...arguments_: readonly any[]): any}>(klass: T) => T; // eslint-disable-line @typescript-eslint/prefer-function-type
+	): <T extends abstract new (...arguments_: readonly any[]) => any>(klass: T, context?: ClassDecoratorContext<T>) => T;
 
 	/**
 	Debugging options for the current instance.
@@ -319,7 +363,7 @@ export default class Emittery<
 
 	Using the same listener multiple times for the same event will result in only one method call per emitted event.
 
-	@returns An unsubscribe method.
+	@returns An unsubscribe method, which is also {@link Disposable} (can be used with `using`).
 
 	@example
 	```
@@ -327,110 +371,92 @@ export default class Emittery<
 
 	const emitter = new Emittery();
 
-	emitter.on('🦄', data => {
+	emitter.on('🦄', ({data}) => {
 		console.log(data);
 	});
 
-	emitter.on(['🦄', '🐶'], data => {
-		console.log(data);
+	emitter.on(['🦄', '🐶'], ({name, data}) => {
+		console.log(name, data);
 	});
 
-	emitter.emit('🦄', '🌈'); // log => '🌈' x2
-	emitter.emit('🐶', '🍖'); // log => '🍖'
+	emitter.emit('🦄', '🌈'); // log => '🌈' and '🦄 🌈'
+	emitter.emit('🐶', '🍖'); // log => '🐶 🍖'
+	```
+
+	@example
+	```
+	// With AbortSignal
+	const abortController = new AbortController();
+
+	emitter.on('🐗', ({data}) => {
+		console.log(data);
+	}, {signal: abortController.signal});
+
+	abortController.abort();
+	```
+
+	@example
+	```
+	// With `using` for automatic cleanup
+	{
+		using off = emitter.on('🦄', ({data}) => {
+			console.log(data);
+		});
+		await emitter.emit('🦄', '🌈'); // Logs '🌈'
+	}
+
+	await emitter.emit('🦄', '🌈'); // Nothing happens
 	```
 	*/
 	on<Name extends keyof AllEventData>(
 		eventName: Name | readonly Name[],
-		listener: (eventData: AllEventData[Name]) => void | Promise<void>,
+		listener: (event: EventDataPair<AllEventData, Name>) => void | Promise<void>,
 		options?: {signal?: AbortSignal}
 	): UnsubscribeFunction;
 
 	/**
 	Get an async iterator which buffers data each time an event is emitted.
 
-	Call `return()` on the iterator to remove the subscription.
+	Call `return()` on the iterator to remove the subscription. You can also pass an {@link AbortSignal} to cancel the subscription externally, or use `await using` for automatic cleanup.
 
 	@example
 	```
 	import Emittery from 'emittery';
 
 	const emitter = new Emittery();
-	const iterator = emitter.events('🦄');
-
-	emitter.emit('🦄', '🌈1'); // Buffered
-	emitter.emit('🦄', '🌈2'); // Buffered
-
-	iterator
-		.next()
-		.then(({value, done}) => {
-			// done === false
-			// value === '🌈1'
-			return iterator.next();
-		})
-		.then(({value, done}) => {
-			// done === false
-			// value === '🌈2'
-			// Revoke subscription
-			return iterator.return();
-		})
-		.then(({done}) => {
-			// done === true
-		});
-	```
-
-	In practice you would usually consume the events using the [for await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) statement. In that case, to revoke the subscription simply break the loop.
 
-	@example
-	```
-	import Emittery from 'emittery';
-
-	const emitter = new Emittery();
-	const iterator = emitter.events('🦄');
-
-	emitter.emit('🦄', '🌈1'); // Buffered
-	emitter.emit('🦄', '🌈2'); // Buffered
+	for await (const {data} of emitter.events('🦄')) {
+		console.log(data);
 
-	// In an async context.
-	for await (const data of iterator) {
 		if (data === '🌈2') {
-			break; // Revoke the subscription when we see the value `🌈2`.
+			break; // Revoke the subscription when we see the value '🌈2'.
 		}
 	}
 	```
 
-	It accepts multiple event names.
-
 	@example
 	```
-	import Emittery from 'emittery';
+	// With multiple event names
+	for await (const {name, data} of emitter.events(['🦄', '🦊'])) {
+		console.log(name, data);
+	}
+	```
 
-	const emitter = new Emittery();
-	const iterator = emitter.events(['🦄', '🦊']);
-
-	emitter.emit('🦄', '🌈1'); // Buffered
-	emitter.emit('🦊', '🌈2'); // Buffered
-
-	iterator
-		.next()
-		.then(({value, done}) => {
-			// done === false
-			// value === '🌈1'
-			return iterator.next();
-		})
-		.then(({value, done}) => {
-			// done === false
-			// value === '🌈2'
-			// Revoke subscription
-			return iterator.return();
-		})
-		.then(({done}) => {
-			// done === true
-		});
+	@example
+	```
+	// With `await using` for automatic cleanup
+	{
+		await using iterator = emitter.events('🦄');
+		for await (const {data} of iterator) {
+			console.log(data);
+		}
+	} // Subscription is automatically revoked
 	```
 	*/
 	events<Name extends keyof EventData>(
-		eventName: Name | readonly Name[]
-	): AsyncIterableIterator<EventData[Name]>;
+		eventName: Name | readonly Name[],
+		options?: {signal?: AbortSignal}
+	): AsyncIterableIterator<EventDataPair<EventData, Name>> & AsyncDisposable;
 
 	/**
 	Remove one or more event subscriptions.
@@ -441,7 +467,7 @@ export default class Emittery<
 
 	const emitter = new Emittery();
 
-	const listener = data => {
+	const listener = ({data}) => {
 		console.log(data);
 	};
 
@@ -451,23 +477,22 @@ export default class Emittery<
 	await emitter.emit('🦊', 'c');
 	emitter.off('🦄', listener);
 	emitter.off(['🐶', '🦊'], listener);
-	await emitter.emit('🦄', 'a'); // nothing happens
-	await emitter.emit('🐶', 'b'); // nothing happens
-	await emitter.emit('🦊', 'c'); // nothing happens
+	await emitter.emit('🦄', 'a'); // Nothing happens
+	await emitter.emit('🐶', 'b'); // Nothing happens
+	await emitter.emit('🦊', 'c'); // Nothing happens
 	```
 	*/
 	off<Name extends keyof AllEventData>(
 		eventName: Name | readonly Name[],
-		listener: (eventData: AllEventData[Name]) => void | Promise<void>
+		listener: (event: EventDataPair<AllEventData, Name>) => void | Promise<void>
 	): void;
 
 	/**
 	Subscribe to one or more events only once. It will be unsubscribed after the first event that matches the predicate (if provided).
 
-	@param eventName - The event name(s) to subscribe to.
-	@param predicate - Optional predicate function to filter event data. The event will only be emitted if the predicate returns true.
+	The second argument can be a predicate function or an options object with `predicate` and/or `signal`.
 
-	@returns The promise of event data when `eventName` is emitted and predicate matches (if provided). This promise is extended with an `off` method.
+	@returns The promise of event data when `eventName` is emitted and predicate matches (if provided). The promise has an `off` method to cancel the subscription.
 
 	@example
 	```
@@ -475,33 +500,55 @@ export default class Emittery<
 
 	const emitter = new Emittery();
 
-	emitter.once('🦄').then(data => {
-		console.log(data);
-		//=> '🌈'
-	});
+	const {data} = await emitter.once('🦄');
+	console.log(data);
+	//=> '🌈'
+	```
 
-	emitter.once(['🦄', '🐶']).then(data => {
-		console.log(data);
-	});
+	@example
+	```
+	// With multiple event names
+	const {name, data} = await emitter.once(['🦄', '🐶']);
+	console.log(name, data);
+	```
 
+	@example
+	```
 	// With predicate
-	emitter.once('data', data => data.ok === true).then(data => {
-		console.log(data);
-		//=> {ok: true, value: 42}
-	});
+	const event = await emitter.once('data', ({data}) => data.ok === true);
+	console.log(event.data);
+	//=> {ok: true, value: 42}
+	```
 
-	emitter.emit('🦄', '🌈'); // Logs `🌈` twice
-	emitter.emit('🐶', '🍖'); // Nothing happens
-	emitter.emit('data', {ok: false}); // Nothing happens
-	emitter.emit('data', {ok: true, value: 42}); // Logs {ok: true, value: 42}
+	@example
+	```
+	// With AbortSignal for timeout
+	await emitter.once('ready', {signal: AbortSignal.timeout(5000)});
+	```
+
+	@example
+	```
+	// Cancel with .off()
+	const promise = emitter.once('🦄');
+	promise.off();
 	```
 	*/
-	once<Name extends keyof AllEventData>(eventName: Name | readonly Name[], predicate?: (eventData: AllEventData[Name]) => boolean): EmitteryOncePromise<AllEventData[Name]>;
+	once<Name extends keyof AllEventData>(
+		eventName: Name | readonly Name[],
+		predicate?: (event: EventDataPair<AllEventData, Name>) => boolean
+	): EmitteryOncePromise<EventDataPair<AllEventData, Name>>;
+	once<Name extends keyof AllEventData>(
+		eventName: Name | readonly Name[],
+		options?: {
+			predicate?: (event: EventDataPair<AllEventData, Name>) => boolean;
+			signal?: AbortSignal;
+		}
+	): EmitteryOncePromise<EventDataPair<AllEventData, Name>>;
 
 	/**
 	Trigger an event asynchronously, optionally with some data. Listeners are called in the order they were added, but executed concurrently.
 
-	@returns A promise that resolves when all the event listeners are done. *Done* meaning executed if synchronous or resolved when an async/promise-returning function. You usually wouldn't want to wait for this, but you could for example catch possible errors. If any of the listeners throw/reject, the returned promise will be rejected with the error, but the other listeners will not be affected.
+	@returns A promise that resolves when all the event listeners are done. *Done* meaning executed if synchronous or resolved when an async/promise-returning function. You usually wouldn't want to wait for this, but you could for example catch possible errors. If any listeners throw/reject, the returned promise rejects with an `AggregateError` — all listener errors are collected in `error.errors`, so no errors are silently lost. All listeners always run to completion, even if some throw or reject.
 	*/
 	emit<Name extends DatalessEvents>(eventName: Name): Promise<void>;
 	emit<Name extends keyof EventData>(
@@ -515,6 +562,25 @@ export default class Emittery<
 	If any of the listeners throw/reject, the returned promise will be rejected with the error and the remaining listeners will *not* be called.
 
 	@returns A promise that resolves when all the event listeners are done.
+
+	@example
+	```
+	import Emittery from 'emittery';
+
+	const emitter = new Emittery();
+
+	emitter.on('🦄', async () => {
+		console.log('listener 1 start');
+		await new Promise(resolve => setTimeout(resolve, 100));
+		console.log('listener 1 done');
+	});
+
+	emitter.on('🦄', () => {
+		console.log('listener 2'); // Only runs after listener 1 is done
+	});
+
+	await emitter.emitSerial('🦄');
+	```
 	*/
 	emitSerial<Name extends DatalessEvents>(eventName: Name): Promise<void>;
 	emitSerial<Name extends keyof EventData>(
@@ -525,76 +591,164 @@ export default class Emittery<
 	/**
 	Subscribe to be notified about any event.
 
-	@returns A method to unsubscribe.
+	@returns A method to unsubscribe, which is also {@link Disposable}.
+
+	@example
+	```
+	import Emittery from 'emittery';
+
+	const emitter = new Emittery();
+
+	const off = emitter.onAny(({name, data}) => {
+		console.log(name, data);
+	});
+
+	emitter.emit('🦄', '🌈'); // log => '🦄 🌈'
+
+	off();
+	```
 	*/
 	onAny(
-		listener: (
-			eventName: keyof EventData,
-			eventData: EventData[keyof EventData]
-		) => void | Promise<void>,
+		listener: (event: EventDataPair<EventData, keyof EventData>) => void | Promise<void>,
 		options?: {signal?: AbortSignal}
 	): UnsubscribeFunction;
 
 	/**
-	Get an async iterator which buffers a tuple of an event name and data each time an event is emitted.
-
-	Call `return()` on the iterator to remove the subscription.
+	Get an async iterator which buffers an event object each time an event is emitted.
 
-	In the same way as for `events`, you can subscribe by using the `for await` statement.
+	Call `return()` on the iterator to remove the subscription. You can also pass an {@link AbortSignal} to cancel the subscription externally, or use `await using` for automatic cleanup.
 
 	@example
 	```
 	import Emittery from 'emittery';
 
 	const emitter = new Emittery();
-	const iterator = emitter.anyEvent();
-
-	emitter.emit('🦄', '🌈1'); // Buffered
-	emitter.emit('🌟', '🌈2'); // Buffered
-
-	iterator.next()
-		.then(({value, done}) => {
-			// done is false
-			// value is ['🦄', '🌈1']
-			return iterator.next();
-		})
-		.then(({value, done}) => {
-			// done is false
-			// value is ['🌟', '🌈2']
-			// revoke subscription
-			return iterator.return();
-		})
-		.then(({done}) => {
-			// done is true
-		});
+
+	for await (const {name, data} of emitter.anyEvent()) {
+		console.log(name, data);
+	}
+	```
+
+	@example
+	```
+	// With `await using` for automatic cleanup
+	{
+		await using iterator = emitter.anyEvent();
+		for await (const {name, data} of iterator) {
+			console.log(name, data);
+		}
+	} // Subscription is automatically revoked
 	```
 	*/
-	anyEvent(): AsyncIterableIterator<
-	[keyof EventData, EventData[keyof EventData]]
-	>;
+	anyEvent(options?: {signal?: AbortSignal}): AsyncIterableIterator<EventDataPair<EventData, keyof EventData>> & AsyncDisposable;
 
 	/**
 	Remove an `onAny` subscription.
 	*/
 	offAny(
-		listener: (
-			eventName: keyof EventData,
-			eventData: EventData[keyof EventData]
-		) => void | Promise<void>
+		listener: (event: EventDataPair<EventData, keyof EventData>) => void | Promise<void>
 	): void;
 
 	/**
 	Clear all event listeners on the instance.
 
-	If `eventName` is given, only the listeners for that event are cleared.
+	If `eventNames` is given, only the listeners for those events are cleared. Accepts a single event name or an array.
+
+	@example
+	```
+	import Emittery from 'emittery';
+
+	const emitter = new Emittery();
+
+	emitter.on('🦄', listener);
+	emitter.on('🐶', listener);
+
+	emitter.clearListeners('🦄'); // Clear a single event
+	emitter.clearListeners(['🐶', '🦊']); // Clear multiple events
+	emitter.clearListeners(); // Clear all events
+	```
 	*/
 	clearListeners<Name extends keyof EventData>(eventName?: Name | readonly Name[]): void;
 
+	/**
+	Register a function to be called when the first `.on()` listener subscribes to `eventName`. The `initFn` can optionally return a cleanup (deinit) function, which is called when the last `.on()` listener unsubscribes (or when `clearListeners()` removes all listeners for that event).
+
+	If `.on()` listeners already exist when `init()` is called, `initFn` is called immediately.
+
+	Note: Lifecycle hooks only apply to `.on()` listeners. Subscriptions via `.events()` async iterators do not trigger the init or deinit functions.
+
+	@returns An unsubscribe function. Calling it removes the init/deinit hooks, and if the init is currently active, it calls deinit immediately.
+
+	@example
+	```
+	import Emittery from 'emittery';
+
+	const emitter = new Emittery();
+
+	emitter.init('mouse', () => {
+		terminal.grabInput({mouse: 'button'});
+
+		terminal.on('mouse', (name, data) => {
+			emitter.emit('mouse', data);
+		});
+
+		return () => {
+			terminal.releaseInput();
+		};
+	});
+
+	// Init is called when the first listener subscribes
+	const off = emitter.on('mouse', handler);
+
+	// Adding more listeners does not call init again
+	emitter.on('mouse', anotherHandler);
+
+	// Removing one listener does not call deinit yet
+	off();
+
+	// Deinit is called when the last listener unsubscribes
+	emitter.off('mouse', anotherHandler);
+	```
+
+	@example
+	```
+	// With `using` for automatic cleanup of hooks
+	{
+		using removeInit = emitter.init('mouse', () => {
+			startListening();
+			return () => stopListening();
+		});
+	} // init/deinit hooks are automatically removed
+	```
+	*/
+	init<Name extends keyof EventData>(
+		eventName: Name,
+		initFn: () => (() => void) | void
+	): UnsubscribeFunction;
+
 	/**
 	The number of listeners for the `eventName` or all events if not specified.
+
+	@example
+	```
+	import Emittery from 'emittery';
+
+	const emitter = new Emittery();
+
+	emitter.on('🦄', listener);
+	emitter.on('🐶', listener);
+
+	emitter.listenerCount('🦄'); // 1
+	emitter.listenerCount(); // 2
+	```
 	*/
 	listenerCount<Name extends keyof EventData>(eventName?: Name | readonly Name[]): number;
 
+	/**
+	Log debug information if debug mode is enabled (either globally via `Emittery.isDebugEnabled` or per-instance via `debug.enabled`).
+	*/
+	logIfDebugEnabled<Name extends keyof EventData>(type: string, eventName?: Name, eventData?: EventData[Name]): void;
+
 	/**
 	Bind the given `methodNames`, or all `Emittery` methods if `methodNames` is not defined, into the `target` object.