@kitware/wslink 2.5.0 → 2.5.3

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@kitware/wslink",
-  "version": "2.5.0",
+  "version": "2.5.3",
   "description": "Rpc and pub/sub between Python and JavaScript over WebSockets",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kitware/wslink.git"
+    "url": "git+https://github.com/Kitware/wslink.git",
+    "directory": "js-lib"
   },
   "bugs": {
-    "url": "https://github.com/kitware/wslink/issues"
+    "url": "https://github.com/Kitware/wslink/issues"
   },
-  "homepage": "https://github.com/kitware/wslink#readme",
+  "homepage": "https://github.com/Kitware/wslink#readme",
   "main": "dist/wslink.umd.js",
   "scripts": {
     "format": "prettier src --write",

package/src/WsLinkClient/index.d.ts

@@ -0,0 +1,196 @@
+export interface vtkSubscription {
+  unsubscribe(): void;
+}
+
+/**
+ * Bind optional dependency from WSLink to our current class.
+ * This is mandatory when using that class
+ *
+ * ```
+ * import SmartConnect from 'wslink/src/SmartConnect';
+ * import vtkWSLinkClient from '@kitware/vtk.js/IO/Core/WSLinkClient';
+ *
+ * vtkWSLinkClient.setSmartConnectClass(SmartConnect);
+ * ```
+ *
+ * @param smartConnectClass
+ */
+export function setSmartConnectClass(smartConnectClass: object): void;
+
+export interface vtkWSLinkClient {
+  /**
+   * Virtually increase work load to maybe keep isBusy() on
+   * while executing a synchronous task.
+   */
+  beginBusy(): void;
+
+  /**
+   * Virtually decreasing work load to maybe free isBusy()
+   * after executing a synchronous task. Other async calls
+   * could still keep the state as busy.
+   */
+  endBusy(): void;
+
+  /**
+   * Return the current state of busy.
+   * Do we still have pending calls?
+   */
+  isBusy(): boolean;
+
+  /**
+   * Return true if the client is currently connected to a server
+   */
+  isConnected(): boolean;
+
+  /**
+   * Initiate the connection with the server
+   * @param {Object} config
+   * @param {Function} [configDecorator] (default: null)
+   */
+  connect(
+    config: object,
+    configDecorator?: (config: object) => object,
+  ): Promise<vtkWSLinkClient>;
+
+  /**
+   * Disconnect from server
+   * @param {Number} timeout amount of second to wait before the server exit as well. If we want to avoid the server from quitting, `-1` should be provided. (default=60)
+   */
+  disconnect(timeout: number): void;
+
+  /**
+   * Register dynamically a protocol after being connected
+   *
+   * @param {String} name
+   * @param {Function} protocol
+   */
+  registerProtocol(name: string, protocol: (session: object) => object): void;
+
+  /**
+   * Remove a given protocol from the available list
+   *
+   * @param {String} name
+   */
+  unregisterProtocol(name: string): void;
+
+  // --- via macro --
+
+  /**
+   * Assign protocols to the client. Those will only be used at connect time and therefore needs to be set before being connected otherwise `registerProtocol` should be used instead.
+   * @returns {Boolean} true if the set method modified the object
+   */
+  setProtocols(protocols: Record<string, any>): boolean;
+
+  /**
+   * Get protocols that were either provided in `newInstance` or via its set
+   */
+  getProtocols(): Record<string, any>;
+
+  /**
+   * Update the list of methods that should be ignore from the busy state monitoring
+   * @returns {Boolean} true if the set method modified the object
+   */
+  setNotBusyList(methodList: [string]): boolean;
+
+  /**
+   * @returns {object} the current set of methods to ignore from busy state
+   */
+  getNotBusyList(): object;
+
+  /**
+   * Should the client auto listen to image stream topic by creating its imageStream object
+   * @param {Boolean} autoCreate (default: true)
+   * @returns {Boolean} true if the set method modified the object
+   */
+  setCreateImageStream(autoCreate: boolean): boolean;
+
+  /**
+   * @returns {Boolean} the autoCreate state for imageStream
+   */
+  getCreateImageStream(): boolean;
+
+  /**
+   * Set a config decorator to possibly alternate the config object that get received from the launcher.
+   * @param decorator function for config object
+   */
+  setConfigDecorator(decorator: (config: object) => object): boolean;
+
+  /**
+   * @returns {Function} configDecorator function if any was provided
+   */
+  getConfigDecorator(): (config: object) => object;
+
+  /**
+   *
+   */
+  getConnection(): any;
+
+  /**
+   *
+   */
+  getConfig(): object;
+
+  /**
+   *
+   */
+  getRemote(): Record<string, any>;
+
+  /**
+   *
+   */
+  getImageStream(): vtkImageStream;
+
+  /**
+   *
+   * @param callback
+   * @param priority
+   */
+  onBusyChange(callback: Function, priority: number): vtkSubscription;
+
+  /**
+   *
+   */
+  invokeBusyChange(): void;
+
+  onConnectionReady(callback: (httpReq: any) => void): vtkSubscription;
+  // invokeConnectionReady(): void
+
+  onConnectionError(callback: (httpReq: any) => void): vtkSubscription;
+  // invokeConnectionError(): void
+
+  onConnectionClose(callback: (httpReq: any) => void): vtkSubscription;
+  // invokeConnectionClose(): void
+}
+
+/**
+ * Method use to decorate a given object (publicAPI+model) with vtkWSLinkClient characteristics.
+ *
+ * @param publicAPI object on which methods will be bounds (public)
+ * @param model object on which data structure will be bounds (protected)
+ * @param {object} [initialValues] (default: {})
+ */
+export function extend(
+  publicAPI: object,
+  model: object,
+  initialValues?: object,
+): void;
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Method use to create a new instance of vtkWSLinkClient
+ * @param {object} [initialValues] for pre-setting some of its content
+ */
+export function newInstance(initialValues?: object): vtkWSLinkClient;
+
+/**
+ * vtkWSLinkClient is a WSLink client for talking to a server over WebSocket
+ */
+export declare const vtkWSLinkClient: {
+  newInstance: typeof newInstance;
+  extend: typeof extend;
+  // static
+  setSmartConnectClass: typeof setSmartConnectClass;
+};
+
+export default vtkWSLinkClient;

package/src/WsLinkClient/index.js

@@ -0,0 +1,237 @@
+import CompositeClosureHelper from "../CompositeClosureHelper";
+// ----------------------------------------------------------------------------
+// Dependency injection
+// ----------------------------------------------------------------------------
+
+let SMART_CONNECT_CLASS = null;
+
+// ----------------------------------------------------------------------------
+
+function setSmartConnectClass(klass) {
+  SMART_CONNECT_CLASS = klass;
+}
+
+// ----------------------------------------------------------------------------
+// Busy feedback handling
+// ----------------------------------------------------------------------------
+
+function busy(fn, update) {
+  return (...args) =>
+    new Promise((resolve, reject) => {
+      update(1);
+      fn(...args).then(
+        (response) => {
+          update(-1);
+          resolve(response);
+        },
+        (error) => {
+          update(-1);
+          reject(error);
+        }
+      );
+    });
+}
+
+// ----------------------------------------------------------------------------
+
+function busyWrap(methodMap, update, skipList = []) {
+  const busyContainer = {};
+  Object.keys(methodMap).forEach((methodName) => {
+    if (skipList.indexOf(methodName) === -1) {
+      busyContainer[methodName] = busy(methodMap[methodName], update);
+    } else {
+      busyContainer[methodName] = methodMap[methodName];
+    }
+  });
+  return busyContainer;
+}
+
+// ----------------------------------------------------------------------------
+// vtkWSLinkClient
+// ----------------------------------------------------------------------------
+
+function vtkWSLinkClient(publicAPI, model) {
+  // --------------------------------------------------------------------------
+  // Internal methods
+  // --------------------------------------------------------------------------
+
+  function notifyBusy() {
+    publicAPI.invokeBusyChange(model.busyCount);
+  }
+
+  // --------------------------------------------------------------------------
+
+  function updateBusy(delta = 0) {
+    model.busyCount += delta;
+
+    // Clear any pending timeout
+    if (model.timeoutId) {
+      clearTimeout(model.timeoutId);
+      model.timeoutId = 0;
+    }
+
+    // Delay notification when idle
+    if (model.busyCount) {
+      notifyBusy();
+    } else {
+      model.timeoutId = setTimeout(notifyBusy, model.notificationTimeout);
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Public methods
+  // --------------------------------------------------------------------------
+
+  publicAPI.beginBusy = () => updateBusy(+1);
+  publicAPI.endBusy = () => updateBusy(-1);
+  publicAPI.isBusy = () => !!model.busyCount;
+  publicAPI.isConnected = () => !!model.connection;
+
+  // --------------------------------------------------------------------------
+
+  publicAPI.connect = (config = {}, configDecorator = null) => {
+    if (!SMART_CONNECT_CLASS) {
+      return Promise.reject(new Error("Need to provide SmartConnect"));
+    }
+    if (model.connection) {
+      return Promise.reject(new Error("Need to disconnect first"));
+    }
+
+    model.config = config;
+    model.configDecorator = configDecorator || model.configDecorator;
+    return new Promise((resolve, reject) => {
+      model.smartConnect = SMART_CONNECT_CLASS.newInstance({
+        config,
+        configDecorator: model.configDecorator,
+      });
+
+      // ready
+      model.smartConnect.onConnectionReady((connection) => {
+        model.connection = connection;
+        model.remote = {};
+        model.config = model.smartConnect.getConfig();
+        const session = connection.getSession();
+
+        // Link remote API
+        model.protocols = model.protocols || {};
+        Object.keys(model.protocols).forEach((name) => {
+          model.remote[name] = busyWrap(
+            model.protocols[name](session),
+            updateBusy,
+            model.notBusyList
+          );
+        });
+
+        // Handle image stream if needed
+        if (model.createImageStream) {
+          model.imageStream = vtkImageStream.newInstance();
+          model.imageStream.connect(session);
+        }
+
+        // Forward ready info as well
+        publicAPI.invokeConnectionReady(publicAPI);
+
+        resolve(publicAPI);
+      });
+
+      // error
+      model.smartConnect.onConnectionError((error) => {
+        publicAPI.invokeConnectionError(error);
+        reject(error);
+      });
+
+      // close
+      model.smartConnect.onConnectionClose((close) => {
+        publicAPI.invokeConnectionClose(close);
+        reject(close);
+      });
+
+      // Start connection
+      model.smartConnect.connect();
+    });
+  };
+
+  // --------------------------------------------------------------------------
+
+  publicAPI.disconnect = (timeout = 60) => {
+    if (model.connection) {
+      model.connection.destroy(timeout);
+      model.connection = null;
+    }
+  };
+
+  // --------------------------------------------------------------------------
+
+  publicAPI.registerProtocol = (name, protocol) => {
+    model.remote[name] = busyWrap(
+      protocol(model.connection.getSession()),
+      updateBusy,
+      model.notBusyList
+    );
+  };
+
+  // --------------------------------------------------------------------------
+
+  publicAPI.unregisterProtocol = (name) => {
+    delete model.remote[name];
+  };
+}
+
+// ----------------------------------------------------------------------------
+// Object factory
+// ----------------------------------------------------------------------------
+
+const DEFAULT_VALUES = {
+  // protocols: null,
+  // connection: null,
+  // config: null,
+  // imageStream
+  notBusyList: [],
+  busyCount: 0,
+  timeoutId: 0,
+  notificationTimeout: 50,
+  createImageStream: true,
+  // configDecorator: null,
+};
+
+// ----------------------------------------------------------------------------
+
+export function extend(publicAPI, model, initialValues = {}) {
+  Object.assign(model, DEFAULT_VALUES, initialValues);
+
+  // Object methods
+  CompositeClosureHelper.set(publicAPI, model, [
+    "protocols",
+    "notBusyList",
+    "createImageStream",
+    "configDecorator",
+  ]);
+  CompositeClosureHelper.get(publicAPI, model, [
+    "connection",
+    "config",
+    "remote",
+    "imageStream",
+    "protocols",
+    "notBusyList",
+    "createImageStream",
+    "configDecorator",
+  ]);
+  CompositeClosureHelper.event(publicAPI, model, "BusyChange");
+  CompositeClosureHelper.event(publicAPI, model, "ConnectionReady");
+  CompositeClosureHelper.event(publicAPI, model, "ConnectionError");
+  CompositeClosureHelper.event(publicAPI, model, "ConnectionClose");
+
+  // Object specific methods
+  vtkWSLinkClient(publicAPI, model);
+}
+
+// ----------------------------------------------------------------------------
+
+export const newInstance = CompositeClosureHelper.newInstance(
+  extend,
+  "vtkWSLinkClient"
+);
+
+// ----------------------------------------------------------------------------
+
+export default { newInstance, extend, setSmartConnectClass };

package/src/index.js

@@ -2,10 +2,12 @@ import CompositeClosureHelper from "./CompositeClosureHelper";
 import ProcessLauncher from "./ProcessLauncher";
 import SmartConnect from "./SmartConnect";
 import WebsocketConnection from "./WebsocketConnection";
+import WsLinkClient from "./WsLinkClient";
 
 export {
   CompositeClosureHelper,
   ProcessLauncher,
   SmartConnect,
   WebsocketConnection,
+  WsLinkClient,
 };