emittery 0.8.0 → 0.9.2

package/index.d.ts

@@ -1,3 +1,5 @@
+/* eslint-disable no-redeclare */
+
 /**
 Emittery accepts strings and symbols as event names.
 
@@ -10,6 +12,126 @@ type DatalessEventNames<EventData> = {
 	[Key in keyof EventData]: EventData[Key] extends undefined ? Key : never;
 }[keyof EventData];
 
+declare const listenerAdded: unique symbol;
+declare const listenerRemoved: unique symbol;
+type OmnipresentEventData = {[listenerAdded]: Emittery.ListenerChangedData; [listenerRemoved]: Emittery.ListenerChangedData};
+
+/**
+Emittery can collect and log debug information.
+
+To enable this feature set the `DEBUG` environment variable to `emittery` or `*`. Additionally, you can set the static `isDebugEnabled` variable to true on the Emittery class, or `myEmitter.debug.enabled` on an instance of it for debugging a single instance.
+
+See API for more information on how debugging works.
+*/
+type DebugLogger<EventData, Name extends keyof EventData> = (type: string, debugName: string, eventName?: Name, eventData?: EventData[Name]) => void;
+
+/**
+Configure debug options of an instance.
+*/
+interface DebugOptions<EventData> {
+	/**
+	Define a name for the instance of Emittery to use when outputting debug data.
+
+	@default undefined
+
+	@example
+	```
+	import Emittery = require('emittery');
+
+	Emittery.isDebugEnabled = true;
+
+	const emitter = new Emittery({debug: {name: 'myEmitter'}});
+
+	emitter.on('test', data => {
+		// …
+	});
+
+	emitter.emit('test');
+	//=> [16:43:20.417][emittery:subscribe][myEmitter] Event Name: test
+	//	data: undefined
+	```
+	*/
+	readonly name: string;
+
+	/**
+	Toggle debug logging just for this instance.
+
+	@default false
+
+	@example
+	```
+	import Emittery = require('emittery');
+
+	const emitter1 = new Emittery({debug: {name: 'emitter1', enabled: true}});
+	const emitter2 = new Emittery({debug: {name: 'emitter2'}});
+
+	emitter1.on('test', data => {
+		// …
+	});
+
+	emitter2.on('test', data => {
+		// …
+	});
+
+	emitter1.emit('test');
+	//=> [16:43:20.417][emittery:subscribe][emitter1] Event Name: test
+	//	data: undefined
+
+	emitter2.emit('test');
+	```
+	*/
+	enabled?: boolean;
+
+	/**
+	Function that handles debug data.
+
+	@default
+	```
+	(type, debugName, eventName, eventData) => {
+		eventData = JSON.stringify(eventData);
+
+		if (typeof eventName === 'symbol') {
+			eventName = eventName.toString();
+		}
+
+		const currentTime = new Date();
+		const logTime = `${currentTime.getHours()}:${currentTime.getMinutes()}:${currentTime.getSeconds()}.${currentTime.getMilliseconds()}`;
+		console.log(`[${logTime}][emittery:${type}][${debugName}] Event Name: ${eventName}\n\tdata: ${eventData}`);
+	}
+	```
+
+	@example
+	```
+	import Emittery = require('emittery');
+
+	const myLogger = (type, debugName, eventName, eventData) => console.log(`[${type}]: ${eventName}`);
+
+	const emitter = new Emittery({
+		debug: {
+			name: 'myEmitter',
+			enabled: true,
+			logger: myLogger
+		}
+	});
+
+	emitter.on('test', data => {
+		// …
+	});
+
+	emitter.emit('test');
+	//=> [subscribe]: test
+	```
+	*/
+	logger?: DebugLogger<EventData, keyof EventData>;
+}
+
+/**
+Configuration options for Emittery.
+*/
+interface Options<EventData> {
+	debug?: DebugOptions<EventData>;
+}
+
 /**
 Emittery is a strictly typed, fully async EventEmitter implementation. Event listeners can be registered with `on` or `once`, and events can be emitted with `emit`.
 
@@ -43,8 +165,42 @@ emitter.emit('other');
 */
 declare class Emittery<
 	EventData = Record<string, any>, // When https://github.com/microsoft/TypeScript/issues/1863 ships, we can switch this to have an index signature including Symbols. If you want to use symbol keys right now, you need to pass an interface with those symbol keys explicitly listed.
