@irrelon/emitter 5.0.6 → 6.0.1

package/.eslintignore

@@ -1 +1,2 @@
-node_modules
+node_modules
+readme.md

package/.prettierignore

@@ -2,8 +2,9 @@ artifacts
 cache
 node_modules
 .next
-yarn.lock
 package-lock.json
 public
 .yarn
 .yarnrc
+.md
+readme.md

package/.prettierrc.yml

@@ -1,9 +1,26 @@
 trailingComma: "none"
 tabWidth: 4
-printWidth: 140
+printWidth: 120
 semi: true
 singleQuote: false
 arrowParens: always
 bracketSpacing: true
 bracketSameLine: false
 jsxSingleQuote: false
+plugins: ['@trivago/prettier-plugin-sort-imports']
+importOrder: [
+    "^react$",
+    "chakra-ui",
+    "<THIRD_PARTY_MODULES>",
+    "interface",
+    "context/",
+    "config",
+    "components/",
+    "utils/",
+    "services/",
+    "enums/",
+    "types/",
+    ".svg",
+    "^../(.*)$",
+    "(?=./styles.module.scss)",
+]

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

@@ -1,31 +1,31 @@
-export declare type AnyFunction<ReturnType = any> = (...args: any[]) => ReturnType;
-export declare type AnyConstructor = new (...args: any[]) => any;
-export declare enum EventReturnFlag {
-    none = 0,
-    cancel = 1
+export type AnyFunction<ReturnType = any> = (...args: any[]) => ReturnType;
+export type AnyConstructor = new (...args: any[]) => any;
+export declare enum ListenerReturnFlag {
+    none = "!+_NONE",
+    cancel = "!+_CANCEL"
 }
-export declare type EventListenerCallback<EventCallbackFunctionSignature extends AnyFunction = AnyFunction> = (...args: Parameters<EventCallbackFunctionSignature>) => ReturnType<EventCallbackFunctionSignature>;
+export type EventListenerCallback<EventCallbackFunctionSignature extends AnyFunction = AnyFunction> = (...args: Parameters<EventCallbackFunctionSignature>) => ReturnType<EventCallbackFunctionSignature>;
 export interface EventStaticEmitterObject<EventCallbackFunctionSignature extends AnyFunction = AnyFunction> {
     id: string;
     args: Parameters<EventCallbackFunctionSignature>;
 }
-export interface EmitterEventsInterface {
+export interface EmitterAnyEventsInterface {
     [key: string]: AnyFunction;
 }
-export declare type ConvertInterfaceToDict<T> = {
+export type EmitterEventsInterface<T> = {
     [K in keyof T]: T[K];
 };
 /**
  * Creates a new class with the capability to emit events.
  */
-export declare class Emitter<EventsInterface extends EmitterEventsInterface = EmitterEventsInterface> {
+export declare class Emitter<EventsInterface extends EmitterEventsInterface<EventsInterface> = EmitterAnyEventsInterface> {
     _eventsEmitting: boolean;
     _eventRemovalQueue: any[];
     _eventListeners?: {
-        [EventName in (keyof EventsInterface)]?: Record<string, EventListenerCallback<EventsInterface[EventName]>[]>;
+        [EventName in keyof EventsInterface]?: Record<string, EventListenerCallback<EventsInterface[EventName]>[]>;
     };
     _eventStaticEmitters: {
-        [EventName in (keyof EventsInterface)]?: EventStaticEmitterObject<EventsInterface[EventName]>[];
+        [EventName in keyof EventsInterface]?: EventStaticEmitterObject<EventsInterface[EventName]>[];
     };
     _eventsAllowDefer: boolean;
     _eventsDeferTimeouts: Record<any, number>;
@@ -101,6 +101,46 @@ export declare class Emitter<EventsInterface extends EmitterEventsInterface = Em
     off<EventName extends keyof EventsInterface>(eventName: EventName, id: string, listener?: EventListenerCallback<EventsInterface[EventName]>): this;
     off<EventName extends keyof EventsInterface>(eventName: EventName, listener?: EventListenerCallback<EventsInterface[EventName]>): this;
     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)[];
+    /**
+     * 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
+     * event rather than all event listeners. If you have more than one event listener
+     * assigned to the event, all others except the first will be ignored and will
+     * not receive the event.
+     * @param eventName The name of the event to call the listener for.
+     * @param {...any} data The arguments to send to the listening method.
+     * If you are sending multiple arguments, separate them with a comma so
+     * that they are received by the function as separate arguments.
+     * @return {number}
+     * @example #Call the Event Listener
+     *     // Emit the event named "hello"
+     *     myEntity.emit('hello');
+     * @example #Call the Event Listener With Data Object
+     *     // Emit the event named "hello"
+     *     myEntity.emit('hello', {moo: true});
+     * @example #Call the Event Listener With Multiple Data Values
+     *     // Emit the event named "hello"
+     *     myEntity.emit('hello', {moo: true}, 'someString');
+     * @example #Register the Listener 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) {
+     *         console.log("Arguments:", arg1, arg2);
+     *         return "foo";
+     *     }
+     *
+     *     // Emit the event named "hello"
+     *     const result = myEntity.emit('hello', 'data1', 'data2');
+     *	   console.log("Result:", result);
+     *
+     *     // The console output is:
+     *     //   Arguments: data1 data2
+     *     //	Result: "foo"
+     */
+    rpc<EventName extends keyof EventsInterface>(eventName: EventName, ...data: Parameters<EventsInterface[EventName]>): ReturnType<EventsInterface[EventName]> | ListenerReturnFlag;
+    rpcId<EventName extends keyof EventsInterface>(eventName: EventName, id: string, ...data: Parameters<EventsInterface[EventName]>): ReturnType<EventsInterface[EventName]> | ListenerReturnFlag;
     /**
      * Emit an event by name.
      * @param eventName The name of the event to emit.
@@ -120,18 +160,23 @@ export declare class Emitter<EventsInterface extends EmitterEventsInterface = Em
      * @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) {
-     *         console.log(arg1, arg2);
+     *   myEntity.on('hello', function (arg1, arg2) {
+     *         console.log("Arguments:", arg1, arg2);
+     *         return "foo";
      *     }
      *
      *     // Emit the event named "hello"
-     *     myEntity.emit('hello', 'data1', 'data2');
+     *     // 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);
      *
      *     // The console output is:
-     *     //    data1, data2
+     *     //   Arguments: data1 data2
+     *     //	Result: ["foo"]
      */
-    emit<EventName extends keyof EventsInterface>(eventName: EventName, ...data: Parameters<EventsInterface[EventName]>): Promise<EventReturnFlag>;
-    emitId<EventName extends keyof EventsInterface>(eventName: EventName, id: string, ...data: Parameters<EventsInterface[EventName]>): EventReturnFlag;
+    emit<EventName extends keyof EventsInterface>(eventName: EventName, ...data: Parameters<EventsInterface[EventName]>): (ReturnType<EventsInterface[EventName]> | ListenerReturnFlag)[];
+    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
@@ -186,13 +231,19 @@ export declare class Emitter<EventsInterface extends EmitterEventsInterface = Em
      * @returns The emitter instance.
      */
     deferEmit<EventName extends keyof EventsInterface>(eventName: EventName, ...data: Parameters<EventsInterface[EventName]>): this;
+    /**
+     * Returns true if the result from an emit() call passed as the first
+     * argument contains a cancellation flag.
+     * @param resultArr
+     */
+    didCancel(resultArr: (unknown | ListenerReturnFlag)[]): boolean;
     /**
      * If events are cleared with the off() method while the event emitter is
      * actively processing any events then the off() calls get added to a
      * queue to be executed after the event emitter is finished. This stops
-     * errors that might occur by potentially modifying the event queue while
-     * the emitter is running through them. This method is called after the
-     * event emitter is finished processing.
+     * errors that might occur by potentially mutating the event listener array
+     * while the emitter is running through them. This method is called after
+     * the event emitter is finished processing.
      * @private
      */
     _processRemovalQueue(): void;

package/dist/cjs/src/Emitter.js

@@ -1,20 +1,11 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeEmitter = exports.Emitter = exports.EventReturnFlag = void 0;
-var EventReturnFlag;
-(function (EventReturnFlag) {
-    EventReturnFlag[EventReturnFlag["none"] = 0] = "none";
-    EventReturnFlag[EventReturnFlag["cancel"] = 1] = "cancel";
-})(EventReturnFlag = exports.EventReturnFlag || (exports.EventReturnFlag = {}));
+exports.makeEmitter = exports.Emitter = exports.ListenerReturnFlag = void 0;
+var ListenerReturnFlag;
+(function (ListenerReturnFlag) {
+    ListenerReturnFlag["none"] = "!+_NONE";
+    ListenerReturnFlag["cancel"] = "!+_CANCEL";
+})(ListenerReturnFlag || (exports.ListenerReturnFlag = ListenerReturnFlag = {}));
 /**
  * Creates a new class with the capability to emit events.
  */
@@ -42,11 +33,13 @@ class Emitter {
             }, 1);
         };
         this._eventListeners = this._eventListeners || {};
-        const nonNullableEventListeners = this._eventListeners[eventName] = this._eventListeners[eventName] || {};
+        const nonNullableEventListeners = (this._eventListeners[eventName] = this._eventListeners[eventName] || {});
         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++) {
@@ -159,6 +152,92 @@ class Emitter {
         // Both id and listener were provided, remove for the specific id
         return this._off(eventName, rest[0], rest[1]);
     }
+    _emitToSingleListener(listener, data) {
+        return listener(...data);
+    }
+    _emitToArrayOfListeners(arr, data) {
+        const arrCount = arr.length;
+        const resultArr = [];
+        for (let arrIndex = 0; arrIndex < arrCount; arrIndex++) {
+            // Check we have a function to execute
+            const tmpFunc = arr[arrIndex];
+            if (typeof tmpFunc !== "function") {
+                continue;
+            }
+            const eventListenerResponse = tmpFunc(...data);
+            resultArr.push(eventListenerResponse);
+            if (eventListenerResponse === ListenerReturnFlag.cancel) {
+                // Cancel further event processing
+                break;
+            }
+        }
+        return resultArr;
+    }
+    /**
+     * 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
+     * event rather than all event listeners. If you have more than one event listener
+     * assigned to the event, all others except the first will be ignored and will
+     * not receive the event.
+     * @param eventName The name of the event to call the listener for.
+     * @param {...any} data The arguments to send to the listening method.
+     * If you are sending multiple arguments, separate them with a comma so
+     * that they are received by the function as separate arguments.
+     * @return {number}
+     * @example #Call the Event Listener
+     *     // Emit the event named "hello"
+     *     myEntity.emit('hello');
+     * @example #Call the Event Listener With Data Object
+     *     // Emit the event named "hello"
+     *     myEntity.emit('hello', {moo: true});
+     * @example #Call the Event Listener With Multiple Data Values
+     *     // Emit the event named "hello"
+     *     myEntity.emit('hello', {moo: true}, 'someString');
+     * @example #Register the Listener 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) {
+     *         console.log("Arguments:", arg1, arg2);
+     *         return "foo";
+     *     }
+     *
+     *     // Emit the event named "hello"
+     *     const result = myEntity.emit('hello', 'data1', 'data2');
+     *	   console.log("Result:", result);
+     *
+     *     // The console output is:
+     *     //   Arguments: data1 data2
+     *     //	Result: "foo"
+     */
+    rpc(eventName, ...data) {
+        return this.rpcId(eventName, "*", ...data);
+    }
+    rpcId(eventName, id, ...data) {
+        if (!this._eventListeners || !this._eventListeners[eventName]) {
+            throw new Error("Cannot make an rpc call without at least one event listener and none were found");
+        }
+        let emitterResult;
+        this._eventsEmitting = true;
+        if (this._eventListeners[eventName][id]) {
+            // Handle id emit
+            const arr = this._eventListeners[eventName][id];
+            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
+            const arr = this._eventListeners[eventName]["*"];
+            emitterResult = this._emitToSingleListener(arr[0], data);
+        }
+        else {
+            if (id === "*") {
+                throw new Error(`Cannot make an rpc call to event "${eventName}" without at least one event listener and none were found, register a listener via on("${eventName}", () => { ...some listener code })`);
+            }
+            throw new Error(`Cannot make an rpc call to event "${eventName}" and id "${id}" without at least one event listener and none were found, register a listener via on("${eventName}", "${id}", () => { ...some listener code })`);
+        }
+        this._eventsEmitting = false;
+        this._processRemovalQueue();
+        return emitterResult;
+    }
     /**
      * Emit an event by name.
      * @param eventName The name of the event to emit.
@@ -178,80 +257,43 @@ 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) {
-     *         console.log(arg1, arg2);
+     *   myEntity.on('hello', function (arg1, arg2) {
+     *         console.log("Arguments:", arg1, arg2);
+     *         return "foo";
      *     }
      *
      *     // Emit the event named "hello"
-     *     myEntity.emit('hello', 'data1', 'data2');
+     *     // 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);
      *
      *     // The console output is:
-     *     //    data1, data2
+     *     //   Arguments: data1 data2
+     *     //	Result: ["foo"]
      */
     emit(eventName, ...data) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this._eventListeners) {
-                return EventReturnFlag.none;
-            }
-            const id = "*";
-            let returnFlag = EventReturnFlag.none;
-            this._eventsEmitting = true;
-            if (this._eventListeners[eventName] && this._eventListeners[eventName][id]) {
-                // Handle global emit
-                const arr = this._eventListeners[eventName][id];
-                const promiseArr = arr.map((tmpFunc) => {
-                    if (typeof tmpFunc !== "function")
-                        return;
-                    return tmpFunc(...data);
-                });
-                const result = (yield Promise.all(promiseArr)).find((tmpResult) => tmpResult !== EventReturnFlag.none);
-                if (result) {
-                    returnFlag = EventReturnFlag.cancel;
-                }
-            }
-            this._eventsEmitting = false;
-            this._processRemovalQueue();
-            return returnFlag;
-        });
+        return this.emitId(eventName, "*", ...data);
     }
     emitId(eventName, id, ...data) {
-        if (!this._eventListeners) {
-            return EventReturnFlag.none;
+        if (!this._eventListeners || !this._eventListeners[eventName]) {
+            return [];
         }
-        this._eventListeners = this._eventListeners || {};
+        let emitterResult = [];
         this._eventsEmitting = true;
-        if (!this._eventListeners[eventName]) {
-            this._eventsEmitting = false;
-            this._processRemovalQueue();
-            return EventReturnFlag.none;
-        }
         // Handle id emit
         if (this._eventListeners[eventName][id]) {
             const arr = this._eventListeners[eventName][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);
-                }
-            }
+            emitterResult = emitterResult.concat(this._emitToArrayOfListeners(arr, data));
         }
