javonet-nodejs-sdk 2.6.7 → 2.6.9

package/dist/types/core/interpreter/Interpreter.d.ts

@@ -7,9 +7,9 @@ export class Interpreter {
      *
      * @param {Command} command
      * @param {IConnectionData} connectionData
-     * @returns {Command | Promise<Command>}
+     * @returns {Promise<Command>}
      */
-    execute(command: Command, connectionData: IConnectionData): Command | Promise<Command>;
+    execute(command: Command, connectionData: IConnectionData): Promise<Command>;
     /**
      *
      * @param {Uint8Array} messageByteArray

package/dist/types/core/protocol/CommandSerializer.d.ts

@@ -5,12 +5,12 @@ export type IConnectionData = import("../../utils/connectionData/IConnectionData
 export class CommandSerializer {
     /**
      * Serializes the root command with connection data and optional runtime version.
-     * @param {Promise<Command> | Command} rootCommand
+     * @param {Command} rootCommand
      * @param {IConnectionData} connectionData
      * @param {number} runtimeVersion
-     * @returns {Promise<Uint8Array> | Uint8Array}
+     * @returns {Uint8Array}
      */
-    serialize(rootCommand: Promise<Command> | Command, connectionData: IConnectionData, runtimeVersion?: number): Promise<Uint8Array> | Uint8Array;
+    serialize(rootCommand: Command, connectionData: IConnectionData, runtimeVersion?: number): Uint8Array;
     /**
      * Recursively serializes command payload.
      * @param {Command} command

package/dist/types/core/receiver/Receiver.d.ts

@@ -3,14 +3,14 @@ export class Receiver {
     static getRuntimeInfo(): string;
     /**
      * @param {Uint8Array} messageByteArray
-     * @returns {Promise<Uint8Array> | Uint8Array}
+     * @returns {Promise<Uint8Array>}
      */
-    static sendCommand(messageByteArray: Uint8Array): Promise<Uint8Array> | Uint8Array;
+    static sendCommand(messageByteArray: Uint8Array): Promise<Uint8Array>;
     /**
      * @param {Uint8Array} messageByteArray
-     * @returns {Promise<Uint8Array> | Uint8Array}
+     * @returns {Promise<Uint8Array>}
      */
-    static heartBeat(messageByteArray: Uint8Array): Promise<Uint8Array> | Uint8Array;
+    static heartBeat(messageByteArray: Uint8Array): Promise<Uint8Array>;
     Receiver(): void;
 }
 import { InMemoryConnectionData } from '../../utils/connectionData/InMemoryConnectionData.js';

package/dist/types/sdk/Activator.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Details for activating a type with constructor arguments
+ */
+export class Activator {
+    /**
+     * Create a new instance of a type
+     * @param {Function} Type - The constructor function/class
+     * @param {any[] | any} args - The arguments to pass to the constructor
+     * @returns {any} The new instance
+     */
+    static createInstance(Type: Function, args: any[] | any): any;
+}

package/dist/types/sdk/ActivatorDetails.d.ts

@@ -4,9 +4,11 @@
 export class ActivatorDetails {
     /**
      * @param {Function} type - The constructor function/class
-     * @param {any[]} [args] - Arguments to pass to constructor
+     * @param {any[]|any} [args] - Arguments to pass to constructor (array or single value)
      */
-    constructor(type: Function, args?: any[]);
-    type: Function;
+    constructor(type: Function, args?: any[] | any);
+    /** @type {Function} */
+    Type: Function;
+    /** @type {any[]} */
     arguments: any[];
 }

package/dist/types/sdk/ConfigRuntimeFactory.d.ts