+	AllEventData = EventData & OmnipresentEventData,
 	DatalessEvents = DatalessEventNames<EventData>
 > {
+	/**
+	Toggle debug mode for all instances.
+
+	Default: `true` if the `DEBUG` environment variable is set to `emittery` or `*`, otherwise `false`.
+
+	@example
+	```
+	import Emittery = require('emittery');
+
+	Emittery.isDebugEnabled = true;
+
+	const emitter1 = new Emittery({debug: {name: 'myEmitter1'}});
+	const emitter2 = new Emittery({debug: {name: 'myEmitter2'}});
+
+	emitter1.on('test', data => {
+		// …
+	});
+
+	emitter2.on('otherTest', data => {
+		// …
+	});
+
+	emitter1.emit('test');
+	//=> [16:43:20.417][emittery:subscribe][myEmitter1] Event Name: test
+	//	data: undefined
+
+	emitter2.emit('otherTest');
+	//=> [16:43:20.417][emittery:subscribe][myEmitter2] Event Name: otherTest
+	//	data: undefined
+	```
+	*/
+	static isDebugEnabled: boolean;
+
 	/**
 	Fires when an event listener was added.
 
@@ -69,7 +225,7 @@ declare class Emittery<
 	});
 	```
 	*/
-	static readonly listenerAdded: unique symbol;
+	static readonly listenerAdded: typeof listenerAdded;
 
 	/**
 	Fires when an event listener was removed.
@@ -97,7 +253,19 @@ declare class Emittery<
 	off();
 	```
 	*/
-	static readonly listenerRemoved: unique symbol;
+	static readonly listenerRemoved: typeof listenerRemoved;
+
+	/**
+	Debugging options for the current instance.
+	*/
+	debug: DebugOptions<EventData>;
+
+	/**
+	Create a new Emittery instance with the specified options.
+
+	@returns An instance of Emittery that you can use to listen for and emit events.
+	*/
+	constructor(options?: Options<EventData>);
 
 	/**
 	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.
@@ -117,7 +285,7 @@ declare class Emittery<
 	static mixin(
 		emitteryPropertyName: string | symbol,
 		methodNames?: readonly string[]
-	): <T extends { new (): any }>(klass: T) => T; // eslint-disable-line @typescript-eslint/prefer-function-type
+	): <T extends {new (): any}>(klass: T) => T; // eslint-disable-line @typescript-eslint/prefer-function-type
 
 	/**
 	Subscribe to one or more events.
@@ -135,6 +303,7 @@ declare class Emittery<
 	emitter.on('🦄', data => {
 		console.log(data);
 	});
+
 	emitter.on(['🦄', '🐶'], data => {
 		console.log(data);
 	});
@@ -143,13 +312,9 @@ declare class Emittery<
 	emitter.emit('🐶', '🍖'); // log => '🍖'
 	```
 	*/
-	on<Name extends keyof EventData>(
+	on<Name extends keyof AllEventData>(
 		eventName: Name,
-		listener: (eventData: EventData[Name]) => void | Promise<void>
-	): Emittery.UnsubscribeFn;
-	on(
-		eventName: typeof Emittery.listenerAdded | typeof Emittery.listenerRemoved,
-		listener: (eventData: Emittery.ListenerChangedData) => void | Promise<void>
+		listener: (eventData: AllEventData[Name]) => void | Promise<void>
 	): Emittery.UnsubscribeFn;
 
 	/**
@@ -236,7 +401,7 @@ declare class Emittery<
 	```
 	*/
 	events<Name extends keyof EventData>(
-		eventName: Name
+		eventName: Name | Name[]
 	): AsyncIterableIterator<EventData[Name]>;
 
 	/**
@@ -262,9 +427,9 @@ declare class Emittery<
 	})();
 	```
 	*/
-	off<Name extends keyof EventData>(
+	off<Name extends keyof AllEventData>(
 		eventName: Name,
-		listener: (eventData: EventData[Name]) => void | Promise<void>
+		listener: (eventData: AllEventData[Name]) => void | Promise<void>
 	): void;
 
 	/**
@@ -283,6 +448,7 @@ declare class Emittery<
 		console.log(data);
 		//=> '🌈'
 	});
+
 	emitter.once(['🦄', '🐶']).then(data => {
 		console.log(data);
 	});
@@ -291,10 +457,7 @@ declare class Emittery<
 	emitter.emit('🐶', '🍖'); // Nothing happens
 	```
 	*/
-	once<Name extends keyof EventData>(eventName: Name): Promise<EventData[Name]>;
-	once(
-		eventName: typeof Emittery.listenerAdded | typeof Emittery.listenerRemoved
-	): Promise<Emittery.ListenerChangedData>;
+	once<Name extends keyof AllEventData>(eventName: Name): Promise<AllEventData[Name]>;
 
 	/**
 	Trigger an event asynchronously, optionally with some data. Listeners are called in the order they were added, but executed concurrently.

package/index.js

@@ -9,6 +9,8 @@ const resolvedPromise = Promise.resolve();
 const listenerAdded = Symbol('listenerAdded');
 const listenerRemoved = Symbol('listenerRemoved');
 
+let isGlobalDebugEnabled = false;
+
 function assertEventName(eventName) {
 	if (typeof eventName !== 'string' && typeof eventName !== 'symbol') {
 		throw new TypeError('eventName must be a string or a symbol');
@@ -189,10 +191,48 @@ class Emittery {
 		};
 	}
 
-	constructor() {
+	static get isDebugEnabled() {
+		if (typeof process !== 'object') {
+			return isGlobalDebugEnabled;
+		}
+
+		const {env} = process || {env: {}};
+		return env.DEBUG === 'emittery' || env.DEBUG === '*' || isGlobalDebugEnabled;
+	}
+
+	static set isDebugEnabled(newValue) {
+		isGlobalDebugEnabled = newValue;
+	}
+
+	constructor(options = {}) {
 		anyMap.set(this, new Set());
 		eventsMap.set(this, new Map());
 		producersMap.set(this, new Map());
+		this.debug = options.debug || {};
+
+		if (this.debug.enabled === undefined) {
+			this.debug.enabled = false;
+		}
+
+		if (!this.debug.logger) {
+			this.debug.logger = (type, debugName, eventName, eventData) => {
+				eventData = JSON.stringify(eventData);
+
+				if (typeof eventName === 'symbol') {
+					eventName = eventName.toString();
+				}
+
+				const currentTime = new Date();
+				const logTime = `${currentTime.getHours()}:${currentTime.getMinutes()}:${currentTime.getSeconds()}.${currentTime.getMilliseconds()}`;
+				console.log(`[${logTime}][emittery:${type}][${debugName}] Event Name: ${eventName}\n\tdata: ${eventData}`);
+			};
+		}
+	}
+
+	logIfDebugEnabled(type, eventName, eventData) {
+		if (Emittery.isDebugEnabled || this.debug.enabled) {
+			this.debug.logger(type, this.debug.name, eventName, eventData);
+		}
 	}
 
 	on(eventNames, listener) {
@@ -203,6 +243,8 @@ class Emittery {
 			assertEventName(eventName);
 			getListeners(this, eventName).add(listener);
 
+			this.logIfDebugEnabled('subscribe', eventName, undefined);
+
 			if (!isListenerSymbol(eventName)) {
 				this.emit(listenerAdded, {eventName, listener});
 			}
@@ -219,6 +261,8 @@ class Emittery {
 			assertEventName(eventName);
 			getListeners(this, eventName).delete(listener);
 
+			this.logIfDebugEnabled('unsubscribe', eventName, undefined);
+
 			if (!isListenerSymbol(eventName)) {
 				this.emit(listenerRemoved, {eventName, listener});
 			}
@@ -246,6 +290,8 @@ class Emittery {
 	async emit(eventName, eventData) {
 		assertEventName(eventName);
 
+		this.logIfDebugEnabled('emit', eventName, eventData);
+
 		enqueueProducers(this, eventName, eventData);
 
 		const listeners = getListeners(this, eventName);
@@ -271,6 +317,8 @@ class Emittery {
 	async emitSerial(eventName, eventData) {
 		assertEventName(eventName);
 
+		this.logIfDebugEnabled('emitSerial', eventName, eventData);
+
 		const listeners = getListeners(this, eventName);
 		const anyListeners = anyMap.get(this);
 		const staticListeners = [...listeners];
@@ -294,6 +342,9 @@ class Emittery {
 
 	onAny(listener) {
 		assertListener(listener);
+
+		this.logIfDebugEnabled('subscribeAny', undefined, undefined);
+
 		anyMap.get(this).add(listener);
 		this.emit(listenerAdded, {listener});
 		return this.offAny.bind(this, listener);
@@ -305,6 +356,9 @@ class Emittery {
 
 	offAny(listener) {
 		assertListener(listener);
+
+		this.logIfDebugEnabled('unsubscribeAny', undefined, undefined);
+
 		this.emit(listenerRemoved, {listener});
 		anyMap.get(this).delete(listener);
 	}
@@ -313,6 +367,8 @@ class Emittery {
 		eventNames = Array.isArray(eventNames) ? eventNames : [eventNames];
 
 		for (const eventName of eventNames) {
+			this.logIfDebugEnabled('clear', eventName, undefined);
+
 			if (typeof eventName === 'string' || typeof eventName === 'symbol') {
 				getListeners(this, eventName).clear();
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "emittery",
-	"version": "0.8.0",
+	"version": "0.9.2",
 	"description": "Simple and modern async event emitter",
 	"license": "MIT",
 	"repository": "sindresorhus/emittery",
@@ -11,7 +11,7 @@
 		"url": "https://sindresorhus.com"
 	},
 	"engines": {
-		"node": ">=10"
+		"node": ">=12"
 	},
 	"scripts": {
 		"test": "xo && nyc ava && tsd"
@@ -48,13 +48,13 @@
 		"typed"
 	],
 	"devDependencies": {
-		"@types/node": "^13.7.5",
+		"@types/node": "^15.6.1",
 		"ava": "^2.4.0",
 		"delay": "^4.3.0",
 		"nyc": "^15.0.0",
 		"p-event": "^4.1.0",
-		"tsd": "^0.14.0",
-		"xo": "^0.36.1"
+		"tsd": "^0.16.0",
+		"xo": "^0.39.0"
 	},
 	"nyc": {
 		"reporter": [

package/readme.md

@@ -2,7 +2,7 @@
 
 > Simple and modern async event emitter
 
-[![Coverage Status](https://codecov.io/gh/sindresorhus/emittery/branch/master/graph/badge.svg)](https://codecov.io/gh/sindresorhus/emittery)
+[![Coverage Status](https://codecov.io/gh/sindresorhus/emittery/branch/main/graph/badge.svg)](https://codecov.io/gh/sindresorhus/emittery)
 [![](https://badgen.net/bundlephobia/minzip/emittery)](https://bundlephobia.com/result?p=emittery)
 
 It works in Node.js and the browser (using a bundler).
@@ -44,7 +44,156 @@ Emittery accepts strings and symbols as event names.
 
 Symbol event names can be used to avoid name collisions when your classes are extended, especially for internal events.
 
-### emitter = new Emittery()
+### isDebugEnabled
+
+Toggle debug mode for all instances.
+
+Default: `true` if the `DEBUG` environment variable is set to `emittery` or `*`, otherwise `false`.
+
+Example:
+
+```js
+const Emittery = require('emittery');
+
+Emittery.isDebugEnabled = true;
+
+const emitter1 = new Emittery({debug: {name: 'myEmitter1'}});
+const emitter2 = new Emittery({debug: {name: 'myEmitter2'}});
+
+emitter1.on('test', data => {
+	// …
+});
+
+emitter2.on('otherTest', data => {
+	// …
+});
+
+emitter1.emit('test');
+//=> [16:43:20.417][emittery:subscribe][myEmitter1] Event Name: test
+//	data: undefined
+
+emitter2.emit('otherTest');
+//=> [16:43:20.417][emittery:subscribe][myEmitter2] Event Name: otherTest
+//	data: undefined
+```
+
+### emitter = new Emittery(options?)
+
+Create a new instance of Emittery.
+
+#### options?
+
+Type: `object`
+
+Configure the new instance of Emittery.
+
+##### debug?
+
+Type: `objcect`
+
+Configure the debugging options for this instance.
+
+###### name
+
+Type: `string`\
+Default: `undefined`
+
+Define a name for the instance of Emittery to use when outputting debug data.
+
+Example:
+
+```js
+const Emittery = require('emittery');
+
+Emittery.isDebugEnabled = true;
+
+const emitter = new Emittery({debug: {name: 'myEmitter'}});
+
+emitter.on('test', data => {
+	// …
+});
+
+emitter.emit('test');
+//=> [16:43:20.417][emittery:subscribe][myEmitter] Event Name: test
+//	data: undefined
+```
+
+###### enabled?
+
+Type: `boolean`\
+Default: `false`
+
+Toggle debug logging just for this instance.
+
+Example:
+
+```js
+const Emittery = require('emittery');
+
+const emitter1 = new Emittery({debug: {name: 'emitter1', enabled: true}});
+const emitter2 = new Emittery({debug: {name: 'emitter2'}});
+
+emitter1.on('test', data => {
+	// …
+});
+
+emitter2.on('test', data => {
+	// …
+});
+
+emitter1.emit('test');
+//=> [16:43:20.417][emittery:subscribe][emitter1] Event Name: test
+//	data: undefined
+
+emitter2.emit('test');
+```
+
+###### logger?
+
+Type: `Function(string, string, EventName?, Record<string, any>?) => void`
+
+Default:
+
+```js
+(type, debugName, eventName, eventData) => {
+	if (typeof eventData === 'object') {
+		eventData = JSON.stringify(eventData);
+	}
+
+	if (typeof eventName === 'symbol') {
+		eventName = eventName.toString();
+	}
+
+	const currentTime = new Date();
+	const logTime = `${currentTime.getHours()}:${currentTime.getMinutes()}:${currentTime.getSeconds()}.${currentTime.getMilliseconds()}`;
+	console.log(`[${logTime}][emittery:${type}][${debugName}] Event Name: ${eventName}\n\tdata: ${eventData}`);
+}
+```
+
+Function that handles debug data.
+
+Example:
+
+```js
+const Emittery = require('emittery');
+
+const myLogger = (type, debugName, eventName, eventData) => console.log(`[${type}]: ${eventName}`);
+
+const emitter = new Emittery({
+	debug: {
+		name: 'myEmitter',
+		enabled: true,
+		logger: myLogger
+	}
+});
+
+emitter.on('test', data => {
+	// …
+});
+
+emitter.emit('test');
+//=> [subscribe]: test
+```
 
 #### on(eventName | eventName[], listener)
 
@@ -62,6 +211,7 @@ const emitter = new Emittery();
 emitter.on('🦄', data => {
 	console.log(data);
 });
+
 emitter.on(['🦄', '🐶'], data => {
 	console.log(data);
 });
@@ -114,6 +264,7 @@ const Emittery = require('emittery');
 const emitter = new Emittery();
 
 const listener = data => console.log(data);
+
 (async () => {
 	emitter.on(['🦄', '🐶', '🦊'], listener);
 	await emitter.emit('🦄', 'a');
@@ -144,6 +295,7 @@ emitter.once('🦄').then(data => {
 	console.log(data);
 	//=> '🌈'
 });
+
 emitter.once(['🦄', '🐶']).then(data => {
 	console.log(data);
 });
@@ -365,6 +517,14 @@ Listeners are not invoked for events emitted *before* the listener was added. Re
 
 Note that when using `.emitSerial()`, a slow listener will delay invocation of subsequent listeners. It's possible for newer events to overtake older ones.
 
+## Debugging
+
+Emittery can collect and log debug information.
+
+To enable this feature set the DEBUG environment variable to 'emittery' or '*'. Additionally you can set the static `isDebugEnabled` variable to true on the Emittery class, or `myEmitter.debug.enabled` on an instance of it for debugging a single instance.
+
+See [API](#api) for more details on how debugging works.
+
 ## FAQ
 
 ### How is this different than the built-in `EventEmitter` in Node.js?