@irrelon/emitter 6.1.0 → 6.2.0

package/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = false

package/dist/cjs/src/Emitter.d.ts

@@ -15,12 +15,12 @@ export interface EmitterAnyEventsInterface {
 export type EmitterEventsInterface<T> = {
     [K in keyof T]: T[K];
 };
-interface WithStar {
+export interface WithStar {
     "*"?: (eventName: string, ...args: any[]) => void;
 }
 export type EmitterEventsWithStar<T> = EmitterEventsInterface<T> & WithStar;
 /**
- * Creates a new class with the capability to emit events.
+ * Creates a new class with the ability to emit events.
  */
 export declare class Emitter<EventsInterface extends EmitterEventsWithStar<EventsInterface> = EmitterAnyEventsInterface> {
     _eventsEmitting: boolean;
@@ -33,6 +33,10 @@ export declare class Emitter<EventsInterface extends EmitterEventsWithStar<Event
     };
     _eventsAllowDefer: boolean;
     _eventsDeferTimeouts: Record<any, number>;
+    _dispatchWindowEventsEnabled: boolean;
+    _dispatchPrefix?: string;
+    constructor(dispatchPrefix?: string, shouldDispatchWindowEvents?: boolean);
+    dispatchWindowEventsEnabled(shouldDispatchWindowEvents: boolean): void;
     /**
      * Attach an event listener to the passed event only if the passed
      * id matches the id for the event being fired.
@@ -117,6 +121,14 @@ export declare class Emitter<EventsInterface extends EmitterEventsWithStar<Event
     off<EventName extends keyof EventsInterface>(eventName: EventName): this;
     _emitToSingleListener<EventName extends keyof EventsInterface>(listener: EventListenerCallback<EventsInterface[EventName]>, data: Parameters<EventsInterface[EventName]>): ReturnType<EventsInterface[EventName]> | ListenerReturnFlag;
     _emitToArrayOfListeners<EventName extends keyof EventsInterface>(arr: EventListenerCallback<EventsInterface[EventName]>[], data: Parameters<EventsInterface[EventName]>): (ReturnType<EventsInterface[EventName]> | ListenerReturnFlag)[];
+    /**
+     * 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 extends keyof EventsInterface>(eventName: EventName, data: any): void;
     /**
      * 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
@@ -150,7 +162,7 @@ export declare class Emitter<EventsInterface extends EmitterEventsWithStar<Event
      *       console.log("Result:", result);
      *
      *     // The console output is:
-     *     //   Arguments: data1 data2
+     *     //	Arguments: data1 data2
      *     //	Result: "foo"
      */
     rpc<EventName extends keyof EventsInterface>(eventName: EventName, ...data: Parameters<EventsInterface[EventName]>): ReturnType<EventsInterface[EventName]> | ListenerReturnFlag;
@@ -161,7 +173,7 @@ export declare class Emitter<EventsInterface extends EmitterEventsWithStar<Event
      * @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');
@@ -174,7 +186,7 @@ export declare class Emitter<EventsInterface extends EmitterEventsWithStar<Event
      * @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";
      *     }
@@ -186,15 +198,26 @@ export declare class Emitter<EventsInterface extends EmitterEventsWithStar<Event
      *       console.log("Result:", result);
      *
      *     // The console output is:
-     *     //   Arguments: data1 data2
+     *     //	Arguments: data1 data2
      *     //	Result: ["foo"]
      */
     emit<EventName extends keyof EventsInterface>(eventName: EventName, ...data: Parameters<EventsInterface[EventName]>): (ReturnType<EventsInterface[EventName]> | ListenerReturnFlag)[];
+    /**
+     * 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 extends keyof EventsInterface>(eventName: EventName, id: string, ...data: Parameters<EventsInterface[EventName]>): (ReturnType<EventsInterface[EventName]> | ListenerReturnFlag)[];
     /**
-     * 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.
@@ -262,7 +285,6 @@ export declare class Emitter<EventsInterface extends EmitterEventsWithStar<Event
      */
     _processRemovalQueue(): void;
 }
-export declare function makeEmitter(obj: AnyConstructor, prototypeMode: boolean): Emitter;
-export declare function makeEmitter(obj: boolean): Emitter;
-export declare function makeEmitter(obj: Record<string, unknown>, prototypeMode: boolean): Emitter;
-export {};
+export declare function makeEmitter<EventsInterface extends EmitterEventsWithStar<EventsInterface> = EmitterAnyEventsInterface>(obj: boolean): Emitter<EventsInterface>;
+export declare function makeEmitter<EventsInterface extends EmitterEventsWithStar<EventsInterface> = EmitterAnyEventsInterface>(obj: Record<string, unknown>, prototypeMode: boolean): Emitter<EventsInterface>;
+export declare function makeEmitter<EventsInterface extends EmitterEventsWithStar<EventsInterface> = EmitterAnyEventsInterface>(obj: AnyConstructor): Emitter<EventsInterface>;

package/dist/cjs/src/Emitter.js

