@quazardous/quarkernel 1.0.9 → 1.0.11

package/README.md

@@ -6,11 +6,16 @@ Micro Custom Event Kernel.
 
 Helps structuring your app with events.
 
-- ES6
-- Async() support with Promise
-- Event scope dependency support
-- Composite event
-- Shared context
+- Modern: ES6, Async() support with Promise
+- Dependency support: easily handle async resource dependencies
+- Composite event: handle complex logic with a common event pipe
+- Shared context: use event data to share variable
+
+## Install
+
+```bash
+npm i "@quazardous/quarkernel"
+```
 
 ## Basic usage
 
@@ -34,14 +39,14 @@ qk.addEventListener('my_event', async (e) => {
     e.context.needed = await needed();
 }, 'foo');
 
-// somewhere else in your app your module bar is waitint after foo to set a specific context
+// somewhere else in your app your module bar is waiting after foo to set a specific context
 qk.addEventListener('my_event', (e) => {
     // something after the async callback
     needing(e.context.needed);
 }, 'bar', 'foo');
 
 // call everything
-qk.dispatchEvent(new QKE('my_event')).then(() => {
+qk.dispatchEvent(new QKE('my_event')).then((e) => {
     // event my_event fully dispatched
     happyEnd();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/quarkernel",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "type": "module",
   "description": "Micro Custom Events Kernel",
   "repository": {

package/src/lib/QuarKernel.js

@@ -2,10 +2,28 @@
 import toposort from 'toposort';
 
 class GraphNode {
+  /**
+   * @param {string} target 
+   * @param {string} name 
+   * @param {Array<string>} requires 
+   * @param {eventListenerCallback|async eventListenerCallback} callback 
+   */
   constructor(target, name, requires, callback) {
+    /**
+     * @type {string}
+     */
     this.target = target;
+    /**
+     * @type {string}
+     */
     this.name = name;
+    /**
+     * @type {Array<string>}
+     */
     this.requires = requires;
+    /**
+     * @type {eventListenerCallback|async eventListenerCallback}
+     */
     this.callback = callback;
   }
 }
@@ -15,7 +33,13 @@ class GraphNodeProcessor {
    * @param {Array<GraphNode>} nodes 
    */
   constructor(nodes) {
+    /**
+     * @type {Object.<string, {promise:Promise<QuarKernelEvent>|null,node:GraphNode}>}
+     */
     this.processMap = {};
+    /**
+     * @type {Array<GraphNode>} nodes 
+     */
     this.nodes = nodes;
     nodes.forEach(n => {
       this.processMap[n.name] = {
@@ -25,35 +49,53 @@ class GraphNodeProcessor {
     });
   }
 
-  processAll(...args) {
+  /**
+   * @param  {QuarKernelEvent} e
+   * @return {Promise<QuarKernelEvent>}
+   * @private
+   */
+  processAll(e) {
     return Promise.all(
-      this.nodes.map(n => this.process(n, ...args))
-    );
+      this.nodes.map(n => this.process(n, e))
+    ).then(() => e);
   }
 
-  process(node, ...args) {
+  /**
+   * @param  {GraphNode} node 
+   * @param  {QuarKernelEvent} e
+   * @return {Promise<*>} 
+   * @private
+   */
+  process(node, e) {
     const process = this.processMap[node.name];
     if (!process.promise) {
       let then = null;
       if (node.callback.constructor.name === 'AsyncFunction') {
         // handle async
-        then = () => node.callback(...args, node.target);
+        then = () => node.callback(e, node.target);
       } else {
         then = () => new Promise((resolve) => {
-          resolve(node.callback(...args, node.target));
+          node.callback(e, node.target);
+          resolve();
         });
       }
-      process.promise = this.processDependencies(node, ...args).then(then);
+      process.promise = this.processDependencies(node, e).then(then);
     }
     return process.promise;
   }
 
-  processDependencies(node, ...args) {
+  /**
+   * @param  {GraphNode} node 
+   * @param  {QuarKernelEvent} e
+   * @return {Promise<*>} 
+   * @private
+   */
+  processDependencies(node, e) {
     if (node.requires.length) {
       const promises = [];
       this.nodes.forEach(n => {
         if (node.requires.includes(n.target)) {
-          promises.push(this.process(n, ...args));
+          promises.push(this.process(n, e));
         }
       });
       return Promise.all(promises);
@@ -94,7 +136,7 @@ class CompositeTrigger {
     this.callback = callback;
     this.reset = reset;
     /**
-     * @type {Object.<string, Array<{e:QuarKernelEvent,p:Promise<*>}>>}
+     * @type {Object.<string, Array<{e:QuarKernelEvent,p:Promise<QuarKernelEvent>}>>}
      */
     this.eventPromiseStack = {};
   }
@@ -103,6 +145,7 @@ class CompositeTrigger {
    * @param {QuarKernelEvent} e 
    * @param {Promise<*>} p
    * @return {Promise<*>|null}
+   * @private
    */
   compose(e, p) {
     if (!this.components.includes(e.type)) {
@@ -135,9 +178,14 @@ class CompositeTrigger {
   }
 }
 
+/**
+ * @callback eventListenerCallback
+ * @param {QuarKernelEvent} [e]
+ */
+
 /**
  * @callback composeTriggerCallback
- * @param {Object.<string, Array<{e:QuarKernelEvent,p:Promise<*>}>>} [stack] Stack of components events/promises
+ * @param {Object.<string, Array<{e:QuarKernelEvent,p:Promise<QuarKernelEvent>}>>} [stack] Stack of components events/promises
  */
 
 /**
@@ -260,8 +308,8 @@ class QuarKernel {
 
   /**
    * @param {QuarKernelEvent} e 
-   * @param {Promise<*>} p
-   * @return {Promise<*>}
+   * @param {Promise<QuarKernelEvent>} p
+   * @return {Promise<QuarKernelEvent>}
    * @private
    */
   composeTrigger(e, p) {
@@ -273,7 +321,7 @@ class QuarKernel {
       }
     });
     if (list.length > 0) {
-      p = p.then(() => Promise.all(list))
+      p = p.then(() => Promise.all(list).then(() => e))
     }
     return p;
   }
@@ -282,7 +330,7 @@ class QuarKernel {
    * Dispatch an event.
    *
    * @param {QuarKernelEvent} e The event
-   * @return {Promise<*>}
+   * @return {Promise<QuarKernelEvent>}
    */
   dispatchEvent(e) {
     if (!(e instanceof QuarKernelEvent)) {
@@ -290,7 +338,7 @@ class QuarKernel {
     }
     if (typeof this.callbacks[e.type] === 'undefined') {
       // no callback registered
-      return this.composeTrigger(e, Promise.resolve());
+      return this.composeTrigger(e, Promise.resolve(e));
     }
     if (typeof this.seqGraph[e.type] !== 'undefined') {
       // using toposort to early detect dependencies loop

package/types/QuarKernel.d.ts

@@ -1,7 +1,8 @@
+export type eventListenerCallback = (e?: QuarKernelEvent) => any;
 export type composeTriggerCallback = (stack?: {
     [x: string]: Array<{
         e: QuarKernelEvent;
-        p: Promise<any>;
+        p: Promise<QuarKernelEvent>;
     }>;
 }) => any;
 export type composeEventFactory = (stack?: {
@@ -9,9 +10,13 @@ export type composeEventFactory = (stack?: {
 }) => QuarKernelEvent;
 export type eventCallback = (e?: QuarKernelEvent, target?: string) => any;
 export type eventAsyncCallback = () => any;
+/**
+ * @callback eventListenerCallback
+ * @param {QuarKernelEvent} [e]
+ */
 /**
  * @callback composeTriggerCallback
- * @param {Object.<string, Array<{e:QuarKernelEvent,p:Promise<*>}>>} [stack] Stack of components events/promises
+ * @param {Object.<string, Array<{e:QuarKernelEvent,p:Promise<QuarKernelEvent>}>>} [stack] Stack of components events/promises
  */
 /**
  * @callback composeEventFactory
@@ -84,8 +89,8 @@ export class QuarKernel {
     addCompositeEvent(components: Array<string>, factory: composeEventFactory, reset?: boolean): void;
     /**
      * @param {QuarKernelEvent} e
-     * @param {Promise<*>} p
-     * @return {Promise<*>}
+     * @param {Promise<QuarKernelEvent>} p
+     * @return {Promise<QuarKernelEvent>}
      * @private
      */
     private composeTrigger;
@@ -93,9 +98,9 @@ export class QuarKernel {
      * Dispatch an event.
      *
      * @param {QuarKernelEvent} e The event
-     * @return {Promise<*>}
+     * @return {Promise<QuarKernelEvent>}
      */
-    dispatchEvent(e: QuarKernelEvent): Promise<any>;
+    dispatchEvent(e: QuarKernelEvent): Promise<QuarKernelEvent>;
     /**
      * @param {string} type
      * @param {string} target