@irrelon/emitter 4.0.1 → 5.0.0

package/src/{Emitter.js → Emitter.ts}

@@ -25,6 +25,12 @@
  Source: https://github.com/irrelon/emitter
 
  Changelog:
+ 	Version 5.0.0:
+ 		Added typescript types, switched from mocha to jest for test
+ 		running.
+ 		Breaking change. When using makeEmitter, prototypeMode is now
+ 		false by default. Simply pass makeEmitter(SomeClass.prototype)
+ 		instead of makeEmitter(SomeClass) to modify a prototype.
  	Version 4.0.1:
  		Updated library to use new ES6 functionality making Overload()
  		less useful so it can be removed as a dependency.
@@ -77,9 +83,49 @@
 	Version 1.0.0:
 		First commit
  */
-"use strict";
+export interface InternalEventListenersType {
+	[eventName: string|symbol]: InternalEventListenersByIdType
+}
+
+export interface InternalEventListenersByIdType {
+	[idName: string|symbol]: Array<EventListenerType>
+}
+
+export type EventListenerType = (...rest: any[]) => any;
+
+export interface InternalEventEmittersType {
+	[eventName: string|symbol]: Array<EventEmitterType>
+}
+
+export interface EventEmitterType {
+	id: string|symbol
+	args: any
+}
+
+/**
+ * @class Emitter
+ * @constructor
+ */
+export class Emitter {
+	private _emitting: boolean;
+	private _noEmitDefer: boolean;
+	private _listeners: InternalEventListenersType
+	private _emitters: InternalEventEmittersType
+	private _eventRemovalQueue: Array<(...rest: any[]) => any>;
+	private _deferTimeout: any;
+
+	constructor (obj?: any) {
+		this._noEmitDefer = false;
+		this._emitting = false;
+		this._listeners = {};
+		this._emitters = {};
+		this._eventRemovalQueue = [];
+
+		if (obj !== undefined) {
+			return makeEmitter(obj);
+		}
+	}
 
-const EventMainMethods = {
 	/**
 	 * Attach an event listener to the passed event only if the passed
 	 * id matches the document id for the event being fired.
@@ -90,10 +136,8 @@ const EventMainMethods = {
 	 * @param {Function} listener The method to call when the event is fired.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	"_on" (event, id, listener) {
-		const self = this;
-
-		const generateTimeout = (emitter) => {
+	_on (event: string|symbol, id: string|symbol, listener: (...rest: any[]) => any) {
+		const generateEmitterTimeout = (emitter: EventEmitterType) => {
 			setTimeout(() => {
 				listener.apply(this, emitter.args);
 			}, 1);
@@ -108,19 +152,17 @@ const EventMainMethods = {
 		if (!this._emitters || !this._emitters[event] || !this._emitters[event].length) return this;
 
 		// Emit events for each emitter
-		for (let i = 0; i < this._emitters[event].length; i++) {
-			const emitter = this._emitters[event];
-
+		this._emitters[event].forEach((emitter: EventEmitterType) => {
 			if (id === "*" || emitter.id === id) {
 				// Call the listener out of process so that any code that expects a listener
 				// to be called at some point in the future rather than immediately on registration
 				// will not fail
-				generateTimeout(emitter);
+				generateEmitterTimeout(emitter);
 			}
-		}
+		});
 
 		return this;
-	},
+	}
 
 	/**
 	 * Attach an event listener to the passed event only if the passed
@@ -132,19 +174,19 @@ const EventMainMethods = {
 	 * @param {Function} listener The method to call when the event is fired.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	"_once" (event, id, listener) {
+	_once (event:string|symbol, id:string|symbol, listener: EventListenerType) {
 		let fired = false;
 
-		const internalCallback = () => {
+		const internalCallback = (...rest: any[]) => {
 			if (fired) return;
 
 			fired = true;
 			this.off(event, id, internalCallback);
-			listener.apply(this, arguments);
+			listener(...rest);
 		};
 
 		return this.on(event, id, internalCallback);
-	},
+	}
 
 	/**
 	 * Cancels an event listener based on an event name, id and listener function.
@@ -156,7 +198,7 @@ const EventMainMethods = {
 	 * or once() call to cancel.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	"_off" (event, id, listener) {
+	_off (event: string|symbol, id: string|symbol, listener?: EventListenerType) {
 		if (this._emitting) {
 			this._eventRemovalQueue = this._eventRemovalQueue || [];
 			this._eventRemovalQueue.push(() => {
@@ -179,20 +221,16 @@ const EventMainMethods = {
 			return this;
 		}
 
-		const arr = this._listeners[event][id] || [],
-			index = arr.indexOf(listener);
+		if (!listener) return this;
+
+		const arr = this._listeners[event][id] || [];
+		const index = arr.indexOf(listener);
 
 		if (index > -1) {
 			arr.splice(index, 1);
 		}
 	}
-};
 
-/**
- * @class Emitter
- * @constructor
- */
-class Emitter {
 	/**
 	 * Attach an event listener to the passed event only if the passed
 	 * id matches the document id for the event being fired.
@@ -203,14 +241,16 @@ class Emitter {
 	 * @param {Function} listener The method to call when the event is fired.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	on (event, ...rest) {
+	on (event: string|symbol, id: string|symbol, listener: EventListenerType): any;
+	on (event: string|symbol, listener: (...rest: any[]) => any): any;
+	on (event: string|symbol, ...rest: any[]) {
 		const restTypes = rest.map((arg) => typeof arg);
 
 		if (restTypes[0] === "function") {
-			return EventMainMethods._on.call(this, event, "*", rest[0]);
+			return this._on.call(this, event, "*", rest[0]);
 		}
 
-		return EventMainMethods._on.call(this, event, rest[0], rest[1]);
+		return this._on.call(this, event, rest[0], rest[1]);
 	}
 
 	/**
@@ -223,14 +263,16 @@ class Emitter {
 	 * @param {Function} listener The method to call when the event is fired.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	once (event, ...rest) {
+	once (event: string, id: string|symbol, listener: EventListenerType): any;
+	once (event: string, listener: (...rest: any[]) => any): any;
+	once (event: string, ...rest: any[]) {
 		const restTypes = rest.map((arg) => typeof arg);
 
 		if (restTypes[0] === "function") {
-			return EventMainMethods._once.call(this, event, "*", rest[0]);
+			return this._once.call(this, event, "*", rest[0]);
 		}
 
-		return EventMainMethods._once.call(this, event, rest[0], rest[1]);
+		return this._once.call(this, event, rest[0], rest[1]);
 	}
 
 	/**
@@ -243,41 +285,46 @@ class Emitter {
 	 * @param {Function} listener The method to call when the event is fired.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	one (event, ...rest) {
+	one (event: string, id: string|symbol, listener: EventListenerType): any;
+	one (event: string, listener: (...rest: any[]) => any): any;
+	one (event: string, ...rest: any[]) {
 		const restTypes = rest.map((arg) => typeof arg);
 
 		if (restTypes[0] === "function") {
 			this.off(event);
-			return EventMainMethods._on.call(this, event, "*", rest[0]);
+			return this._on.call(this, event, "*", rest[0]);
 		}
 
 		this.off(event, rest[0]);
-		return EventMainMethods._on.call(this, event, rest[0], rest[1]);
+		return this._on.call(this, event, rest[0], rest[1]);
 	}
 
 	/**
 	 * Cancels an event listener based on an event name, id and listener function.
 	 * @memberOf Emitter
 	 * @method off
-	 * @param {String} event The event to cancel listener for.
-	 * @param {String} id The ID of the event to cancel listening for.
-	 * @param {Function} listener The event listener function used in the on()
+	 * @param event The event to cancel listener for.
+	 * @param id The ID of the event to cancel listening for.
+	 * @param listener The event listener function used in the on()
 	 * or once() call to cancel.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	off (event, ...rest) {
+	off (event: string|symbol, id: string|symbol, listener?: EventListenerType): any;
+	off (event: string|symbol, listener: (...rest: any[]) => any): any;
+	off (event: string|symbol): any;
+	off (event: string|symbol, ...rest: any[]) {
 		if (rest.length === 0) {
 			// Only event was provided
-			return EventMainMethods._off.call(this, event, "*");
+			return this._off.call(this, event, "*");
 		}
 
 		const restTypes = rest.map((arg) => typeof arg);
 
 		if (restTypes[0] === "function") {
-			return EventMainMethods._off.call(this, event, "*", rest[0]);
+			return this._off.call(this, event, "*", rest[0]);
 		}
 
-		return EventMainMethods._off.call(this, event, rest[0], rest[1]);
+		return this._off.call(this, event, rest[0], rest[1]);
 	}
 
 	/**
@@ -287,7 +334,7 @@ class Emitter {
 	 * @returns {Emitter} The emitter instance.
 	 * @private
 	 */
-	emit (event, ...data) {
+	emit (event: string|symbol, ...data: any[]) {
 		const id = "*";
 		this._listeners = this._listeners || {};
 		this._emitting = true;
@@ -313,11 +360,11 @@ class Emitter {
 		return this;
 	}
 
-	emitId (event, id, ...data) {
+	emitId (event: string|symbol, id: string|symbol, ...data: any[]) {
 		this._listeners = this._listeners || {};
 		this._emitting = true;
 
-		if (!this._listeners[event]) {
+		if (!this._listeners || !this._listeners[event]) {
 			this._emitting = false;
 			this._processRemovalQueue();
 
@@ -361,34 +408,13 @@ class Emitter {
 	}
 
 	/**
-	 * Handles emitting events, is an internal method not called directly.
+	 * Creates a static event emitter that is emitted whenever an
+	 * event listener is created with the same name.
 	 * @param {String} event The name of the event to emit.
 	 * @param {*} data The data to emit with the event.
 	 * @returns {Emitter} The emitter instance.
-	 * @private
 	 */
-	emitStatic (event, ...data) {
-		const id = "*";
-		this._listeners = this._listeners || {};
-		this._emitting = true;
-
-		if (this._listeners[event] && this._listeners[event][id]) {
-			// Handle global emit
-			const arr = this._listeners[event][id];
-			const arrCount = arr.length;
-
-			for (let arrIndex = 0; arrIndex < arrCount; arrIndex++) {
-				// Check we have a function to execute
-				const tmpFunc = arr[arrIndex];
-
-				if (typeof tmpFunc === "function") {
-					tmpFunc.call(this, ...data);
-				}
-			}
-		}
-
-		this._emitting = false;
-
+	emitStatic (event: string|symbol, ...data: any[]) {
 		this._emitters = this._emitters || {};
 		this._emitters[event] = this._emitters[event] || [];
 		this._emitters[event].push({
@@ -396,58 +422,23 @@ class Emitter {
 			"args": data
 		});
 
+		this.emit(event, ...data);
+
 		this._processRemovalQueue();
 
 		return this;
 	}
 
 	/**
-	 * Handles emitting events, is an internal method not called directly.
+	 * Creates a static event emitter that is emitted whenever an
+	 * event listener is created with the same name and id.
 	 * @param {String} event The name of the event to emit.
 	 * @param {String} id The id of the event to emit.
 	 * @param {*} data The data to emit with the event.
 	 * @returns {Emitter} The emitter instance.
-	 * @private
 	 */
-	emitStaticId (event, id, ...data) {
-		if (!id) throw new Error("Missing id from emitId call!");
-
-		this._listeners = this._listeners || {};
-		this._emitting = true;
-
-		if (this._listeners[event]) {
-			// Handle id emit
-			if (this._listeners[event][id]) {
-				const arr = this._listeners[event][id];
-				const arrCount = arr.length;
-
-				for (let arrIndex = 0; arrIndex < arrCount; arrIndex++) {
-					// Check we have a function to execute
-					const tmpFunc = arr[arrIndex];
-
-					if (typeof tmpFunc === "function") {
-						tmpFunc.call(this, ...data);
-					}
-				}
-			}
-
-			// Handle global emit
-			if (this._listeners[event]["*"]) {
-				const arr = this._listeners[event]["*"];
-				const arrCount = arr.length;
-
-				for (let arrIndex = 0; arrIndex < arrCount; arrIndex++) {
-					// Check we have a function to execute
-					const tmpFunc = arr[arrIndex];
-
-					if (typeof tmpFunc === "function") {
-						tmpFunc.call(this, ...data);
-					}
-				}
-			}
-		}
-
-		this._emitting = false;
+	emitStaticId (event: string|symbol, id: string|symbol, ...data: any[]) {
+		if (!id) throw new Error("Missing id from emitStaticId call!");
 
 		this._emitters = this._emitters || {};
 		this._emitters[event] = this._emitters[event] || [];
@@ -456,7 +447,7 @@ class Emitter {
 			"args": data
 		});
 
-		this._processRemovalQueue();
+		this.emitId(event, id, ...data);
 
 		return this;
 	}
@@ -467,7 +458,7 @@ class Emitter {
 	 * @returns {Emitter} The emitter instance.
 	 * @private
 	 */
-	cancelStatic (event) {
+	cancelStatic (event: string|symbol) {
 		this._emitters = this._emitters || {};
 		this._emitters[event] = [];
 
@@ -482,7 +473,7 @@ class Emitter {
 	 * @returns {boolean} True if one or more event listeners are registered for
 	 * the event. False if none are found.
 	 */
-	willEmit (event) {
+	willEmit (event: string|symbol) {
 		const id = "*";
 
 		if (!this._listeners || !this._listeners[event]) {
@@ -513,7 +504,7 @@ class Emitter {
 	 * @returns {boolean} True if one or more event listeners are registered for
 	 * the event. False if none are found.
 	 */
-	willEmitId (event, id) {
+	willEmitId (event: string|symbol, id: string|symbol) {
 		if (!this._listeners || !this._listeners[event]) {
 			return false;
 		}
@@ -555,31 +546,32 @@ class Emitter {
 	 * Queues an event to be fired. This has automatic de-bouncing so that any
 	 * events of the same type that occur within 100 milliseconds of a previous
 	 * one will all be wrapped into a single emit rather than emitting tons of
-	 * events for lots of chained inserts etc. Only the data from the last
-	 * de-bounced event will be emitted.
+	 * events for the same eventName. Only the data from the last de-bounced event
+	 * will be emitted.
 	 * @memberOf Emitter
 	 * @method deferEmit
 	 * @param {String} eventName The name of the event to emit.
 	 * @param {*=} data Optional data to emit with the event.
 	 * @returns {Emitter} The emitter instance.
 	 */
-	deferEmit (eventName, ...data) {
-		if (!this._noEmitDefer && (!this._db || (this._db && !this._db._noEmitDefer))) {
-			// Check for an existing timeout
-			this._deferTimeout = this._deferTimeout || {};
+	deferEmit (eventName: string|symbol, ...data: any[]) {
+		if (this._noEmitDefer) {
+			this.emit(eventName, ...data);
+			return this;
+		}
 
-			if (this._deferTimeout[eventName]) {
-				clearTimeout(this._deferTimeout[eventName]);
-			}
+		// Check for an existing timeout
+		this._deferTimeout = this._deferTimeout || {};
 
-			// Set a timeout
-			this._deferTimeout[eventName] = setTimeout(() => {
-				this.emit.call(this, eventName, ...data);
-			}, 1);
-		} else {
-			this.emit.call(this, eventName, ...data);
+		if (this._deferTimeout[eventName]) {
+			clearTimeout(this._deferTimeout[eventName]);
 		}
 
+		// Set a timeout
+		this._deferTimeout[eventName] = setTimeout(() => {
+			this.emit(eventName, ...data);
+		}, 100);
+
 		return this;
 	}
 
@@ -591,6 +583,7 @@ class Emitter {
 	 * the emitter is running through them. This method is called after the
 	 * event emitter is finished processing.
 	 * @private
+	 * @returns {undefined}
 	 */
 	_processRemovalQueue () {
 		if (!this._eventRemovalQueue || !this._eventRemovalQueue.length) {
@@ -610,17 +603,23 @@ class Emitter {
 /**
  * Makes the passed class or object into an emitter by modifying either the
  * prototype or the actual object to include event emitter methods.
- * @param {Object} [obj={}] The object / function / class to add event methods to.
+ * @param obj The object / function / class to add event methods to.
  * If none is provided a new object will be created. This allows you to use
  * new Emitter() to generate an event emitter that is not tied to any other
  * object or class.
- * @param {Boolean} [prototypeMode=true] Defaults to true. Set to true to add emitter
+ * @param prototypeMode Defaults to true. Set to true to add emitter
  * methods to the the passed object"s prototype property e.g. obj.prototype.on
  * = emitter.on. Set to false to add emitter methods the object directly e.g.
  * obj.on = emitter.on.
  * @returns {Object} The newly augmented object.
  */
-const makeEmitter = function (obj, prototypeMode) {
+type MakeEmitter = {
+	(obj: Record<string, unknown>|boolean|undefined, prototypeMode: boolean): any,
+	(obj: boolean): any,
+	(obj: undefined): any
+}
+
+export const makeEmitter: MakeEmitter = (obj: Record<string, unknown>|boolean|undefined, prototypeMode = false) => {
 	let operateOnObject;
 
 	if (obj === undefined && prototypeMode === undefined) {
@@ -634,24 +633,24 @@ const makeEmitter = function (obj, prototypeMode) {
 	}
 
 	if (prototypeMode === undefined) {
-		prototypeMode = true;
+		prototypeMode = false;
 	}
 
 	if (typeof obj !== "object" && typeof obj !== "function") {
-		throw new Error("Cannot operate on a non-object / non-function passed as first argument!");
+		throw new Error("Cannot operate on passed value, it is not an object, function or class!");
 	}
 
 	if (prototypeMode) {
 		if (obj.prototype === undefined) {
-			throw new Error("Cannot modify prototype of passed object, it has no prototype property! Was it instantiated with the new operator correctly?");
+			throw new Error("Cannot modify prototype of passed object, it has no prototype property!");
 		}
 
-		operateOnObject = obj.prototype;
+		operateOnObject = obj.prototype as Record<string, unknown>;
 	} else {
 		operateOnObject = obj;
 	}
 
-	// Convert the object prototype to have eventing capability
+	// Convert the object to have eventing capability
 	operateOnObject.on = Emitter.prototype.on;
 	operateOnObject.off = Emitter.prototype.off;
 	operateOnObject.one = Emitter.prototype.one;
@@ -665,11 +664,9 @@ const makeEmitter = function (obj, prototypeMode) {
 	operateOnObject.willEmit = Emitter.prototype.willEmit;
 	operateOnObject.willEmitId = Emitter.prototype.willEmitId;
 	operateOnObject._processRemovalQueue = Emitter.prototype._processRemovalQueue;
+	operateOnObject._on = Emitter.prototype._on;
+	operateOnObject._off = Emitter.prototype._off;
+	operateOnObject._once = Emitter.prototype._once;
 
 	return obj;
-};
-
-module.exports = {
-	Emitter,
-	makeEmitter
 };

package/tests/Emitter.test.js

@@ -1,4 +1,3 @@
-const {beforeEach, afterEach, describe, it} = require("mocha");
 const {Emitter, makeEmitter} = require("../dist/Emitter");
 const assert = require("assert");
 
@@ -22,8 +21,7 @@ function check () {
 	if (expectedAssertions === undefined || expectedAssertions === actualAssertions) {
 		return;
 	}
-	const err = new Error("expected " + expectedAssertions + " assertions, got " + actualAssertions);
-	this.currentTest.emit("error", err);
+	throw new Error("expected " + expectedAssertions + " assertions, got " + actualAssertions);
 }
 
 beforeEach(reset);
@@ -44,6 +42,28 @@ describe("Emitter", () => {
 			assert.strictEqual(!myClass._listeners.moo || !myClass._listeners.moo["*"] || myClass._listeners.moo["*"].length, true, "Listeners all removed from event");
 		});
 
+		it("Augments an object passed to makeEmitter()", (resolve) => {
+			const obj = {
+				"someExistingProp": "hello"
+			};
+			makeEmitter(obj);
+
+			function test () {
+				assert.strictEqual(this.someExistingProp, "hello", "Able to access object props via `this`");
+				assert.strictEqual(obj._listeners.moo["*"].length, 1, "Listener registered on event");
+
+				resolve();
+			}
+
+			obj.on("moo", test);
+
+			obj.emit("moo");
+
+			obj.off("moo");
+
+			assert.strictEqual(!obj._listeners.moo || !obj._listeners.moo["*"] || obj._listeners.moo["*"].length, true, "Listeners all removed from event");
+		});
+
 		it("Supports extending Emitter as a base class", () => {
 			let testFuncCount = 0;
 
@@ -196,7 +216,7 @@ describe("Emitter", () => {
 
 			expect(1);
 
-			makeEmitter(MyClass);
+			makeEmitter(MyClass.prototype);
 
 			const myClass = new MyClass();
 			myClass.emitStatic("moo");
@@ -215,7 +235,7 @@ describe("Emitter", () => {
 
 			expect(1);
 
-			makeEmitter(MyClass);
+			makeEmitter(MyClass.prototype);
 
 			const myClass = new MyClass();
 			myClass.emitStatic("moo");
@@ -242,7 +262,7 @@ describe("Emitter", () => {
 			};
 			expect(1);
 
-			makeEmitter(MyClass);
+			makeEmitter(MyClass.prototype);
 
 			const myClass = new MyClass();
 			myClass.on("moo", () => {

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+	"compilerOptions": {
+		"target": "ES2015",
+		"module": "CommonJS",
+		"lib": [
+			"dom",
+			"dom.iterable",
+			"esnext"
+		],
+		"allowJs": false,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		"strict": true,
+		"forceConsistentCasingInFileNames": true,
+		"suppressImplicitAnyIndexErrors": true,
+		"noFallthroughCasesInSwitch": false,
+		"moduleResolution": "node",
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"noEmit": false,
+		"jsx": "react-jsx",
+		"outDir": "dist",
+		"declaration": true
+	},
+	"include": [
+		"src"
+	]
+}