emittery 0.1.2 → 0.4.1

package/Emittery.d.ts

@@ -0,0 +1,131 @@
+export = Emittery;
+
+declare class Emittery {
+	/**
+	 * Subscribe to an event.
+	 *
+	 * Returns an unsubscribe method.
+	 *
+	 * Using the same listener multiple times for the same event will result
+	 * in only one method call per emitted event.
+	 */
+	on(eventName: string, listener: (eventData?: any) => any): Emittery.UnsubscribeFn;
+
+	/**
+	 * Remove an event subscription.
+	 */
+	off(eventName: string, listener: (eventData?: any) => any): void;
+
+	/**
+	 * Subscribe to an event only once. It will be unsubscribed after the first
+	 * event.
+	 *
+	 * Returns a promise for the event data when `eventName` is emitted.
+	 */
+	once(eventName: string): Promise<any>;
+
+	/**
+	 * Trigger an event asynchronously, optionally with some data. Listeners
+	 * are called in the order they were added, but execute concurrently.
+	 *
+	 * Returns a promise for 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 for when all the event listeners are done.
+	 */
+	emit(eventName: string, eventData?: any): Promise<void>;
+
+	/**
+	 * Same as `emit()`, but it waits for each listener to resolve before
+	 * triggering the next one. This can be useful if your events depend on each
+	 * other. Although ideally they should not. Prefer `emit()` whenever
+	 * possible.
+	 *
+	 * 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 for when all the event listeners are done.
+	 */
+	emitSerial(eventName: string, eventData?: any): Promise<void>;
+
+	/**
+	 * Subscribe to be notified about any event.
+	 *
+	 * Returns a method to unsubscribe.
+	 */
+	onAny(listener: (eventName: string, eventData?: any) => any): Emittery.UnsubscribeFn;
+
+	/**
+	 * Remove an `onAny` subscription.
+	 */
+	offAny(listener: (eventName: string, eventData?: any) => any): void;
+
+	/**
+	 * Clear all event listeners on the instance.
+	 *
+	 * If `eventName` is given, only the listeners for that event are cleared.
+	 */
+	clearListeners(eventName?: string): void;
+
+	/**
+	 * The number of listeners for the `eventName` or all events if not
+	 * specified.
+	 */
+	listenerCount(eventName?: string): number;
+}
+
+declare namespace Emittery {
+	/**
+	 * Removes an event subscription.
+	 */
+	type UnsubscribeFn = () => void;
+
+	/**
+	 * Maps event names to their emitted data type.
+	 */
+	interface Events {
+		[eventName: string]: any;
+	}
+
+	/**
+	 * Async event emitter.
+	 *
+	 * Must list supported events and the data type they emit, if any.
+	 *
+	 * For example:
+	 *
+	 * ```ts
+	 * import Emittery = require('emittery');
+	 *
+	 * const ee = new Emittery.Typed<{value: string}, 'open' | 'close'>();
+	 *
+	 * ee.emit('open');
+	 * ee.emit('value', 'foo\n');
+	 * ee.emit('value', 1); // TS compilation error
+	 * ee.emit('end'); // TS compilation error
+	 * ```
+	 */
+	class Typed<EventDataMap extends Events, EmptyEvents extends string = never> extends Emittery {
+		on<Name extends Extract<keyof EventDataMap, string>>(eventName: Name, listener: (eventData: EventDataMap[Name]) => any): Emittery.UnsubscribeFn;
+		on<Name extends EmptyEvents>(eventName: Name, listener: () => any): Emittery.UnsubscribeFn;
+
+		once<Name extends Extract<keyof EventDataMap, string>>(eventName: Name): Promise<EventDataMap[Name]>;
+		once<Name extends EmptyEvents>(eventName: Name): Promise<void>;
+
+		off<Name extends Extract<keyof EventDataMap, string>>(eventName: Name, listener: (eventData: EventDataMap[Name]) => any): void;
+		off<Name extends EmptyEvents>(eventName: Name, listener: () => any): void;
+
+		onAny(listener: (eventName: Extract<keyof EventDataMap, string> | EmptyEvents, eventData?: EventDataMap[Extract<keyof EventDataMap, string>]) => any): Emittery.UnsubscribeFn;
+		offAny(listener: (eventName: Extract<keyof EventDataMap, string> | EmptyEvents, eventData?: EventDataMap[Extract<keyof EventDataMap, string>]) => any): void;
+
+		emit<Name extends Extract<keyof EventDataMap, string>>(eventName: Name, eventData: EventDataMap[Name]): Promise<void>;
+		emit<Name extends EmptyEvents>(eventName: Name): Promise<void>;
+
+		emitSerial<Name extends Extract<keyof EventDataMap, string>>(eventName: Name, eventData: EventDataMap[Name]): Promise<void>;
+		emitSerial<Name extends EmptyEvents>(eventName: Name): Promise<void>;
+	}
+}

