noflo 1.4.2 → 1.5.0

package/src/lib/InPort.js

@@ -1,35 +1,55 @@
 //     NoFlo - Flow-Based Programming for JavaScript
 //     (c) 2014-2017 Flowhub UG
 //     NoFlo may be freely distributed under the MIT license
-import BasePort from './BasePort';
+import BasePort from './BasePort.js';
 
 // ## NoFlo inport
 //
 // Input Port (inport) implementation for NoFlo components. These
 // ports are the way a component receives Information Packets.
+/**
+ * @typedef InPortOptions
+ * @property {any} [default]
+ * @property {Array<any>} [values]
+ * @property {boolean} [control]
+ * @property {boolean} [triggering]
+ */
+/**
+ * @callback HasValidationCallback
+ * @param {import("./IP").default} ip
+ * @returns {boolean}
+ */
+/**
+ * @typedef {import("./BasePort").BaseOptions & InPortOptions} PortOptions
+ */
+
 export default class InPort extends BasePort {
+  /**
+   * @param {PortOptions} [options]
+   */
   constructor(options = {}) {
     const opts = options;
     if (opts.control == null) { opts.control = false; }
     if (opts.scoped == null) { opts.scoped = true; }
     if (opts.triggering == null) { opts.triggering = true; }
 
-    if (opts.process) {
-      throw new Error('InPort process callback is deprecated. Please use Process API');
-    }
-
-    if (opts.handle) {
-      throw new Error('InPort handle callback is deprecated. Please use Process API');
-    }
-
     super(opts);
 
+    const baseOptions = this.options;
+    this.options = /** @type {PortOptions} */ (baseOptions);
+
+    /** @type {import("./Component").Component|null} */
     this.nodeInstance = null;
 
     this.prepareBuffer();
   }
 
-  // Assign a delegate for retrieving data should this inPort
+  /**
+   * Assign a delegate for retrieving data should this inPort
+   *
+   * @param {import("./InternalSocket").InternalSocket} socket
+   * @param {number|null} [localId]
+   */
   attachSocket(socket, localId = null) {
     // have a default value.
     if (this.hasDefault()) {
@@ -47,11 +67,17 @@ export default class InPort extends BasePort {
     socket.on('ip', (ip) => this.handleIP(ip, localId));
   }
 
-  handleIP(packet, index) {
+  /**
+   * @param {import("./IP").default} packet
+   * @param {number|null} [index]
+   */
+  handleIP(packet, index = null) {
     if (this.options.control && (packet.type !== 'data')) { return; }
     const ip = packet;
     ip.owner = this.nodeInstance;
-    if (this.isAddressable()) { ip.index = index; }
+    if (this.isAddressable()) {
+      ip.index = index;
+    }
     if (ip.datatype === 'all') {
       // Stamp non-specific IP objects with port datatype
       ip.datatype = this.getDataType();
@@ -68,6 +94,11 @@ export default class InPort extends BasePort {
     this.emit('ip', ip, index);
   }
 
+  /**
+   * @param {string} event
+   * @param {any} payload
+   * @param {number} [id]
+   */
   handleSocketEvent(event, payload, id) {
     // Emit port event
     if (this.isAddressable()) {
@@ -134,6 +165,9 @@ export default class InPort extends BasePort {
     return this.buffer;
   }
 
+  /**
+   * @param {any} data
+   */
   validateData(data) {
     if (!this.options.values) { return; }
     if (this.options.values.indexOf(data) === -1) {
@@ -188,14 +222,25 @@ export default class InPort extends BasePort {
     return buf.shift();
   }
 
-  // Fetches a packet from the port
-  get(scope, index) {
+  /**
+   * Fetches a packet from the port
+   * @param {string|null} scope
+   * @param {number|null} [index]
+   */
+  get(scope, index = null) {
     const res = this.getFromBuffer(scope, index);
     if (res !== undefined) { return res; }
     // Try to find an IIP instead
     return this.getFromBuffer(null, index, true);
   }
 
+  /**
+   * Fetches a packet from the port
+   * @param {string|null} scope
+   * @param {number|null} index
+   * @param {HasValidationCallback} validate
+   * @param {boolean} [initial]
+   */
   hasIPinBuffer(scope, index, validate, initial = false) {
     const buf = this.getBuffer(scope, index, initial);
     if (!(buf != null ? buf.length : undefined)) { return false; }
@@ -205,31 +250,51 @@ export default class InPort extends BasePort {
     return false;
   }
 
+  /**
+   * @param {number|null} index
+   * @param {HasValidationCallback} validate
+   */
   hasIIP(index, validate) {
     return this.hasIPinBuffer(null, index, validate, true);
   }
 
-  // Returns true if port contains packet(s) matching the validator
+  /**
+   * Returns true if port contains packet(s) matching the validator
+   * @param {string|null} scope
+   * @param {number|null|HasValidationCallback} index
+   * @param {HasValidationCallback} [validate]
+   */
   has(scope, index, validate) {
     let valid = validate;
-    let idx = index;
-    if (!this.isAddressable()) {
-      valid = idx;
+    /** @type {number|null} */
+    let idx;
+    if (typeof index === 'function') {
+      valid = /** @type {HasValidationCallback} */ (index);
       idx = null;
+    } else {
+      idx = index;
     }
     if (this.hasIPinBuffer(scope, idx, valid)) { return true; }
     if (this.hasIIP(idx, valid)) { return true; }
     return false;
   }
 
-  // Returns the number of data packets in an inport
-  length(scope, index) {
+  /**
+   * Returns the number of data packets in an inport
+   * @param {string|null} scope
+   * @param {number|null} [index]
+   * @returns {number}
+   */
+  length(scope, index = null) {
     const buf = this.getBuffer(scope, index);
     if (!buf) { return 0; }
     return buf.length;
   }
 
-  // Tells if buffer has packets or not
+  /**
+   * Tells if buffer has packets or not
+   * @param {string|null} scope
+   */
   ready(scope) {
     return this.length(scope) > 0;
   }

package/src/lib/InternalSocket.js

@@ -3,7 +3,8 @@
 //     (c) 2011-2012 Henri Bergius, Nemein
 //     NoFlo may be freely distributed under the MIT license
 import { EventEmitter } from 'events';
-import IP from './IP';
+import IP from './IP.js';
+import { makeAsync } from './Platform.js';
 
 function legacyToIp(event, payload) {
   // No need to wrap modern IP Objects
@@ -44,6 +45,13 @@ function ipToLegacy(ip) {
   }
 }
 
+/**
+ * @typedef SocketError
+ * @property {Error} error
+ * @property {string} [id]
+ * @property {import("fbp-graph/lib/Types").GraphNodeMetadata} [metadata]
+ */
+
 // ## Internal Sockets
 //
 // The default communications mechanism between NoFlo processes is
@@ -52,10 +60,16 @@ function ipToLegacy(ip) {
 // events so that the packets can be caught to the inport of the
 // connected process.
 export class InternalSocket extends EventEmitter {
+  /**
+   * @private
+   */
   regularEmitEvent(event, data) {
     this.emit(event, data);
   }
 
+  /**
+   * @private
+   */
   debugEmitEvent(event, data) {
     try {
       this.emit(event, data);
@@ -70,25 +84,51 @@ export class InternalSocket extends EventEmitter {
       if (this.listeners('error').length === 0) { throw error; }
 
       this.emit('error', {
-        id: this.to.process.id,
+        id: this.to ? this.to.process.id : null,
         error,
         metadata: this.metadata,
       });
     }
   }
 
-  constructor(metadata = {}) {
+  /**
+   * @typedef InternalSocketOptions
+   * @property {boolean} [debug] - Whether to catch exceptions caused by IP transmission
+   * @property {boolean} [async] - Whether IP transmission should be asynchronous
+   */
+
+  /**
+   * @param {import("fbp-graph/lib/Types").GraphEdgeMetadata} [metadata]
+   * @param {InternalSocketOptions} [options]
+   */
+  constructor(metadata = {}, options = {}) {
     super();
     this.metadata = metadata;
     this.brackets = [];
     this.connected = false;
     this.dataDelegate = null;
-    this.debug = false;
-    this.emitEvent = this.regularEmitEvent;
+    this.debug = options.debug || false;
+    this.async = options.async || false;
     this.from = null;
     this.to = null;
   }
 
+  emitEvent(event, data) {
+    if (this.debug) {
+      if (this.async) {
+        makeAsync(() => this.debugEmitEvent(event, data));
+        return;
+      }
+      this.debugEmitEvent(event, data);
+      return;
+    }
+    if (this.async) {
+      makeAsync(() => this.regularEmitEvent(event, data));
+      return;
+    }
+    this.regularEmitEvent(event, data);
+  }
+
   // ## Socket connections
   //
   // Sockets that are attached to the ports of processes may be
@@ -223,7 +263,6 @@ export class InternalSocket extends EventEmitter {
   // notification to the developer.
   setDebug(active) {
     this.debug = active;
-    this.emitEvent = this.debug ? this.debugEmitEvent : this.regularEmitEvent;
   }
 
   // ## Socket identifiers
@@ -291,9 +330,10 @@ export class InternalSocket extends EventEmitter {
 }
 
 /**
- * @param {Object} [metadata]
+ * @param {import("fbp-graph/lib/Types").GraphEdgeMetadata} [metadata]
+ * @param {InternalSocketOptions} [options]
  * @returns {InternalSocket}
  */
-export function createSocket(metadata = {}) {
-  return new InternalSocket(metadata);
+export function createSocket(metadata = {}, options = {}) {
+  return new InternalSocket(metadata, options);
 }

package/src/lib/LegacyNetwork.js

@@ -2,8 +2,8 @@
 //     (c) 2013-2018 Flowhub UG
 //     (c) 2011-2012 Henri Bergius, Nemein
 //     NoFlo may be freely distributed under the MIT license
-import { BaseNetwork } from './BaseNetwork';
-import { deprecated } from './Platform';
+import { BaseNetwork } from './BaseNetwork.js';
+import { deprecated } from './Platform.js';
 
 /* eslint-disable
     import/prefer-default-export,

package/src/lib/Network.js

@@ -2,8 +2,8 @@
 //     (c) 2013-2018 Flowhub UG
 //     (c) 2011-2012 Henri Bergius, Nemein
 //     NoFlo may be freely distributed under the MIT license
-import { BaseNetwork } from './BaseNetwork';
-import { deprecated } from './Platform';
+import { BaseNetwork } from './BaseNetwork.js';
+import { deprecated } from './Platform.js';
 
 /* eslint-disable
     no-param-reassign,

package/src/lib/NoFlo.js

@@ -52,6 +52,8 @@ import { graph } from 'fbp-graph';
 //   immediate execution
 // * `flowtrace`: (default: NULL) Flowtrace instance to create a retroactive debugging
 //   trace of the network run.
+// * `asyncDelivery`: (default: FALSE) Whether Information Packets should be
+//   delivered asynchronously.
 // * `subscribeGraph`: (default: FALSE) Whether the network should monitor the underlying
 //   graph for changes
 //
@@ -61,9 +63,9 @@ import { graph } from 'fbp-graph';
 //
 // The options object can also be used for setting ComponentLoader options in this
 // network.
-import { Network } from './Network';
-import { LegacyNetwork } from './LegacyNetwork';
-import { deprecated } from './Platform';
+import { Network } from './Network.js';
+import { LegacyNetwork } from './LegacyNetwork.js';
+import { deprecated } from './Platform.js';
 
 export {
   graph,
@@ -76,7 +78,7 @@ export {
 //
 // NoFlo works on both Node.js and the browser. Because some dependencies are different,
 // we need a way to detect which we're on.
-export { isBrowser } from './Platform';
+export { isBrowser } from './Platform.js';
 
 // ### Component Loader
 //
@@ -84,33 +86,33 @@ export { isBrowser } from './Platform';
 // NoFlo components. Component Loader uses [fbp-manifest](https://github.com/flowbased/fbp-manifest)
 // to find components and graphs by traversing the NPM dependency tree from a given root
 // directory on the file system.
-export { ComponentLoader } from './ComponentLoader';
+export { ComponentLoader } from './ComponentLoader.js';
 
 // ### Component baseclasses
 //
 // These baseclasses can be used for defining NoFlo components.
-export { Component } from './Component';
+export { Component } from './Component.js';
 
 // ### NoFlo ports
 //
 // These classes are used for instantiating ports on NoFlo components.
-export { InPorts, OutPorts } from './Ports';
+export { InPorts, OutPorts } from './Ports.js';
 
-export { default as InPort } from './InPort';
-export { default as OutPort } from './OutPort';
+export { default as InPort } from './InPort.js';
+export { default as OutPort } from './OutPort.js';
 
 // ### NoFlo sockets
 //
 // The NoFlo [internalSocket](InternalSocket.html) is used for connecting ports of
 // different components together in a network.
-import * as internalSocket from './InternalSocket';
+import * as internalSocket from './InternalSocket.js';
 
 export { internalSocket };
 
 // ### Information Packets
 //
 // NoFlo Information Packets are defined as "IP" objects.
-export { default as IP } from './IP';
+export { default as IP } from './IP.js';
 
 /**
  * @callback NetworkCallback
@@ -221,7 +223,7 @@ export function saveFile(graphInstance, file, callback) {
 //       // Do something with results
 //     });
 //
-export { asCallback, asPromise } from './AsCallback';
+export { asCallback, asPromise } from './AsCallback.js';
 
 // ## Generating components from JavaScript functions
 //
@@ -235,4 +237,4 @@ export { asCallback, asPromise } from './AsCallback';
 //       });
 //     };
 //
-export { asComponent } from './AsComponent';
+export { asComponent } from './AsComponent.js';

package/src/lib/OutPort.js

@@ -1,26 +1,24 @@
 //     NoFlo - Flow-Based Programming for JavaScript
 //     (c) 2014-2017 Flowhub UG
 //     NoFlo may be freely distributed under the MIT license
-import BasePort from './BasePort';
-import IP from './IP';
+import BasePort from './BasePort.js';
+import IP from './IP.js';
 
 // ## NoFlo outport
 //
 // Outport Port (outport) implementation for NoFlo components.
 // These ports are the way a component sends Information Packets.
 /**
- * @typedef {Object} OutportOptions - Options for configuring outports
- * @property {string} [description='']
- * @property {string} [datatype='all']
- * @property {string} [schema=null]
- * @property {boolean} [required=false]
- * @property {boolean} [caching=false]
- * @property {boolean} [scoped=true]
+ * @typedef OutPortOptions
+ * @property {boolean} [caching]
+ */
+/**
+ * @typedef {import("./BasePort").BaseOptions & OutPortOptions} PortOptions
  */
 
 export default class OutPort extends BasePort {
   /**
-   * @param {OutportOptions} options - Options for the outport
+   * @param {PortOptions} options - Options for the outport
    */
   constructor(options = {}) {
     const opts = options;
@@ -29,16 +27,28 @@ export default class OutPort extends BasePort {
       opts.caching = false;
     }
     super(opts);
+
+    const baseOptions = this.options;
+    this.options = /** @type {PortOptions} */ (baseOptions);
+
+    /** @type {Object<string, IP>} */
     this.cache = {};
   }
 
+  /**
+   * @param {import("./InternalSocket").InternalSocket} socket
+   * @param {number|null} [index]
+   */
   attach(socket, index = null) {
     super.attach(socket, index);
-    if (this.isCaching() && (this.cache[index] != null)) {
-      this.send(this.cache[index], index);
+    if (this.isCaching() && (this.cache[`${index}`] != null)) {
+      this.send(this.cache[`${index}`], index);
     }
   }
 
+  /**
+   * @param {number|null} [index]
+   */
   connect(index = null) {
     const sockets = this.getSockets(index);
     this.checkRequired(sockets);
@@ -48,6 +58,10 @@ export default class OutPort extends BasePort {
     });
   }
 
+  /**
+   * @param {string} group
+   * @param {number|null} [index]
+   */
   beginGroup(group, index = null) {
     const sockets = this.getSockets(index);
     this.checkRequired(sockets);
@@ -57,11 +71,15 @@ export default class OutPort extends BasePort {
     });
   }
 
+  /**
+   * @param {any} data
+   * @param {number|null} [index]
+   */
   send(data, index = null) {
     const sockets = this.getSockets(index);
     this.checkRequired(sockets);
-    if (this.isCaching() && (data !== this.cache[index])) {
-      this.cache[index] = data;
+    if (this.isCaching() && (data !== this.cache[`${index}`])) {
+      this.cache[`${index}`] = data;
     }
     sockets.forEach((socket) => {
       if (!socket) { return; }
@@ -69,6 +87,9 @@ export default class OutPort extends BasePort {
     });
   }
 
+  /**
+   * @param {number|null} [index]
+   */
   endGroup(index = null) {
     const sockets = this.getSockets(index);
     this.checkRequired(sockets);
@@ -78,6 +99,9 @@ export default class OutPort extends BasePort {
     });
   }
 
+  /**
+   * @param {number|null} [index]
+   */
   disconnect(index = null) {
     const sockets = this.getSockets(index);
     this.checkRequired(sockets);
@@ -87,14 +111,24 @@ export default class OutPort extends BasePort {
     });
   }
 
-  sendIP(type, data, options, index, autoConnect = true) {
+  /**
+   * @param {string|IP} type
+   * @param {any} [data]
+   * @param {import("./IP").IPOptions} [options]
+   * @param {number|null} [index]
+   * @param {boolean} [autoConnect]
+   */
+  sendIP(type, data, options, index = null, autoConnect = true) {
+    /** @type {IP} */
     let ip;
     let idx = index;
     if (IP.isIP(type)) {
-      ip = type;
+      ip = /** @type {IP} */ (type);
       idx = ip.index;
-    } else {
+    } else if (typeof type === 'string') {
       ip = new IP(type, data, options);
+    } else {
+      throw new Error('Unknown type for IP type');
     }
     const sockets = this.getSockets(idx);
     this.checkRequired(sockets);
@@ -108,9 +142,9 @@ export default class OutPort extends BasePort {
       ip.schema = this.getSchema();
     }
 
-    const cachedData = this.cache[idx] != null ? this.cache[idx].data : undefined;
+    const cachedData = this.cache[`${idx}`] != null ? this.cache[`${idx}`].data : undefined;
     if (this.isCaching() && data !== cachedData) {
-      this.cache[idx] = ip;
+      this.cache[`${idx}`] = ip;
     }
     let pristine = true;
     sockets.forEach((socket) => {
@@ -126,30 +160,57 @@ export default class OutPort extends BasePort {
     return this;
   }
 
+  /**
+   * @param {string|null} data
+   * @param {import("./IP").IPOptions} options
+   * @param {number|null} [index]
+   */
   openBracket(data = null, options = {}, index = null) {
     return this.sendIP('openBracket', data, options, index);
   }
 
+  /**
+   * @param {any} data
+   * @param {import("./IP").IPOptions} options
+   * @param {number|null} [index]
+   */
   data(data, options = {}, index = null) {
     return this.sendIP('data', data, options, index);
   }
 
+  /**
+   * @param {string|null} data
+   * @param {import("./IP").IPOptions} options
+   * @param {number|null} [index]
+   */
   closeBracket(data = null, options = {}, index = null) {
     return this.sendIP('closeBracket', data, options, index);
   }
 
+  /**
+   * @param {Array<import("./InternalSocket").InternalSocket|void>} sockets
+   */
   checkRequired(sockets) {
     if ((sockets.length === 0) && this.isRequired()) {
       throw new Error(`${this.getId()}: No connections available`);
     }
   }
 
+  /**
+   * @param {number|null} index
+   * @returns {Array<import("./InternalSocket").InternalSocket|void>}
+   */
   getSockets(index) {
     // Addressable sockets affect only one connection at time
     if (this.isAddressable()) {
-      if (index === null) { throw new Error(`${this.getId()} Socket ID required`); }
-      if (!this.sockets[index]) { return []; }
-      return [this.sockets[index]];
+      if (index === null) {
+        throw new Error(`${this.getId()} Socket ID required`);
+      }
+      const idx = /** @type {number} */ (index);
+      if (!this.sockets[idx]) {
+        return [];
+      }
+      return [this.sockets[idx]];
     }
     // Regular sockets affect all outbound connections
     return this.sockets;

package/src/lib/Platform.js

@@ -41,12 +41,17 @@ export function deprecated(message) {
  * @param {Function} func
  * @returns {void}
  */
-export function makeAsync(func) {
+export function makeAsync(func, sameLoop = false) {
   if (isBrowser()) {
+    // FIXME: Browsers don't have setImmediate yet so can't do same loop
     setTimeout(func, 0);
     return;
   }
-  setImmediate(() => {
-    func();
-  });
+  if (sameLoop) {
+    setImmediate(() => {
+      func();
+    });
+    return;
+  }
+  process.nextTick(func);
 }