noflo 1.4.2 → 1.5.0

package/src/lib/AsCallback.js

@@ -7,10 +7,10 @@
     import/prefer-default-export,
 */
 import { Graph } from 'fbp-graph';
-import { ComponentLoader } from './ComponentLoader';
-import { Network } from './Network';
-import IP from './IP';
-import * as internalSocket from './InternalSocket';
+import { ComponentLoader } from './ComponentLoader.js';
+import { Network } from './Network.js';
+import IP from './IP.js';
+import * as internalSocket from './InternalSocket.js';
 
 // ## asCallback embedding API
 //
@@ -46,6 +46,14 @@ import * as internalSocket from './InternalSocket';
  * @property {Object} [flowtrace] - Flowtrace instance to use for tracing this network run
  * @property {NetworkCallback} [networkCallback] - Access to Network instance
  * @property {boolean} [raw] - Whether the callback should operate on raw noflo.IP objects
+ * @property {boolean} [asyncDelivery] - Make Information Packet delivery asynchronous
+ */
+
+/**
+ * @typedef {Array<Object<string, IP>>} OutputMap
+ */
+/**
+ * @typedef {Object<string, Array<IP|any>>|Array<Object<string, IP|any>>} InputMap
  */
 
 /**
@@ -70,6 +78,9 @@ function normalizeOptions(options, component) {
   if (!options.raw) {
     options.raw = false;
   }
+  if (!options.asyncDelivery) {
+    options.asyncDelivery = false;
+  }
   return options;
 }
 
@@ -138,7 +149,7 @@ function prepareNetwork(component, options) {
 /**
  * @param {Network} network
  * @param {any} inputs
- * @returns {Promise<any>}
+ * @returns {Promise<OutputMap>}
  */
 function runNetwork(network, inputs) {
   return new Promise((resolve, reject) => {
@@ -157,9 +168,11 @@ function runNetwork(network, inputs) {
       if (!process || !process.component) {
         return;
       }
-      outSockets[outport] = internalSocket.createSocket();
+      outSockets[outport] = internalSocket.createSocket({}, {
+        debug: false,
+      });
       network.subscribeSocket(outSockets[outport]);
-      process.component.outPorts[portDef.port].attach(outSockets[outport]);
+      process.component.outPorts.ports[portDef.port].attach(outSockets[outport]);
       outSockets[outport].from = {
         process,
         port: portDef.port,
@@ -172,9 +185,19 @@ function runNetwork(network, inputs) {
       });
     });
     // Subscribe to process errors
-    let onEnd = null;
-    let onError = null;
-    onError = (err) => {
+    /**
+     * @callback EndListener
+     * @returns {void}
+     */
+    /**
+     * @callback ErrorListener
+     * @param {import("./InternalSocket").SocketError} err
+     * @returns {void}
+     */
+    /** @type {EndListener} */
+    let onEnd;
+    /** @type {ErrorListener} */
+    const onError = (err) => {
       reject(err.error);
       network.removeListener('end', onEnd);
     };
@@ -213,13 +236,15 @@ function runNetwork(network, inputs) {
                 reject(new Error(`Process ${portDef.process} for port ${port} not available in the graph`));
                 return;
               }
-              inSockets[port] = internalSocket.createSocket();
+              inSockets[port] = internalSocket.createSocket({}, {
+                debug: false,
+              });
               network.subscribeSocket(inSockets[port]);
               inSockets[port].to = {
                 process,
                 port,
               };
-              process.component.inPorts[portDef.port].attach(inSockets[port]);
+              process.component.inPorts.ports[portDef.port].attach(inSockets[port]);
             }
             try {
               if (IP.isIP(value)) {
@@ -239,6 +264,11 @@ function runNetwork(network, inputs) {
   });
 }
 
+/**
+ * @param {any} inputs
+ * @param {Network} network
+ * @returns {string}
+ */
 function getType(inputs, network) {
   // Scalar values are always simple inputs
   if (typeof inputs !== 'object' || !inputs) { return 'simple'; }
@@ -261,6 +291,12 @@ function getType(inputs, network) {
   return 'map';
 }
 
+/**
+ * @param {any} inputs
+ * @param {string} inputType
+ * @param {Network} network
+ * @returns {InputMap}
+ */
 function prepareInputMap(inputs, inputType, network) {
   // Sequence we can use as-is
   if (inputType === 'sequence') { return inputs; }
@@ -272,15 +308,25 @@ function prepareInputMap(inputs, inputType, network) {
     return {};
   }
   // If we have a port named "IN", send to that
-  if (network.graph.inports.in) { inPort = 'in'; }
+  if (network.graph.inports.in) {
+    inPort = 'in';
+  }
+  /** @type {InputMap} */
   const map = {};
   map[inPort] = inputs;
   return [map];
 }
 
+/**
+ * @param {Array<IP>} values
+ * @param {AsCallbackOptions} options
+ * @returns {Array<any>}
+ */
 function normalizeOutput(values, options) {
   if (options.raw) { return values; }
+  /** @type {Array<any>} */
   const result = [];
+  /** @type {Array<any>|null} */
   let previous = null;
   let current = result;
   values.forEach((packet) => {
@@ -293,7 +339,7 @@ function normalizeOutput(values, options) {
       current.push(packet.data);
     }
     if (packet.type === 'closeBracket') {
-      current = previous;
+      current = /** @type {Array<any>} */ (previous);
     }
   });
   if (result.length === 1) {
@@ -301,7 +347,11 @@ function normalizeOutput(values, options) {
   }
   return result;
 }
-
+/**
+ * @param {OutputMap} outputs
+ * @param {string} resultType
+ * @param {AsCallbackOptions} options
+ */
 function sendOutputMap(outputs, resultType, options) {
   // First check if the output sequence contains errors
   const errors = outputs.filter((map) => map.error != null).map((map) => map.error);
@@ -311,6 +361,7 @@ function sendOutputMap(outputs, resultType, options) {
 
   if (resultType === 'sequence') {
     return Promise.resolve(outputs.map((map) => {
+      /** @type {Object<string, any|IP>} */
       const res = {};
       Object.keys(map).forEach((key) => {
         const val = map[key];
@@ -325,11 +376,14 @@ function sendOutputMap(outputs, resultType, options) {
   }
 
   // Flatten the sequence
+  /** @type {Object<string, Array<any|IP>>} */
   const mappedOutputs = {};
   outputs.forEach((map) => {
     Object.keys(map).forEach((key) => {
       const val = map[key];
-      if (!mappedOutputs[key]) { mappedOutputs[key] = []; }
+      if (!mappedOutputs[key]) {
+        mappedOutputs[key] = [];
+      }
       mappedOutputs[key].push(val);
     });
   });
@@ -344,6 +398,7 @@ function sendOutputMap(outputs, resultType, options) {
     // Single outport
     return Promise.resolve(normalizeOutput(mappedOutputs[withValue[0]], options));
   }
+  /** @type {Object<string, any|IP>} */
   const result = {};
   Object.keys(mappedOutputs).forEach((port) => {
     const packets = mappedOutputs[port];

package/src/lib/AsComponent.js

@@ -5,7 +5,7 @@
     import/prefer-default-export,
 */
 import * as getParams from 'get-function-params';
-import { Component } from './Component';
+import { Component } from './Component.js';
 
 /**
  * @typedef FuncParam
@@ -101,8 +101,9 @@ export function asComponent(func, options) {
     c.forwardBrackets[p.param] = ['out', 'error'];
   });
   if (!params.length) {
-    c.inPorts.add('in',
-      { datatype: 'bang' });
+    c.inPorts.add('in', {
+      datatype: 'bang',
+    });
   }
 
   c.outPorts.add('out');

package/src/lib/BaseNetwork.js

@@ -10,11 +10,11 @@
 */
 
 import { EventEmitter } from 'events';
-import * as internalSocket from './InternalSocket';
-import { ComponentLoader } from './ComponentLoader';
-import { debounce } from './Utils';
-import IP from './IP';
-import { deprecated, isBrowser, makeAsync } from './Platform';
+import * as internalSocket from './InternalSocket.js';
+import { ComponentLoader } from './ComponentLoader.js';
+import { debounce } from './Utils.js';
+import IP from './IP.js';
+import { deprecated, isBrowser, makeAsync } from './Platform.js';
 
 /**
  * @typedef NetworkProcess
@@ -39,7 +39,7 @@ import { deprecated, isBrowser, makeAsync } from './Platform';
  * @param {internalSocket.InternalSocket} socket
  * @param {NetworkProcess} process
  * @param {string} port
- * @param {number|void} index
+ * @param {number|null} index
  * @param {boolean} inbound
  * @returns {Promise<internalSocket.InternalSocket>}
  */
@@ -89,6 +89,7 @@ function connectPort(socket, process, port, index, inbound) {
  * @property {string} [baseDir] - Project base directory for component loading
  * @property {ComponentLoader} [componentLoader] - Component loader instance to use, if any
  * @property {Object} [flowtrace] - Flowtrace instance to use for tracing this network run
+ * @property {boolean} [asyncDelivery] - Make Information Packet delivery asynchronous
  */
 
 /**
@@ -135,6 +136,7 @@ export class BaseNetwork extends EventEmitter {
     this.started = false;
     this.stopped = true;
     this.debug = true;
+    this.asyncDelivery = options.asyncDelivery || false;
     /** @type {Array<NetworkEvent>} */
     this.eventBuffer = [];
 
@@ -569,6 +571,7 @@ export class BaseNetwork extends EventEmitter {
     }
 
     instance.network.setDebug(this.debug);
+    instance.network.setAsyncDelivery(this.asyncDelivery);
     if (this.flowtrace) {
       instance.network.setFlowtrace(this.flowtrace, node.componentName, false);
     }
@@ -720,8 +723,10 @@ export class BaseNetwork extends EventEmitter {
     }
     const promise = this.ensureNode(edge.from.node, 'outbound')
       .then((from) => {
-        const socket = internalSocket.createSocket(edge.metadata);
-        socket.setDebug(this.debug);
+        const socket = internalSocket.createSocket(edge.metadata, {
+          debug: this.debug,
+          async: this.asyncDelivery,
+        });
         return this.ensureNode(edge.to.node, 'inbound')
           .then((to) => {
             // Subscribe to events from the socket
@@ -785,8 +790,10 @@ export class BaseNetwork extends EventEmitter {
         if (!port.hasDefault() || port.isAttached()) {
           return Promise.resolve();
         }
-        const socket = internalSocket.createSocket();
-        socket.setDebug(this.debug);
+        const socket = internalSocket.createSocket({}, {
+          debug: this.debug,
+          async: this.asyncDelivery,
+        });
 
         // Subscribe to events from the socket
         this.subscribeSocket(socket);
@@ -814,8 +821,10 @@ export class BaseNetwork extends EventEmitter {
 
     const promise = this.ensureNode(initializer.to.node, 'inbound')
       .then((to) => {
-        const socket = internalSocket.createSocket(initializer.metadata);
-        socket.setDebug(this.debug);
+        const socket = internalSocket.createSocket(initializer.metadata, {
+          debug: this.debug,
+          async: this.asyncDelivery,
+        });
 
         // Subscribe to events from the socket
         this.subscribeSocket(socket);
@@ -891,7 +900,7 @@ export class BaseNetwork extends EventEmitter {
    */
   sendInitials() {
     return new Promise((resolve) => {
-      makeAsync(resolve);
+      makeAsync(resolve, true);
     })
       .then(() => this.initials.reduce((chain, initial) => chain
         .then(() => {
@@ -1067,8 +1076,9 @@ export class BaseNetwork extends EventEmitter {
     }
     this.started = true;
     this.stopped = false;
-    this.bufferedEmit('start',
-      { start: this.startupDate });
+    this.bufferedEmit('start', {
+      start: this.startupDate,
+    });
   }
 
   checkIfFinished() {
@@ -1111,6 +1121,29 @@ export class BaseNetwork extends EventEmitter {
     });
   }
 
+  /**
+   * @param {boolean} active
+   */
+  setAsyncDelivery(active) {
+    if (active === this.asyncDelivery) { return; }
+    this.asyncDelivery = active;
+
+    this.connections.forEach((socket) => {
+      socket.async = this.asyncDelivery;
+    });
+    Object.keys(this.processes).forEach((processId) => {
+      const process = this.processes[processId];
+      if (!process.component) {
+        return;
+      }
+      const instance = process.component;
+      if (instance.isSubgraph()) {
+        const inst = /** @type {import("../components/Graph").Graph} */ (instance);
+        inst.network.setAsyncDelivery(active);
+      }
+    });
+  }
+
   /**
    * @param {Object|null} flowtrace
    * @param {string|null} [name]

package/src/lib/BasePort.js

@@ -27,6 +27,8 @@ const validTypes = [
 /**
  * @typedef {Object} BaseOptions - Options for configuring all types of ports
  * @property {string} [description='']
+ * @property {boolean} [addressable=false]
+ * @property {boolean} [buffered=false]
  * @property {string} [datatype='all']
  * @property {string} [schema=null]
  * @property {string} [type=null]
@@ -78,13 +80,16 @@ function handleOptions(options) {
 }
 
 export default class BasePort extends EventEmitter {
+  /**
+   * @param {BaseOptions} options
+   */
   constructor(options) {
     super();
     // Options holds all options of the current port
     this.options = handleOptions(options);
     // Sockets list contains all currently attached
     // connections to the port
-    /** @type {Array<import("./InternalSocket").InternalSocket>} */
+    /** @type {Array<import("./InternalSocket").InternalSocket|void>} */
     this.sockets = [];
     // Name of the graph node this port is in
     /** @type {string|null} */
@@ -103,14 +108,21 @@ export default class BasePort extends EventEmitter {
     return `${this.node} ${this.name.toUpperCase()}`;
   }
 
-  getDataType() { return this.options.datatype; }
+  /**
+   * @returns {string}
+   */
+  getDataType() { return this.options.datatype || 'all'; }
 
   getSchema() { return this.options.schema || null; }
 
   getDescription() { return this.options.description; }
 
+  /**
+   * @param {import("./InternalSocket").InternalSocket} socket
+   * @param {number|null} [index]
+   */
   attach(socket, index = null) {
-    let idx = index;
+    let idx = /** @type {number} */ (index);
     if (!this.isAddressable() || (index === null)) {
       idx = this.sockets.length;
     }
@@ -123,9 +135,15 @@ export default class BasePort extends EventEmitter {
     this.emit('attach', socket);
   }
 
-  // eslint-disable-next-line class-methods-use-this,no-unused-vars
-  attachSocket(socket, index = null) { }
+  /**
+   * @param {import("./InternalSocket").InternalSocket} socket
+   * @param {number|null} [index]
+   */
+  attachSocket(socket, index = null) { } // eslint-disable-line class-methods-use-this,no-unused-vars,max-len
 
+  /**
+   * @param {import("./InternalSocket").InternalSocket} socket
+   */
   detach(socket) {
     const index = this.sockets.indexOf(socket);
     if (index === -1) {
@@ -154,12 +172,18 @@ export default class BasePort extends EventEmitter {
     return false;
   }
 
+  /**
+   * @param {number|null} socketId
+   * @returns {boolean}
+   */
   isAttached(socketId = null) {
     if (this.isAddressable() && (socketId !== null)) {
       if (this.sockets[socketId]) { return true; }
       return false;
     }
-    if (this.sockets.length) { return true; }
+    if (this.sockets.length) {
+      return true;
+    }
     return false;
   }
 
@@ -172,11 +196,21 @@ export default class BasePort extends EventEmitter {
     return attached;
   }
 
+  /**
+   * @param {number|null} socketId
+   * @returns {boolean}
+   */
   isConnected(socketId = null) {
     if (this.isAddressable()) {
-      if (socketId === null) { throw new Error(`${this.getId()}: Socket ID required`); }
-      if (!this.sockets[socketId]) { throw new Error(`${this.getId()}: Socket ${socketId} not available`); }
-      return this.sockets[socketId].isConnected();
+      if (socketId === null) {
+        throw new Error(`${this.getId()}: Socket ID required`);
+      }
+      if (!this.sockets[socketId]) {
+        throw new Error(`${this.getId()}: Socket ${socketId} not available`);
+      }
+      // eslint-disable-next-line max-len
+      const socket = /** @type {import("./InternalSocket").InternalSocket} */ (this.sockets[socketId]);
+      return socket.isConnected();
     }
 
     let connected = false;

package/src/lib/Component.js

@@ -10,14 +10,14 @@
 */
 import { EventEmitter } from 'events';
 import debug from 'debug';
-import { InPorts, OutPorts, normalizePortName } from './Ports';
-import { deprecated } from './Platform';
-import InPort from './InPort'; // eslint-disable-line no-unused-vars
-import OutPort from './OutPort'; // eslint-disable-line no-unused-vars
-import ProcessContext from './ProcessContext';
-import ProcessInput from './ProcessInput';
-import ProcessOutput from './ProcessOutput';
-import IP from './IP'; // eslint-disable-line no-unused-vars
+import { InPorts, OutPorts, normalizePortName } from './Ports.js';
+import { deprecated } from './Platform.js';
+import InPort from './InPort.js'; // eslint-disable-line no-unused-vars
+import OutPort from './OutPort.js'; // eslint-disable-line no-unused-vars
+import ProcessContext from './ProcessContext.js';
+import ProcessInput from './ProcessInput.js';
+import ProcessOutput from './ProcessOutput.js';
+import IP from './IP.js'; // eslint-disable-line no-unused-vars
 
 const debugComponent = debug('noflo:component');
 const debugBrackets = debug('noflo:component:brackets');

package/src/lib/ComponentLoader.js

@@ -10,8 +10,8 @@
 */
 
 import { Graph } from 'fbp-graph';
-import * as registerLoader from './loader/register';
-import { deprecated, makeAsync } from './Platform';
+import * as registerLoader from './loader/register.js';
+import { deprecated, makeAsync } from './Platform.js';
 
 /**
  * @callback ComponentFactory
@@ -226,9 +226,8 @@ export class ComponentLoader {
     return promise;
   }
 
-  // Creates an instance of a component.
   /**
-   * @protected
+   * Creates an instance of a component.
    * @param {string} name
    * @param {ComponentDefinitionWithoutGraph} component
    * @param {import("fbp-graph/lib/Types").GraphNodeMetadata} metadata

package/src/lib/IP.js

@@ -27,6 +27,10 @@
 //   - 'openBracket'
 //   - 'closeBracket'
 
+/**
+ * @typedef {Object<string, boolean|string>} IPOptions
+ */
+
 export default class IP {
   // Detects if an arbitrary value is an IP
   /**
@@ -42,7 +46,7 @@ export default class IP {
   /**
    * @param {string} type
    * @param {any} data
-   * @param {Object<string, boolean|string>} [options]
+   * @param {IPOptions} [options]
    */
   constructor(type, data = null, options = {}) {
     this.type = type || 'data';
@@ -50,7 +54,7 @@ export default class IP {
     this.isIP = true;
     /** @type {string|null} */
     this.scope = null; // sync scope id
-    /** @type {string|null} */
+    /** @type {import("./Component").Component|null} */
     this.owner = null; // packet owner process
     this.clonable = false; // cloning safety flag
     /** @type {number|null} */
@@ -61,7 +65,6 @@ export default class IP {
     if (typeof options === 'object') {
       Object.keys(options).forEach((key) => { this[key] = options[key]; });
     }
-    return this;
   }
 
   // Creates a new IP copying its contents by value not reference
@@ -85,7 +88,7 @@ export default class IP {
 
   // Moves an IP to a different owner
   /**
-   * @param {string|null} owner
+   * @param {import("./Component").Component|null} owner
    */
   move(owner) {
     // no-op