@@ -65,6 +65,13 @@ export class ConfigRuntimeFactory {
      * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
      */
     nodejs(configName?: string): RuntimeContext;
+    /**
+     * Creates RuntimeContext instance to interact with the Php runtime.
+     * @param {string} [configName="default"] - The name of the configuration to use (optional).
+     * @return {RuntimeContext} a RuntimeContext instance for the Php runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
+    php(configName?: string): RuntimeContext;
     /**
      * Creates RuntimeContext instance to interact with the Python 2.7 runtime.
      * @param {string} [configName="default"] - The name of the configuration to use (optional).

package/dist/types/sdk/InvocationContext.d.ts

@@ -12,6 +12,7 @@ export type IConnectionData = import("../utils/connectionData/IConnectionData.js
  * @class
  */
 export class InvocationContext {
+    static _invocationContexts: Map<any, any>;
     /**
      *
      * @param {RuntimeNameType} runtimeName
@@ -20,22 +21,21 @@ export class InvocationContext {
      * @param {boolean} isExecuted
      */
     constructor(runtimeName: RuntimeNameType, connectionData: IConnectionData, command: Command, isExecuted?: boolean);
+    /**
+     * @returns {string} guid of this InvocationContext
+     */
+    getGuid(): string;
     /**
      * @returns {Command|null}
      */
     get_current_command(): Command | null;
     /**
      * Executes the current command.
-     * Because invocation context is building the intent of executing particular expression on target environment, we call the initial state of invocation context as non-materialized.
-     * The non-materialized context wraps either single command or chain of recursively nested commands.
-     * Commands are becoming nested through each invocation of methods on Invocation Context.
-     * Each invocation triggers the creation of new Invocation Context instance wrapping the current command with new parent command valid for invoked method.
-     * Developer can decide on any moment of the materialization for the context taking full control of the chunks of the expression being transferred and processed on target runtime.
-     * @returns {Promise<InvocationContext> | InvocationContext} the InvocationContext after executing the command.
-     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/execute-method)
+     * Returns the InvocationContext after executing the command.
+     * @returns {Promise<InvocationContext>}
      * @method
      */
-    execute(): Promise<InvocationContext> | InvocationContext;
+    execute(): Promise<InvocationContext>;
     /**
      * Invokes a static method on the target runtime.
      * @param {string} methodName - The name of the method to invoke.
@@ -64,9 +64,10 @@ export class InvocationContext {
     setStaticField(fieldName: string, value: any): InvocationContext;
     /**
      * Creates a new instance of a class in the target runtime.
+     * Adds the newly created context to the static invocation contexts map and
+     * includes the context GUID as the first argument of CreateClassInstance command payload.
      * @param {...any} args - The arguments to pass to the class constructor
      * @returns {InvocationContext} A new InvocationContext instance that wraps the command to create the instance.
-     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/calling-methods/creating-instance-and-calling-instance-methods)
      * @method
      */
     createInstance(...args: any[]): InvocationContext;
@@ -196,11 +197,11 @@ export class InvocationContext {
     getInstanceMethodAsDelegate(methodName: string, ...args: any[]): InvocationContext;
     /**
      * Retrieves the type of the object from the target runtime.
-     * @returns {Promise<string> | string} The type of the object.
+     * @returns {Promise<string>} The type of the object.
      * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/type-handling/getting-object-type)
      * @method
      */
-    getResultType(): Promise<string> | string;
+    getResultType(): Promise<string>;
     /**
      * Retrieves the name of the runtime where the command is executed.
      * @returns {number} The name of the runtime.
@@ -210,6 +211,7 @@ export class InvocationContext {
     getRuntimeName(): number;
     /**
      * Retrieves an array from the target runtime.
+     * @async
      * @returns {Promise<any[]>}
      * @method
      */
@@ -222,12 +224,12 @@ export class InvocationContext {
      * @method
      */
     getValue(): unknown;
-    [Symbol.iterator]: () => {
-        next: () => {
-            value: InvocationContext;
-            done: boolean;
-        };
-    };
+    /**
+     * Async iterator for InvocationContext arrays
+     * Use: for await (const item of invocationContext) { ... }
+     * @returns {AsyncGenerator<InvocationContext, void, unknown>}
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<InvocationContext, void, unknown>;
     #private;
 }
 import { Command } from '../utils/Command.js';

package/dist/types/sdk/Javonet.d.ts

@@ -77,7 +77,8 @@ import { WsConnectionData } from '../utils/connectionData/WsConnectionData.js';
 import { CommandSerializer } from '../core/protocol/CommandSerializer.js';
 import { CommandDeserializer } from '../core/protocol/CommandDeserializer.js';
 import { ConfigPriority } from './configuration/ConfigPriority.js';
+import { ComplexTypeResolver } from './tools/ComplexTypeResolver.js';
 import { RuntimeFactory } from './RuntimeFactory.js';
 import { ConfigRuntimeFactory } from './ConfigRuntimeFactory.js';
 import { RuntimeContext } from './RuntimeContext.js';
-export { TcpConnectionData, WsConnectionData, CommandSerializer, CommandDeserializer, ConfigPriority };
+export { TcpConnectionData, WsConnectionData, CommandSerializer, CommandDeserializer, ConfigPriority, ComplexTypeResolver };

package/dist/types/sdk/RuntimeContext.d.ts

@@ -40,20 +40,21 @@ export class 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)
+     * @returns {Promise<void>}
      * @method
      */
-    execute(): void;
+    execute(): Promise<void>;
     /**
      * 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.
+     * @returns {Promise<RuntimeContext>} RuntimeContext instance.
      * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/getting-started/adding-references-to-libraries)
      * @method
      */
-    loadLibrary(libraryPath: string): RuntimeContext;
+    loadLibrary(libraryPath: string): Promise<RuntimeContext>;
     /**
      * 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.

package/dist/types/sdk/configuration/ConfigSourceResolver.d.ts

@@ -1,7 +1,24 @@
 export class ConfigSourceResolver {
-    static addConfigs(priority: any, configSource: any): void;
-    static getConfig(configName: any): any;
+    /**
+     * @param {import('./ConfigPriority.js').ConfigPriority} priority
+     * @param {string | any} configSource
+     */
+    static addConfigs(priority: any, configSource: string | any): void;
+    /**
+     * @param {string} configName
+     * @returns {*}
+     */
+    static getConfig(configName: string): any;
     static clearConfigs(): void;
-    static _getConfigSourceAsString(configSource: any): any;
-    static _parseConfigsAndAddToCollection(priority: any, configString: any): void;
+    /**
+     * @param {string} configSource
+     * @returns {string}
+     */
+    static _getConfigSourceAsString(configSource: string): string;
+    /**
+     * @param {import('./ConfigPriority.js').ConfigPriority} priority
+     * @param {string} configString
+     * @returns
+     */
+    static _parseConfigsAndAddToCollection(priority: any, configString: string): void;
 }

package/dist/types/sdk/tools/ComplexTypeResolver.d.ts

@@ -1,7 +1,4 @@
 export type RuntimeName = import("../../types.d.ts").RuntimeName;
-/**
- * @typedef {import('../../types.d.ts').RuntimeName} RuntimeName
- */
 export class ComplexTypeResolver {
     /**
      * Resolve type from string name and optional module
@@ -10,6 +7,19 @@ export class ComplexTypeResolver {
      * @returns {Function} The resolved type/constructor function
      */
     static resolveType(typeName: string, moduleName?: string): Function;
+    /**
+     * Attempts to extract the underlying element type from an array type string
+     * @param {string} type - The type string to parse (e.g., "MyType[]")
+     * @returns {string | null} Object indicating success and the element type
+     * @throws {Error} If the array element type is a primitive type
+     */
+    static tryGetUnderlyingArrayType(type: string): string | null;
+    /**
+     * @param {RuntimeName} runtimeName
+     * @param {string} resultType
+     * @returns {any}
+     */
+    static tryGetTypeParsingFunction(runtimeName: RuntimeName, resultType: string): any;
     /**
      * Register a custom type mapping
      * @param {string} resultType - The type name from the target runtime
@@ -20,9 +30,15 @@ export class ComplexTypeResolver {
     /**
      * Convert InvocationContext result to appropriate JavaScript type
      * @param {InvocationContext} ic - The invocation context
-     * @returns {Promise<any> | any} The converted result
+     * @returns {Promise<any>} The converted result
+     */
+    convertResult(ic: InvocationContext): Promise<any>;
+    /**
+     * @param {string} resultType
+     * @returns {ActivatorDetails | null}
      */
-    convertResult(ic: InvocationContext): Promise<any> | any;
+    tryGetValueFromTypeMap(resultType: string): ActivatorDetails | null;
     #private;
 }
 import { InvocationContext } from '../InvocationContext.js';
+import { ActivatorDetails } from '../ActivatorDetails.js';

package/dist/types/utils/CommandType.d.ts

@@ -47,4 +47,5 @@ export namespace CommandType {
     let AsKwargs: 45;
     let GetResultType: 46;
     let GetGlobalField: 47;
+    let UpdateInvocationContext: 48;
 }

package/dist/types/utils/Primitives.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Set of primitive type names that are not supported as array element types
+ * @type {Set<string>}
+ */
+export const PrimitiveSet: Set<string>;

package/dist/utils/CommandType.cjs

@@ -71,7 +71,8 @@ const CommandType = (
     GetAsyncOperationResult: 44,
     AsKwargs: 45,
     GetResultType: 46,
-    GetGlobalField: 47
+    GetGlobalField: 47,
+    UpdateInvocationContext: 48
   }
 );
 // Annotate the CommonJS export names for ESM import in node:

package/dist/utils/Primitives.cjs

@@ -0,0 +1,201 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Primitives_exports = {};
+__export(Primitives_exports, {
+  PrimitiveSet: () => PrimitiveSet
+});
+module.exports = __toCommonJS(Primitives_exports);
+const PrimitiveSet = new Set(
+  [
+    // --- JavaScript / TypeScript ---
+    "string",
+    "number",
+    "boolean",
+    "bigint",
+    "symbol",
+    "undefined",
+    "null",
+    // --- .NET / C# ---
+    "bool",
+    "boolean",
+    "byte",
+    "sbyte",
+    "char",
+    "decimal",
+    "double",
+    "float",
+    "single",
+    "int",
+    "int32",
+    "uint",
+    "uint32",
+    "long",
+    "int64",
+    "ulong",
+    "uint64",
+    "short",
+    "int16",
+    "ushort",
+    "uint16",
+    "object",
+    "string",
+    "system.boolean",
+    "system.byte",
+    "system.sbyte",
+    "system.char",
+    "system.decimal",
+    "system.double",
+    "system.single",
+    "system.int",
+    "system.int32",
+    "system.uint",
+    "system.uint32",
+    "system.int64",
+    "system.uint64",
+    "system.int16",
+    "system.uint16",
+    "system.object",
+    "system.string",
+    // --- Java ---
+    "byte",
+    "short",
+    "int",
+    "long",
+    "float",
+    "double",
+    "char",
+    "boolean",
+    "java.lang.string",
+    // --- Python ---
+    "str",
+    "int",
+    "float",
+    "bool",
+    "bytes",
+    "bytearray",
+    // --- Go ---
+    "rune",
+    "byte",
+    "bool",
+    "string",
+    "int",
+    "int8",
+    "int16",
+    "int32",
+    "int64",
+    "uint",
+    "uint8",
+    "uint16",
+    "uint32",
+    "uint64",
+    "float32",
+    "float64",
+    // --- C / C++ ---
+    "char",
+    "short",
+    "int",
+    "long",
+    "float",
+    "double",
+    "signed char",
+    "unsigned char",
+    "unsigned short",
+    "unsigned int",
+    "unsigned long",
+    // --- Rust ---
+    "bool",
+    "u8",
+    "i8",
+    "u16",
+    "i16",
+    "u32",
+    "i32",
+    "u64",
+    "i64",
+    "f32",
+    "f64",
+    "usize",
+    "isize",
+    "str",
+    // --- Kotlin ---
+    "boolean",
+    "byte",
+    "short",
+    "int",
+    "long",
+    "float",
+    "double",
+    "char",
+    "string",
+    // --- Swift ---
+    "bool",
+    "int",
+    "uint",
+    "float",
+    "double",
+    "string",
+    "character",
+    // --- PHP ---
+    "int",
+    "integer",
+    "float",
+    "double",
+    "string",
+    "bool",
+    "boolean",
+    "mixed",
+    // --- Ruby ---
+    "string",
+    "integer",
+    "fixnum",
+    "float",
+    "symbol",
+    "boolean",
+    // --- Dart ---
+    "int",
+    "double",
+    "num",
+    "bool",
+    "string",
+    // --- Scala ---
+    "int",
+    "long",
+    "double",
+    "float",
+    "char",
+    "boolean",
+    "string",
+    // --- Haskell ---
+    "int",
+    "float",
+    "double",
+    "char",
+    "bool",
+    "integer",
+    // --- Generic aliases ---
+    "text",
+    "primitive",
+    "any",
+    "void"
+  ].map((x) => x.toLowerCase())
+);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PrimitiveSet
+});

