JPC: Fix TypeScript errors (#340)

* Fix TypeScript errors in jpc and jpc-ws

Mostly fixing lax jsdoc types, but I needed a couple of jsdoc type casts and also a @ts-ignore in one spot.

lib/jpc-ws/WSCall.js

@@ -3,7 +3,7 @@ import { assert } from "../jpc/util.js";
 
 export default class WSCall extends MessageCall {
   /**
-   * @param webSocket {WebSocket from ws}
+   * @param webSocket {import("ws").WebSocket}
    */
   constructor(webSocket) {
     assert(typeof (webSocket.on) == "function");

lib/jpc-ws/protocol.js

@@ -3,6 +3,9 @@ import JPCProtocol from "../jpc/protocol.js";
 import WebSocketNode, { WebSocketServer } from "ws";
 import { assert } from "../jpc/util.js";
 
+/** @typedef {number} Integer */
+/** @typedef {object} JSON */
+
 /**
  * Wire protocol API
  */
@@ -96,6 +99,7 @@ export default class JPCWebSocket extends JPCProtocol {
     let webSocket;
     if (typeof WebSocket == "function") { // browser
       webSocket = new WebSocket(url);
+      // @ts-ignore
       webSocket.on = (eventName, func) => {
         webSocket.addEventListener(eventName, message => func(message.data), false);
       };
@@ -137,7 +141,7 @@ export default class JPCWebSocket extends JPCProtocol {
    * Implements the wire protocol.
    *
    * @param method {string} the message name, e.g. "func", "get", etc.
-   * @param listener {async function(payload {JSON}}
+   * @param listener {function(JSON): Promise<any>}
    * What the listener function returns is sent back as result to the caller.
    * If listener throws, sends the error message to the caller at the remote end.
    */
@@ -150,8 +154,8 @@ export default class JPCWebSocket extends JPCProtocol {
    * Implements the wire protocol.
    *
    * @param method {string} the message name, e.g. "func", "get" etc.
-   * @param payload {JSON} see value in PROTOCOL.md
-   * @returns {any} see value in PROTOCOL.md
+   * @param [payload] {JSON} see value in PROTOCOL.md
+   * @returns {Promise<any>} see value in PROTOCOL.md
    *   The payload of the corresponding answer.
    * @throws {Error} if:
    *   - the remote end threw an exception

lib/jpc/message.js

@@ -1,5 +1,7 @@
 import { assert, consoleError } from "./util.js";
 
+/** @typedef {object} JSON */
+
 /**
  * Abstract base implementation for protocols.
  *
@@ -58,8 +60,8 @@ export default class MessageCall  {
 
   /**
    * @param path {string}  URL relative to the root, e.g. "/app/user"
-   * @param func {async function(arg)} will be called when the path is invoked
-   *   arg {Object} parameter from the caller
+   * @param func {function(object): Promise} will be called when the path is invoked
+   *   arg {object} parameter from the caller
    *   Whatever the function returns will be sent back to the caller.
    *   If the function throws, the error .message {string} and .code {string} will
    *   be sent to the caller as exception.
@@ -71,12 +73,12 @@ export default class MessageCall  {
   }
 
   /**
-   * @param message {JSON or JSON as string}
+   * @param message {JSON | string}
    */
   async _incomingMessage(message) {
     try {
       if (typeof(message) == "string") {
-        message = JSON.parse(message);
+        message = /** @type {JSON} */(JSON.parse(message));
       }
     } catch (ex) {
       return;
@@ -139,7 +141,7 @@ export default class MessageCall  {
    *    E.g. "/contact/call/" or "register".
    *    Must match the registration on the other side exactly, including leading slash or not.
    * @param arg {JSON}   arguments for the function call
-   * @param {Promise} waits until the call returns with a result or Exception
+   * @returns {Promise} waits until the call returns with a result or Exception
    */
   async makeCall(path, arg) {
     assert(path && typeof(path) == "string");

lib/jpc/obj.js

@@ -1,6 +1,8 @@
 import { assert } from "./util.js";
 import { Buffer } from "buffer";
 
+/** @typedef {object} JSON */
+
 function getClassName(obj) {
   let proto = Object.getPrototypeOf(obj);
   return (proto && (proto[Symbol.toStringTag] || proto.constructor.name)) || "Object";
@@ -11,6 +13,8 @@ function isPrivateProperty(propName) {
 }
 
 // This is only set as a function on classes that are known to be observers
+// @param this {RemoteClass}
+// @param subscriber {function(self {RemoteClass})}
 function subscribe(subscriber) {
   subscriber(this);
   if (!this._subscribers) {
@@ -23,6 +27,10 @@ function subscribe(subscriber) {
 class RemoteClass {
   constructor(className) {
     this.className = className;
+    /** @type {Set<function(RemoteClass): void> | undefined} */
+    this._subscribers;
+    /** @type string */
+    this._jpc_id;
   }
   _notifySubscribers() {
     if (this._subscribers) {
@@ -39,6 +47,11 @@ class RemoteClass {
 }
 
 export default class BaseProtocol {
+  /**
+   * @param method {string}
+   * @paqram [payload] {any}
+   * @returns {Promise<any>}
+   */
   callRemote(method, payload) {
     throw new Error("Implement this");
   }
@@ -49,7 +62,7 @@ export default class BaseProtocol {
    * Called by the wire protocol implementation,
    * before calling any of the other functions.
    *
-   * @param jpcProtocol {JPCProtocol} Wire protocol implementation
+   * @param startObject {any}
    */
   start(startObject) {
     this.registerIncomingCall("class", this.getClassDescription.bind(this));
@@ -161,7 +174,7 @@ export default class BaseProtocol {
    * Generates a stub object instance
    *
    * @param objDescrJSON {JSON} Describes the remote object, see PROTOCOL.md
-   * @returns {StubObj}
+   * @returns {Promise<RemoteClass>}
    */
   async makeStub(objDescrJSON) {
     let proto = this._remoteClasses.get(objDescrJSON.className);
@@ -270,7 +283,7 @@ export default class BaseProtocol {
    * @param value {any} string, number, boolean,
    *   array, JSON obj,
    *   Object description or Object references, as defined by PROTOCOL.md
-   * @return {any} same as value, just Object descriptions and Object references
+   * @return {Promise<any>} same as value, just Object descriptions and Object references
    *   replaced with `StubObject`s.
    */
   async mapIncomingObjects(value) {
@@ -433,7 +446,7 @@ export default class BaseProtocol {
     let obj = this.getRemoteObject(objDescrJSON.idSender);
     if (obj) {
       if (obj instanceof Promise) {
-        obj = await obj;
+        obj = /** @type {RemoteClass} */(await obj);
       }
       await this.updateObjectProperties(obj, objDescrJSON.properties);
       obj._notifySubscribers();
@@ -560,7 +573,7 @@ export default class BaseProtocol {
   /**
    * Return an object instance to the remote party that they did not see yet.
    *
-   * @param obj {Object} local object
+   * @param obj {object} local object
    * @returns {JSON} Object description, see PROTOCOL.md
    */
   createObjectDescription(obj, id) {
@@ -687,7 +700,7 @@ export default class BaseProtocol {
 
   /**
    * @param id {string} ID of object refererence
-   * @returns {Promise|StubObj?} remote object
+   * @returns {Promise|RemoteClass?} remote object
    */
   getRemoteObject(id) {
     let ref = this._remoteObjects.get(id);
@@ -730,7 +743,7 @@ export default class BaseProtocol {
 
   /**
    * @param id {string} ID for remote object, as set by the remote side
-   * @param obj {StubObj} Remote object
+   * @param obj {RemoteClass | function} Remote object
    */
   addRemoteObject(id, obj) {
     let existing = this.getRemoteObject(id);

lib/jpc/protocol.js

@@ -1,5 +1,7 @@
 import BaseProtocol from "./obj.js";
 
+/** @typedef {object} JSON */
+
 /**
  * Wire protocol API
  */
@@ -30,7 +32,7 @@ export default class JPCProtocol extends BaseProtocol {
    * Implements the wire protocol.
    *
    * @param method {string} the message name, e.g. "func", "get", "func-r" etc.
-   * @param listener {async function(payload {JSON}}
+   * @param listener {function(object): Promise<any>}
    * What the listener function returns is sent back as result to the caller.
    * If listener throws, sends the error message to the caller at the remote end.
    */
@@ -43,8 +45,8 @@ export default class JPCProtocol extends BaseProtocol {
    * Implements the wire protocol.
    *
    * @param method {string} the message name, e.g. "func", "get" etc.
-   * @param payload {JSON} see value in PROTOCOL.md
-   * @returns {any} see value in PROTOCOL.md
+   * @param [payload] {JSON} see value in PROTOCOL.md
+   * @returns {Promise<any>} see value in PROTOCOL.md
    *   The payload of the corresponding answer.
    * @throws {Error} if:
    *   - the remote end threw an exception

lib/jpc/util.js

@@ -1,6 +1,6 @@
 /**
  * @param test {boolean}
- * @param errorMsg {string}
+ * @param [errorMsg] {string}
  */
 export function assert(test, errorMsg) {
   if (!test) {