emittery 1.0.3 → 1.2.0

package/index.d.ts

@@ -341,7 +341,8 @@ export default class Emittery<
 	*/
 	on<Name extends keyof AllEventData>(
 		eventName: Name | readonly Name[],
-		listener: (eventData: AllEventData[Name]) => void | Promise<void>
+		listener: (eventData: AllEventData[Name]) => void | Promise<void>,
+		options?: {signal?: AbortSignal}
 	): UnsubscribeFunction;
 
 	/**
@@ -461,10 +462,12 @@ export default class Emittery<
 	): void;
 
 	/**
-	Subscribe to one or more events 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 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.
 
-	@returns The promise of event data when `eventName` is emitted. This promise is extended with an `off` method.
+	@returns The promise of event data when `eventName` is emitted and predicate matches (if provided). This promise is extended with an `off` method.
 
 	@example
 	```
@@ -481,11 +484,19 @@ export default class Emittery<
 		console.log(data);
 	});
 
+	// With predicate
+	emitter.once('data', data => data.ok === true).then(data => {
+		console.log(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}
 	```
 	*/
-	once<Name extends keyof AllEventData>(eventName: Name | readonly Name[]): EmitteryOncePromise<AllEventData[Name]>;
+	once<Name extends keyof AllEventData>(eventName: Name | readonly Name[], predicate?: (eventData: AllEventData[Name]) => boolean): EmitteryOncePromise<AllEventData[Name]>;
 
 	/**
 	Trigger an event asynchronously, optionally with some data. Listeners are called in the order they were added, but executed concurrently.
@@ -520,7 +531,8 @@ export default class Emittery<
 		listener: (
 			eventName: keyof EventData,
 			eventData: EventData[keyof EventData]
-		) => void | Promise<void>
+		) => void | Promise<void>,
+		options?: {signal?: AbortSignal}
 	): UnsubscribeFunction;
 
 	/**

package/index.js

@@ -165,13 +165,15 @@ function defaultMethodNamesOrAssert(methodNames) {
 const isMetaEvent = eventName => eventName === listenerAdded || eventName === listenerRemoved;
 
 function emitMetaEvent(emitter, eventName, eventData) {
-	if (isMetaEvent(eventName)) {
-		try {
-			canEmitMetaEvents = true;
-			emitter.emit(eventName, eventData);
-		} finally {
-			canEmitMetaEvents = false;
-		}
+	if (!isMetaEvent(eventName)) {
+		return;
+	}
+
+	try {
+		canEmitMetaEvents = true;
+		emitter.emit(eventName, eventData);
+	} finally {
+		canEmitMetaEvents = false;
 	}
 }
 
@@ -273,7 +275,7 @@ export default class Emittery {
 		}
 	}
 
-	on(eventNames, listener) {
+	on(eventNames, listener, {signal} = {}) {
 		assertListener(listener);
 
 		eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
@@ -295,7 +297,18 @@ export default class Emittery {
 			}
 		}
 
-		return this.off.bind(this, eventNames, listener);
+		const off = () => {
+			this.off(eventNames, listener);
+			signal?.removeEventListener('abort', off);
+		};
+
+		signal?.addEventListener('abort', off, {once: true});
+
+		if (signal?.aborted) {
+			off();
+		}
+
+		return off;
 	}
 
 	off(eventNames, listener) {
@@ -321,11 +334,19 @@ export default class Emittery {
 		}
 	}
 
-	once(eventNames) {
+	once(eventNames, predicate) {
+		if (predicate !== undefined && typeof predicate !== 'function') {
+			throw new TypeError('predicate must be a function');
+		}
+
 		let off_;
 
 		const promise = new Promise(resolve => {
 			off_ = this.on(eventNames, data => {
+				if (predicate && !predicate(data)) {
+					return;
+				}
+
 				off_();
 				resolve(data);
 			});
@@ -405,14 +426,26 @@ export default class Emittery {
 		/* eslint-enable no-await-in-loop */
 	}
 
-	onAny(listener) {
+	onAny(listener, {signal} = {}) {
 		assertListener(listener);
 
 		this.logIfDebugEnabled('subscribeAny', undefined, undefined);
 
 		anyMap.get(this).add(listener);
 		emitMetaEvent(this, listenerAdded, {listener});
-		return this.offAny.bind(this, listener);
+
+		const offAny = () => {
+			this.offAny(listener);
+			signal?.removeEventListener('abort', offAny);
+		};
+
+		signal?.addEventListener('abort', offAny, {once: true});
+
+		if (signal?.aborted) {
+			offAny();
+		}
+
+		return offAny;
 	}
 
 	anyEvent() {

package/package.json

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

package/readme.md

@@ -197,7 +197,7 @@ emitter.emit('test');
 //=> [subscribe]: test
 ```
 
-#### on(eventName | eventName[], listener)
+#### on(eventName | eventName[], listener, options?: {signal?: AbortSignal})
 
 Subscribe to one or more events.
 
@@ -222,6 +222,21 @@ emitter.emit('🦄', '🌈'); // log => '🌈' x2
 emitter.emit('🐶', '🍖'); // log => '🍖'
 ```
 
+You can pass an [abort signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to unsubscribe too:
+
+```js
+import Emittery from 'emittery';
+
+const abortController = new AbortController();
+
+emitter.on('🐗', data => {
+	console.log(data);
+}, {signal: abortController.signal});
+
+abortController.abort();
+emitter.emit('🐗', '🍞'); // nothing happens
+```
+
 ##### Custom subscribable events
 
 Emittery exports some symbols which represent "meta" events that can be passed to `Emitter.on` and similar methods.
@@ -282,11 +297,11 @@ await emitter.emit('🦊', 'c'); // Nothing happens
 
 ##### listener(data)
 
-#### once(eventName | eventName[])
+#### once(eventName | eventName[], predicate?)
 
-Subscribe to one or more events 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 that matches the predicate (if provided).
 
-Returns a promise for the event data when `eventName` is emitted. This promise is extended with an `off` method.
+Returns a promise for the event data when `eventName` is emitted and predicate matches (if provided). This promise is extended with an `off` method.
 
 ```js
 import Emittery from 'emittery';
@@ -302,8 +317,16 @@ emitter.once(['🦄', '🐶']).then(data => {
 	console.log(data);
 });
 
+// With predicate
+emitter.once('data', data => data.ok === true).then(data => {
+	console.log(data);
+	//=> {ok: true, value: 42}
+});
+
 emitter.emit('🦄', '🌈'); // Log => '🌈' x2
 emitter.emit('🐶', '🍖'); // Nothing happens
+emitter.emit('data', {ok: false}); // Nothing happens
+emitter.emit('data', {ok: true, value: 42}); // Log => {ok: true, value: 42}
 ```
 
 #### events(eventName)
@@ -399,11 +422,11 @@ Same as above, but it waits for each listener to resolve before triggering the n
 
 If any of the listeners throw/reject, the returned promise will be rejected with the error and the remaining listeners will *not* be called.
 
-#### onAny(listener)
+#### onAny(listener, options?: {signal?: AbortSignal})
 
 Subscribe to be notified about any event.
 
-Returns a method to unsubscribe.
+Returns a method to unsubscribe. Abort signal is respected too.
 
 ##### listener(eventName, data)