comes 0.0.1 → 0.0.2

package/build/index.d.ts

@@ -30,11 +30,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>;
 };
 /**
@@ -50,12 +74,12 @@ export declare class EventSystem {
     };
     /**
      * 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
      */
@@ -67,25 +91,58 @@ 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;
+    /**
+     * 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: string, listener: (event: any) => void): void;
     /**
-     * Configure a loader to execute when the first listener is registered and no value exists yet.
+     * 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}.
      *
-     * @param id The address name
+     * 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

@@ -30,7 +30,7 @@ class EventSystem {
     }
     /**
      * 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,7 +39,7 @@ 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
      */
@@ -58,7 +58,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 +68,102 @@ 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.
+     * Configure a {@link ES_ValueType.loader loader} to execute when the first listener is registered and no value exists yet.
      *
-     * @param id The address name
+     * 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, 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.emit(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.2",
   "description": "Simple Event System Communication",
   "keywords": [
     "event",