noflo 1.4.2 → 1.5.0

package/lib/InPort.js

@@ -3,12 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 //     NoFlo - Flow-Based Programming for JavaScript
 //     (c) 2014-2017 Flowhub UG
 //     NoFlo may be freely distributed under the MIT license
-const BasePort_1 = require("./BasePort");
+const BasePort_js_1 = require("./BasePort.js");
 // ## NoFlo inport
 //
 // Input Port (inport) implementation for NoFlo components. These
 // ports are the way a component receives Information Packets.
-class InPort extends BasePort_1.default {
+/**
+ * @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
+ */
+class InPort extends BasePort_js_1.default {
+    /**
+     * @param {PortOptions} [options]
+     */
     constructor(options = {}) {
         const opts = options;
         if (opts.control == null) {
@@ -20,17 +38,19 @@ class InPort extends BasePort_1.default {
         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()) {
@@ -46,7 +66,11 @@ class InPort extends BasePort_1.default {
         socket.on('disconnect', () => this.handleSocketEvent('disconnect', socket, localId));
         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;
         }
@@ -70,6 +94,11 @@ class InPort extends BasePort_1.default {
         }
         this.emit('ip', ip, index);
     }
+    /**
+     * @param {string} event
+     * @param {any} payload
+     * @param {number} [id]
+     */
     handleSocketEvent(event, payload, id) {
         // Emit port event
         if (this.isAddressable()) {
@@ -138,6 +167,9 @@ class InPort extends BasePort_1.default {
         }
         return this.buffer;
     }
+    /**
+     * @param {any} data
+     */
     validateData(data) {
         if (!this.options.values) {
             return;
@@ -201,8 +233,12 @@ class InPort extends BasePort_1.default {
         }
         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;
@@ -210,6 +246,13 @@ class InPort extends BasePort_1.default {
         // 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)) {
@@ -222,17 +265,30 @@ class InPort extends BasePort_1.default {
         }
         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;
         }
@@ -241,15 +297,23 @@ class InPort extends BasePort_1.default {
         }
         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/lib/InternalSocket.d.ts

@@ -1,20 +1,61 @@
 /**
- * @param {Object} [metadata]
+ * @param {import("fbp-graph/lib/Types").GraphEdgeMetadata} [metadata]
+ * @param {InternalSocketOptions} [options]
  * @returns {InternalSocket}
  */
-export function createSocket(metadata?: any): InternalSocket;
+export function createSocket(metadata?: import("fbp-graph/lib/Types").GraphEdgeMetadata, options?: {
+    /**
+     * - Whether to catch exceptions caused by IP transmission
+     */
+    debug?: boolean;
+    /**
+     * - Whether IP transmission should be asynchronous
+     */
+    async?: boolean;
+}): InternalSocket;
+/**
+ * @typedef SocketError
+ * @property {Error} error
+ * @property {string} [id]
+ * @property {import("fbp-graph/lib/Types").GraphNodeMetadata} [metadata]
+ */
 export class InternalSocket extends EventEmitter {
-    constructor(metadata?: {});
-    regularEmitEvent(event: any, data: any): void;
-    debugEmitEvent(event: any, data: any): void;
-    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?: import("fbp-graph/lib/Types").GraphEdgeMetadata, options?: {
+        /**
+         * - Whether to catch exceptions caused by IP transmission
+         */
+        debug?: boolean;
+        /**
+         * - Whether IP transmission should be asynchronous
+         */
+        async?: boolean;
+    });
+    /**
+     * @private
+     */
+    private regularEmitEvent;
+    /**
+     * @private
+     */
+    private debugEmitEvent;
+    metadata: import("fbp-graph/lib/Types").PropertyMap;
     brackets: any[];
     connected: boolean;
     dataDelegate: any;
     debug: boolean;
-    emitEvent: (event: any, data: any) => void;
+    async: boolean;
     from: any;
     to: any;
+    emitEvent(event: any, data: any): void;
     connect(): void;
     disconnect(): void;
     isConnected(): boolean;
@@ -27,4 +68,9 @@ export class InternalSocket extends EventEmitter {
     getId(): string;
     handleSocketEvent(event: any, payload: any, autoConnect?: boolean): void;
 }
+export type SocketError = {
+    error: Error;
+    id?: string;
+    metadata?: import("fbp-graph/lib/Types").GraphNodeMetadata;
+};
 import { EventEmitter } from "events";

package/lib/InternalSocket.js

@@ -6,20 +6,21 @@ exports.createSocket = exports.InternalSocket = void 0;
 //     (c) 2011-2012 Henri Bergius, Nemein
 //     NoFlo may be freely distributed under the MIT license
 const events_1 = require("events");
-const IP_1 = require("./IP");
+const IP_js_1 = require("./IP.js");
+const Platform_js_1 = require("./Platform.js");
 function legacyToIp(event, payload) {
     // No need to wrap modern IP Objects
-    if (IP_1.default.isIP(payload)) {
+    if (IP_js_1.default.isIP(payload)) {
         return payload;
     }
     // Wrap legacy events into appropriate IP objects
     switch (event) {
         case 'begingroup':
-            return new IP_1.default('openBracket', payload);
+            return new IP_js_1.default('openBracket', payload);
         case 'endgroup':
-            return new IP_1.default('closeBracket');
+            return new IP_js_1.default('closeBracket');
         case 'data':
-            return new IP_1.default('data', payload);
+            return new IP_js_1.default('data', payload);
         default:
             return null;
     }
@@ -45,6 +46,12 @@ function ipToLegacy(ip) {
             return null;
     }
 }
+/**
+ * @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
@@ -53,9 +60,15 @@ function ipToLegacy(ip) {
 // events so that the packets can be caught to the inport of the
 // connected process.
 class InternalSocket extends events_1.EventEmitter {
+    /**
+     * @private
+     */
     regularEmitEvent(event, data) {
         this.emit(event, data);
     }
+    /**
+     * @private
+     */
     debugEmitEvent(event, data) {
         try {
             this.emit(event, data);
@@ -73,23 +86,47 @@ class InternalSocket extends events_1.EventEmitter {
                 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) {
+                (0, Platform_js_1.makeAsync)(() => this.debugEmitEvent(event, data));
+                return;
+            }
+            this.debugEmitEvent(event, data);
+            return;
+        }
+        if (this.async) {
+            (0, Platform_js_1.makeAsync)(() => this.regularEmitEvent(event, data));
+            return;
+        }
+        this.regularEmitEvent(event, data);
+    }
     // ## Socket connections
     //
     // Sockets that are attached to the ports of processes may be
@@ -220,7 +257,6 @@ class InternalSocket extends events_1.EventEmitter {
     // notification to the developer.
     setDebug(active) {
         this.debug = active;
-        this.emitEvent = this.debug ? this.debugEmitEvent : this.regularEmitEvent;
     }
     // ## Socket identifiers
     //
@@ -244,7 +280,7 @@ class InternalSocket extends events_1.EventEmitter {
     }
     /* eslint-disable no-param-reassign */
     handleSocketEvent(event, payload, autoConnect = true) {
-        const isIP = (event === 'ip') && IP_1.default.isIP(payload);
+        const isIP = (event === 'ip') && IP_js_1.default.isIP(payload);
         const ip = isIP ? payload : legacyToIp(event, payload);
         if (!ip) {
             return;
@@ -296,10 +332,11 @@ class InternalSocket extends events_1.EventEmitter {
 }
 exports.InternalSocket = InternalSocket;
 /**
- * @param {Object} [metadata]
+ * @param {import("fbp-graph/lib/Types").GraphEdgeMetadata} [metadata]
+ * @param {InternalSocketOptions} [options]
  * @returns {InternalSocket}
  */
-function createSocket(metadata = {}) {
-    return new InternalSocket(metadata);
+function createSocket(metadata = {}, options = {}) {
+    return new InternalSocket(metadata, options);
 }
 exports.createSocket = createSocket;

package/lib/LegacyNetwork.d.ts

@@ -1,5 +1,15 @@
 export class LegacyNetwork extends BaseNetwork {
     constructor(graph: any, options?: {});
-    subscribeGraph(): import("fbp-graph/lib/Graph").Graph;
+    /**
+     * @callback ErrorableCallback
+     * @param {Error|null} [err]
+     * @returns {void}
+     */
+    /**
+     * @param {ErrorableCallback} [callback]
+     * @returns {Promise<this>}
+     */
+    connect(callback?: (err?: Error | null) => void): Promise<LegacyNetwork>;
+    subscribeGraph(): import("fbp-graph/lib/Graph.js").Graph;
 }
-import { BaseNetwork } from "./BaseNetwork";
+import { BaseNetwork } from "./BaseNetwork.js";

package/lib/LegacyNetwork.js

@@ -5,8 +5,8 @@ exports.LegacyNetwork = void 0;
 //     (c) 2013-2018 Flowhub UG
 //     (c) 2011-2012 Henri Bergius, Nemein
 //     NoFlo may be freely distributed under the MIT license
-const BaseNetwork_1 = require("./BaseNetwork");
-const Platform_1 = require("./Platform");
+const BaseNetwork_js_1 = require("./BaseNetwork.js");
+const Platform_js_1 = require("./Platform.js");
 /* eslint-disable
     import/prefer-default-export,
 */
@@ -19,7 +19,7 @@ const Platform_1 = require("./Platform");
 // instantiate all the necessary processes from the designated
 // components, attach sockets between them, and handle the sending
 // of Initial Information Packets.
-class LegacyNetwork extends BaseNetwork_1.BaseNetwork {
+class LegacyNetwork extends BaseNetwork_js_1.BaseNetwork {
     // All NoFlo networks are instantiated with a graph. Upon instantiation
     // they will load all the needed components, instantiate them, and
     // set up the defined connections and IIPs.
@@ -28,7 +28,7 @@ class LegacyNetwork extends BaseNetwork_1.BaseNetwork {
     // accordingly, including removing connections, adding new nodes,
     // and sending new IIPs.
     constructor(graph, options = {}) {
-        Platform_1.deprecated('subscribeGraph: true is deprecated. Live-edit network graphs via the network methods instead');
+        (0, Platform_js_1.deprecated)('subscribeGraph: true is deprecated. Live-edit network graphs via the network methods instead');
         super(graph, options);
     }
     /**
@@ -47,7 +47,7 @@ class LegacyNetwork extends BaseNetwork_1.BaseNetwork {
             return this;
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.connect is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.connect is deprecated, use Promises');
             promise.then(() => {
                 callback(null);
             }, callback);

package/lib/Network.d.ts

@@ -5,11 +5,22 @@
  * @property {import("./Component").Component} [component]
  */
 export class Network extends BaseNetwork {
-    constructor(graph: import("fbp-graph/lib/Graph").Graph, options?: import("./BaseNetwork").NetworkOptions);
+    /**
+     * @param {import("fbp-graph/lib/Types").GraphNode} node
+     * @param {Object} options
+     * @returns {Promise<NetworkProcess>}
+     */
+    addNode(node: import("fbp-graph/lib/Types").GraphNode, options: any, callback: any): Promise<NetworkProcess>;
+    removeNode(node: any, callback: any): Promise<any>;
+    renameNode(oldId: any, newId: any, callback: any): Promise<void>;
+    addEdge(edge: any, options: any, callback: any): Promise<import("./InternalSocket.js").InternalSocket>;
+    removeEdge(edge: any, callback: any): Promise<any>;
+    addInitial(iip: any, options: any, callback: any): Promise<import("./InternalSocket.js").InternalSocket>;
+    removeInitial(iip: any, callback: any): Promise<void>;
 }
 export type NetworkProcess = {
     id: string;
     componentName?: string;
     component?: import("./Component").Component;
 };
-import { BaseNetwork } from "./BaseNetwork";
+import { BaseNetwork } from "./BaseNetwork.js";

package/lib/Network.js

@@ -5,8 +5,8 @@ exports.Network = void 0;
 //     (c) 2013-2018 Flowhub UG
 //     (c) 2011-2012 Henri Bergius, Nemein
 //     NoFlo may be freely distributed under the MIT license
-const BaseNetwork_1 = require("./BaseNetwork");
-const Platform_1 = require("./Platform");
+const BaseNetwork_js_1 = require("./BaseNetwork.js");
+const Platform_js_1 = require("./Platform.js");
 /* eslint-disable
     no-param-reassign,
     import/prefer-default-export,
@@ -26,7 +26,7 @@ const Platform_1 = require("./Platform");
 // instantiate all the necessary processes from the designated
 // components, attach sockets between them, and handle the sending
 // of Initial Information Packets.
-class Network extends BaseNetwork_1.BaseNetwork {
+class Network extends BaseNetwork_js_1.BaseNetwork {
     // Add a process to the network. The node will also be registered
     // with the current graph.
     /**
@@ -48,7 +48,7 @@ class Network extends BaseNetwork_1.BaseNetwork {
             return process;
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.addNode is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.addNode is deprecated, use Promises');
             promise.then((process) => {
                 callback(null, process);
             }, callback);
@@ -64,7 +64,7 @@ class Network extends BaseNetwork_1.BaseNetwork {
             return null;
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.removeNode is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.removeNode is deprecated, use Promises');
             promise.then(() => {
                 callback(null);
             }, callback);
@@ -79,7 +79,7 @@ class Network extends BaseNetwork_1.BaseNetwork {
             this.graph.renameNode(oldId, newId);
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.renameNode is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.renameNode is deprecated, use Promises');
             promise.then(() => {
                 callback(null);
             }, callback);
@@ -102,7 +102,7 @@ class Network extends BaseNetwork_1.BaseNetwork {
             return socket;
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.addEdge is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.addEdge is deprecated, use Promises');
             promise.then((socket) => {
                 callback(null, socket);
             }, callback);
@@ -118,7 +118,7 @@ class Network extends BaseNetwork_1.BaseNetwork {
             return null;
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.removeEdge is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.removeEdge is deprecated, use Promises');
             promise.then(() => {
                 callback(null);
             }, callback);
@@ -141,7 +141,7 @@ class Network extends BaseNetwork_1.BaseNetwork {
             return socket;
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.addInitial is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.addInitial is deprecated, use Promises');
             promise.then(() => {
                 callback(null);
             }, callback);
@@ -156,7 +156,7 @@ class Network extends BaseNetwork_1.BaseNetwork {
             this.graph.removeInitial(iip.to.node, iip.to.port);
         });
         if (callback) {
-            Platform_1.deprecated('Providing a callback to Network.removeInitial is deprecated, use Promises');
+            (0, Platform_js_1.deprecated)('Providing a callback to Network.removeInitial is deprecated, use Promises');
             promise.then(() => {
                 callback(null);
             }, callback);

package/lib/NoFlo.d.ts

@@ -32,14 +32,14 @@ export function loadFile(file: string, options: NetworkOptions, callback?: any):
  * @returning {Promise<string>}
  */
 export function saveFile(graphInstance: graph.Graph, file: string, callback?: any): void;
-export { isBrowser } from "./Platform";
-export { ComponentLoader } from "./ComponentLoader";
-export { Component } from "./Component";
-export { default as InPort } from "./InPort";
-export { default as OutPort } from "./OutPort";
+export { isBrowser } from "./Platform.js";
+export { ComponentLoader } from "./ComponentLoader.js";
+export { Component } from "./Component.js";
+export { default as InPort } from "./InPort.js";
+export { default as OutPort } from "./OutPort.js";
 export { internalSocket };
-export { default as IP } from "./IP";
-export { asComponent } from "./AsComponent";
+export { default as IP } from "./IP.js";
+export { asComponent } from "./AsComponent.js";
 export type NetworkCallback = (err: Error | null, network?: Network | LegacyNetwork) => any;
 export type CreateNetworkOptions = {
     /**
@@ -51,11 +51,11 @@ export type CreateNetworkOptions = {
      */
     delay?: boolean;
 };
-export type NetworkOptions = CreateNetworkOptions & import("./BaseNetwork").NetworkOwnOptions & import("./ComponentLoader").ComponentLoaderOptions;
-import { Network } from "./Network";
-import { LegacyNetwork } from "./LegacyNetwork";
+export type NetworkOptions = CreateNetworkOptions & import("./BaseNetwork").NetworkOptions;
+import { Network } from "./Network.js";
+import { LegacyNetwork } from "./LegacyNetwork.js";
 import { graph } from "fbp-graph";
-import * as internalSocket from "./InternalSocket";
+import * as internalSocket from "./InternalSocket.js";
 export { graph, Graph, journal, Journal } from "fbp-graph";
-export { InPorts, OutPorts } from "./Ports";
-export { asCallback, asPromise } from "./AsCallback";
+export { InPorts, OutPorts } from "./Ports.js";
+export { asCallback, asPromise } from "./AsCallback.js";