-        // Handle global emit
-        if (this._eventListeners[eventName]["*"]) {
+        // Handle global emit if the id passed wasn't already a global (*) id
+        if (id !== "*" && this._eventListeners[eventName]["*"]) {
             const arr = this._eventListeners[eventName]["*"];
-            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);
-                }
-            }
+            emitterResult = emitterResult.concat(this._emitToArrayOfListeners(arr, data));
         }
         this._eventsEmitting = false;
         this._processRemovalQueue();
-        return EventReturnFlag.none;
+        return emitterResult;
     }
     /**
      * Creates a persistent emitter record that will fire a listener if
@@ -282,8 +324,8 @@ class Emitter {
         this._eventStaticEmitters = this._eventStaticEmitters || {};
         this._eventStaticEmitters[eventName] = this._eventStaticEmitters[eventName] || [];
         this._eventStaticEmitters[eventName].push({
-            "id": "*",
-            "args": data
+            id: "*",
+            args: data
         });
         this._processRemovalQueue();
         return this;
@@ -334,7 +376,7 @@ class Emitter {
         this._eventStaticEmitters[eventName] = this._eventStaticEmitters[eventName] || [];
         this._eventStaticEmitters[eventName].push({
             id,
-            "args": data
+            args: data
         });
         this._processRemovalQueue();
         return this;
@@ -436,13 +478,21 @@ class Emitter {
         }
         return this;
     }
+    /**
+     * Returns true if the result from an emit() call passed as the first
+     * argument contains a cancellation flag.
+     * @param resultArr
+     */
+    didCancel(resultArr) {
+        return resultArr.findIndex((result) => result === ListenerReturnFlag.cancel) > -1;
+    }
     /**
      * If events are cleared with the off() method while the event emitter is
      * actively processing any events then the off() calls get added to a
      * queue to be executed after the event emitter is finished. This stops
-     * errors that might occur by potentially modifying the event queue while
-     * the emitter is running through them. This method is called after the
-     * event emitter is finished processing.
+     * errors that might occur by potentially mutating the event listener array
+     * while the emitter is running through them. This method is called after
+     * the event emitter is finished processing.
      * @private
      */
     _processRemovalQueue() {