emittery 0.8.1 → 0.10.0

package/index.d.ts

@@ -1,3 +1,5 @@
+/* eslint-disable no-redeclare */
+
 /**
 Emittery accepts strings and symbols as event names.
 
@@ -14,6 +16,122 @@ 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`.
 
@@ -50,6 +168,39 @@ declare class Emittery<
 	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.
 
@@ -104,6 +255,18 @@ declare class Emittery<
 	*/
 	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.
 
@@ -122,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.
@@ -140,6 +303,7 @@ declare class Emittery<
 	emitter.on('🦄', data => {
 		console.log(data);
 	});
+
 	emitter.on(['🦄', '🐶'], data => {
 		console.log(data);
 	});
@@ -149,7 +313,7 @@ declare class Emittery<
 	```
 	*/
 	on<Name extends keyof AllEventData>(
-		eventName: Name,
+		eventName: Name | Name[],
 		listener: (eventData: AllEventData[Name]) => void | Promise<void>
 	): Emittery.UnsubscribeFn;
 
@@ -264,7 +428,7 @@ declare class Emittery<
 	```
 	*/
 	off<Name extends keyof AllEventData>(
-		eventName: Name,
+		eventName: Name | Name[],
 		listener: (eventData: AllEventData[Name]) => void | Promise<void>
 	): void;
 
@@ -284,6 +448,7 @@ declare class Emittery<
 		console.log(data);
 		//=> '🌈'
 	});
+
 	emitter.once(['🦄', '🐶']).then(data => {
 		console.log(data);
 	});
@@ -292,7 +457,7 @@ declare class Emittery<
 	emitter.emit('🐶', '🍖'); // Nothing happens
 	```
 	*/
-	once<Name extends keyof AllEventData>(eventName: Name): Promise<AllEventData[Name]>;
+	once<Name extends keyof AllEventData>(eventName: Name | Name[]): Promise<AllEventData[Name]>;
 
 	/**
 	Trigger an event asynchronously, optionally with some data. Listeners are called in the order they were added, but executed concurrently.
@@ -383,12 +548,12 @@ declare class Emittery<
 
 	If `eventName` is given, only the listeners for that event are cleared.
 	*/
-	clearListeners(eventName?: keyof EventData): void;
+	clearListeners<Name extends keyof EventData>(eventName?: Name | Name[]): void;
 
 	/**
 	The number of listeners for the `eventName` or all events if not specified.
 	*/
-	listenerCount(eventName?: keyof EventData): number;
+	listenerCount<Name extends keyof EventData>(eventName?: Name | Name[]): number;
 
 	/**
 	Bind the given `methodNames`, or all `Emittery` methods if `methodNames` is not defined, into the `target` object.

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.1",
+	"version": "0.10.0",
 	"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?