javonet-nodejs-sdk 2.5.16 → 2.5.18

package/lib/core/interpreter/Interpreter.js

@@ -1,5 +1,6 @@
+// @ts-check
 import { ConnectionType } from '../../utils/ConnectionType.js'
-import { isNodejsRuntime, getRuntimeExtension, getRequire, getDirname } from '../../utils/Runtime.js'
+import { isNodejsRuntime, getRequire } from '../../utils/Runtime.js'
 import { RuntimeName } from '../../utils/RuntimeName.js'
 import { CommandDeserializer } from '../protocol/CommandDeserializer.js'
 import { CommandSerializer } from '../protocol/CommandSerializer.js'
@@ -8,17 +9,16 @@ import { TransmitterWebsocket } from '../transmitter/TransmitterWebsocket.js'
 import { Handler } from '../handler/Handler.js'
 
 /**
- * @typedef {import('../receiver/Receiver.js').Receiver} Receiver
- * @typedef {import('../transmitter/Transmitter.js').Transmitter} Transmitter
- * @typedef {import('../transmitter/TransmitterWebsocket.js').TransmitterWebsocket} TransmitterWebsocket
- * @typedef {import('../transmitter/TransmitterWebsocketBrowser.js').TransmitterWebsocketBrowser} TransmitterWebsocketBrowser
+ * @typedef {import('../../utils/connectionData/IConnectionData.js').IConnectionData} IConnectionData
+ * @typedef {typeof import('../../types.d.ts').RuntimeName} RuntimeNameType
+ * @typedef {import('../../utils/Command.js').Command} Command
  */
 
-/** @type {Receiver | null} */
+/** @type {typeof import('../receiver/Receiver.js').Receiver | null} */
 let _Receiver = null
-/** @type {Transmitter | null} */
+/** @type {typeof import('../transmitter/Transmitter.js').Transmitter | null} */
 let _Transmitter = null
