comes 0.0.1 → 0.0.3

package/build/index.d.ts

@@ -1,9 +1,5 @@
-/**
- * Function to exclude an item from the array.
- * @param item Item that will be removed
- * @param list Array where to find the item
- */
-export declare function deleteFromArray(item: any, list: any[]): void;
+export type EventListenerType<T = any> = (event: T) => void;
+export type EventInterceptorType<T = any> = (id: string, event: T, es: EventSystem) => T;
 /**
  * Type that holds the value for an event address.
  */
@@ -15,7 +11,7 @@ export type ES_ValueType = {
     /**
      * Listeners of this event.
      */
-    listeners: ((event: any) => void)[];
+    listeners: EventListenerType[];
     /**
      * Last time an event was emitted.
      *
@@ -30,11 +26,35 @@ export type ES_ValueType = {
      * If some event/value was emitted before the first listener registered, so
      * this function will not be called.
      *
-     * @param id The address name
+     * @param id The address name of the event
      * @param args Extra parameters to the function
-     * @returns
+     * @returns void
      */
     loader?: (id: string, ...args: any[]) => void;
+    /**
+     * Error handler of the loader. If the execution of the loader throw
+     * an Error/Exception then this function will be called with the
+     * exception.
+     *
+     * This function can be async, and will be awaited.
+     *
+     * If this functions returns a value (not undefined), then the loader will
+     * resolve successfully with that value.
+     * If this function does not return a value, then loader will reject with the
+     * original exception.
+     * If this function throws an exception, then the loader will reject with that exception,
+     * and the original exception of the loader will be in the "loaderEx" field of that exception.
+     *
+     * @param id The address name of the event
+     * @param ex Exception thrown by the loader
+     * @returns void
+     */
+    loaderCatch?: (id: string, ex: Error | any) => any;
+    /**
+     * Promise resolved when loader ends execution.
+     * If some error occurss then the "loaderCatch" function
+     * will be called.
+     */
     loaderProm?: Promise<any>;
 };
 /**
@@ -48,18 +68,30 @@ export declare class EventSystem {
     data: {
         [id: string]: ES_ValueType;
     };
+    /**
+     * Interceptors to transform data.
+     * Interceptors are called in the installation order.
+     * The special empty string event address will be called for all events sent.
+     *
+     * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+     * the event sent to an address. The sequence of interceptors will be called like a
+     * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+     * will not be executed, and the listeners not called.
+     */
+    inters: {
+        [id: string]: EventInterceptorType[];
+    };
     /**
      * Gets a reference to {@link ES_ValueType} of the address informed.
-     * @param id The address name
+     * @param id The address name of the event
      */
     get(id: string): ES_ValueType;
     /**
      * Sends the value to the listeners of the event address.
-     * @param id The address name
+     * @param id The address name of the event
      * @param event The value to send to listeners
-     * @returns The value informed
      */
-    emit<T>(id: string, event: T): T;
+    send<T>(id: string, event: T): Promise<T>;
     /**
      * Register a listener for the address.
      * The listener will receive the last value emitted.
@@ -67,25 +99,84 @@ export declare class EventSystem {
      *
      * The listener will be called with the last value available in the cache.
      *
-     * @param id The address name
+     * @param id The address name of the event
      * @param listener The listener, will be called every time a new value is emitted to this address
      * @returns An unregister function. Use this function to remove the listener
      */
-    listen(id: string, listener: (event: any) => void): () => void;
-    unlisten(id: string, listener: (event: any) => void): void;
+    listen(id: string, listener: EventListenerType): () => void;
     /**
-     * Configure a loader to execute when the first listener is registered and no value exists yet.
+     * Remove the listener from the list of this event address.
+     *
+     * If you need to remove a listener from the event address inside the exection of
+     * the listener, then use this function like so:
+     * ```ts
+     * const listener = () => {
+     *    es.unlisten(ES_EVENT_NAME, listener);
+     *    // then do what you need...
+     *    // ...
+     * };
+     * es.listen(ES_EVENT_NAME, listener);
+     * ```
+     * This is because in some cases the return value of the {@link EventSystem.listen listen}
+     * will not be ready to unregister the listener (the variable will not be set yet).
      *
-     * @param id The address name
+     * @param id The address name of the event
+     * @param listener Listener to remove
+     */
+    unlisten(id: string, listener: EventListenerType): void;
+    /**
+     * Add an interceptor to transform data.
+     * Interceptors are called in the installation order.
+     * The special empty string event address will be called for all events sent.
+     *
+     * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+     * the event sent to an address. The sequence of interceptors will be called like a
+     * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+     * will not be executed, and the listeners not called.
+     *
+     * Interceptors will be executed synchronous in the call of the {@link send} method.
+     * So any exception thrown will be thrown also in the {@link send} call.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    addInter(id: string, listener: EventInterceptorType): () => void;
+    /**
+     * Remove an interceptor.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    removeInter(id: string, listener: EventInterceptorType): void;
+    /**
+     * Configure a {@link ES_ValueType.loader loader} to execute when the first listener is registered and no value exists yet.
+     *
+     * Remember to configure a Error Handler ({@link ES_ValueType.loaderCatch loaderCatch}) before configuring
+     * the {@link ES_ValueType.loader loader}, or use the 3o argumento to
+     * configure the {@link ES_ValueType.loaderCatch loaderCatch}.
+     *
+     * If any listener is registered, and no value was emitted yet, then the loader will
+     * be called by this method to fetch the first value of the event address.
+     *
+     * @param id The address name of the event
      * @param loader The function to execute when the first liteners is registered
      *               and no value exists yet.
+     * @param loaderCatch The error handler for exceptions thrown by the {@link ES_ValueType.loader loader}
      */