@@ -8,16 +8,22 @@ var ListenerReturnFlag;
     ListenerReturnFlag["cancel"] = "!+_CANCEL";
 })(ListenerReturnFlag || (exports.ListenerReturnFlag = ListenerReturnFlag = {}));
 /**
- * Creates a new class with the capability to emit events.
+ * Creates a new class with the ability to emit events.
  */
 class Emitter {
-    constructor() {
+    constructor(dispatchPrefix, shouldDispatchWindowEvents = false) {
         this._eventsEmitting = false;
         this._eventRemovalQueue = [];
         this._eventListeners = {};
         this._eventStaticEmitters = {};
         this._eventsAllowDefer = false;
         this._eventsDeferTimeouts = {};
+        this._dispatchWindowEventsEnabled = false;
+        this._dispatchPrefix = dispatchPrefix;
+        this._dispatchWindowEventsEnabled = shouldDispatchWindowEvents;
+    }
+    dispatchWindowEventsEnabled(shouldDispatchWindowEvents) {
+        this._dispatchWindowEventsEnabled = shouldDispatchWindowEvents;
     }
     /**
      * Attach an event listener to the passed event only if the passed
@@ -38,9 +44,7 @@ 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++) {
@@ -188,6 +192,22 @@ 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
@@ -221,7 +241,7 @@ class Emitter {
      *       console.log("Result:", result);
      *
      *     // The console output is:
-     *     //   Arguments: data1 data2
+     *     //	Arguments: data1 data2
      *     //	Result: "foo"
      */
     rpc(eventName, ...data) {
@@ -259,7 +279,7 @@ 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');
@@ -272,7 +292,7 @@ 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";
      *     }
@@ -284,12 +304,22 @@ class Emitter {
      *       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] && !this._eventListeners["*"])) {
             return [];
@@ -317,9 +347,11 @@ class Emitter {
         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.

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

@@ -40,7 +40,8 @@ describe("Emitter", () => {
         it("Creates emitter instance by instantiation", () => {
             var _a, _b;
             const myClass = new Emitter_1.Emitter();
-            myClass.on("moo", () => { });
+            myClass.on("moo", () => {
+            });
             assert_1.default.strictEqual((_a = myClass._eventListeners) === null || _a === void 0 ? void 0 : _a.moo["*"].length, 1, "Listener registered on event");
             myClass.off("moo");
             assert_1.default.strictEqual(!((_b = myClass._eventListeners) === null || _b === void 0 ? void 0 : _b.moo) ||
@@ -241,11 +242,15 @@ describe("Emitter", () => {
         it("Cancels all listeners (event)", () => {
             var _a, _b, _c, _d, _e, _f, _g;
             const myClass = new Emitter_1.Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert_1.default.strictEqual((_a = myClass._eventListeners) === null || _a === void 0 ? void 0 : _a.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert_1.default.strictEqual((_b = myClass._eventListeners) === null || _b === void 0 ? void 0 : _b.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert_1.default.strictEqual((_c = myClass._eventListeners) === null || _c === void 0 ? void 0 : _c.moo["*"].length, 2, "Listeners registered on event");
@@ -259,11 +264,15 @@ describe("Emitter", () => {
         it("Cancels id-based listeners (event, id)", () => {
             var _a, _b, _c, _d, _e, _f, _g;
             const myClass = new Emitter_1.Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert_1.default.strictEqual((_a = myClass._eventListeners) === null || _a === void 0 ? void 0 : _a.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert_1.default.strictEqual((_b = myClass._eventListeners) === null || _b === void 0 ? void 0 : _b.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert_1.default.strictEqual((_c = myClass._eventListeners) === null || _c === void 0 ? void 0 : _c.moo["*"].length, 2, "Listeners registered on event");
@@ -276,11 +285,15 @@ describe("Emitter", () => {
         it("Cancels listener-based listeners (event, listener)", () => {
             var _a, _b, _c, _d, _e, _f;
             const myClass = new Emitter_1.Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert_1.default.strictEqual((_a = myClass._eventListeners) === null || _a === void 0 ? void 0 : _a.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert_1.default.strictEqual((_b = myClass._eventListeners) === null || _b === void 0 ? void 0 : _b.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert_1.default.strictEqual((_c = myClass._eventListeners) === null || _c === void 0 ? void 0 : _c.moo["*"].length, 2, "Listeners registered on event");
@@ -293,11 +306,15 @@ describe("Emitter", () => {
         it("Cancels id-based + listener-based listeners (event, id, listener)", () => {
             var _a, _b, _c, _d, _e, _f;
             const myClass = new Emitter_1.Emitter();
-            const listener1 = () => { };
-            const listener2 = () => { };
-            myClass.on("moo", () => { });
+            const listener1 = () => {
+            };
+            const listener2 = () => {
+            };
+            myClass.on("moo", () => {
+            });
             assert_1.default.strictEqual((_a = myClass._eventListeners) === null || _a === void 0 ? void 0 : _a.moo["*"].length, 1, "Listeners registered on event");
-            myClass.on("moo", "testId", () => { });
+            myClass.on("moo", "testId", () => {
+            });
             assert_1.default.strictEqual((_b = myClass._eventListeners) === null || _b === void 0 ? void 0 : _b.moo["testId"].length, 1, "Listeners registered on event");
             myClass.on("moo", listener1);
             assert_1.default.strictEqual((_c = myClass._eventListeners) === null || _c === void 0 ? void 0 : _c.moo["*"].length, 2, "Listeners registered on event");