package/index.js

@@ -1,37 +1,52 @@
 'use strict';
 
+const anyMap = new WeakMap();
+const eventsMap = new WeakMap();
 const resolvedPromise = Promise.resolve();
 
-module.exports = class Emittery {
-	constructor() {
-		this._events = new Map();
-		this._anyEvents = new Set();
+function assertEventName(eventName) {
+	if (typeof eventName !== 'string') {
+		throw new TypeError('eventName must be a string');
 	}
+}
 
-	_getListeners(eventName) {
-		if (!this._events.has(eventName)) {
-			this._events.set(eventName, new Set());
-		}
+function assertListener(listener) {
+	if (typeof listener !== 'function') {
+		throw new TypeError('listener must be a function');
+	}
+}
 
-		return this._events.get(eventName);
+function getListeners(instance, eventName) {
+	const events = eventsMap.get(instance);
+	if (!events.has(eventName)) {
+		events.set(eventName, new Set());
+	}
+
+	return events.get(eventName);
+}
+
+class Emittery {
+	constructor() {
+		anyMap.set(this, new Set());
+		eventsMap.set(this, new Map());
 	}
 
 	on(eventName, listener) {
-		this._getListeners(eventName).add(listener);
+		assertEventName(eventName);
+		assertListener(listener);
+		getListeners(this, eventName).add(listener);
 		return this.off.bind(this, eventName, listener);
 	}
 
 	off(eventName, listener) {
-		if (!listener) {
-			this._getListeners(eventName).clear();
-			return;
-		}
-
-		this._getListeners(eventName).delete(listener);
+		assertEventName(eventName);
+		assertListener(listener);
+		getListeners(this, eventName).delete(listener);
 	}
 
 	once(eventName) {
 		return new Promise(resolve => {
+			assertEventName(eventName);
 			const off = this.on(eventName, data => {
 				off();
 				resolve(data);
@@ -40,56 +55,98 @@ module.exports = class Emittery {
 	}
 
 	async emit(eventName, eventData) {
+		assertEventName(eventName);
+
+		const listeners = getListeners(this, eventName);
+		const anyListeners = anyMap.get(this);
+		const staticListeners = [...listeners];
+		const staticAnyListeners = [...anyListeners];
+
 		await resolvedPromise;
-		const listeners = [...this._getListeners(eventName)].map(async listener => listener(eventData));
-		const anyListeners = [...this._anyEvents].map(async listener => listener(eventName, eventData));
-		return Promise.all([...listeners, ...anyListeners]);
+		return Promise.all([
+			...staticListeners.map(async listener => {
+				if (listeners.has(listener)) {
+					return listener(eventData);
+				}
+			}),
+			...staticAnyListeners.map(async listener => {
+				if (anyListeners.has(listener)) {
+					return listener(eventName, eventData);
+				}
+			})
+		]);
 	}
 
 	async emitSerial(eventName, eventData) {
-		await resolvedPromise;
+		assertEventName(eventName);
+
+		const listeners = getListeners(this, eventName);
+		const anyListeners = anyMap.get(this);
+		const staticListeners = [...listeners];
+		const staticAnyListeners = [...anyListeners];
 
+		await resolvedPromise;
 		/* eslint-disable no-await-in-loop */
-		for (const listener of this._getListeners(eventName)) {
-			await listener(eventData);
+		for (const listener of staticListeners) {
+			if (listeners.has(listener)) {
+				await listener(eventData);
+			}
 		}
 
-		for (const listener of this._anyEvents) {
-			await listener(eventName, eventData);
+		for (const listener of staticAnyListeners) {
+			if (anyListeners.has(listener)) {
+				await listener(eventName, eventData);
+			}
 		}
 		/* eslint-enable no-await-in-loop */
 	}
 
 	onAny(listener) {
-		this._anyEvents.add(listener);
+		assertListener(listener);
+		anyMap.get(this).add(listener);
 		return this.offAny.bind(this, listener);
 	}
 
 	offAny(listener) {
-		if (!listener) {
-			this._anyEvents.clear();
-			return;
-		}
-
-		this._anyEvents.delete(listener);
+		assertListener(listener);
+		anyMap.get(this).delete(listener);
 	}
 
-	clear() {
-		this._events.clear();
-		this._anyEvents.clear();
+	clearListeners(eventName) {
+		if (typeof eventName === 'string') {
+			getListeners(this, eventName).clear();
+		} else {
+			anyMap.get(this).clear();
+			for (const listeners of eventsMap.get(this).values()) {
+				listeners.clear();
+			}
+		}
 	}
 
 	listenerCount(eventName) {
-		if (!eventName) {
-			let count = this._anyEvents.size;
+		if (typeof eventName === 'string') {
+			return anyMap.get(this).size + getListeners(this, eventName).size;
+		}
 
-			for (const value of this._events.values()) {
-				count += value.size;
-			}
+		if (typeof eventName !== 'undefined') {
+			assertEventName(eventName);
+		}
 
-			return count;
+		let count = anyMap.get(this).size;
+
+		for (const value of eventsMap.get(this).values()) {
+			count += value.size;
 		}
 
-		return this._anyEvents.size + this._getListeners(eventName).size;
+		return count;
 	}
-};
+}
+
+// Subclass used to encourage TS users to type their events.
+Emittery.Typed = class extends Emittery {};
+Object.defineProperty(Emittery.Typed, 'Typed', {
+	enumerable: false,
+	value: undefined
+});
+
+module.exports = Emittery;

package/legacy.d.ts

@@ -0,0 +1,2 @@
+import Emittery = require('./Emittery')
+export = Emittery

package/legacy.js

@@ -0,0 +1,171 @@
+'use strict';
+
+function _asyncToGenerator(fn) { return function () { var gen = fn.apply(this, arguments); return new Promise(function (resolve, reject) { function step(key, arg) { try { var info = gen[key](arg); var value = info.value; } catch (error) { reject(error); return; } if (info.done) { resolve(value); } else { return Promise.resolve(value).then(function (value) { step("next", value); }, function (err) { step("throw", err); }); } } return step("next"); }); }; }
+
+const anyMap = new WeakMap();
+const eventsMap = new WeakMap();
+const resolvedPromise = Promise.resolve();
+
+function assertEventName(eventName) {
+	if (typeof eventName !== 'string') {
+		throw new TypeError('eventName must be a string');
+	}
+}
+
+function assertListener(listener) {
+	if (typeof listener !== 'function') {
+		throw new TypeError('listener must be a function');
+	}
+}
+
+function getListeners(instance, eventName) {
+	const events = eventsMap.get(instance);
+	if (!events.has(eventName)) {
+		events.set(eventName, new Set());
+	}
+
+	return events.get(eventName);
+}
+
+class Emittery {
+	constructor() {
+		anyMap.set(this, new Set());
+		eventsMap.set(this, new Map());
+	}
+
+	on(eventName, listener) {
+		assertEventName(eventName);
+		assertListener(listener);
+		getListeners(this, eventName).add(listener);
+		return this.off.bind(this, eventName, listener);
+	}
+
+	off(eventName, listener) {
+		assertEventName(eventName);
+		assertListener(listener);
+		getListeners(this, eventName).delete(listener);
+	}
+
+	once(eventName) {
+		return new Promise(resolve => {
+			assertEventName(eventName);
+			const off = this.on(eventName, data => {
+				off();
+				resolve(data);
+			});
+		});
+	}
+
+	emit(eventName, eventData) {
+		var _this = this;
+
+		return _asyncToGenerator(function* () {
+			assertEventName(eventName);
+
+			const listeners = getListeners(_this, eventName);
+			const anyListeners = anyMap.get(_this);
+			const staticListeners = [...listeners];
+			const staticAnyListeners = [...anyListeners];
+
+			yield resolvedPromise;
+			return Promise.all([...staticListeners.map((() => {
+				var _ref = _asyncToGenerator(function* (listener) {
+					if (listeners.has(listener)) {
+						return listener(eventData);
+					}
+				});
+
+				return function (_x) {
+					return _ref.apply(this, arguments);
+				};
+			})()), ...staticAnyListeners.map((() => {
+				var _ref2 = _asyncToGenerator(function* (listener) {
+					if (anyListeners.has(listener)) {
+						return listener(eventName, eventData);
+					}
+				});
+
+				return function (_x2) {
+					return _ref2.apply(this, arguments);
+				};
+			})())]);
+		})();
+	}
+
+	emitSerial(eventName, eventData) {
+		var _this2 = this;
+
+		return _asyncToGenerator(function* () {
+			assertEventName(eventName);
+
+			const listeners = getListeners(_this2, eventName);
+			const anyListeners = anyMap.get(_this2);
+			const staticListeners = [...listeners];
+			const staticAnyListeners = [...anyListeners];
+
+			yield resolvedPromise;
+			/* eslint-disable no-await-in-loop */
+			for (const listener of staticListeners) {
+				if (listeners.has(listener)) {
+					yield listener(eventData);
+				}
+			}
+
+			for (const listener of staticAnyListeners) {
+				if (anyListeners.has(listener)) {
+					yield listener(eventName, eventData);
+				}
+			}
+			/* eslint-enable no-await-in-loop */
+		})();
+	}
+
+	onAny(listener) {
+		assertListener(listener);
+		anyMap.get(this).add(listener);
+		return this.offAny.bind(this, listener);
+	}
+
+	offAny(listener) {
+		assertListener(listener);
+		anyMap.get(this).delete(listener);
+	}
+
+	clearListeners(eventName) {
+		if (typeof eventName === 'string') {
+			getListeners(this, eventName).clear();
+		} else {
+			anyMap.get(this).clear();
+			for (const listeners of eventsMap.get(this).values()) {
+				listeners.clear();
+			}
+		}
+	}
+
+	listenerCount(eventName) {
+		if (typeof eventName === 'string') {
+			return anyMap.get(this).size + getListeners(this, eventName).size;
+		}
+
+		if (typeof eventName !== 'undefined') {
+			assertEventName(eventName);
+		}
+
+		let count = anyMap.get(this).size;
+
+		for (const value of eventsMap.get(this).values()) {
+			count += value.size;
+		}
+
+		return count;
+	}
+}
+
+// Subclass used to encourage TS users to type their events.
+Emittery.Typed = class extends Emittery {};
+Object.defineProperty(Emittery.Typed, 'Typed', {
+	enumerable: false,
+	value: undefined
+});
+
+module.exports = Emittery;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "emittery",
-	"version": "0.1.2",
+	"version": "0.4.1",
 	"description": "Simple and modern async event emitter",
 	"license": "MIT",
 	"repository": "sindresorhus/emittery",
@@ -10,14 +10,21 @@
 		"url": "sindresorhus.com"
 	},
 	"engines": {
-		"node": ">=8"
+		"node": ">=6"
 	},
 	"scripts": {
-		"test": "xo && ava"
+		"build": "babel --out-file=legacy.js index.js",
+		"build:watch": "npm run build -- --watch",
+		"prepare": "npm run build",
+		"test": "xo && tsc --noEmit && nyc ava"
 	},
 	"files": [
-		"index.js"
+		"Emittery.d.ts",
+		"index.js",
+		"legacy.js",
+		"legacy.d.ts"
 	],
+	"typings": "./Emittery.d.ts",
 	"keywords": [
 		"event",
 		"emitter",
@@ -43,8 +50,24 @@
 		"promise"
 	],
 	"devDependencies": {
+		"@types/node": "^10.1.2",
 		"ava": "*",
-		"delay": "^2.0.0",
+		"babel-cli": "^6.26.0",
+		"babel-core": "^6.26.0",
+		"babel-plugin-transform-async-to-generator": "^6.24.1",
+		"codecov": "^3.0.0",
+		"delay": "^3.0.0",
+		"glob": "^7.1.2",
+		"nyc": "^12.0.2",
+		"ts-node": "^6.0.3",
+		"typescript": "^2.9.0",
 		"xo": "*"
+	},
+	"nyc": {
+		"reporter": [
+			"html",
+			"lcov",
+			"text"
+		]
 	}
 }

package/readme.md

@@ -2,10 +2,12 @@
 
 > Simple and modern async event emitter
 
-[![Build Status](https://travis-ci.org/sindresorhus/emittery.svg?branch=master)](https://travis-ci.org/sindresorhus/emittery)
+[![Build Status](https://travis-ci.org/sindresorhus/emittery.svg?branch=master)](https://travis-ci.org/sindresorhus/emittery) [![codecov](https://codecov.io/gh/sindresorhus/emittery/branch/master/graph/badge.svg)](https://codecov.io/gh/sindresorhus/emittery)
 
 It's only ~200 bytes minified and gzipped. [I'm not fanatic about keeping the size at this level though.](https://github.com/sindresorhus/emittery/pull/5#issuecomment-347479211)
 
+It's works in Node.js and the browser (using a bundler).
+
 Emitting events asynchronously is important for production code where you want the least amount of synchronous operations.
 
 
@@ -30,6 +32,10 @@ emitter.on('🦄', data => {
 emitter.emit('🦄', '🌈');
 ```
 
+### Node.js 6
+
+The above only works in Node.js 8 or newer. For older Node.js versions you can use `require('emittery/legacy')`.
+
 
 ## API
 
@@ -45,11 +51,11 @@ Using the same listener multiple times for the same event will result in only on
 
 ##### listener(data)
 
-#### off(eventName, [listener])
+#### off(eventName, listener)
 
-Unsubscribe to an event.
+Remove an event subscription.
 
-If you don't pass in a `listener`, it will remove all listeners for that event.
+##### listener(data)
 
 #### once(eventName)
 
@@ -78,7 +84,7 @@ 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.
 
-#### onAll(listener)
+#### onAny(listener)
 
 Subscribe to be notified about any event.
 
@@ -86,20 +92,44 @@ Returns a method to unsubscribe.
 
 ##### listener(eventName, data)
 
-#### offAny([listener])
-
-Unsubscribe an `onAny` listener.
+#### offAny(listener)
 
-If you don't pass in a `listener`, it will remove all `onAny` listeners.
+Remove an `onAny` subscription.
 
-#### clear()
+#### clearListeners()
 
 Clear all event listeners on the instance.
 
+If `eventName` is given, only the listeners for that event are cleared.
+
 #### listenerCount([eventName])
 
 The number of listeners for the `eventName` or all events if not specified.
 
+## TypeScript
+
+Definition for `emittery` and `emittery/legacy` are included. Use `import Emittery = require('emittery')` or `import Emittery = require('emittery/legacy')` to load the desired implementation.
+
+The default `Emittery` class does not let you type allowed event names and their associated data. However you can use `Emittery.Typed` with generics:
+
+```ts
+import Emittery = require('emittery');
+
+const ee = new Emittery.Typed<{value: string}, 'open' | 'close'>();
+
+ee.emit('open');
+ee.emit('value', 'foo\n');
+ee.emit('value', 1); // TS compilation error
+ee.emit('end'); // TS compilation error
+```
+
+
+## Scheduling details
+
+Listeners are not invoked for events emitted *before* the listener was added. Removing a listener will prevent that listener from being invoked, even if events are in the process of being (asynchronously!) emitted. This also applies to `.clearListeners()`, which removes all listeners. Listeners will be called in the order they were added. So-called *any* listeners are called *after* event-specific listeners.
+
+Note that when using `.emitSerial()`, a slow listener will delay invocation of subsequent listeners. It's possible for newer events to overtake older ones.
+
 
 ## FAQ
 
@@ -130,11 +160,14 @@ But I would argue doing that shows a deeper lack of Node.js and async comprehens
 
 ### Can you support multiple arguments for `emit()`?
 
-No, just use the [spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator):
+No, just use [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment):
 
 ```js
+emitter.on('🦄', ([foo, bar]) => {
+	console.log(foo, bar);
+});
+
 emitter.emit('🦄', [foo, bar]);
-emitter.on('🦄', data => console.log(...data));
 ```