-    setLoader(id: string, loader: ES_ValueType['loader']): void;
+    setLoader(id: string, loader: ES_ValueType['loader'], loaderCatch?: ES_ValueType['loaderCatch']): void;
+    setLoaderCatch(id: string, loaderCatch: ES_ValueType['loaderCatch']): void;
     /**
-     * Executes the loader for an address.
-     * @param id The address name
-     * @param args Arguments to pass to the loader
-     * @returns Promise that will resolve when the loader resolves
+     * Executes the {@link ES_ValueType.loader loader} for an address.
+     *
+     * If some error hapens in the {@link ES_ValueType.loader loader} function, then the {@link ES_ValueType.loaderCatch loaderCatch} will be
+     * called with the error (if configured).
+     * Check the {@link ES_ValueType.loaderCatch loaderCatch} docs to understand the behavior.
+     *
+     * @param id The address name of the event
+     * @param args Arguments to pass to the {@link ES_ValueType.loader loader}
+     * @returns Promise that will resolve when the {@link ES_ValueType.loader loader} resolves
      */
     load<T>(id: string, ...args: any[]): Promise<() => T>;
 }

package/build/index.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.es = exports.EventSystem = void 0;
-exports.deleteFromArray = deleteFromArray;
 // -------
 /**
  * Function to exclude an item from the array.
@@ -27,10 +26,21 @@ class EventSystem {
          * holds the last value for the address.
          */
         this.data = {};
