@irrelon/emitter 6.0.1 → 6.2.0

package/dist/esm/src/Emitter.js

@@ -4,7 +4,7 @@ export var ListenerReturnFlag;
     ListenerReturnFlag["cancel"] = "!+_CANCEL";
 })(ListenerReturnFlag || (ListenerReturnFlag = {}));
 /**
- * Creates a new class with the capability to emit events.
+ * Creates a new class with the ability to emit events.
  */
 export class Emitter {
     _eventsEmitting = false;
@@ -13,6 +13,15 @@ export class Emitter {
     _eventStaticEmitters = {};
     _eventsAllowDefer = false;
     _eventsDeferTimeouts = {};
+    _dispatchWindowEventsEnabled = false;
+    _dispatchPrefix;
+    constructor(dispatchPrefix, shouldDispatchWindowEvents = false) {
+        this._dispatchPrefix = dispatchPrefix;
+        this._dispatchWindowEventsEnabled = shouldDispatchWindowEvents;
+    }
+    dispatchWindowEventsEnabled(shouldDispatchWindowEvents) {
+        this._dispatchWindowEventsEnabled = shouldDispatchWindowEvents;
+    }
     /**
      * Attach an event listener to the passed event only if the passed
      * id matches the id for the event being fired.
@@ -32,9 +41,7 @@ export class Emitter {
         nonNullableEventListeners[id] = nonNullableEventListeners[id] || [];
         nonNullableEventListeners[id].push(listener);
         // Check for any static emitters, and fire the event if any exist
-        if (!this._eventStaticEmitters ||
-            !this._eventStaticEmitters[eventName] ||
-            !this._eventStaticEmitters[eventName].length)
+        if (!this._eventStaticEmitters || !this._eventStaticEmitters[eventName] || !this._eventStaticEmitters[eventName].length)
             return this;
         // Emit events for each emitter
         for (let i = 0; i < this._eventStaticEmitters[eventName].length; i++) {
@@ -110,6 +117,13 @@ export class Emitter {
         }
         return this;
     }
+    /**
+     * Creates an event listener that listens for any and all events
+     * emitted.
+     */
+    onAny(listener) {
+        this.on("*", listener);
+    }
     on(eventName, idOrListener, listener) {
         if (typeof idOrListener === "string") {
             return this._on(eventName, idOrListener, listener);
@@ -132,6 +146,13 @@ export class Emitter {
         this.off(eventName, rest[0]);
         return this._on(eventName, rest[0], rest[1]);
     }
+    /**
+     * Removes an event listener that listens for any and all events
+     * emitted.
+     */
+    offAny(listener) {
+        this.off("*", listener);
+    }
     off(eventName, ...rest) {
         if (rest.length === 0) {
             // Only event was provided, use * as the id to mean "any without"
@@ -168,6 +189,22 @@ export class Emitter {
         }
         return resultArr;
     }
+    /**
+     * Dispatches an event originating in our emitter to the browser's
+     * window object.
+     * @param eventName The name of the event to emit. This gets prefixed with the
+     * dispatch prefix if one is set.
+     * @param data
+     */
+    _emitToWindowDispatch(eventName, data) {
+        if (typeof window === "undefined")
+            return;
+        if (!this._dispatchWindowEventsEnabled) {
+            return;
+        }
+        const finalEventName = (this._dispatchPrefix ? `${this._dispatchPrefix}.${eventName}` : eventName);
+        window.dispatchEvent(new CustomEvent(finalEventName, { detail: data }));
+    }
     /**
      * Call an event listener by name. The `rpc()` function differs from `emit()` in
      * that it will only call and return data from the first event listener for the
@@ -198,10 +235,10 @@ export class Emitter {
      *
      *     // Emit the event named "hello"
      *     const result = myEntity.emit('hello', 'data1', 'data2');
-     *	   console.log("Result:", result);
+     *       console.log("Result:", result);
      *
      *     // The console output is:
-     *     //   Arguments: data1 data2
+     *     //	Arguments: data1 data2
      *     //	Result: "foo"
      */
     rpc(eventName, ...data) {
@@ -219,7 +256,7 @@ export class Emitter {
             emitterResult = this._emitToSingleListener(arr[0], data);
         }
         else if (id !== "*" && this._eventListeners[eventName]["*"]) {
-            // Handle global emit if the id passed wasn't already a global (*) id
+            // Handle wildcard emit if the id passed wasn't already a wildcard (*) id
             const arr = this._eventListeners[eventName]["*"];
             emitterResult = this._emitToSingleListener(arr[0], data);
         }
@@ -239,7 +276,7 @@ export class Emitter {
      * @param {...any} data The arguments to send to any listening methods.
      * If you are sending multiple arguments, separate them with a comma so
      * that they are received by the function as separate arguments.
-     * @return {number}
+     * @return {any[]} An array of all return values from all the listeners for the event.
      * @example #Emit an Event
      *     // Emit the event named "hello"
      *     myEntity.emit('hello');
@@ -252,7 +289,7 @@ export class Emitter {
      * @example #Listen for Event Data
      *     // Set a listener to listen for the data (multiple values emitted
      *     // from an event are passed as function arguments)
-     *   myEntity.on('hello', function (arg1, arg2) {
+     *	   myEntity.on('hello', function (arg1, arg2) {
      *         console.log("Arguments:", arg1, arg2);
      *         return "foo";
      *     }
@@ -261,39 +298,57 @@ export class Emitter {
      *     // The result is returned as an array of all return values
      *     // from all the listeners for the event
      *     const result = myEntity.emit('hello', 'data1', 'data2');
-     * 	   console.log("Result:", result);
+     *       console.log("Result:", result);
      *
      *     // The console output is:
-     *     //   Arguments: data1 data2
+     *     //	Arguments: data1 data2
      *     //	Result: ["foo"]
      */
     emit(eventName, ...data) {
+        this._emitToWindowDispatch(eventName, data);
         return this.emitId(eventName, "*", ...data);
     }
+    /**
+     * Emits an event by name and id.
+     * @param eventName The name of the event to emit.
+     * @param id The id of the event to emit.
+     * @param {...any} data The arguments to send to any listening methods.
+     * If you are sending multiple arguments, separate them with a comma so
+     * that they are received by the function as separate arguments.
+     * @return {any[]} An array of all return values from all the listeners for the event.
+     */
     emitId(eventName, id, ...data) {
-        if (!this._eventListeners || !this._eventListeners[eventName]) {
+        if (!this._eventListeners || (!this._eventListeners[eventName] && !this._eventListeners["*"])) {
             return [];
         }
         let emitterResult = [];
         this._eventsEmitting = true;
-        // Handle id emit
-        if (this._eventListeners[eventName][id]) {
-            const arr = this._eventListeners[eventName][id];
-            emitterResult = emitterResult.concat(this._emitToArrayOfListeners(arr, data));
+        if (this._eventListeners[eventName]) {
+            // Handle id emit
+            if (this._eventListeners[eventName][id]) {
+                const arr = this._eventListeners[eventName][id];
+                emitterResult = emitterResult.concat(this._emitToArrayOfListeners(arr, data));
+            }
+            // Handle id wildcard emit if the id passed wasn't already a wildcard (*) id
+            if (id !== "*" && this._eventListeners[eventName]["*"]) {
+                const arr = this._eventListeners[eventName]["*"];
+                emitterResult = emitterResult.concat(this._emitToArrayOfListeners(arr, data));
+            }
         }
-        // Handle global emit if the id passed wasn't already a global (*) id
-        if (id !== "*" && this._eventListeners[eventName]["*"]) {
-            const arr = this._eventListeners[eventName]["*"];
-            emitterResult = emitterResult.concat(this._emitToArrayOfListeners(arr, data));
+        if (this._eventListeners["*"]) {
+            const arr = this._eventListeners["*"]["*"];
+            emitterResult = emitterResult.concat(this._emitToArrayOfListeners(arr, [eventName, ...data]));
         }
         this._eventsEmitting = false;
         this._processRemovalQueue();
         return emitterResult;
     }
     /**
-     * Creates a persistent emitter record that will fire a listener if
-     * one is added for this event after the emitStatic() call has been
-     * made.
+     * Creates a persistent event. Once emitStatic() has been called, a
+     * persistent event is registered. Any existing event listeners will
+     * be called just like when you call emit(), however, any new
+     * listeners that are registered for this event via on() will also be
+     * called as soon as they are added.
      * @param eventName The name of the event to emit.
      * @param {...any} data Optional arguments to emit with the event.
      * @returns The emitter instance.
@@ -304,7 +359,7 @@ export class Emitter {
         this._eventListeners = this._eventListeners || {};
         this._eventsEmitting = true;
         if (this._eventListeners[eventName] && this._eventListeners[eventName][id]) {
-            // Handle global emit
+            // Handle id wildcard emit
             const arr = this._eventListeners[eventName][id];
             const arrCount = arr.length;
             for (let arrIndex = 0; arrIndex < arrCount; arrIndex++) {
@@ -353,7 +408,7 @@ export class Emitter {
                     }
                 }
             }
-            // Handle global emit
+            // Handle wildcard emit
             if (this._eventListeners[eventName]["*"]) {
                 const arr = this._eventListeners[eventName]["*"];
                 const arrCount = arr.length;
@@ -432,7 +487,7 @@ export class Emitter {
                 }
             }
         }
-        // Handle global emit
+        // Handle wildcard emit
         if (this._eventListeners[eventName]["*"]) {
             const arr = this._eventListeners[eventName]["*"];
             const arrCount = arr.length;
@@ -529,7 +584,9 @@ export function makeEmitter(obj, prototypeMode) {
     }
     // Convert the object prototype to have eventing capability
     operateOnObject.on = Emitter.prototype.on;
+    operateOnObject.onAny = Emitter.prototype.onAny;
     operateOnObject.off = Emitter.prototype.off;
+    operateOnObject.offAny = Emitter.prototype.offAny;
     operateOnObject.once = Emitter.prototype.once;
     operateOnObject.emit = Emitter.prototype.emit;
     operateOnObject.emitId = Emitter.prototype.emitId;

package/dist/esm/tests/Emitter.test.js

@@ -1,30 +1,32 @@
+import { jest } from "@jest/globals";
 import assert from "assert";
 import { Emitter, ListenerReturnFlag } from "../src/Emitter";
 let expectedAssertions = 0;
 let actualAssertions = 0;
-function expect(val) {
+function expectAssertionCount(val) {
     expectedAssertions = val;
 }
-function reset() {
+function resetAssertionCount() {
     expectedAssertions = 0;
     actualAssertions = 0;
 }
 function countAssertion() {
     actualAssertions++;
 }
-function check() {
+function checkAssertionCount() {
     if (expectedAssertions === undefined || expectedAssertions === actualAssertions) {
         return;
     }
     throw new Error("expected " + expectedAssertions + " assertions, got " + actualAssertions);
 }
-beforeEach(reset);
-afterEach(check);
+beforeEach(resetAssertionCount);
+afterEach(checkAssertionCount);
 describe("Emitter", () => {
     describe("new Emitter()", () => {
         it("Creates emitter instance by instantiation", () => {
             const myClass = new Emitter();
-            myClass.on("moo", () => { });
+            myClass.on("moo", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 1, "Listener registered on event");
             myClass.off("moo");
             assert.strictEqual(!myClass._eventListeners?.moo ||
@@ -32,12 +34,8 @@ describe("Emitter", () => {
                 myClass._eventListeners.moo["*"].length, true, "Listeners all removed from event");
         });
         it("Supports extending Emitter as a base class", () => {
-            let testFuncCount = 0;
             // Test extending Emitter and modifying base functionality
             class MyClass extends Emitter {
-                testFunc() {
-                    testFuncCount++;
-                }
                 on(eventName, ...rest) {
                     const restTypes = rest.map((arg) => typeof arg);
                     if (restTypes[0] === "function") {
@@ -150,6 +148,7 @@ describe("Emitter", () => {
             await Promise.all(emitter.emit("foo"));
             const delta = new Date().getTime() - time;
             assert.ok(delta > 900, "Delta was not correct, await may not have paused?");
+            assert.strictEqual(listenerFiredCount, 2, "Listener fire count was incorect");
         });
         it("Supports awaiting async and non-async listener return data", async () => {
             const emitter = new Emitter();
@@ -226,11 +225,15 @@ describe("Emitter", () => {
     describe("off()", () => {
         it("Cancels all listeners (event)", () => {
             const myClass = new Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 2, "Listeners registered on event");
@@ -243,11 +246,15 @@ describe("Emitter", () => {
         });
         it("Cancels id-based listeners (event, id)", () => {
             const myClass = new Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 2, "Listeners registered on event");
@@ -259,11 +266,15 @@ describe("Emitter", () => {
         });
         it("Cancels listener-based listeners (event, listener)", () => {
             const myClass = new Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 2, "Listeners registered on event");
@@ -275,11 +286,15 @@ describe("Emitter", () => {
         });
         it("Cancels id-based + listener-based listeners (event, id, listener)", () => {
             const myClass = new Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert.strictEqual(myClass._eventListeners?.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert.strictEqual(myClass._eventListeners?.moo["*"].length, 2, "Listeners registered on event");
@@ -294,7 +309,7 @@ describe("Emitter", () => {
         it("Static emitter will emit when a new listener is added", (resolve) => {
             class MyClass extends Emitter {
             }
-            expect(1);
+            expectAssertionCount(1);
             const myClass = new MyClass();
             myClass.emitStatic("moo");
             myClass.on("moo", () => {
@@ -308,7 +323,7 @@ describe("Emitter", () => {
         it("Removes static emitter", (resolve) => {
             class MyClass extends Emitter {
             }
-            expect(1);
+            expectAssertionCount(1);
             const myClass = new MyClass();
             myClass.emitStatic("moo");
             myClass.on("moo", () => {
@@ -329,7 +344,7 @@ describe("Emitter", () => {
         it("Only fires the last listener added, cancelling all other listeners before it", (resolve) => {
             class MyClass extends Emitter {
             }
-            expect(1);
+            expectAssertionCount(1);
             const myClass = new MyClass();
             myClass.on("moo", () => {
                 countAssertion();
@@ -351,7 +366,7 @@ describe("Emitter", () => {
         it("Only fires the last listener added (with id), cancelling all other listeners before it", (resolve) => {
             class MyClass extends Emitter {
             }
-            expect(2);
+            expectAssertionCount(2);
             const myClass = new MyClass();
             // Define a listener without an id, this should not be overwritten
             myClass.on("moo", () => {
@@ -406,4 +421,36 @@ describe("Emitter", () => {
                 myClass._eventListeners?.moo["*"].length === 0, true, "Listeners all removed from event");
         });
     });
+    describe("Global listener functionality", () => {
+        it("Listens for any event emitted and fires the listener with the onAny() function", () => {
+            const emitter = new Emitter();
+            const spy = jest.fn();
+            emitter.onAny(spy);
+            emitter.emit("someEvent", "someArg1", true, false);
+            expect(spy).toHaveBeenCalledWith("someEvent", "someArg1", true, false);
+        });
+        it(`Listens for any event emitted and fires the listener with the on("*") function`, () => {
+            const emitter = new Emitter();
+            const spy = jest.fn();
+            emitter.on("*", spy);
+            emitter.emit("someEvent", "someArg1", true, false);
+            expect(spy).toHaveBeenCalledWith("someEvent", "someArg1", true, false);
+        });
+        it(`Cancels an event listener for any event emitted with the offAny() function`, () => {
+            const emitter = new Emitter();
+            const spy = jest.fn();
+            emitter.on("*", spy);
+            emitter.offAny(spy);
+            emitter.emit("someEvent", "someArg1", true, false);
+            expect(spy).toHaveBeenCalledTimes(0);
+        });
+        it(`Cancels an event listener for any event emitted with the off("*") function`, () => {
+            const emitter = new Emitter();
+            const spy = jest.fn();
+            emitter.on("*", spy);
+            emitter.off("*", spy);
+            emitter.emit("someEvent", "someArg1", true, false);
+            expect(spy).toHaveBeenCalledTimes(0);
+        });
+    });
 });