scoundrel-remote-eval 1.0.6 → 1.0.8

package/eslint.config.js

@@ -0,0 +1,18 @@
+import js from "@eslint/js"
+import globals from "globals"
+import {defineConfig} from "eslint/config"
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    plugins: {js},
+    extends: ["js/recommended"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.jasmine
+      }
+    }
+  }
+])

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "scoundrel-remote-eval",
   "type": "module",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "",
   "main": "src/index.js",
   "scripts": {
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit",
     "test": "jasmine"
   },
   "repository": {
@@ -21,7 +23,13 @@
   },
   "homepage": "https://github.com/kaspernj/scoundrel#readme",
   "devDependencies": {
-    "jasmine": "^5.1.0"
+    "@eslint/js": "^9.39.2",
+    "@types/jasmine": "^5.1.13",
+    "@types/node": "^25.0.2",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "jasmine": "^5.1.0",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
     "ws": "^8.14.2"

package/spec/reference-with-proxy-spec.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import Client from "../src/client/index.js"
 import ClientWebSocket from "../src/client/connections/web-socket/index.js"
 import referenceWithProxy from "../src/client/reference-proxy.js"
@@ -36,9 +38,13 @@ describe("referenceWithProxy", () => {
     const stringObjectReference = await shared.client.newObjectWithReference("Array")
     const stringObject = referenceWithProxy(stringObjectReference)
 
+    // @ts-ignore
     await stringObject.push("test1")
+
+    // @ts-ignore
     await stringObject.push("test2")
 
+    // @ts-ignore
     const result = await stringObject.__serialize()
 
     expect(result).toEqual(["test1", "test2"])
@@ -65,9 +71,13 @@ describe("referenceWithProxy", () => {
     const stringObjectReference = await shared.client.newObjectWithReference("Array")
     const stringObject = referenceWithProxy(stringObjectReference)
 
+    // @ts-ignore
     await stringObject.push("test1")
+
+    // @ts-ignore
     await stringObject.push("test2")
 
+    // @ts-ignore
     const result = await stringObject.__serialize()
 
     expect(result).toEqual(["test1", "test2"])
@@ -77,9 +87,13 @@ describe("referenceWithProxy", () => {
     const stringObjectReference = await shared.serverClient.newObjectWithReference("Array")
     const stringObject = referenceWithProxy(stringObjectReference)
 
+    // @ts-ignore
     await stringObject.push("test1")
+
+    // @ts-ignore
     await stringObject.push("test2")
 
+    // @ts-ignore
     const result = await stringObject.__serialize()
 
     expect(result).toEqual(["test1", "test2"])

package/spec/web-socket-javascript-spec.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import Client from "../src/client/index.js"
 import ClientWebSocket from "../src/client/connections/web-socket/index.js"
 import Server from "../src/server/index.js"
@@ -46,4 +48,19 @@ describe("scoundrel - web-socket - javascript", () => {
 
     expect(result).toEqual("test1, test2")
   })
+
+  it("handles errors from method calls", async () => {
+    const stringObject = await shared.client.newObjectWithReference("Array")
+
+    let caughtError = null
+
+    try {
+      await stringObject.callMethod("nonExistentMethod")
+    } catch (error) {
+      caughtError = error
+    }
+
+    expect(caughtError).toBeInstanceOf(Error)
+    expect(caughtError.message).toEqual("No method called 'nonExistentMethod' on a 'Array'")
+  })
 })

package/spec/web-socket-python-spec.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import Client from "../src/client/index.js"
 import ClientWebSocket from "../src/client/connections/web-socket/index.js"
 import Logger from "../src/logger.js"

package/src/client/connections/web-socket/index.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import Logger from "../../../logger.js"
 
 const logger = new Logger("Scoundrel WebSocket")
@@ -5,10 +7,20 @@ const logger = new Logger("Scoundrel WebSocket")
 // logger.setDebug(true)
 
 export default class WebSocket {
+  /**
+   * Creates a new WebSocket connection handler
+   * @param {WebSocket} ws The WebSocket instance
+   */
   constructor(ws) {
     this.ws = ws
+
+    // @ts-ignore
     this.ws.addEventListener("error", this.onSocketError)
+
+    // @ts-ignore
     this.ws.addEventListener("open", this.onSocketOpen)
+
+    // @ts-ignore
     this.ws.addEventListener("message", this.onSocketMessage)
 
     this.commands = {}
@@ -19,33 +31,58 @@ export default class WebSocket {
     await this.ws.close()
   }
 
+  /**
+   * @param {(data: any) => void} callback
+   */
   onCommand(callback) {
     this.onCommandCallback = callback
   }
 
+  /**
+   * @param {Event} event
+   */
   onSocketError = (event) => {
     logger.error(() => ["onSocketError", event])
   }
 
+  /**
+   * @param {MessageEvent} event
+   */
   onSocketMessage = (event) => {
     const data = JSON.parse(event.data)
 
     logger.log(() => ["Client::Connections::WebSocket onSocketMessage", data])
+
+    if (!this.onCommandCallback) {
+      throw new Error("No onCommand callback set, ignoring message")
+    }
+
     this.onCommandCallback(data)
   }
 
-  onSocketOpen = (_event) => {
+  /**
+   * @param {Event} _event
+   */
+  onSocketOpen = (_event) => { // eslint-disable-line no-unused-vars
     logger.log("onSocketOpen")
   }
 
+  /**
+   * @param {Record<string, any>} data
+   */
   send(data) {
     const sendData = JSON.stringify(data)
     logger.log(() => ["Sending", sendData])
+
+    // @ts-ignore
     this.ws.send(sendData)
   }
 
   waitForOpened = () => new Promise((resolve, reject) => {
+    // @ts-ignore
     this.ws.addEventListener("open", resolve)
+
+    // @ts-ignore
     this.ws.addEventListener("error", reject)
   })
 }

package/src/client/index.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import Logger from "../logger.js"
 import Reference from "./reference.js"
 
@@ -15,14 +17,23 @@ export default class Client {
     this.backend = backend
     this.backend.onCommand(this.onCommand)
 
+    /** @type {Record<number, any>} */
     this.outgoingCommands = {}
     this.incomingCommands = {}
     this.outgoingCommandsCount = 0
 
+    /** @type {Record<string, any>} */
     this._classes = {}
+
+    /** @type {Record<string, any>} */
     this._objects = {}
+
+    /** @type {Record<string, Reference>} */
     this.references = {}
+
+    /** @type {Record<number, any>} */
     this.objects = {}
+
     this.objectsCount = 0
   }
 
@@ -130,7 +141,8 @@ export default class Client {
   /**
    * Spawns a new reference to an object
    *
-   * @param {string} id
+   * @param {string} className
+   * @param  {...any} args
    * @returns {Promise<Reference>}
    */
   async newObjectWithReference(className, ...args) {
@@ -148,6 +160,11 @@ export default class Client {
     return this.spawnReference(id)
   }
 
+  /**
+   * Checks if the input is a plain object
+   * @param {any} input
+   * @returns {boolean}
+   */
   isPlainObject(input) {
     if (input && typeof input === "object" && !Array.isArray(input)) {
       return true
@@ -156,7 +173,18 @@ export default class Client {
     return false
   }
 
-  onCommand = ({command, command_id: commandID, data, ...restArgs}) => {
+  /**
+   * Handles an incoming command from the backend
+   * @param {object} args
+   * @param {string} args.command
+   * @param {number} args.command_id
+   * @param {any} args.data
+   * @param {string} [args.error]
+   * @param {string} [args.errorStack]
+   */
+  onCommand = ({command, command_id: commandID, data, error, errorStack, ...restArgs}) => {
+    logger.log(() => ["onCommand", {command, commandID, data, error, errorStack, restArgs}])
+
     try {
       if (!command) {
         throw new Error(`No command key given in data: ${Object.keys(restArgs).join(", ")}`)
@@ -167,7 +195,7 @@ export default class Client {
         if (serverObject) {
           object = serverObject
         } else {
-          object = global[data.object_name]
+          object = globalThis[data.object_name]
 
           if (!object) throw new Error(`No such object: ${data.object_name}`)
         }
@@ -181,7 +209,7 @@ export default class Client {
         let object
 
         if (typeof className == "string") {
-          const ClassInstance = this.getClass(className) || global[className]
+          const ClassInstance = this.getClass(className) || globalThis[className]
 
           if (!ClassInstance) throw new Error(`No such class: ${className}`)
 
@@ -233,20 +261,22 @@ export default class Client {
           this.respondToCommand(commandID, {response: attribute})
         }
       } else if (command == "command_response") {
-        if (!(commandID in this.outgoingCommands)) throw new Error(`Outgoing command ${commandID} not found`)
+        if (!(commandID in this.outgoingCommands)) {
+          throw new Error(`Outgoing command ${commandID} not found: ${Object.keys(this.outgoingCommands).join(", ")}`)
+        }
 
         const savedCommand = this.outgoingCommands[commandID]
 
         delete this.outgoingCommands[commandID]
 
-        if (data.error) {
-          const error = new Error(data.error)
+        if (error) {
+          const errorToThrow = new Error(error)
 
-          if (data.errorStack) {
-            error.stack = `${data.errorStack}\n\n${error.stack}`
+          if (errorStack) {
+            errorToThrow.stack = `${errorStack}\n\n${errorToThrow.stack}`
           }
 
-          savedCommand.reject(error)
+          savedCommand.reject(errorToThrow)
         } else {
           logger.log(() => [`Resolving command ${commandID} with data`, data])
           savedCommand.resolve(data.data)
@@ -255,9 +285,13 @@ export default class Client {
         throw new Error(`Unknown command: ${command}`)
       }
     } catch (error) {
-      this.send({command: "command_response", command_id: commandID, error: `Unknown command: ${error.message}`, errorStack: error.stack})
+      if (error instanceof Error) {
+        this.send({command: "command_response", command_id: commandID, error: error.message, errorStack: error.stack})
+      } else {
+        this.send({command: "command_response", command_id: commandID, error: String(error)})
+      }
 
-      console.error(error)
+      logger.error(error)
     }
   }
 
@@ -276,6 +310,7 @@ export default class Client {
         __scoundrel_type: "reference"
       }
     } else if (this.isPlainObject(arg)) {
+      /** @type {Record<any, any>} */
       const newObject = {}
 
       for (const key in arg) {
@@ -368,10 +403,21 @@ export default class Client {
     return this._objects[objectName]
   }
 
+  /**
+   * Responds to a command from the backend
+   * @param {number} commandId
+   * @param {any} data
+   */
   respondToCommand(commandId, data) {
     this.sendCommand("command_response", {command_id: commandId, data})
   }
 
+  /**
+   * Sends a command to the backend and returns a promise that resolves with the response
+   * @param {string} command
+   * @param {any} data
+   * @returns {Promise<any>}
+   */
   sendCommand(command, data) {
     return new Promise((resolve, reject) => {
       const outgoingCommandCount = ++this.outgoingCommandsCount
@@ -387,6 +433,10 @@ export default class Client {
     })
   }
 
+  /**
+   * Sends data to the backend
+   * @param {any} data
+   */
   send(data) {
     this.backend.send(data)
   }
@@ -407,7 +457,7 @@ export default class Client {
    * Spawns a new reference to an object
    *
    * @param {string} id
-   * @returns {Promise<Reference>}
+   * @returns {Reference}
    */
   spawnReference(id) {
     const reference = new Reference(this, id)

package/src/client/reference-proxy.js

@@ -1,6 +1,18 @@
+// @ts-check
+
+/**
+ * @param {import("./reference.js").default} reference
+ * @param {string} prop
+ * @returns {(...args: any[]) => Promise<any>}
+ */
 const proxyMethodSpawner = (reference, prop) => (...args) => reference.callMethodWithReference(prop, ...args)
 
 const proxyObjectHandler = {
+  /**
+   * @param {import("./reference.js").default|(() => import("./reference.js").default)} reference
+   * @param {string} prop
+   * @returns {any}
+   */
   get(reference, prop) {
     if (typeof reference == "function") reference = reference()
 
@@ -14,16 +26,28 @@ const proxyObjectHandler = {
     return proxyMethodSpawner(reference, prop)
   },
 
+  /**
+   * @param {import("./reference.js").default|(() => import("./reference.js").default)} receiver
+   * @param {string} prop
+   * @param {any} newValue
+   */
   set(receiver, prop, newValue) {
     throw new Error("set property isn't supported yet")
 
-    if (typeof receiver == "function") receiver = receiver()
-    if (!(prop in receiver)) throw new PropertyNotFoundError(`Property not found: ${prop}`)
+    // @ts-expect-error
+    if (typeof receiver == "function") receiver = receiver() // eslint-disable-line no-unreachable
+
+    // @ts-expect-error
+    if (!(prop in receiver)) throw new PropertyNotFoundError(`Property not found: ${prop}`) // eslint-disable-line no-undef
 
     return Reflect.set(receiver, prop, newValue)
   }
 }
 
+/**
+ * @param {any} wrappedObject
+ * @returns {Proxy}
+ */
 const referenceProxy = (wrappedObject) => new Proxy(wrappedObject, proxyObjectHandler)
 
 export default referenceProxy

package/src/client/reference.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 export default class Reference {
   /**
    * Creates a new Reference

package/src/logger.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 export default class Logger {
   /**
    * Creates a new Logger instance
@@ -29,13 +31,25 @@ export default class Logger {
 
   /**
    * Logs a message to the console if debug is enabled
-   *
    * @param  {...any} args
    */
   log(...args) {
     return this._sendToConsole("log", ...args)
   }
 
+  /**
+   * Logs a warning message to the console if debug is enabled
+   * @param  {...any} args
+   */
+  warn(...args) {
+    return this._sendToConsole("warn", ...args)
+  }
+
+  /**
+   * Sends the log message to the console
+   * @param {string} logType
+   * @param  {...any} args
+   */
   _sendToConsole(logType, ...args) {
     if (!this.debug) {
       return

package/src/python-web-socket-runner.js

@@ -1,12 +1,23 @@
+// @ts-check
+
 import {exec, spawn} from "child_process"
 import Logger from "./logger.js"
-import {realpath} from "node:fs/promises"
+import {realpath} from "fs/promises"
 
 const logger = new Logger("Scoundrel PythonWebSocketRunner")
 
 // logger.setDebug(true)
 
 export default class PythonWebSocketRunner {
+  /** @type {Error | null} */
+  waitForPidRejectError = null
+
+  /** @type {((value: any) => void) | null} */
+  waitForPidResolve = null
+
+  /** @type {((value: any) => void) | null} */
+  waitForPidReject = null
+
   constructor() {
     process.on("exit", this.onProcessExit)
   }
@@ -36,10 +47,18 @@ export default class PythonWebSocketRunner {
     }
   }
 
+  /**
+   * @param {number} code
+   * @param {string} signal
+   */
   onChildExit = (code, signal) => {
     logger.log(() => `Child process exited with code ${code} and signal ${signal}`)
 
     if (this.waitForPidRejectError) {
+      if (!this.waitForPidReject) {
+        throw new Error("waitForPidReject is undefined while waitForPidRejectError is set")
+      }
+
       this.waitForPidReject(this.waitForPidRejectError)
       this.waitForPidResolve = null
       this.waitForPidReject = null
@@ -52,6 +71,9 @@ export default class PythonWebSocketRunner {
     }
   }
 
+  /**
+   * @param {string | Buffer} data
+   */
   onChildStderr = (data) => {
     logger.error(() => `stderr: ${data}`)
 
@@ -60,6 +82,9 @@ export default class PythonWebSocketRunner {
     }
   }
 
+  /**
+   * @param {string | Buffer} data
+   */
   onChildStdout = (data) => {
     logger.log(() => `stdout: ${data}`)
 
@@ -71,7 +96,11 @@ export default class PythonWebSocketRunner {
       logger.log(() => `Registered PID ${this.pid}`)
 
       if (this.waitForPidResolve) {
-        this.waitForPidResolve()
+        if (!this.waitForPidResolve) {
+          throw new Error("waitForPidResolve is undefined while waitForPidRejectError is set")
+        }
+
+        this.waitForPidResolve(null)
         this.waitForPidResolve = null
         this.waitForPidReject = null
         this.waitForPidRejectError = null

package/src/server/connections/web-socket/client.js

@@ -1,4 +1,10 @@
+// @ts-check
+
 export default class WebSocketClient {
+  /**
+   * Creates a new WebSocketClient
+   * @param {import("ws").WebSocket} ws The WebSocket instance
+   */
   constructor(ws) {
     this.ws = ws
 
@@ -6,14 +12,23 @@ export default class WebSocketClient {
     ws.on("message", this.onMessage)
   }
 
+  /**
+   * @param {(data: any) => void} callback
+   */
   onCommand(callback) {
     this.onCommandCallback = callback
   }
 
+  /**
+   * @param {Error} error
+   */
   onError = (error) => {
     console.error("WebSocketClient error", error)
   }
 
+  /**
+   * @param {string} rawData
+   */
   onMessage = (rawData) => {
     const data = JSON.parse(rawData)
 
@@ -22,6 +37,9 @@ export default class WebSocketClient {
     this.onCommandCallback(data)
   }
 
+  /**
+   * @param {any} data
+   */
   async send(data) {
     await this.ws.send(JSON.stringify(data))
   }

package/src/server/connections/web-socket/index.js

@@ -1,6 +1,12 @@
+// @ts-check
+
 import WebSocketClient from "./client.js"
 
 export default class WebSocket {
+  /**
+   * Creates a new WebSocket connection handler
+   * @param {import("ws").Server} webSocketServer The WebSocket server instance
+   */
   constructor(webSocketServer) {
     this.wss = webSocketServer
     this.wss.on("connection", this.onConnection)
@@ -8,12 +14,18 @@ export default class WebSocket {
 
   close() { this.wss.close() }
 
+  /**
+   * @param {import("ws").WebSocket} ws
+   */
   onConnection = (ws) => {
     if (!this.onNewClientCallback) throw new Error("'onNewClient' hasn't been called")
 
     this.onNewClientCallback(new WebSocketClient(ws))
   }
 
+  /**
+   * @param {(client: import("./client.js").default) => void} callback
+   */
   onNewClient(callback) {
     if (!callback) throw new Error("No callback was given")
 

package/src/server/index.js

@@ -1,17 +1,29 @@
+// @ts-check
+
 import Client from "../client/index.js"
 import EventEmitter from "events"
 
 export default class ScoundrelServer {
+  /**
+   * Creates a new Scoundrel server
+   * @param {import("./connections/web-socket/index.js").default} backend The backend connection handler
+   */
   constructor(backend) {
     this.backend = backend
     this.backend.onNewClient(this.onNewClient)
+
+    /** @type {Client[]} */
     this.clients = []
+
     this.events = new EventEmitter()
   }
 
   close() { this.backend.close() }
   getClients() { return this.clients }
 
+  /**
+   * @param {import("./connections/web-socket/client.js").default} clientBackend
+   */
   onNewClient = (clientBackend) => {
     const client = new Client(clientBackend)
 

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "noEmit": true,
+    "target": "ES2020",
+
+    "moduleResolution": "nodenext",
+    "module": "nodenext",
+
+    "lib": ["dom", "ES2020"],
+    "types": ["jasmine", "node"]
+  }
+}