+        /**
+         * Interceptors to transform data.
+         * Interceptors are called in the installation order.
+         * The special empty string event address will be called for all events sent.
+         *
+         * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+         * the event sent to an address. The sequence of interceptors will be called like a
+         * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+         * will not be executed, and the listeners not called.
+         */
+        this.inters = {};
     }
     /**
      * Gets a reference to {@link ES_ValueType} of the address informed.
-     * @param id The address name
+     * @param id The address name of the event
      */
     get(id) {
         if (!this.data[id])
@@ -39,17 +49,34 @@ class EventSystem {
     }
     /**
      * Sends the value to the listeners of the event address.
-     * @param id The address name
+     * @param id The address name of the event
      * @param event The value to send to listeners
-     * @returns The value informed
      */
-    emit(id, event) {
+    async send(id, event) {
+        let inters = [...(this.inters[''] || []), ...(this.inters[id] || [])];
+        let newValue = event;
+        try {
+            for (let inte of inters) {
+                newValue = await inte(id, newValue, this);
+            }
+        }
+        catch (err) {
+            console.error(`error on interceptor of ${id}`, err);
+            throw err;
+        }
         let esData = this.get(id);
-        esData.last = event;
+        esData.last = newValue;
         esData.date = new Date();
-        for (let func of esData.listeners)
-            func(event);
-        return event;
+        for (let func of esData.listeners) {
+            try {
+                await func(newValue);
+            }
+            catch (err) {
+                console.error(`Error on listener of ${id}, ${func}`, err);
+                throw err;
+            }
+        }
+        return newValue;
     }
     /**
      * Register a listener for the address.
@@ -58,7 +85,7 @@ class EventSystem {
      *
      * The listener will be called with the last value available in the cache.
      *
-     * @param id The address name
+     * @param id The address name of the event
      * @param listener The listener, will be called every time a new value is emitted to this address
      * @returns An unregister function. Use this function to remove the listener
      */
@@ -68,40 +95,135 @@ class EventSystem {
         if (esData.date)
             listener(esData.last);
         else if (esData.loader)
-            exports.es.load(id);
+            esData.loaderProm = this.load(id);
         return () => this.unlisten(id, listener);
     }
+    /**
+     * Remove the listener from the list of this event address.
+     *
+     * If you need to remove a listener from the event address inside the exection of
+     * the listener, then use this function like so:
+     * ```ts
+     * const listener = () => {
+     *    es.unlisten(ES_EVENT_NAME, listener);
+     *    // then do what you need...
+     *    // ...
+     * };
+     * es.listen(ES_EVENT_NAME, listener);
+     * ```
+     * This is because in some cases the return value of the {@link EventSystem.listen listen}
+     * will not be ready to unregister the listener (the variable will not be set yet).
+     *
+     * @param id The address name of the event
+     * @param listener Listener to remove
+     */
     unlisten(id, listener) {
         let esData = this.get(id);
         deleteFromArray(listener, esData.listeners);
     }
     /**
-     * Configure a loader to execute when the first listener is registered and no value exists yet.
+     * Add an interceptor to transform data.
+     * Interceptors are called in the installation order.
+     * The special empty string event address will be called for all events sent.
+     *
+     * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+     * the event sent to an address. The sequence of interceptors will be called like a
+     * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+     * will not be executed, and the listeners not called.
+     *
+     * Interceptors will be executed synchronous in the call of the {@link send} method.
+     * So any exception thrown will be thrown also in the {@link send} call.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    addInter(id, listener) {
+        if (!this.inters[id])
+            this.inters[id] = [];
+        this.inters[id].push(listener);
+        return () => this.removeInter(id, listener);
+    }
+    /**
+     * Remove an interceptor.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    removeInter(id, listener) {
+        deleteFromArray(listener, this.inters[id]);
+    }
+    /**
+     * Configure a {@link ES_ValueType.loader loader} to execute when the first listener is registered and no value exists yet.
+     *
+     * Remember to configure a Error Handler ({@link ES_ValueType.loaderCatch loaderCatch}) before configuring
+     * the {@link ES_ValueType.loader loader}, or use the 3o argumento to
+     * configure the {@link ES_ValueType.loaderCatch loaderCatch}.
+     *
+     * If any listener is registered, and no value was emitted yet, then the loader will
+     * be called by this method to fetch the first value of the event address.
      *
-     * @param id The address name
+     * @param id The address name of the event
      * @param loader The function to execute when the first liteners is registered
      *               and no value exists yet.
+     * @param loaderCatch The error handler for exceptions thrown by the {@link ES_ValueType.loader loader}
      */
-    setLoader(id, loader) {
+    setLoader(id, loader, loaderCatch) {
         let esData = this.get(id);
         esData.loader = loader;
+        if (loaderCatch)
+            esData.loaderCatch = loaderCatch;
         if (!esData.date && esData.listeners.length)
-            this.load(id);
+            esData.loaderProm = this.load(id);
+    }
+    setLoaderCatch(id, loaderCatch) {
+        let esData = this.get(id);
+        esData.loaderCatch = loaderCatch;
     }
     /**
-     * Executes the loader for an address.
-     * @param id The address name
-     * @param args Arguments to pass to the loader
-     * @returns Promise that will resolve when the loader resolves
+     * Executes the {@link ES_ValueType.loader loader} for an address.
+     *
+     * If some error hapens in the {@link ES_ValueType.loader loader} function, then the {@link ES_ValueType.loaderCatch loaderCatch} will be
+     * called with the error (if configured).
+     * Check the {@link ES_ValueType.loaderCatch loaderCatch} docs to understand the behavior.
+     *
+     * @param id The address name of the event
+     * @param args Arguments to pass to the {@link ES_ValueType.loader loader}
+     * @returns Promise that will resolve when the {@link ES_ValueType.loader loader} resolves
      */
     async load(id, ...args) {
         let esData = this.get(id);
-        if (!esData.loader)
-            return esData.last;
-        esData.loaderProm = new Promise(async (res) => {
-            await esData.loader(id, ...args);
+        if (!esData.loader) {
             esData.loaderProm = undefined;
-            res(esData.last);
+            return esData.last;
+        }
+        esData.loaderProm = new Promise(async (res, rej) => {
+            try {
+                await esData.loader(id, ...args);
+                esData.loaderProm = undefined;
+                res(esData.last);
+            }
+            catch (ex) {
+                if (esData.loaderCatch) {
+                    try {
+                        const catchRes = await esData.loaderCatch(id, ex);
+                        if (catchRes !== undefined) {
+                            this.send(id, catchRes);
+                            res(catchRes);
+                        }
+                    }
+                    catch (ex2) {
+                        try {
+                            ex2.loaderEx = ex;
+                        }
+                        catch (ex3) { /* do nothing */ }
+                        rej(ex2);
+                    }
+                }
+                else
+                    rej(ex);
+            }
         });
         return esData.loaderProm;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comes",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Simple Event System Communication",
   "keywords": [
     "event",