javonet-nodejs-sdk 2.6.8 → 2.6.10

package/dist/core/handler/Handler.cjs

@@ -22,6 +22,11 @@ __export(Handler_exports, {
   handlers: () => handlers
 });
 module.exports = __toCommonJS(Handler_exports);
+var import_CommandType = require("../../utils/CommandType.cjs");
+var import_Command = require("../../utils/Command.cjs");
+var import_TypesHandler = require("../../utils/TypesHandler.cjs");
+var import_ExceptionSerializer = require("../../utils/exception/ExceptionSerializer.cjs");
+var import_AbstractHandler = require("./AbstractHandler.cjs");
 var import_ReferencesCache = require("../referenceCache/ReferencesCache.cjs");
 var import_ValueHandler = require("./ValueHandler.cjs");
 var import_LoadLibraryHandler = require("./LoadLibraryHandler.cjs");
@@ -71,11 +76,8 @@ var import_GetAsyncOperationResultHandler = require("./GetAsyncOperationResultHa
 var import_AsKwargsHandler = require("./AsKwargsHandler.cjs");
 var import_GetResultTypeHandler = require("./GetResultTypeHandler.cjs");
 var import_GetGlobalFieldHandler = require("./GetGlobalFieldHandler.cjs");
-var import_CommandType = require("../../utils/CommandType.cjs");
-var import_Command = require("../../utils/Command.cjs");
-var import_TypesHandler = require("../../utils/TypesHandler.cjs");
-var import_ExceptionSerializer = require("../../utils/exception/ExceptionSerializer.cjs");
-var import_AbstractHandler = require("./AbstractHandler.cjs");
+var import_RegisterForUpdateHandler = require("./RegisterForUpdateHandler.cjs");
+var import_ValueForUpdateHandler = require("./ValueForUpdateHandler.cjs");
 const handlers = {
   [import_CommandType.CommandType.Value]: new import_ValueHandler.ValueHandler(),
   [import_CommandType.CommandType.LoadLibrary]: new import_LoadLibraryHandler.LoadLibraryHandler(),
@@ -124,7 +126,9 @@ const handlers = {
   [import_CommandType.CommandType.GetAsyncOperationResult]: new import_GetAsyncOperationResultHandler.GetAsyncOperationResultHandler(),
   [import_CommandType.CommandType.AsKwargs]: new import_AsKwargsHandler.AsKwargsHandler(),
   [import_CommandType.CommandType.GetResultType]: new import_GetResultTypeHandler.GetResultTypeHandler(),
-  [import_CommandType.CommandType.GetGlobalField]: new import_GetGlobalFieldHandler.GetGlobalFieldHandler()
+  [import_CommandType.CommandType.GetGlobalField]: new import_GetGlobalFieldHandler.GetGlobalFieldHandler(),
+  [import_CommandType.CommandType.RegisterForUpdate]: new import_RegisterForUpdateHandler.RegisterForUpdateHandler(),
+  [import_CommandType.CommandType.ValueForUpdate]: new import_ValueForUpdateHandler.ValueForUpdateHandler()
 };
 class Handler {
   /**
@@ -153,9 +157,19 @@ class Handler {
       const response = handlers[command.commandType].handleCommand(command);
       return this.parseCommand(response, command.runtimeName);
     } catch (e) {
-      return import_ExceptionSerializer.ExceptionSerializer.serializeException(e, command);
+      return Handler.resolveException(e, command);
     }
   }
+  /**
+   * Prefer innerException (or cause) when available.
+   * @param {any} error
+   * @param {Command} command
+   * @returns {Command}
+   */
+  static resolveException(error, command) {
+    const inner = error?.cause;
+    return import_ExceptionSerializer.ExceptionSerializer.serializeException(inner ?? error, command);
+  }
   /**
    * @param {any} response
    * @param {RuntimeName} runtimeName
@@ -167,13 +181,37 @@ class Handler {
         return this.parseCommand(resolvedResponse, runtimeName);
       });
     }
+    let responseCommand;
     if (import_TypesHandler.TypesHandler.isPrimitiveOrNullOrUndefined(response)) {
-      return import_Command.Command.createResponse(response, runtimeName);
+      responseCommand = import_Command.Command.createResponse(response, runtimeName);
     } else {
-      let cache = import_ReferencesCache.ReferencesCache.getInstance();
-      let uuid = cache.cacheReference(response);
-      return import_Command.Command.createReference(uuid, runtimeName);
+      const refCache = import_ReferencesCache.ReferencesCache.getInstance();
+      const uuid = refCache.cacheReference(response);
+      responseCommand = import_Command.Command.createReference(uuid, runtimeName);
+    }
+    const invocationContexts = import_RegisterForUpdateHandler.RegisterForUpdateHandler._invocationContexts.Value;
+    if (invocationContexts && invocationContexts.size > 0) {
+      const refCache = import_ReferencesCache.ReferencesCache.getInstance();
+      for (const [contextKey, instance] of invocationContexts.entries()) {
+        const instanceGuid = refCache.cacheReference(instance);
+        const updateContextCommand = new import_Command.Command(
+          runtimeName,
+          import_CommandType.CommandType.ValueForUpdate,
+          [
+            contextKey.toString(),
+            instanceGuid
+          ]
+        );
+        if (typeof responseCommand.addArgToPayload === "function") {
+          responseCommand = responseCommand.addArgToPayload(updateContextCommand);
+        } else {
+          responseCommand.payload = responseCommand.payload || [];
+          responseCommand.payload.push(updateContextCommand);
+        }
+      }
+      invocationContexts.clear();
     }
+    return responseCommand;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/core/handler/InvokeInstanceMethodHandler.cjs

@@ -44,7 +44,7 @@ class InvokeInstanceMethodHandler extends import_AbstractHandler.AbstractHandler
         let methods = Object.getOwnPropertyNames(instance.__proto__).filter(function(property) {
           return typeof instance.__proto__[property] === "function";
         });
-        let message = `Method ${methodName} not found in object. Available methods:
+        let message = `Method ${methodName} not found in object ${instance.constructor.name}. Available methods:
 `;
         methods.forEach((methodIter) => {
           message += `${methodIter}

package/dist/core/handler/InvokeStaticMethodHandler.cjs

@@ -44,7 +44,7 @@ class InvokeStaticMethodHandler extends import_AbstractHandler.AbstractHandler {
         let methods = Object.getOwnPropertyNames(type).filter(function(property) {
           return typeof type[property] === "function";
         });
-        let message = `Method ${methodName} not found in class. Available methods:
+        let message = `Method ${methodName} not found in class ${type.name}. Available methods:
 `;
         methods.forEach((methodIter) => {
           message += `${methodIter}

package/dist/core/handler/RegisterForUpdateHandler.cjs

@@ -0,0 +1,60 @@
+"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 RegisterForUpdateHandler_exports = {};
+__export(RegisterForUpdateHandler_exports, {
+  RegisterForUpdateHandler: () => RegisterForUpdateHandler
+});
+module.exports = __toCommonJS(RegisterForUpdateHandler_exports);
+var import_AbstractHandler = require("./AbstractHandler.cjs");
+class RegisterForUpdateHandler extends import_AbstractHandler.AbstractHandler {
+  requiredParametersCount = 2;
+  /* type {Map<string, any>} */
+  static _invocationContexts = { Value: /* @__PURE__ */ new Map() };
+  /**
+   * Ensure context map exists and return it.
+   * @returns {Map<string, any>}
+   */
+  static getOrCreateContextMap() {
+    const container = RegisterForUpdateHandler._invocationContexts;
+    if (!container.Value) {
+      container.Value = /* @__PURE__ */ new Map();
+    }
+    return container.Value;
+  }
+  /**
+   * @param {any} command
+   * @returns {any}
+   */
+  process(command) {
+    if (command.payload.length < this.requiredParametersCount) {
+      throw new Error("RegisterForUpdateHandler parameters mismatch");
+    }
+    const objectToRegister = command.payload[0];
+    const guidToRegister = command.payload.length > 1 && typeof command.payload[1] === "string" ? command.payload[1] : "";
+    const contextMap = RegisterForUpdateHandler.getOrCreateContextMap();
+    if (!contextMap.has(guidToRegister)) {
+      contextMap.set(guidToRegister, objectToRegister);
+    }
+    return objectToRegister;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RegisterForUpdateHandler
+});

package/dist/core/handler/ValueForUpdateHandler.cjs

@@ -0,0 +1,36 @@
+"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 ValueForUpdateHandler_exports = {};
+__export(ValueForUpdateHandler_exports, {
+  ValueForUpdateHandler: () => ValueForUpdateHandler
+});
+module.exports = __toCommonJS(ValueForUpdateHandler_exports);
+var import_AbstractHandler = require("./AbstractHandler.cjs");
+class ValueForUpdateHandler extends import_AbstractHandler.AbstractHandler {
+  /**
+   * @param {any} command
+   */
+  process(command) {
+    throw new Error(`${this.constructor.name} is not implemented in Node.js`);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ValueForUpdateHandler
+});

package/dist/sdk/InvocationContext.cjs

@@ -25,10 +25,22 @@ var import_DelegatesCache = require("../core/delegatesCache/DelegatesCache.cjs")
 var import_Interpreter = require("../core/interpreter/Interpreter.cjs");
 var import_Command = require("../utils/Command.cjs");
 var import_CommandType = require("../utils/CommandType.cjs");
-var import_ConnectionType = require("../utils/ConnectionType.cjs");
 var import_ExceptionThrower = require("../utils/exception/ExceptionThrower.cjs");
 var import_RuntimeName = require("../utils/RuntimeName.cjs");
 var import_TypesHandler = require("../utils/TypesHandler.cjs");
+var import_uuid = require("uuid");
+class AsyncLock {
+  constructor() {
+    this._tail = Promise.resolve();
+  }
+  async lock() {
+    let release;
+    const prev = this._tail;
+    this._tail = new Promise((res) => release = res);
+    await prev;
+    return () => release(void 0);
+  }
+}
 class InvocationContext {
   /** @type {RuntimeNameType} */
   #runtimeName;
@@ -42,6 +54,12 @@ class InvocationContext {
   #isExecuted = false;
   /** @type {Interpreter | null} */
   #interpreter = null;
+  /** @type {string | null} */
+  #guid = null;
+  /** @type {AsyncLock} */
+  #materializationLock = new AsyncLock();
+  // Static map holding contexts waiting for materialization (guid -> InvocationContext)
+  static _invocationContexts = /* @__PURE__ */ new Map();
   /**
    *
    * @param {RuntimeNameType} runtimeName
@@ -56,6 +74,13 @@ class InvocationContext {
     this.#responseCommand = null;
     this.#isExecuted = isExecuted;
     this.#interpreter = null;
+    this.#guid = (0, import_uuid.v4)();
+  }
+  /**
+   * @returns {string} guid of this InvocationContext
+   */
+  getGuid() {
+    return this.#guid;
   }
   /**
    * @param {Command} localCommand
@@ -71,7 +96,7 @@ class InvocationContext {
   /**
    * @returns {Command|null}
    */
-  get_current_command() {
+  getCurrentCommand() {
     return this.#currentCommand;
   }
   //destructor() {
@@ -101,13 +126,8 @@ class InvocationContext {
   }
   /**
    * 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>} 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
    */
   async execute() {
@@ -117,19 +137,73 @@ class InvocationContext {
     if (!this.#interpreter) {
       this.#interpreter = new import_Interpreter.Interpreter();
     }
-    this.#responseCommand = await this.#interpreter.execute(this.#currentCommand, this.#connectionData);
-    if (!this.#responseCommand) {
-      throw new Error("responseCommand is undefined in Invocation Context execute method");
+    const entries = Array.from(InvocationContext._invocationContexts.entries());
+    entries.sort((a, b) => String(a[0]).localeCompare(String(b[0])));
+    const releases = [];
+    for (const [, ic] of entries) {
+      const release = await ic.#materializationLock.lock();
+      releases.push(release);
     }
-    if (this.#responseCommand.commandType === import_CommandType.CommandType.Exception) {
-      throw import_ExceptionThrower.ExceptionThrower.throwException(this.#responseCommand);
+    try {
+      this.#responseCommand = await this.#interpreter.execute(this.#currentCommand, this.#connectionData);
+      if (!this.#responseCommand) {
+        throw new Error("responseCommand is undefined in Invocation Context execute method");
+      }
+      if (this.#responseCommand.commandType === import_CommandType.CommandType.Exception) {
+        throw import_ExceptionThrower.ExceptionThrower.throwException(this.#responseCommand);
+      }
+      this.#responseCommand = this.#processUpdateInvocationContextCommands(this.#responseCommand);
+      if (this.#responseCommand.commandType === import_CommandType.CommandType.CreateClassInstance) {
+        this.#currentCommand = this.#responseCommand;
+        this.#isExecuted = true;
+        return this;
+      }
+      return new InvocationContext(this.#runtimeName, this.#connectionData, this.#responseCommand, true);
+    } finally {
+      for (let i = releases.length - 1; i >= 0; i--) {
+        try {
+          releases[i]();
+        } catch {
+        }
+      }
     }
-    if (this.#responseCommand.commandType === import_CommandType.CommandType.CreateClassInstance) {
-      this.#currentCommand = this.#responseCommand;
-      this.#isExecuted = true;
-      return this;
+  }
+  /**
+   * Process UpdateInvocationContext commands in the provided responseCommand payload.
+   * For each ValueForUpdate command, set the referenced InvocationContext's currentCommand to a Reference command,
+   * remove that InvocationContext from the static map and remove ValueForUpdate items from response payload.
+   * @param {Command} responseCommand
+   * @returns {Command}
+   */
+  #processUpdateInvocationContextCommands(responseCommand) {
+    if (!responseCommand?.payload || responseCommand.payload.length === 0) {
+      return responseCommand;
+    }
+    const commandsToUpdate = [];
+    for (const item of responseCommand.payload) {
+      if (item instanceof import_Command.Command && item.commandType === import_CommandType.CommandType.ValueForUpdate) {
+        commandsToUpdate.push(item);
+      }
+    }
+    if (commandsToUpdate.length === 0) {
+      return responseCommand;
+    }
+    const updatedPayload = Array.from(responseCommand.payload);
+    for (const cmd of commandsToUpdate) {
+      const cmdPayload = cmd.payload;
+      if (cmdPayload && cmdPayload.length >= 2) {
+        const contextGuid = String(cmdPayload[0]);
+        const instanceGuid = String(cmdPayload[1]);
+        const invCtx = InvocationContext._invocationContexts.get(contextGuid);
+        if (invCtx) {
+          invCtx.#currentCommand = new import_Command.Command(invCtx.#runtimeName, import_CommandType.CommandType.Reference, [instanceGuid]);
+          InvocationContext._invocationContexts.delete(contextGuid);
+        }
+      }
+      const idx = updatedPayload.indexOf(cmd);
+      if (idx >= 0) updatedPayload.splice(idx, 1);
     }
-    return new InvocationContext(this.#runtimeName, this.#connectionData, this.#responseCommand, true);
+    return new import_Command.Command(responseCommand.runtimeName, responseCommand.commandType, updatedPayload);
   }
   /**
    * Invokes a static method on the target runtime.
@@ -171,14 +245,25 @@ class 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) {
-    let localCommand = new import_Command.Command(this.#runtimeName, import_CommandType.CommandType.CreateClassInstance, args);
-    return this.#createInstanceContext(localCommand);
+    const localCommand = new import_Command.Command(this.#runtimeName, import_CommandType.CommandType.CreateClassInstance, [...args]);
+    const createInstanceInvCtx = this.#createInstanceContext(localCommand);
+    return createInstanceInvCtx.#registerForUpdate();
+  }
+  /**
+   * Registers the current InvocationContext for updates.
+   * @returns {InvocationContext}
+   */
+  #registerForUpdate() {
+    this.#currentCommand = this.#buildCommand(new import_Command.Command(this.#runtimeName, import_CommandType.CommandType.RegisterForUpdate, [this.getGuid()]));
+    InvocationContext._invocationContexts.set(this.getGuid(), this);
+    return this;
   }
   /**
    * Retrieves the value of an instance field from the target runtime.
@@ -450,7 +535,7 @@ class InvocationContext {
       }
       return payloadItem;
     } else if (payloadItem instanceof InvocationContext) {
-      return payloadItem.get_current_command();
+      return payloadItem.getCurrentCommand();
     } else if (payloadItem instanceof Array) {
       const copiedArray = payloadItem.map((item) => this.#encapsulatePayloadItem(item));
       return new import_Command.Command(this.#runtimeName, import_CommandType.CommandType.Array, copiedArray);

package/dist/sdk/RuntimeContext.cjs

@@ -284,7 +284,7 @@ class RuntimeContext {
       }
       return payloadItem;
     } else if (payloadItem instanceof import_InvocationContext.InvocationContext) {
-      const command = payloadItem?.get_current_command();
+      const command = payloadItem?.getCurrentCommand();
       if (!command) {
         throw new Error("Command not found");
       }

package/dist/types/core/handler/Handler.d.ts

@@ -1,5 +1,12 @@
 export type RuntimeName = import("../../types.d.ts").RuntimeName;
 export class Handler {
+    /**
+     * Prefer innerException (or cause) when available.
+     * @param {any} error
+     * @param {Command} command
+     * @returns {Command}
+     */
+    static resolveException(error: any, command: Command): Command;
     /**
      * @param {import('../interpreter/Interpreter.js').Interpreter} interpreter
      */

package/dist/types/core/handler/RegisterForUpdateHandler.d.ts

@@ -0,0 +1,17 @@
+export class RegisterForUpdateHandler extends AbstractHandler {
+    static _invocationContexts: {
+        Value: Map<any, any>;
+    };
+    /**
+     * Ensure context map exists and return it.
+     * @returns {Map<string, any>}
+     */
+    static getOrCreateContextMap(): Map<string, any>;
+    requiredParametersCount: number;
+    /**
+     * @param {any} command
+     * @returns {any}
+     */
+    process(command: any): any;
+}
+import { AbstractHandler } from './AbstractHandler.js';

package/dist/types/core/handler/ValueForUpdateHandler.d.ts

@@ -0,0 +1,7 @@
+export class ValueForUpdateHandler extends AbstractHandler {
+    /**
+     * @param {any} command
+     */
+    process(command: any): void;
+}
+import { AbstractHandler } from './AbstractHandler.js';

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

@@ -1,9 +1,5 @@
 export type RuntimeNameType = import("../types.d.ts").RuntimeName;
 export type IConnectionData = import("../utils/connectionData/IConnectionData.js").IConnectionData;
-/**
- * @typedef {import('../types.d.ts').RuntimeName} RuntimeNameType
- * @typedef {import('../utils/connectionData/IConnectionData.js').IConnectionData} IConnectionData
- */
 /**
  * InvocationContext is a class that represents a context for invoking commands.
  * It implements several interfaces for different types of interactions.
@@ -12,6 +8,7 @@ export type IConnectionData = import("../utils/connectionData/IConnectionData.js
  * @class
  */
 export class InvocationContext {
+    static _invocationContexts: Map<any, any>;
     /**
      *
      * @param {RuntimeNameType} runtimeName
@@ -20,19 +17,18 @@ 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;
+    getCurrentCommand(): 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>} 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>;
@@ -64,9 +60,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;

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

@@ -47,4 +47,6 @@ export namespace CommandType {
     let AsKwargs: 45;
     let GetResultType: 46;
     let GetGlobalField: 47;
+    let RegisterForUpdate: 48;
+    let ValueForUpdate: 49;
 }

package/dist/utils/CommandType.cjs

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

package/lib/core/handler/Handler.js

@@ -1,4 +1,11 @@
 //@ts-check
+
+import { CommandType } from '../../utils/CommandType.js'
+import { Command } from '../../utils/Command.js'
+import { TypesHandler } from '../../utils/TypesHandler.js'
+import { ExceptionSerializer } from '../../utils/exception/ExceptionSerializer.js'
+import { AbstractHandler } from './AbstractHandler.js'
+
 import { ReferencesCache } from '../referenceCache/ReferencesCache.js'
 import { ValueHandler } from './ValueHandler.js'
 import { LoadLibraryHandler } from './LoadLibraryHandler.js'
@@ -48,11 +55,8 @@ import { GetAsyncOperationResultHandler } from './GetAsyncOperationResultHandler
 import { AsKwargsHandler } from './AsKwargsHandler.js'
 import { GetResultTypeHandler } from './GetResultTypeHandler.js'
 import { GetGlobalFieldHandler } from './GetGlobalFieldHandler.js'
-import { CommandType } from '../../utils/CommandType.js'
-import { Command } from '../../utils/Command.js'
-import { TypesHandler } from '../../utils/TypesHandler.js'
-import { ExceptionSerializer } from '../../utils/exception/ExceptionSerializer.js'
-import { AbstractHandler } from './AbstractHandler.js'
+import { RegisterForUpdateHandler } from './RegisterForUpdateHandler.js'
+import { ValueForUpdateHandler } from './ValueForUpdateHandler.js'
 
 /**
  * @typedef {import('../../types.d.ts').RuntimeName} RuntimeName
@@ -110,6 +114,8 @@ const handlers = {
     [CommandType.AsKwargs]: new AsKwargsHandler(),
     [CommandType.GetResultType]: new GetResultTypeHandler(),
     [CommandType.GetGlobalField]: new GetGlobalFieldHandler(),
+    [CommandType.RegisterForUpdate]: new RegisterForUpdateHandler(),
+    [CommandType.ValueForUpdate]: new ValueForUpdateHandler(),
 }
 
 class Handler {
@@ -144,14 +150,26 @@ class Handler {
                 const responseArray = handlers[CommandType.Reference].handleCommand(command.payload[0])
                 return Command.createArrayResponse(responseArray, command.runtimeName)
             }
+
             /** @type {any} */
             const response = handlers[command.commandType].handleCommand(command)
             return this.parseCommand(response, command.runtimeName)
         } catch (e) {
-            return ExceptionSerializer.serializeException(e, command)
+            return Handler.resolveException(e, command)
         }
     }
 
+    /**
+     * Prefer innerException (or cause) when available.
+     * @param {any} error
+     * @param {Command} command
+     * @returns {Command}
+     */
+    static resolveException(error, command) {
+        const inner = error?.cause
+        return ExceptionSerializer.serializeException(inner ?? error, command)
+    }
+
     /**
      * @param {any} response
      * @param {RuntimeName} runtimeName
@@ -164,13 +182,41 @@ class Handler {
             })
         }
 
+        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)
+            const refCache = ReferencesCache.getInstance()
+            const uuid = refCache.cacheReference(response)
+            responseCommand = Command.createReference(uuid, runtimeName)
+        }
+
+        const invocationContexts = RegisterForUpdateHandler._invocationContexts.Value
+        if (invocationContexts && 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.ValueForUpdate,
+                    [contextKey.toString(),
+                    instanceGuid]
+                )
+
+                if (typeof responseCommand.addArgToPayload === 'function') {
+                    responseCommand = responseCommand.addArgToPayload(updateContextCommand)
+                } else {
+                    responseCommand.payload = responseCommand.payload || []
+                    responseCommand.payload.push(updateContextCommand)
+                }
+            }
+
+            // Clear all entries after processing this request
+            invocationContexts.clear()
         }
+
+        return responseCommand
     }
 }
 

package/lib/core/handler/InvokeInstanceMethodHandler.js

@@ -29,7 +29,7 @@ class InvokeInstanceMethodHandler extends AbstractHandler {
                 let methods = Object.getOwnPropertyNames(instance.__proto__).filter(function (property) {
                     return typeof instance.__proto__[property] === 'function'
                 })
-                let message = `Method ${methodName} not found in object. Available methods:\n`
+                let message = `Method ${methodName} not found in object ${instance.constructor.name}. Available methods:\n`
                 methods.forEach((methodIter) => {
                     message += `${methodIter}\n`
                 })

package/lib/core/handler/InvokeStaticMethodHandler.js

@@ -29,7 +29,7 @@ class InvokeStaticMethodHandler extends AbstractHandler {
                 let methods = Object.getOwnPropertyNames(type).filter(function (property) {
                     return typeof type[property] === 'function'
                 })
-                let message = `Method ${methodName} not found in class. Available methods:\n`
+                let message = `Method ${methodName} not found in class ${type.name}. Available methods:\n`
                 methods.forEach((methodIter) => {
                     message += `${methodIter}\n`
                 })

package/lib/core/handler/RegisterForUpdateHandler.js

@@ -0,0 +1,40 @@
+// @ts-check
+import { AbstractHandler } from './AbstractHandler.js'
+
+export class RegisterForUpdateHandler extends AbstractHandler {
+    requiredParametersCount = 2
+    /* type {Map<string, any>} */
+    static _invocationContexts = { Value: new Map() }
+
+    /**
+     * Ensure context map exists and return it.
+     * @returns {Map<string, any>}
+     */
+    static getOrCreateContextMap() {
+        const container = RegisterForUpdateHandler._invocationContexts
+        if (!container.Value) {
+            container.Value = new Map()
+        }
+        return container.Value
+    }
+
+    /**
+     * @param {any} command
+     * @returns {any}
+     */
+    process(command) {
+        if (command.payload.length < this.requiredParametersCount) {
+            throw new Error('RegisterForUpdateHandler parameters mismatch')
+        }
+
+        const objectToRegister = command.payload[0]
+        const guidToRegister = command.payload.length > 1 && typeof command.payload[1] === 'string' ? command.payload[1] : '' // Guid.Empty -> empty string
+
+        const contextMap = RegisterForUpdateHandler.getOrCreateContextMap()
+        if (!contextMap.has(guidToRegister)) {
+            contextMap.set(guidToRegister, objectToRegister)
+        }
+
+        return objectToRegister
+    }
+}

package/lib/core/handler/ValueForUpdateHandler.js

@@ -0,0 +1,11 @@
+// @ts-check
+import { AbstractHandler } from './AbstractHandler.js'
+
+export class ValueForUpdateHandler extends AbstractHandler {
+    /**
+     * @param {any} command
+     */
+    process(command) {
+        throw new Error(`${this.constructor.name} is not implemented in Node.js`)
+    }
+}

package/lib/sdk/InvocationContext.js

@@ -3,16 +3,35 @@ import { delegatesCacheInstance } from '../core/delegatesCache/DelegatesCache.js
 import { Interpreter } from '../core/interpreter/Interpreter.js'
 import { Command } from '../utils/Command.js'
 import { CommandType } from '../utils/CommandType.js'
-import { ConnectionType } from '../utils/ConnectionType.js'
 import { ExceptionThrower } from '../utils/exception/ExceptionThrower.js'
 import { RuntimeName } from '../utils/RuntimeName.js'
 import { TypesHandler } from '../utils/TypesHandler.js'
+import { v4 as uuidv4 } from 'uuid' // add lightweight uuid generation
 
 /**
  * @typedef {import('../types.d.ts').RuntimeName} RuntimeNameType
  * @typedef {import('../utils/connectionData/IConnectionData.js').IConnectionData} IConnectionData
  */
 
+/**
+ * Simple async lock implementation to ensure sequential execution of critical sections.
+ */
+class AsyncLock {
+    constructor() {
+        this._tail = Promise.resolve()
+    }
+    async lock() {
+        /**
+         * @type {(value?: any) => void}
+         */
+        let release
+        const prev = this._tail
+        this._tail = new Promise((res) => (release = res))
+        await prev
+        return () => release(undefined)
+    }
+}
+
 /**
  * InvocationContext is a class that represents a context for invoking commands.
  * It implements several interfaces for different types of interactions.
@@ -33,6 +52,13 @@ class InvocationContext {
     #isExecuted = false
     /** @type {Interpreter | null} */
     #interpreter = null
+    /** @type {string | null} */
+    #guid = null
+    /** @type {AsyncLock} */
+    #materializationLock = new AsyncLock()
+
+    // Static map holding contexts waiting for materialization (guid -> InvocationContext)
+    static _invocationContexts = new Map()
 
     /**
      *
@@ -48,6 +74,15 @@ class InvocationContext {
         this.#responseCommand = null
         this.#isExecuted = isExecuted
         this.#interpreter = null
+        this.#guid = uuidv4()
+    }
+
+    /**
+     * @returns {string} guid of this InvocationContext
+     */
+    getGuid() {
+        // @ts-ignore
+        return this.#guid
     }
 
     /**
@@ -65,7 +100,7 @@ class InvocationContext {
     /**
      * @returns {Command|null}
      */
-    get_current_command() {
+    getCurrentCommand() {
         return this.#currentCommand
     }
 
@@ -99,38 +134,100 @@ class InvocationContext {
 
     /**
      * 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>} 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
      */
     async execute() {
         if (this.#currentCommand === null) {
             throw new Error('currentCommand is undefined in Invocation Context execute method')
         }
-
         if (!this.#interpreter) {
             this.#interpreter = new Interpreter()
         }
 
-        this.#responseCommand = await this.#interpreter.execute(this.#currentCommand, this.#connectionData)
+        // Zablokuj wszystkie konteksty do materializacji w deterministycznej kolejności (po GUID)
+        const entries = Array.from(InvocationContext._invocationContexts.entries())
+        entries.sort((a, b) => String(a[0]).localeCompare(String(b[0])))
+        const releases = []
+        for (const [, ic] of entries) {
+            // eslint-disable-next-line no-await-in-loop
+            const release = await ic.#materializationLock.lock()
+            releases.push(release)
+        }
+
+        try {
+            // Execute command on interpreter
+            this.#responseCommand = await this.#interpreter.execute(this.#currentCommand, this.#connectionData)
+
+            if (!this.#responseCommand) {
+                throw new Error('responseCommand is undefined in Invocation Context execute method')
+            }
+            if (this.#responseCommand.commandType === CommandType.Exception) {
+                throw ExceptionThrower.throwException(this.#responseCommand)
+            }
+
+            // Process ValueForUpdate commands (jeśli są) przychodzące z runtime
+            this.#responseCommand = this.#processUpdateInvocationContextCommands(this.#responseCommand)
 
-        if (!this.#responseCommand) {
-            throw new Error('responseCommand is undefined in Invocation Context execute method')
+            if (this.#responseCommand.commandType === CommandType.CreateClassInstance) {
+                this.#currentCommand = this.#responseCommand
+                this.#isExecuted = true
+                return this
+            }
+            return new InvocationContext(this.#runtimeName, this.#connectionData, this.#responseCommand, true)
+        } finally {
+            // Zwolnij locki w odwrotnej kolejności
+            for (let i = releases.length - 1; i >= 0; i--) {
+                try { releases[i]() } catch { /* ignore */ }
+            }
         }
-        if (this.#responseCommand.commandType === CommandType.Exception) {
-            throw ExceptionThrower.throwException(this.#responseCommand)
+    }
+
+    /**
+     * Process UpdateInvocationContext commands in the provided responseCommand payload.
+     * For each ValueForUpdate command, set the referenced InvocationContext's currentCommand to a Reference command,
+     * remove that InvocationContext from the static map and remove ValueForUpdate items from response payload.
+     * @param {Command} responseCommand
+     * @returns {Command}
+     */
+    #processUpdateInvocationContextCommands(responseCommand) {
+        if (!responseCommand?.payload || responseCommand.payload.length === 0) {
+            return responseCommand
         }
-        if (this.#responseCommand.commandType === CommandType.CreateClassInstance) {
-            this.#currentCommand = this.#responseCommand
-            this.#isExecuted = true
-            return this
+
+        /** @type {Command[]} */
+        const commandsToUpdate = []
+        for (const item of responseCommand.payload) {
+            if (item instanceof Command && item.commandType === CommandType.ValueForUpdate) {
+                commandsToUpdate.push(item)
+            }
+        }
+        if (commandsToUpdate.length === 0) {
+            return responseCommand
+        }
+
+        // create a copy of the payload to modify
+        const updatedPayload = Array.from(responseCommand.payload)
+
+        // update each InvocationContext referenced in ValueForUpdate commands
+        for (const cmd of commandsToUpdate) {
+            const cmdPayload = cmd.payload
+            if (cmdPayload && cmdPayload.length >= 2) {
+                const contextGuid = String(cmdPayload[0])
+                const instanceGuid = String(cmdPayload[1])
+                const invCtx = InvocationContext._invocationContexts.get(contextGuid)
+                if (invCtx) {
+                    invCtx.#currentCommand = new Command(invCtx.#runtimeName, CommandType.Reference, [instanceGuid])
+                    InvocationContext._invocationContexts.delete(contextGuid)
+                }
+            }
+            // remove ValueForUpdate command from payload
+            const idx = updatedPayload.indexOf(cmd)
+            if (idx >= 0) updatedPayload.splice(idx, 1)
         }
-        return new InvocationContext(this.#runtimeName, this.#connectionData, this.#responseCommand, true)
+
+        return new Command(responseCommand.runtimeName, responseCommand.commandType, updatedPayload)
     }
 
     /**
@@ -176,14 +273,26 @@ class 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) {
-        let localCommand = new Command(this.#runtimeName, CommandType.CreateClassInstance, args)
-        return this.#createInstanceContext(localCommand)
+        const localCommand = new Command(this.#runtimeName, CommandType.CreateClassInstance, [...args])
+        const createInstanceInvCtx = this.#createInstanceContext(localCommand)
+        return createInstanceInvCtx.#registerForUpdate()
+    }
+
+    /**
+     * Registers the current InvocationContext for updates.
+     * @returns {InvocationContext}
+     */
+    #registerForUpdate() {
+        this.#currentCommand = this.#buildCommand(new Command(this.#runtimeName, CommandType.RegisterForUpdate, [this.getGuid()]))
+        InvocationContext._invocationContexts.set(this.getGuid(), this)
+        return this
     }
 
     /**
@@ -429,7 +538,7 @@ class InvocationContext {
         await localInvCtx.execute()
 
         const resolve = (/** @type {any} */ item) => {
-            return item?.commandType === CommandType.Reference ? 
+            return item?.commandType === CommandType.Reference ?
             new InvocationContext(
                 this.#runtimeName,
                 this.#connectionData,
@@ -441,11 +550,11 @@ class InvocationContext {
         if (!respCommand) {
             return []
         }
-        
+
         if (respCommand.payload) {
             return respCommand.payload.map((/** @type {any} */ item) => resolve(item))
         }
-        
+
         return respCommand.payload || []
     }
 
@@ -484,7 +593,7 @@ class InvocationContext {
             return payloadItem
             // eslint-disable-next-line valid-typeof
         } else if (payloadItem instanceof InvocationContext) {
-            return payloadItem.get_current_command()
+            return payloadItem.getCurrentCommand()
         } else if (payloadItem instanceof Array) {
             const copiedArray = payloadItem.map((item) => this.#encapsulatePayloadItem(item))
             return new Command(this.#runtimeName, CommandType.Array, copiedArray)

package/lib/sdk/RuntimeContext.js

@@ -303,7 +303,7 @@ class RuntimeContext {
             }
             return payloadItem
         } else if (payloadItem instanceof InvocationContext) {
-            const command = payloadItem?.get_current_command()
+            const command = payloadItem?.getCurrentCommand()
             if (!command) {
                 throw new Error('Command not found')
             }

package/lib/utils/CommandType.js

@@ -48,4 +48,6 @@ export const CommandType = /** @type {const} */ ({
     AsKwargs: 45,
     GetResultType: 46,
     GetGlobalField: 47,
+    RegisterForUpdate: 48,
+    ValueForUpdate: 49,
 })

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "javonet-nodejs-sdk",
-    "version": "2.6.8",
+    "version": "2.6.10",
     "description": "Javonet allows you to reference and use modules or packages written in (Java/Kotlin/Groovy/Clojure, C#/VB.NET, Ruby, Perl, Python, JavaScript/TypeScript) like they were created in your technology. It works on Linux/Windows and MacOS for applications created in JVM, CLR/Netcore, Perl, Python, Ruby, NodeJS, C++ or GoLang and gives you unparalleled freedom and flexibility with native performance in building your mixed-technologies products. Let it be accessing best AI or cryptography libraries, devices SDKs, legacy client modules, internal custom packages or anything from public repositories available on NPM, Nuget, PyPI, Maven/Gradle, RubyGems or GitHub. Get free from programming languages barriers today! For more information check out our guides at https://www.javonet.com/guides/v2/",
     "keywords": [],
     "author": "SdNCenter Sp. z o. o.",
@@ -40,12 +40,13 @@
         "format": "prettier --write ."
     },
     "dependencies": {
+        "@types/uuid": "^10.0.0",
         "@types/ws": "^8.18.1",
         "buffer": "^6.0.3",
         "glob": "^10.4.5",
         "js-yaml": "^4.1.0",
         "uuid": "^10.0.0",
-        "ws": "^8.13.0"
+        "ws": "^8.18.1"
     },
     "devDependencies": {
         "@babel/cli": "^7.25.9",
@@ -58,7 +59,7 @@
         "@types/js-yaml": "^4.0.9",
         "babel-loader": "^9.2.1",
         "cross-env": "^7.0.3",
-        "esbuild": "^0.24.0",
+        "esbuild": "^0.27.0",
         "eslint": "^9.15.0",
         "eslint-config-prettier": "^9.1.0",
         "eslint-plugin-jest": "^28.9.0",