-/** @type {TransmitterWebsocket | null} */
+/** @type {typeof import('../transmitter/TransmitterWebsocket.js').TransmitterWebsocket | typeof import('../transmitter/TransmitterWebsocketBrowser.js').TransmitterWebsocketBrowser | null} */
 let _TransmitterWebsocket = null
 
 if (!_TransmitterWebsocket) {
@@ -28,7 +28,8 @@ if (!_TransmitterWebsocket) {
 const requireDynamic = getRequire(import.meta.url)
 
 export class Interpreter {
-    handler
+    /** @type {Handler | null} */
+    handler = null
     /**
      *
      * @param {Command} command
@@ -37,8 +38,12 @@ export class Interpreter {
      */
     async executeAsync(command, connectionData) {
         try {
+            if (!this.handler) {
+                this.handler = new Handler(this)
+            }
             let messageByteArray = new CommandSerializer().serialize(command, connectionData)
-            let responseByteArray
+            /** @type {Int8Array | undefined} */
+            let responseByteArray = undefined
 
             if (
                 command.runtimeName === RuntimeName.Nodejs &&
@@ -47,16 +52,16 @@ export class Interpreter {
                 if (isNodejsRuntime()) {
                     // lazy receiver loading
                     if (!_Receiver) {
-                        const { Receiver } = requireDynamic('../receiver/Receiver.js');
+                        const { Receiver } = requireDynamic('../receiver/Receiver.js')
                         _Receiver = Receiver
                     }
-                    responseByteArray = _Receiver.sendCommand(messageByteArray)
+                    responseByteArray = _Receiver?.sendCommand(messageByteArray)
                 } else {
                     throw new Error('Node.js runtime not found')
                 }
             } else if (connectionData.connectionType === ConnectionType.WEB_SOCKET) {
                 try {
-                    const _response = await _TransmitterWebsocket.sendCommand(
+                    const _response = await _TransmitterWebsocket?.sendCommand(
                         messageByteArray,
                         connectionData
                     )
@@ -76,13 +81,15 @@ export class Interpreter {
                         const { Transmitter } = requireDynamic('../transmitter/Transmitter.js')
                         _Transmitter = Transmitter
                     }
-                    responseByteArray = await _Transmitter.sendCommand(messageByteArray)
+                    responseByteArray = await _Transmitter?.sendCommand(messageByteArray)
                 } else {
                     throw new Error('Allowed only to run in nodejs runtime')
                 }
             }
+            if (!responseByteArray) {
+                throw new Error('No response received from Transmitter')
+            }
             return new CommandDeserializer(responseByteArray).deserialize()
-            // eslint-disable-next-line no-unused-vars
         } catch (error) {
             throw error
         }
@@ -91,13 +98,17 @@ export class Interpreter {
     /**
      *
      * @param {Command} command
-     * @param {WsConnectionData} connectionData
-     * @returns {Promise<Command>}
+     * @param {IConnectionData} connectionData
+     * @returns {Command | Promise<Command>}
      */
     execute(command, connectionData) {
         try {
+            if (!this.handler) {
+                this.handler = new Handler(this)
+            }
             let messageByteArray = new CommandSerializer().serialize(command, connectionData)
-            let responseByteArray
+            /** @type {Int8Array | undefined} */
+            let responseByteArray = undefined
 
             if (
                 command.runtimeName === RuntimeName.Nodejs &&
@@ -106,14 +117,18 @@ export class Interpreter {
                 if (isNodejsRuntime()) {
                     // lazy receiver loading
                     if (!_Receiver) {
-                        const { Receiver } = requireDynamic('../receiver/Receiver.js');
+                        const { Receiver } = requireDynamic('../receiver/Receiver.js')
                         _Receiver = Receiver
                     }
-                    responseByteArray = _Receiver.sendCommand(messageByteArray)
+                    responseByteArray = _Receiver?.sendCommand(messageByteArray)
                 }
             } else if (connectionData.connectionType === ConnectionType.WEB_SOCKET) {
                 // lazy transmitter websocket loading
-                const promise = _TransmitterWebsocket.sendCommand(messageByteArray, connectionData)
+                const promise = _TransmitterWebsocket?.sendCommand(messageByteArray, connectionData)
+
+                if (!promise) {
+                    throw new Error('TransmitterWebsocket not found')
+                }
 
                 return promise
                     .then((_response) => {
@@ -133,13 +148,16 @@ export class Interpreter {
                         const { Transmitter } = requireDynamic('../transmitter/Transmitter.js')
                         _Transmitter = Transmitter
                     }
-                    responseByteArray = _Transmitter.sendCommand(messageByteArray)
+
+                    responseByteArray = _Transmitter?.sendCommand(messageByteArray)
                 } else {
                     throw new Error('Allowed only to run in nodejs runtime')
                 }
             }
+            if (!responseByteArray) {
+                throw new Error('No response received from Transmitter')
+            }
             return new CommandDeserializer(responseByteArray).deserialize()
-            // eslint-disable-next-line no-unused-vars
         } catch (error) {
             throw error
         }
@@ -147,7 +165,7 @@ export class Interpreter {
 
     /**
      *
-     * @param {number[]} messageByteArray
+     * @param {Int8Array} messageByteArray
      * @returns {Command}
      */
     process(messageByteArray) {

package/lib/core/namespaceCache/NamespaceCache.js

@@ -1,5 +1,9 @@
+// @ts-check
+
 class NamespaceCache {
+    /** @type {NamespaceCache | null} */
     static _instance = null
+    /** @type {string[]} */
     namespaceCache = []
 
     constructor() {
@@ -9,14 +13,24 @@ class NamespaceCache {
         return NamespaceCache._instance
     }
 
+    /**
+     * @param {string} namespaceRegex
+     */
     cacheNamespace(namespaceRegex) {
         this.namespaceCache.push(namespaceRegex)
     }
 
+    /**
+     * @returns {boolean}
+     */
     isNamespaceCacheEmpty() {
         return this.namespaceCache.length === 0
     }
 
+    /**
+     * @param {string} typeToCheck
+     * @returns {boolean}
+     */
     isTypeAllowed(typeToCheck) {
         for (let pattern of this.namespaceCache) {
             if (new RegExp(pattern).test(typeToCheck.constructor.name)) {

package/lib/core/protocol/CommandDeserializer.js

@@ -1,9 +1,12 @@
+// @ts-check
 import { Command } from '../../utils/Command.js'
-import { CommandType } from '../../utils/CommandType.js'
 import { Type } from '../../utils/Type.js'
 import { TypeDeserializer } from './TypeDeserializer.js'
 
 export class CommandDeserializer {
+    /**
+     * @param {Int8Array} buffer
+     */
     constructor(buffer) {
         this.buffer = buffer
         this.command = new Command(buffer[0], buffer[10], [])
@@ -24,8 +27,14 @@ export class CommandDeserializer {
         return this.position === this.buffer.length
     }
 
+    /**
+     * @param {number} typeNum
+     * @returns {any}
+     */
     readObject(typeNum) {
-        const type = Object.entries(Type).find((entry) => entry[1] === typeNum)[0]
+        const entry = Object.entries(Type).find((entry) => entry[1] === typeNum)
+        if (!entry) throw new Error('Unknown type number: ' + typeNum)
+        const type = entry[0]
         switch (type) {
             case 'JAVONET_COMMAND':
                 return this.readCommand()

package/lib/core/protocol/CommandSerializer.js

@@ -1,42 +1,73 @@
-import { TypeSerializer } from './TypeSerializer.js';
-import { Command } from '../../utils/Command.js';
-import { RuntimeName } from '../../utils/RuntimeName.js';
+import { TypeSerializer } from './TypeSerializer.js'
+import { ReferencesCache } from '../referenceCache/ReferencesCache.js'
+import { Command } from '../../utils/Command.js'
+import { CommandType } from '../../utils/CommandType.js'
+import { RuntimeName } from '../../utils/RuntimeName.js'
+import { TypesHandler } from '../../utils/TypesHandler.js'
 
+/**
+ * @typedef {import('../../utils/connectionData/IConnectionData.js').IConnectionData} IConnectionData
+ */
 class CommandSerializer {
-    serialize(rootCommand, connectionData) {
+    /**
+     * Serializes the root command with connection data and optional runtime version.
+     * @param {Command} rootCommand
+     * @param {IConnectionData} connectionData
+     * @param {number} runtimeVersion
+     * @returns {Int8Array}
+     */
+    serialize(rootCommand, connectionData, runtimeVersion = 0) {
         const buffers = []
-        // Write runtime name and a zero byte for runtime version.
-        buffers.push(Uint8Array.of(rootCommand.runtimeName, 0))
 
+        // Write runtime name and version
+        buffers.push(Uint8Array.of(rootCommand.runtimeName, runtimeVersion))
+
+        // Write connection data or default zeros
         if (connectionData) {
             buffers.push(connectionData.serializeConnectionData())
         } else {
             buffers.push(Uint8Array.of(0, 0, 0, 0, 0, 0, 0))
         }
 
-        buffers.push(Uint8Array.of(RuntimeName.Nodejs, rootCommand.commandType))
+        // Write target runtime and command type
+        buffers.push(Uint8Array.of(RuntimeName.Python, rootCommand.commandType))
 
+        // Recursively serialize command and its payload
         this.serializeRecursively(rootCommand, buffers)
 
         return concatenateUint8Arrays(buffers)
     }
 
+    /**
+     * Recursively serializes command payload.
+     * @param {Command} command
+     * @param {Array<Uint8Array>} buffers
+     */
     serializeRecursively(command, buffers) {
         for (const item of command.payload) {
             if (item instanceof Command) {
                 buffers.push(TypeSerializer.serializeCommand(item))
                 this.serializeRecursively(item, buffers)
-            } else {
+            } else if (TypesHandler.isPrimitiveOrNullOrUndefined(item)) {
                 buffers.push(TypeSerializer.serializePrimitive(item))
+            } else {
+                const cachedReference = ReferencesCache.getInstance().cacheReference(item)
+                const refCommand = new Command(RuntimeName.Nodejs, CommandType.Reference, cachedReference)
+                buffers.push(TypeSerializer.serializeCommand(refCommand))
+                this.serializeRecursively(refCommand, buffers)
             }
         }
     }
 }
 
+/**
+ * Concatenates multiple Uint8Array buffers into one.
+ * @param {Array<Uint8Array>} arrays
+ * @returns {Uint8Array}
+ */
 function concatenateUint8Arrays(arrays) {
     let totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0)
     const result = new Uint8Array(totalLength)
-
     let offset = 0
     for (const arr of arrays) {
         result.set(arr, offset)

package/lib/core/protocol/TypeDeserializer.js

@@ -1,12 +1,21 @@
+// @ts-check
 import { Command } from '../../utils/Command.js'
 import { Buffer } from 'buffer'
 import { StringEncodingMode } from '../../utils/StringEncodingMode.js'
 
 export class TypeDeserializer {
+    /**
+     * @param {Int8Array} encodedCommand
+     * @returns {Command}
+     */
     static deserializeCommand(encodedCommand) {
         return new Command(encodedCommand[0], encodedCommand[1], [])
     }
 
+    /**
+     * @param {number} stringEncodingMode
+     * @param {Int8Array} encodedString
+     */
     static deserializeString(stringEncodingMode, encodedString) {
         switch (stringEncodingMode) {
             case StringEncodingMode.ASCII:
@@ -33,6 +42,9 @@ export class TypeDeserializer {
         }
     }
 
+    /**
+     * @param {Int8Array} encodedInt
+     */
     static deserializeInt(encodedInt) {
         return (
             (encodedInt[0] & 0xff) |
@@ -42,34 +54,58 @@ export class TypeDeserializer {
         )
     }
 
+    /**
+     * @param {Int8Array} encodedBool
+     */
     static deserializeBool(encodedBool) {
         return encodedBool[0] === 1
     }
 
+    /**
+     * @param {Int8Array} encodedFloat
+     */
     static deserializeFloat(encodedFloat) {
         return Buffer.from(encodedFloat).readFloatLE()
     }
 
+    /**
+     * @param {Int8Array} encodedByte
+     */
     static deserializeByte(encodedByte) {
         return Buffer.from(encodedByte).readUint8()
     }
 
+    /**
+     * @param {Int8Array} encodedChar
+     */
     static deserializeChar(encodedChar) {
         return Buffer.from(encodedChar).readUint8()
     }
 
+    /**
+     * @param {Int8Array} encodedLongLong
+     */
     static deserializeLongLong(encodedLongLong) {
         return Buffer.from(encodedLongLong).readBigInt64LE()
     }
 
+    /**
+     * @param {Int8Array} encodedDouble
+     */
     static deserializeDouble(encodedDouble) {
         return Buffer.from(encodedDouble).readDoubleLE()
     }
 
+    /**
+     * @param {Int8Array} encodedULLong
+     */
     static deserializeULLong(encodedULLong) {
         return Buffer.from(encodedULLong).readBigUInt64LE()
     }
 
+    /**
+     * @param {Int8Array} encodedUInt
+     */
     static deserializeUInt(encodedUInt) {
         return Buffer.from(encodedUInt).readUIntLE(0, 4)
     }

package/lib/core/protocol/TypeSerializer.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { Command } from '../../utils/Command.js'
 import { Type } from '../../utils/Type.js'
 import { StringEncodingMode } from '../../utils/StringEncodingMode.js'
@@ -7,42 +8,66 @@ import { CustomError } from '../../utils/CustomError.js'
 const encoder = new TextEncoder()
 
 class TypeSerializer {
+    /**
+     * @param {unknown} payload_item
+     */
     static serializePrimitive(payload_item) {
         if (payload_item === null) {
             return TypeSerializer.serializeNull()
         }
         if (payload_item instanceof Command) {
             return TypeSerializer.serializeCommand(payload_item)
-        } else if (typeof payload_item === 'number' || payload_item instanceof Number) {
+        } else if (typeof payload_item === 'number') {
             if (Number.isInteger(payload_item)) {
                 return TypeSerializer.serializeInt(payload_item)
             } else {
                 return TypeSerializer.serializeDouble(payload_item)
             }
-        } else if (typeof payload_item === 'string' || payload_item instanceof String) {
+        } else if (typeof payload_item === 'string') {
             return TypeSerializer.serializeString(payload_item)
-        } else if (typeof payload_item === 'boolean' || payload_item instanceof Boolean) {
+        } else if (typeof payload_item === 'boolean') {
             return TypeSerializer.serializeBool(payload_item)
         } else {
             if (payload_item instanceof Promise) {
-                throw new CustomError('Type not supported - Promise', JSON.stringify(payload_item))
+                const message =
+                    'Unsupported payload item type: ' +
+                    (payload_item?.constructor?.name || typeof payload_item) +
+                    ' for payload item: ' +
+                    payload_item
+                throw new CustomError(message, 'JAVONET_PROMISE')
             }
             if (payload_item === undefined) {
-                throw 'Type not supported - undefined'
+                throw Error(
+                    'Unsupported payload item type: ' +
+                        typeof payload_item +
+                        ' for payload item: ' +
+                        payload_item
+                )
             }
-            throw 'Unknown type - not supported in JavaScript'
+            throw Error(
+                'Unsupported payload item type: ' +
+                    (payload_item?.constructor?.name || typeof payload_item) +
+                    ' for payload item: ' +
+                    payload_item
+            )
         }
     }
 
+    /**
+     * @param {Command} command
+     */
     static serializeCommand(command) {
         const buffer = Buffer.alloc(7)
         buffer.writeUInt8(Type.JAVONET_COMMAND, 0)
         buffer.fill(Buffer.from(this.serializeIntValue(command.payload.length)), 1, 5)
-        buffer.writeUInt8(command.runtime, 5)
+        buffer.writeUInt8(command.runtimeName, 5)
         buffer.writeUInt8(command.commandType, 6)
         return buffer
     }
 
+    /**
+     * @param {string} string_value
+     */
     static serializeString(string_value) {
         let bytes = encoder.encode(string_value)
         const buffer = Buffer.alloc(6 + bytes.length)
@@ -53,6 +78,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} int_value
+     */
     static serializeInt(int_value) {
         const buffer = Buffer.alloc(6)
         buffer.writeUInt8(Type.JAVONET_INTEGER, 0)
@@ -61,6 +89,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {boolean} bool_value
+     */
     static serializeBool(bool_value) {
         const buffer = Buffer.alloc(3)
         buffer.writeUInt8(Type.JAVONET_BOOLEAN, 0)
@@ -69,6 +100,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} float_value
+     */
     static serializeFloat(float_value) {
         const buffer = Buffer.alloc(6)
         buffer.writeUInt8(Type.JAVONET_FLOAT, 0)
@@ -77,6 +111,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} byte_value
+     */
     static serializeByte(byte_value) {
         const buffer = Buffer.alloc(3)
         buffer.writeUInt8(Type.JAVONET_BYTE, 0)
@@ -85,6 +122,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} char_value
+     */
     static serializeChar(char_value) {
         const buffer = Buffer.alloc(3)
         buffer.writeUInt8(Type.JAVONET_CHAR, 0)
@@ -93,6 +133,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} longlong_value
+     */
     static serializeLongLong(longlong_value) {
         const buffer = Buffer.alloc(10)
         buffer.writeUInt8(Type.JAVONET_LONG_LONG, 0)
@@ -101,6 +144,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} double_value
+     */
     static serializeDouble(double_value) {
         const buffer = Buffer.alloc(10)
         buffer.writeUInt8(Type.JAVONET_DOUBLE, 0)
@@ -109,6 +155,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {bigint} ullong_value
+     */
     static serializeULLong(ullong_value) {
         const buffer = Buffer.alloc(10)
         buffer.writeUInt8(Type.JAVONET_UNSIGNED_LONG_LONG, 0)
@@ -117,6 +166,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} uint_value
+     */
     static serializeUInt(uint_value) {
         const buffer = Buffer.alloc(6)
         buffer.writeUInt8(Type.JAVONET_UNSIGNED_INTEGER, 0)
@@ -133,6 +185,9 @@ class TypeSerializer {
         return buffer
     }
 
+    /**
+     * @param {number} int_value
+     */
     static serializeIntValue(int_value) {
         const buffer = Buffer.alloc(4)
         buffer.writeInt32LE(int_value, 0)

package/lib/core/receiver/Receiver.js

@@ -1,9 +1,10 @@
+// @ts-check
 import { Interpreter } from '../interpreter/Interpreter.js'
 import { CommandSerializer } from '../protocol/CommandSerializer.js'
 import { getRequire } from '../../utils/Runtime.js'
 import { InMemoryConnectionData } from '../../utils/connectionData/InMemoryConnectionData.js'
 
-/** @type {import('../../utils/RuntimeLogger.js').RuntimeLogger | null} */
+/** @type {typeof import('../../utils/RuntimeLogger.js').RuntimeLogger | null} */
 let _RuntimeLogger = null
 
 const requireDynamic = getRequire(import.meta.url)
@@ -19,7 +20,7 @@ export class Receiver {
     }
 
     /**
-     * @param {number[]} messageByteArray
+     * @param {Int8Array} messageByteArray
      */
     static sendCommand(messageByteArray) {
         return new CommandSerializer().serialize(

package/lib/core/receiver/ReceiverNative.js

@@ -1,13 +1,21 @@
+// @ts-check
 import { Receiver } from './Receiver.js'
 
 export class ReceiverNative {
+    /**
+     * @param {Int8Array} messageByteArray
+     */
     static sendCommand(messageByteArray) {
         return Receiver.sendCommand(messageByteArray)
     }
 
+    /**
+     * @param {Int8Array} messageByteArray
+     */
     static heartBeat(messageByteArray) {
         return Receiver.heartBeat(messageByteArray)
     }
 }
 
+// @ts-expect-error
 global.ReceiverNative = ReceiverNative

package/lib/core/transmitter/Transmitter.js

@@ -1,18 +1,35 @@
+// @ts-check
 import { TransmitterWrapper } from './TransmitterWrapper.js'
 
 export class Transmitter {
+    /**
+     * @param {Int8Array} messageArray
+     * @returns {Int8Array}
+     */
     static sendCommand(messageArray) {
         return TransmitterWrapper.sendCommand(messageArray)
     }
 
-    static activate = function (licenseKey) {
+    /**
+     * @param {string} licenseKey 
+     * @returns {void}
+     */
+    static activate (licenseKey) {
         return TransmitterWrapper.activate(licenseKey)
     }
 
+    /**
+     * @param {string} configSource
+     * @returns {void}
+    */
     static setConfigSource(configSource) {
         return TransmitterWrapper.setConfigSource(configSource)
     }
 
+    /**
+     * @param {string} workingDirectory 
+     * @returns 
+     */
     static setJavonetWorkingDirectory(workingDirectory) {
         return TransmitterWrapper.setJavonetWorkingDirectory(workingDirectory)
     }