emittery 0.6.0 → 0.7.0

package/index.d.ts

@@ -5,6 +5,11 @@ Symbol event names can be used to avoid name collisions when your classes are ex
 */
 type EventName = string | symbol;
 
+/**
+Emittery also accepts an array of strings and symbols as event names.
+*/
+type EventNames = EventName | readonly EventName[];
+
 declare class Emittery {
 	/**
 	In TypeScript, it returns a decorator which mixins `Emittery` as property `emitteryPropertyName` and `methodNames`, or all `Emittery` methods if `methodNames` is not defined, into the target class.
@@ -78,14 +83,31 @@ declare class Emittery {
 	static readonly listenerRemoved: unique symbol;
 
 	/**
-	Subscribe to an event.
+	Subscribe to one or more events.
 
 	Using the same listener multiple times for the same event will result in only one method call per emitted event.
 
 	@returns An unsubscribe method.
+
+	@example
+	```
+	import Emittery = require('emittery');
+
+	const emitter = new Emittery();
+
+	emitter.on('🦄', data => {
+		console.log(data);
+	});
+	emitter.on(['🦄', '🐶'], data => {
+		console.log(data);
+	});
+
+	emitter.emit('🦄', '🌈'); // log => '🌈' x2
+	emitter.emit('🐶', '🍖'); // log => '🍖'
+	```
 	*/
 	on(eventName: typeof Emittery.listenerAdded | typeof Emittery.listenerRemoved, listener: (eventData: Emittery.ListenerChangedData) => void): Emittery.UnsubscribeFn
-	on(eventName: EventName, listener: (eventData?: unknown) => void): Emittery.UnsubscribeFn;
+	on(eventName: EventNames, listener: (eventData?: unknown) => void): Emittery.UnsubscribeFn;
 
 	/**
 	Get an async iterator which buffers data each time an event is emitted.
@@ -139,22 +161,90 @@ declare class Emittery {
 		}
 	}
 	```
+
+	It accepts multiple event names.
+
+	@example
+	```
+	import Emittery = require('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
+		});
+	```
 	*/
-	events(eventName: EventName): AsyncIterableIterator<unknown>
+	events(eventName: EventNames): AsyncIterableIterator<unknown>
 
 	/**
-	Remove an event subscription.
+	Remove one or more event subscriptions.
+
+	@example
+	```
+	import Emittery = require('emittery');
+
+	const emitter = new Emittery();
+
+	const listener = data => console.log(data);
+	(async () => {
+		emitter.on(['🦄', '🐶', '🦊'], listener);
+		await emitter.emit('🦄', 'a');
+		await emitter.emit('🐶', 'b');
+		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
+	})();
+	```
 	*/
-	off(eventName: EventName, listener: (eventData?: unknown) => void): void;
+	off(eventName: EventNames, listener: (eventData?: unknown) => void): void;
 
 	/**
-	Subscribe to an event only once. It will be unsubscribed after the first
+	Subscribe to one or more events only once. It will be unsubscribed after the first
 	event.
 
 	@returns The event data when `eventName` is emitted.
+
+	@example
+	```
+	import Emittery = require('emittery');
+
+	const emitter = new Emittery();
+
+	emitter.once('🦄').then(data => {
+		console.log(data);
+		//=> '🌈'
+	});
+	emitter.once(['🦄', '🐶']).then(data => {
+		console.log(data);
+	});
+
+	emitter.emit('🦄', '🌈'); // Logs `🌈` twice
+	emitter.emit('🐶', '🍖'); // Nothing happens
+	```
 	*/
 	once(eventName: typeof Emittery.listenerAdded | typeof Emittery.listenerRemoved): Promise<Emittery.ListenerChangedData>
-	once(eventName: EventName): Promise<unknown>;
+	once(eventName: EventNames): Promise<unknown>;
 
 	/**
 	Trigger an event asynchronously, optionally with some data. Listeners are called in the order they were added, but executed concurrently.
@@ -225,12 +315,12 @@ declare class Emittery {
 
 	If `eventName` is given, only the listeners for that event are cleared.
 	*/
-	clearListeners(eventName?: EventName): void;
+	clearListeners(eventName?: EventNames): void;
 
 	/**
 	The number of listeners for the `eventName` or all events if not specified.
 	*/
-	listenerCount(eventName?: EventName): number;
+	listenerCount(eventName?: EventNames): number;
 
 	/**
 	Bind the given `methodNames`, or all `Emittery` methods if `methodNames` is not defined, into the `target` object.

package/index.js

@@ -56,7 +56,9 @@ function enqueueProducers(instance, eventName, eventData) {
 	}
 }
 
-function iterator(instance, eventName) {
+function iterator(instance, eventNames) {
+	eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
+
 	let isFinished = false;
 	let flush = () => {};
 	let queue = [];
@@ -72,7 +74,9 @@ function iterator(instance, eventName) {
 		}
 	};
 
-	getEventProducers(instance, eventName).add(producer);
+	for (const eventName of eventNames) {
+		getEventProducers(instance, eventName).add(producer);
+	}
 
 	return {
 		async next() {
@@ -101,7 +105,11 @@ function iterator(instance, eventName) {
 
 		async return(value) {
 			queue = undefined;
-			getEventProducers(instance, eventName).delete(producer);
+
+			for (const eventName of eventNames) {
+				getEventProducers(instance, eventName).delete(producer);
+			}
+
 			flush();
 
 			return arguments.length > 0 ?
@@ -187,42 +195,52 @@ class Emittery {
 		producersMap.set(this, new Map());
 	}
 
-	on(eventName, listener) {
-		assertEventName(eventName);
+	on(eventNames, listener) {
 		assertListener(listener);
-		getListeners(this, eventName).add(listener);
 
-		if (!isListenerSymbol(eventName)) {
-			this.emit(listenerAdded, {eventName, listener});
+		eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
+		for (const eventName of eventNames) {
+			assertEventName(eventName);
+			getListeners(this, eventName).add(listener);
+
+			if (!isListenerSymbol(eventName)) {
+				this.emit(listenerAdded, {eventName, listener});
+			}
 		}
 
-		return this.off.bind(this, eventName, listener);
+		return this.off.bind(this, eventNames, listener);
 	}
 
-	off(eventName, listener) {
-		assertEventName(eventName);
+	off(eventNames, listener) {
 		assertListener(listener);
 
-		if (!isListenerSymbol(eventName)) {
-			this.emit(listenerRemoved, {eventName, listener});
-		}
+		eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
+		for (const eventName of eventNames) {
+			assertEventName(eventName);
+			getListeners(this, eventName).delete(listener);
 
-		getListeners(this, eventName).delete(listener);
+			if (!isListenerSymbol(eventName)) {
+				this.emit(listenerRemoved, {eventName, listener});
+			}
+		}
 	}
 
-	once(eventName) {
+	once(eventNames) {
 		return new Promise(resolve => {
-			assertEventName(eventName);
-			const off = this.on(eventName, data => {
+			const off = this.on(eventNames, data => {
 				off();
 				resolve(data);
 			});
 		});
 	}
 
-	events(eventName) {
-		assertEventName(eventName);
-		return iterator(this, eventName);
+	events(eventNames) {
+		eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
+		for (const eventName of eventNames) {
+			assertEventName(eventName);
+		}
+
+		return iterator(this, eventNames);
 	}
 
 	async emit(eventName, eventData) {
@@ -236,7 +254,7 @@ class Emittery {
 		const staticAnyListeners = isListenerSymbol(eventName) ? [] : [...anyListeners];
 
 		await resolvedPromise;
-		return Promise.all([
+		await Promise.all([
 			...staticListeners.map(async listener => {
 				if (listeners.has(listener)) {
 					return listener(eventData);
@@ -291,52 +309,62 @@ class Emittery {
 		anyMap.get(this).delete(listener);
 	}
 
-	clearListeners(eventName) {
-		if (typeof eventName === 'string') {
-			getListeners(this, eventName).clear();
+	clearListeners(eventNames) {
+		eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
 
-			const producers = getEventProducers(this, eventName);
+		for (const eventName of eventNames) {
+			if (typeof eventName === 'string') {
+				getListeners(this, eventName).clear();
 
-			for (const producer of producers) {
-				producer.finish();
-			}
-
-			producers.clear();
-		} else {
-			anyMap.get(this).clear();
+				const producers = getEventProducers(this, eventName);
 
-			for (const listeners of eventsMap.get(this).values()) {
-				listeners.clear();
-			}
-
-			for (const producers of producersMap.get(this).values()) {
 				for (const producer of producers) {
 					producer.finish();
 				}
 
 				producers.clear();
+			} else {
+				anyMap.get(this).clear();
+
+				for (const listeners of eventsMap.get(this).values()) {
+					listeners.clear();
+				}
+
+				for (const producers of producersMap.get(this).values()) {
+					for (const producer of producers) {
+						producer.finish();
+					}
+
+					producers.clear();
+				}
 			}
 		}
 	}
 
-	listenerCount(eventName) {
-		if (typeof eventName === 'string') {
-			return anyMap.get(this).size + getListeners(this, eventName).size +
-				getEventProducers(this, eventName).size + getEventProducers(this).size;
-		}
+	listenerCount(eventNames) {
+		eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
+		let count = 0;
 
-		if (typeof eventName !== 'undefined') {
-			assertEventName(eventName);
-		}
+		for (const eventName of eventNames) {
+			if (typeof eventName === 'string') {
+				count += anyMap.get(this).size + getListeners(this, eventName).size +
+					getEventProducers(this, eventName).size + getEventProducers(this).size;
+				continue;
+			}
 
-		let count = anyMap.get(this).size;
+			if (typeof eventName !== 'undefined') {
+				assertEventName(eventName);
+			}
 
-		for (const value of eventsMap.get(this).values()) {
-			count += value.size;
-		}
+			count += anyMap.get(this).size;
+
+			for (const value of eventsMap.get(this).values()) {
+				count += value.size;
+			}
 
-		for (const value of producersMap.get(this).values()) {
-			count += value.size;
+			for (const value of producersMap.get(this).values()) {
+				count += value.size;
+			}
 		}
 
 		return count;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "emittery",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Simple and modern async event emitter",
 	"license": "MIT",
 	"repository": "sindresorhus/emittery",

package/readme.md

@@ -45,14 +45,30 @@ Symbol event names can be used to avoid name collisions when your classes are ex
 
 ### emitter = new Emittery()
 
-#### on(eventName, listener)
+#### on(eventName | eventName[], listener)
 
-Subscribe to an event.
+Subscribe to one or more events.
 
 Returns an unsubscribe method.
 
 Using the same listener multiple times for the same event will result in only one method call per emitted event.
 
+```js
+const Emittery = require('emittery');
+
+const emitter = new Emittery();
+
+emitter.on('🦄', data => {
+	console.log(data);
+});
+emitter.on(['🦄', '🐶'], data => {
+	console.log(data);
+});
+
+emitter.emit('🦄', '🌈'); // log => '🌈' x2
+emitter.emit('🐶', '🍖'); // log => '🍖'
+```
+
 ##### Custom subscribable events
 
 Emittery exports some symbols which represent custom events that can be passed to `Emitter.on` and similar methods.
@@ -87,15 +103,34 @@ Only events that are not of this type are able to trigger these events.
 
 ##### listener(data)
 
-#### off(eventName, listener)
+#### off(eventName | eventName[], listener)
+
+Remove one or more event subscriptions.
+
+```js
+const Emittery = require('emittery');
+
+const emitter = new Emittery();
 
-Remove an event subscription.
+const listener = data => console.log(data);
+(async () => {
+	emitter.on(['🦄', '🐶', '🦊'], listener);
+	await emitter.emit('🦄', 'a');
+	await emitter.emit('🐶', 'b');
+	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
+})();
+```
 
 ##### listener(data)
 
-#### once(eventName)
+#### once(eventName | eventName[])
 
-Subscribe to an event only once. It will be unsubscribed after the first event.
+Subscribe to one or more events only once. It will be unsubscribed after the first event.
 
 Returns a promise for the event data when `eventName` is emitted.
 
@@ -108,8 +143,12 @@ emitter.once('🦄').then(data => {
 	console.log(data);
 	//=> '🌈'
 });
+emitter.once(['🦄', '🐶']).then(data => {
+	console.log(data);
+});
 
-emitter.emit('🦄', '🌈');
+emitter.emit('🦄', '🌈'); // log => '🌈' x2
+emitter.emit('🐶', '🍖'); // nothing happens
 ```
 
 #### events(eventName)
@@ -164,6 +203,35 @@ for await (const data of iterator) {
 }
 ```
 
+It accepts multiple event names.
+
+```js
+const Emittery = require('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
+	});
+```
+
 #### emit(eventName, data?)
 
 Trigger an event asynchronously, optionally with some data. Listeners are called in the order they were added, but executed concurrently.
@@ -222,15 +290,15 @@ iterator.next()
 
 In the same way as for `events`, you can subscribe by using the `for await` statement
 
-#### clearListeners()
+#### clearListeners(eventNames?)
 
 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 that events are cleared.
 
-#### listenerCount(eventName?)
+#### listenerCount(eventNames?)
 
-The number of listeners for the `eventName` or all events if not specified.
+The number of listeners for the `eventNames` or all events if not specified.
 
 #### bindMethods(target, methodNames?)