javonet-nodejs-sdk 2.1.13 → 2.2.0

package/lib/sdk/internal/RuntimeContext.js

@@ -1,140 +1,246 @@
-const Interpreter = require("../../core/interpreter/Interpreter")
-const Command = require("../../utils/Command")
-const CommandType = require("../../utils/CommandType")
-const InvocationContext = require("./InvocationContext")
+const Interpreter = require("../../core/interpreter/Interpreter");
+const Command = require("../../utils/Command");
+const CommandType = require("../../utils/CommandType");
+const InvocationContext = require("./InvocationContext");
 const ConnectionType = require("../../utils/ConnectionType");
 const GeneratorHandler = require("../../core/generator/handler/GeneratorHandler");
-const ExceptionThrower = require('../../core/exception/ExceptionThrower')
-const homedir = require('os').homedir();
-
-
+const ExceptionThrower = require("../../core/exception/ExceptionThrower");
+const homedir = require("os").homedir();
+
+/**
+ * Represents a single context which allows interaction with a selected technology.
+ * Refers to a single instance of the called runtime within a particular target OS process.
+ * This can be either the local currently running process (inMemory) or a particular remote process identified by the IP Address and PORT of the target Javonet instance.
+ * Multiple Runtime Contexts can be initialized within one process.
+ * Calling the same technology on inMemory communication channel will return the existing instance of runtime context.
+ * Calling the same technology on TCP channel but on different nodes will result in unique Runtime Contexts.
+ * Within the runtime context, any number of libraries can be loaded and any objects from the target technology can be interacted with, as they are aware of each other due to sharing the same memory space and same runtime instance.
+ * @see [Javonet Guides]{@link https://www.javonet.com/guides/v2/javascript/foundations/runtime-context}
+ * @class
+ */
 class RuntimeContext {
-    static memoryRuntimeContexts = new Map();
-    static networkRuntimeContexts = new Map();
-    #currentCommand
-    #responseCommand
-    #interpreter
-    #generatorHandler
-
-
-    constructor(runtimeName, connectionType, tcpConnectionData = null) {
-        this.runtimeName = runtimeName
-        this.connectionType = connectionType
-        this.tcpConnectionData = tcpConnectionData
-        this.#currentCommand = null
-        this.#responseCommand = null
-        this.#interpreter = new Interpreter()
-        this.#generatorHandler = new GeneratorHandler();
-    }
-
-    static getInstance(runtime, connectionType, tcpConnectionData = null) {
-        if ((ConnectionType.TCP === connectionType) && tcpConnectionData != null) {
-            if (RuntimeContext.networkRuntimeContexts.has(tcpConnectionData)) {
-                const runtimeCtx = RuntimeContext.networkRuntimeContexts.get(tcpConnectionData)
-                runtime.command = null;
-                return runtimeCtx;
-            } else {
-                const runtimeCtx = new RuntimeContext(runtime, connectionType, tcpConnectionData)
-                RuntimeContext.networkRuntimeContexts.set(tcpConnectionData, runtimeCtx)
-                return runtimeCtx
-            }
-        } else {
-            if (RuntimeContext.memoryRuntimeContexts.has(runtime)) {
-                const runtimeCtx = this.memoryRuntimeContexts.get(runtime)
-                runtimeCtx.command = null;
-                return runtimeCtx;
-            } else {
-                const runtimeCtx = new RuntimeContext(runtime, connectionType)
-                RuntimeContext.networkRuntimeContexts.set(runtime, runtimeCtx)
-                return runtimeCtx
-            }
-        }
-    }
-
-    execute() {
-        this.#responseCommand = this.#interpreter.execute(this.#currentCommand, this.connectionType, this.tcpConnectionData)
-        this.#currentCommand = null
-        if (this.#responseCommand.commandType === CommandType.Exception) {
-            throw ExceptionThrower.throwException(this.#responseCommand)
-        }
+  static memoryRuntimeContexts = new Map();
+  static networkRuntimeContexts = new Map();
+  #currentCommand;
+  #responseCommand;
+  #interpreter;
+  #generatorHandler;
+
+  constructor(runtimeName, connectionType, tcpConnectionData = null) {
+    this.runtimeName = runtimeName;
+    this.connectionType = connectionType;
+    this.tcpConnectionData = tcpConnectionData;
+    this.#currentCommand = null;
+    this.#responseCommand = null;
+    this.#interpreter = new Interpreter();
+    this.#generatorHandler = new GeneratorHandler();
+  }
+
+  static getInstance(runtime, connectionType, tcpConnectionData = null) {
+    if (ConnectionType.TCP === connectionType && tcpConnectionData != null) {
+      if (RuntimeContext.networkRuntimeContexts.has(tcpConnectionData)) {
+        const runtimeCtx =
+            RuntimeContext.networkRuntimeContexts.get(tcpConnectionData);
+        runtime.command = null;
+        return runtimeCtx;
+      } else {
+        const runtimeCtx = new RuntimeContext(
+            runtime,
+            connectionType,
+            tcpConnectionData
+        );
+        RuntimeContext.networkRuntimeContexts.set(
+            tcpConnectionData,
+            runtimeCtx
+        );
+        return runtimeCtx;
+      }
+    } else {
+      if (RuntimeContext.memoryRuntimeContexts.has(runtime)) {
+        const runtimeCtx = this.memoryRuntimeContexts.get(runtime);
+        runtimeCtx.command = null;
+        return runtimeCtx;
+      } else {
+        const runtimeCtx = new RuntimeContext(runtime, connectionType);
+        RuntimeContext.networkRuntimeContexts.set(runtime, runtimeCtx);
+        return runtimeCtx;
+      }
     }
-
-    loadLibrary(...args) {
-        let localCommand = new Command(this.runtimeName, CommandType.LoadLibrary, args)
-        this.#currentCommand = this.#buildCommand(localCommand)
-        this.execute()
-        return this
+  }
+
+  /**
+   * Executes the current command. The initial state of RuntimeContext is non-materialized,
+   * wrapping either a single command or a chain of recursively nested commands.
+   * Commands become nested through each invocation of methods on RuntimeContext.
+   * Each invocation triggers the creation of a new RuntimeContext instance wrapping the current command with a new parent command.
+   * The developer can decide at any moment of the materialization for the context, taking full control of the chunks of the expression being transferred and processed on the target runtime.
+   * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/execute-method)
+   * @method
+   */
+  execute() {
+    this.#responseCommand = this.#interpreter.execute(
+        this.#currentCommand,
+        this.connectionType,
+        this.tcpConnectionData
+    );
+    this.#currentCommand = null;
+    if (this.#responseCommand.commandType === CommandType.Exception) {
+      throw ExceptionThrower.throwException(this.#responseCommand);
     }
-
-    getType(...args) {
-        let localCommand = new Command(this.runtimeName, CommandType.GetType, args)
-        this.#currentCommand = null
-        return new InvocationContext(this.runtimeName, this.connectionType, this.tcpConnectionData, this.#buildCommand(localCommand))
+  }
+
+  /**
+   * Adds a reference to a library. Javonet allows you to reference and use modules or packages written in various languages.
+   * This method allows you to use any library from all supported technologies. The necessary libraries need to be referenced.
+   * The argument is a relative or full path to the library. If the library has dependencies on other libraries, the latter needs to be added first.
+   * After referencing the library, any objects stored in this package can be used. Use static classes, create instances, call methods, use fields and properties, and much more.
+   * @param {string} libraryPath - The relative or full path to the library.
+   * @returns {RuntimeContext} RuntimeContext instance.
+   * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/getting-started/adding-references-to-libraries)
+   * @method
+   */
+  loadLibrary(libraryPath) {
+    let localCommand = new Command(
+        this.runtimeName,
+        CommandType.LoadLibrary,
+        [libraryPath]
+    );
+    this.#currentCommand = this.#buildCommand(localCommand);
+    this.execute();
+    return this;
+  }
+
+  /**
+   * Retrieves a reference to a specific type. The type can be a class, interface or enum. The type can be retrieved from any referenced library.
+   * @param {string} typeName - The full name of the type.
+   * @param {...any} args - The arguments to be passed, if needed
+   * @returns {InvocationContext} InvocationContext instance, that wraps the command to get the type.
+   * @method
+   */
+  getType(typeName, ...args) {
+    let localCommand = new Command(this.runtimeName, CommandType.GetType, [typeName, ...args]);
+    this.#currentCommand = null;
+    return new InvocationContext(
+        this.runtimeName,
+        this.connectionType,
+        this.tcpConnectionData,
+        this.#buildCommand(localCommand)
+    );
+  }
+
+  /**
+   * Casts the provided value to a specific type. This method is used when invoking methods that require specific types of arguments.
+   * The arguments include the target type and the value to be cast. The target type must be retrieved from the called runtime using the getType method.
+   * After casting the value, it can be used as an argument when invoking methods.
+   * @param {...any} args - The target type and the value to be cast.
+   * @returns {InvocationContext} InvocationContext instance that wraps the command to cast the value.
+   * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/casting/casting)
+   * @method
+   */
+  cast(...args) {
+    let localCommand = new Command(this.runtimeName, CommandType.Cast, args);
+    this.#currentCommand = null;
+    return new InvocationContext(
+        this.runtimeName,
+        this.connectionType,
+        this.tcpConnectionData,
+        this.#buildCommand(localCommand)
+    );
+  }
+
+  /**
+   * Retrieves a specific item from an enum type. This method is used when working with enums from the called runtime.
+   * The arguments include the enum type and the name of the item. The enum type must be retrieved from the called runtime using the getType method.
+   * After retrieving the item, it can be used as an argument when invoking methods or for other operations.
+   * @param {...any} args - The enum type and the name of the item.
+   * @returns {InvocationContext} InvocationContext instance that wraps the command to get the enum item.
+   * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/enums/using-enum-type)
+   * @method
+   */
+  getEnumItem(...args) {
+    let localCommand = new Command(
+        this.runtimeName,
+        CommandType.GetEnumItem,
+        args
+    );
+    this.#currentCommand = null;
+    return new InvocationContext(
+        this.runtimeName,
+        this.connectionType,
+        this.tcpConnectionData,
+        this.#buildCommand(localCommand)
+    );
+  }
+
+  /**
+   * Creates a reference type argument that can be passed to a method with a ref parameter modifier. This method is used when working with methods from the called runtime that require arguments to be passed by reference.
+   * The arguments include the value and optionally the type of the reference. The type must be retrieved from the called runtime using the getType method.
+   * After creating the reference, it can be used as an argument when invoking methods.
+   * @param {...any} args - The value and optionally the type of the reference.
+   * @returns {InvocationContext} InvocationContext instance that wraps the command to create a reference as ref.
+   * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/methods-arguments/passing-arguments-by-reference-with-ref-keyword)
+   * @method
+   */
+  asRef(...args) {
+    let localCommand = new Command(this.runtimeName, CommandType.AsRef, args);
+    this.#currentCommand = null;
+    return new InvocationContext(
+        this.runtimeName,
+        this.connectionType,
+        this.tcpConnectionData,
+        this.#buildCommand(localCommand)
+    );
+  }
+
+  /**
+   * Creates a reference type argument that can be passed to a method with an out parameter modifier. This method is used when working with methods from the called runtime that require arguments to be passed by reference.
+   * The arguments include the value and optionally the type of the reference. The type must be retrieved from the called runtime using the getType method.
+   * After creating the reference, it can be used as an argument when invoking methods.
+   * @param {...any} args - The value and optionally the type of the reference.
+   * @returns {InvocationContext} InvocationContext instance that wraps the command to create a reference as out.
+   * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/methods-arguments/passing-arguments-by-reference-with-out-keyword |Passing Arguments by Reference with out Keyword Guide)
+   * @method
+   */
+  asOut(...args) {
+    let localCommand = new Command(this.runtimeName, CommandType.AsOut, args);
+    this.#currentCommand = null;
+    return new InvocationContext(
+        this.runtimeName,
+        this.connectionType,
+        this.tcpConnectionData,
+        this.#buildCommand(localCommand)
+    );
+  }
+
+  #buildCommand = function (command) {
+    for (let i = 0; i < command.payload.length; i++) {
+      command.payload[i] = this.#encapsulatePayloadItem(command.payload[i]);
     }
-
-    cast(...args) {
-        let localCommand = new Command(this.runtimeName, CommandType.Cast, args)
-        this.#currentCommand = null
-        return new InvocationContext(this.runtimeName, this.connectionType, this.tcpConnectionData, this.#buildCommand(localCommand))
-    }
-
-    getEnumItem(...args) {
-        let localCommand = new Command(this.runtimeName, CommandType.GetEnumItem, args)
-        this.#currentCommand = null
-        return new InvocationContext(this.runtimeName, this.connectionType, this.tcpConnectionData, this.#buildCommand(localCommand))
-    }
-
-    invokeGlobalMethod(...args) {
-        let localCommand = new Command(this.runtimeName, CommandType.InvokeGlobalMethod, args)
-        this.#currentCommand = null
-        return new InvocationContext(this.runtimeName, this.connectionType, this.tcpConnectionData, this.#buildCommand(localCommand))
-    }
-
-    generateLibrary(...args) {
-        let cmd = new Command(this.runtimeName, CommandType.GenerateLib, args)
-        this.execute(cmd);
-        this.#generatorHandler.generate(this.command, homedir);
-        return this;
-    }
-
-    asRef(...args) {
-        let localCommand = new Command(this.runtimeName, CommandType.AsRef, args)
-        this.#currentCommand = null
-        return new InvocationContext(this.runtimeName, this.connectionType, this.tcpConnectionData, this.#buildCommand(localCommand))
-    }
-
-    asOut(...args) {
-        let localCommand = new Command(this.runtimeName, CommandType.AsOut, args)
-        this.#currentCommand = null
-        return new InvocationContext(this.runtimeName, this.connectionType, this.tcpConnectionData, this.#buildCommand(localCommand))
-    }
-
-
-    #buildCommand = function (command) {
-        for (let i = 0; i < command.payload.length; i++) {
-            command.payload[i] = this.#encapsulatePayloadItem(command.payload[i])
-        }
-        return command.prependArgToPayload(this.#currentCommand)
-    }
-
-    #encapsulatePayloadItem = function (payloadItem) {
-        if (typeof (payloadItem) === 'Command' || payloadItem instanceof Command) {
-            for (let i = 0; i < payloadItem.payload.length; i++) {
-                payloadItem.payload[i] = this.#encapsulatePayloadItem(payloadItem.payload[i])
-            }
-            return payloadItem
-        } else if (typeof (payloadItem) === 'InvocationContext' || payloadItem instanceof InvocationContext) {
-            return payloadItem.get_current_command()
-        } else if (payloadItem instanceof Array) {
-            for (let i = 0; i < payloadItem.length; i++) {
-                payloadItem[i] = this.#encapsulatePayloadItem(payloadItem[i])
-            }
-            return new Command(this.runtimeName, CommandType.Array, payloadItem)
-        } else {
-            return new Command(this.runtimeName, CommandType.Value, [payloadItem])
-        }
+    return command.prependArgToPayload(this.#currentCommand);
+  };
+
+  #encapsulatePayloadItem = function (payloadItem) {
+    if (typeof payloadItem === "Command" || payloadItem instanceof Command) {
+      for (let i = 0; i < payloadItem.payload.length; i++) {
+        payloadItem.payload[i] = this.#encapsulatePayloadItem(
+            payloadItem.payload[i]
+        );
+      }
+      return payloadItem;
+    } else if (
+        typeof payloadItem === "InvocationContext" ||
+        payloadItem instanceof InvocationContext
+    ) {
+      return payloadItem.get_current_command();
+    } else if (payloadItem instanceof Array) {
+      for (let i = 0; i < payloadItem.length; i++) {
+        payloadItem[i] = this.#encapsulatePayloadItem(payloadItem[i]);
+      }
+      return new Command(this.runtimeName, CommandType.Array, payloadItem);
+    } else {
+      return new Command(this.runtimeName, CommandType.Value, [payloadItem]);
     }
+  };
 }
 
-
-module.exports = RuntimeContext
+module.exports = RuntimeContext;

package/lib/sdk/internal/RuntimeFactory.js

@@ -1,40 +1,76 @@
 const Runtime = require("../../utils/RuntimeName")
 const RuntimeContext = require("./RuntimeContext")
 
+/**
+ * The RuntimeFactory class provides methods for creating runtime contexts.
+ * Each method corresponds to a specific runtime (CLR, JVM, .NET Core, Perl, Ruby, Node.js, Python) and returns a RuntimeContext instance for that runtime.
+ * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+ */
 class RuntimeFactory {
     constructor(connectionType, tcpConnectionData = null) {
         this.connectionType = connectionType
         this.tcpConnectionData = tcpConnectionData
     }
 
+    /**
+     * Creates RuntimeContext instance to interact with the .NET Framework runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the .NET Framework runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
     clr() {
         return RuntimeContext.getInstance(Runtime.Clr, this.connectionType, this.tcpConnectionData)
     }
 
-    go() {
-        return RuntimeContext.getInstance(Runtime.Go, this.connectionType, this.tcpConnectionData)
-    }
-
+    /**
+     * Creates RuntimeContext instance to interact with the JVM runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the JVM runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
     jvm() {
         return RuntimeContext.getInstance(Runtime.Jvm, this.connectionType, this.tcpConnectionData)
     }
 
+    /**
+     * Creates RuntimeContext instance to interact with the .NET runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the .NET runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
     netcore() {
         return RuntimeContext.getInstance(Runtime.Netcore, this.connectionType, this.tcpConnectionData)
     }
 
+    /**
+     * Creates RuntimeContext instance to interact with the Perl runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the Perl runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
     perl() {
         return RuntimeContext.getInstance(Runtime.Perl, this.connectionType, this.tcpConnectionData)
     }
 
+    /**
+     * Creates RuntimeContext instance to interact with the Python runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the Python runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
     python() {
         return RuntimeContext.getInstance(Runtime.Python, this.connectionType, this.tcpConnectionData)
     }
 
+    /**
+     * Creates RuntimeContext instance to interact with the Ruby runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the Ruby runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
     ruby() {
         return RuntimeContext.getInstance(Runtime.Ruby, this.connectionType, this.tcpConnectionData)
     }
 
+    /**
+     * Creates RuntimeContext instance to interact with Node.js runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the Node.js runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
     nodejs() {
         return RuntimeContext.getInstance(Runtime.Nodejs, this.connectionType, this.tcpConnectionData)
     }

package/lib/utils/RuntimeName.js

@@ -6,5 +6,6 @@ module.exports = {
     Perl: 4,
     Python: 5,
     Ruby: 6,
-    Nodejs: 7
+    Nodejs: 7,
+    Cpp: 8
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javonet-nodejs-sdk",
-  "version": "2.1.13",
+  "version": "2.2.0",
   "description": "Javonet SDK for NodeJS",
   "main": "lib/Javonet.js",
   "keywords": [],

package/Binaries/Perl/Linux/X64/deps/lib/perl5/x86_64-linux-gnu-thread-multi/.meta/Devel-StackTrace-2.04/install.json

@@ -1 +0,0 @@
-{"provides":{"Devel::StackTrace::Frame":{"version":"2.04","file":"lib/Devel/StackTrace/Frame.pm"},"Devel::StackTrace":{"file":"lib/Devel/StackTrace.pm","version":"2.04"}},"dist":"Devel-StackTrace-2.04","name":"Devel::StackTrace","target":"Devel::StackTrace","pathname":"D/DR/DROLSKY/Devel-StackTrace-2.04.tar.gz","version":"2.04"}