package/lib/core/handler/CreateClassInstanceHandler.js

@@ -8,10 +8,28 @@ import { AbstractHandler } from './AbstractHandler.js'
 class CreateClassInstanceHandler extends AbstractHandler {
     requiredParametersCount = 1
 
+    // Add a simple invocation contexts store (Map GUID -> object)
+    static _invocationContexts = new Map()
+
+    static getOrCreateContextDictionary() {
+        // In a simple approach we keep a single map for the process.
+        return CreateClassInstanceHandler._invocationContexts
+    }
+
     constructor() {
         super()
     }
 
+    // Helper to detect GUID in payload (standard format)
+    /**
+     * @param {{ toString: () => any; } | null} value
+     */
+    static isGuid(value) {
+        if (value == null) return false
+        const s = value.toString()
+        return /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(s)
+    }
+
     /**
      * @param {Command} command
      */
@@ -20,8 +38,29 @@ class CreateClassInstanceHandler extends AbstractHandler {
             if (command.payload.length < this.requiredParametersCount) {
                 throw new Error('Create Class Instance parameters mismatch')
             }
+
             let clazz = command.payload[0]
-            let constructorArguments = command.payload.slice(1)
+
+            // Extract optional GUID and constructor arguments
+            let payloadLength = command.payload.length
+            let contextGuid = null
+            let constructorArguments = []
+
+            if (payloadLength > 1 && CreateClassInstanceHandler.isGuid(command.payload[1])) {
+                contextGuid = command.payload[1].toString()
+                if (payloadLength > 2) {
+                    constructorArguments = command.payload.slice(2)
+                } else {
+                    constructorArguments = []
+                }
+            } else {
+                if (payloadLength > 1) {
+                    constructorArguments = command.payload.slice(1)
+                } else {
+                    constructorArguments = []
+                }
+            }
+
             let instance = new clazz(...constructorArguments)
             if (typeof instance === 'undefined') {
                 let methods = Object.getOwnPropertyNames(clazz).filter(function (property) {
@@ -33,6 +72,12 @@ class CreateClassInstanceHandler extends AbstractHandler {
                 })
                 throw new Error(message)
             } else {
+                // If GUID provided, store instance in context dictionary
+                if (contextGuid) {
+                    const contextDict = CreateClassInstanceHandler.getOrCreateContextDictionary()
+                    // Overwrite or add entry
+                    contextDict.set(contextGuid, instance)
+                }
                 return instance
             }
         } catch (error) {

package/lib/core/handler/Handler.js

@@ -135,19 +135,14 @@ class Handler {
 
     /**
      * @param {Command} command
+     * @returns {Promise<Command> | Command}
      */
     handleCommand(command) {
         try {
             if (command.commandType === CommandType.RetrieveArray) {
                 /** @type {any} */
                 const responseArray = handlers[CommandType.Reference].handleCommand(command.payload[0])
-                if (responseArray instanceof Promise) {
-                    return responseArray.then((resolvedResponseArray) => {
-                        return Command.createArrayResponse(resolvedResponseArray, command.runtimeName)
-                    })
-                } else {
-                    return Command.createArrayResponse(responseArray, command.runtimeName)
-                }
+                return Command.createArrayResponse(responseArray, command.runtimeName)
             }
             /** @type {any} */
             const response = handlers[command.commandType].handleCommand(command)
@@ -169,13 +164,43 @@ class Handler {
             })
         }
 
+        // Create base responseCommand (either primitive response or a reference)
+        let responseCommand
         if (TypesHandler.isPrimitiveOrNullOrUndefined(response)) {
-            return Command.createResponse(response, runtimeName)
+            responseCommand = Command.createResponse(response, runtimeName)
         } else {
             let cache = ReferencesCache.getInstance()
             let uuid = cache.cacheReference(response)
-            return Command.createReference(uuid, runtimeName)
+            responseCommand = Command.createReference(uuid, runtimeName)
         }
+
+        // If any invocation contexts were created during instance creation, attach UpdateInvocationContext commands
+        const invocationContexts = CreateClassInstanceHandler._invocationContexts
+        if (invocationContexts && typeof invocationContexts.size === 'number' && invocationContexts.size > 0) {
+            const refCache = ReferencesCache.getInstance()
+            for (const [contextKey, instance] of invocationContexts.entries()) {
+                const instanceGuid = refCache.cacheReference(instance)
+                const updateContextCommand = new Command(
+                    runtimeName,
+                    CommandType.UpdateInvocationContext,
+                    [contextKey.toString(),
+                    instanceGuid]
+                )
+
+                // Prefer using addArgToPayload if available, otherwise push into payload array
+                if (typeof responseCommand.addArgToPayload === 'function') {
+                    responseCommand = responseCommand.addArgToPayload(updateContextCommand)
+                } else {
+                    responseCommand.payload = responseCommand.payload || []
+                    responseCommand.payload.push(updateContextCommand)
+                }
+            }
+
+            // Clear contexts after attaching them to the response
+            invocationContexts.clear()
+        }
+
+        return responseCommand
     }
 }