javonet-nodejs-sdk 2.6.13 → 2.6.14

package/dist/types/plugins/interfaces/ICommunitySendingPlugin.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents a sending plugin that executes before commands are sent to the target runtime.
+ * Sending plugins can add authentication tokens, modify payloads, or inject custom data.
+ *
+ * @interface ICommunitySendingPlugin
+ * @extends {ICommunityPlugin}
+ */
+export class ICommunitySendingPlugin extends ICommunityPlugin {
+    /**
+     * Executes the plugin and returns the result.
+     * This method is called before sending commands to the target runtime.
+     * The returned object will be serialized and included in the command payload.
+     *
+     * @abstract
+     * @returns {object} The result of plugin execution as an object.
+     * @throws {Error} If not implemented by derived class
+     *
+     * @example
+     * class JwtPlugin extends ICommunitySendingPlugin {
+     *   execute() {
+     *     return { token: 'abc123', timestamp: Date.now() }
+     *   }
+     * }
+     */
+    execute(): object;
+}
+import { ICommunityPlugin } from './ICommunityPlugin.js';

package/dist/types/plugins/settings/BasePluginSettings.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Represents the base configuration model shared by all plugins.
+ * This class contains common metadata such as plugin ID, path, and language type.
+ *
+ * @abstract
+ * @class BasePluginSettings
+ */
+export class BasePluginSettings {
+    /**
+     * A unique identifier assigned by the developer using a predefined plugin.
+     * Used to reference or distinguish plugin instances during registration or execution.
+     * @type {string}
+     */
+    pluginId: string;
+    /**
+     * The file system path to the plugin code.
+     * This may point to a DLL (for .NET) or other file (for external languages).
+     * Should remain empty if the plugin is executed directly from a referenced package.
+     * @type {string}
+     */
+    pluginPath: string;
+    /**
+     * Defines the language or technology in which the plugin is implemented.
+     * Used to determine how the plugin should be loaded or invoked.
+     * @type {PluginLangType}
+     */
+    pluginLangType: PluginLangType;
+}
+/**
+ * Specifies the programming language or runtime environment used to implement a plugin.
+ */
+export type PluginLangType = number;
+export namespace PluginLangType {
+    let Clr: number;
+    let Go: number;
+    let Jvm: number;
+    let Netcore: number;
+    let Perl: number;
+    let Python: number;
+    let Ruby: number;
+    let Nodejs: number;
+    let Cpp: number;
+    let Php: number;
+    let Python27: number;
+}

package/dist/types/plugins/settings/JwtGraftocodePluginSettings.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents configuration settings specific to JWT plugins,
+ * including user identity and authorization logic class information.
+ * Inherits shared properties from BasePluginSettings.
+ *
+ * @class JwtGraftocodePluginSettings
+ * @extends {BasePluginSettings}
+ */
+export class JwtGraftocodePluginSettings extends BasePluginSettings {
+    /**
+     * Username for JWT token generation.
+     * @type {string}
+     */
+    username: string;
+    /**
+     * Secret key used for JWT token signing and validation.
+     * @type {string}
+     */
+    secretKey: string;
+    /**
+     * Whether to use attributes for authorization checks.
+     * @type {boolean}
+     */
+    useAttributes: boolean;
+    /**
+     * JWT authorization class implementation.
+     * In Node.js, this is typically a class constructor/function rather than a Type.
+     * @type {Function | null}
+     */
+    jwtAuthorizeClass: Function | null;
+}
+import { BasePluginSettings } from './BasePluginSettings.js';

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

@@ -11,12 +11,14 @@ export class InvocationContext {
     static _invocationContexts: Map<any, any>;
     /**
      *
+     * @param {string} runtimeContextId
      * @param {RuntimeNameType} runtimeName
      * @param {IConnectionData} connectionData
-     * @param {Command} command
+     * @param {Command | null} command
      * @param {boolean} isExecuted
+     * @param {boolean} isDto
      */
-    constructor(runtimeName: RuntimeNameType, connectionData: IConnectionData, command: Command, isExecuted?: boolean);
+    constructor(runtimeContextId: string, runtimeName: RuntimeNameType, connectionData: IConnectionData, command: Command | null, isExecuted?: boolean, isDto?: boolean);
     /**
      * @returns {string} guid of this InvocationContext
      */
@@ -191,6 +193,22 @@ export class InvocationContext {
      * @method
      */
     getInstanceMethodAsDelegate(methodName: string, ...args: any[]): InvocationContext;
+    /**
+     * Returns a new InvocationContext that acts as a DTO (Data Transfer Object).
+     * When actAsDto is true, field get/set operate on local state without remote calls.
+     * @param {boolean} actAsDto - Whether to treat this context as a DTO.
+     * @returns {InvocationContext} A new InvocationContext with the DTO flag set.
+     * @method
+     */
+    asDto(actAsDto?: boolean): InvocationContext;
+    /**
+     * Projects the result as a DTO with the specified property names.
+     * When propertiesNames is a single empty string, returns this context unchanged.
+     * @param {...string} propertiesNames - Names of properties to include in the DTO.
+     * @returns {InvocationContext} A new InvocationContext that will materialize as a DTO.
+     * @method
+     */
+    projectResultAsDto(...propertiesNames: string[]): InvocationContext;
     /**
      * Retrieves the type of the object from the target runtime.
      * @returns {Promise<string>} The type of the object.

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

@@ -38,6 +38,12 @@ export class RuntimeContext {
     _isExecuted: boolean;
     runtimeName: import("../types.d.ts").RuntimeName;
     connectionData: import("../utils/connectionData/IConnectionData.js").IConnectionData;
+    /**
+     * Gets the unique runtime context ID for this instance.
+     * This ID is used to associate plugins with specific runtime contexts.
+     * @returns {string} The runtime context ID (GUID/UUID string)
+     */
+    get runtimeContextId(): string;
     /**
      * Executes the current command. The initial state of RuntimeContext is non-materialized,
      * wrapping either a single command or a chain of recursively nested commands.

package/dist/types/sdk/configuration/configResolvers/ConfigResolver.d.ts

@@ -6,12 +6,9 @@ export class ConfigResolver {
      */
     static tryParseRuntime(runtime: string): any;
     /**
-     * Build appropriate connection data object from a host string.
-     * - empty / null => InMemoryConnectionData
-     * - "inmemory" or "in-memory" => InMemoryConnectionData
-     * - ws:// or wss:// => WsConnectionData(fullAddress)
-     * - tcp://... => parsed by parseTcp
-     * - host:port or host:port/... => TcpConnectionData(host, port) if valid, otherwise InMemoryConnectionData
+     * Builds connection data from the host string from config (JSON, YAML, or connection string).
+     * Recognized formats: empty (in-memory), "inmemory"/"in-memory", ws://..., wss://..., tcp://host:port, host:port.
+     * When the value is missing, invalid, or unparseable, falls back to InMemoryConnectionData and logs the reason.
      * @param {string} hostValue
      * @returns {InMemoryConnectionData|WsConnectionData|TcpConnectionData}
      */

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

@@ -0,0 +1,35 @@
+export class DtoHelper {
+    /**
+     * Attempts to retrieve a DTO field value by field name from a command chain.
+     *
+     * @param {Command | null} command - The command to search through.
+     * @param {string} fieldName - The name of the field to retrieve.
+     * @returns {any}
+     */
+    static tryGetDtoFieldValue(command: Command | null, fieldName: string): any;
+    /**
+     * Attempts to extract the field name from a SetInstanceField command.
+     * @param {Command} command
+     * @returns {boolean}
+     */
+    static _tryGetDtoFieldName(command: Command): boolean;
+    /**
+     * Extracts the field name from a SetInstanceField command.
+     * @param {Command} command
+     * @returns {string}
+     */
+    static _getDtoFieldName(command: Command): string;
+    /**
+     * Attempts to extract the field value from a SetInstanceField command.
+     * @param {Command} command
+     * @returns {any}
+     */
+    static _tryGetDtoFieldValueFromCommand(command: Command): any;
+    /**
+     * Attempts to extract a value from a payload item, handling Value command types.
+     * @param {any} payloadItem
+     * @returns {any}
+     */
+    static _tryGetPayloadValue(payloadItem: any): any;
+}
+import { Command } from '../../utils/Command.js';

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

@@ -42,5 +42,10 @@ export class Command {
      * @returns {Command}
      */
     prependArgToPayload(current_command: Command | null): Command;
+    /**
+     * Returns string representation of the Command instance for debugging purposes.
+     * @returns {string}
+     */
+    toString(): string;
 }
 export type RuntimeName = import("../types.d.ts").RuntimeName;

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

@@ -49,4 +49,7 @@ export namespace CommandType {
     let GetGlobalField: 47;
     let RegisterForUpdate: 48;
     let ValueForUpdate: 49;
+    let AsDto: 50;
+    let DtoProperty: 51;
+    let ProjectResultAsDto: 52;
 }

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

@@ -11,5 +11,6 @@ export namespace Type {
     let JAVONET_UNSIGNED_LONG_LONG: 9;
     let JAVONET_UNSIGNED_INTEGER: 10;
     let JAVONET_NULL: 11;
-    let JAVONET_VOID: 12;
+    let JAVONET_UNDEFINED: 12;
+    let JAVONET_VOID: 13;
 }

package/dist/utils/Command.cjs

@@ -80,6 +80,46 @@ class Command {
       return new Command(this.runtimeName, this.commandType, [current_command].concat(this.payload));
     }
   }
+  /**
+   * Returns string representation of the Command instance for debugging purposes.
+   * @returns {string}
+   */
+  toString() {
+    try {
+      let result = "  { ";
+      result += `RuntimeName: ${this.runtimeName}, `;
+      result += `CommandType: ${this.commandType}, `;
+      result += "Payload: \n";
+      result += "    [";
+      const payload = this.payload || [];
+      const len = payload.length;
+      if (len > 0) {
+        result += "\n";
+        for (let i = 0; i < len; i++) {
+          const item = payload[i];
+          let itemStr;
+          if (item === null || item === void 0) {
+            itemStr = "null";
+          } else if (typeof item === "string") {
+            itemStr = `  "${item}"`;
+          } else if (item instanceof Command) {
+            itemStr = item.toString().replace(/\n/g, "\n    ");
+          } else {
+            itemStr = "  " + String(item);
+          }
+          result += "    " + itemStr;
+          result += i < len - 1 ? ",\n" : "\n";
+        }
+        result += "    ]\n";
+      } else {
+        result += "  ]\n";
+      }
+      result += "  }";
+      return result;
+    } catch (ex) {
+      return "Error while converting command to string:" + ex;
+    }
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/utils/CommandType.cjs

@@ -73,7 +73,10 @@ const CommandType = (
     GetResultType: 46,
     GetGlobalField: 47,
     RegisterForUpdate: 48,
-    ValueForUpdate: 49
+    ValueForUpdate: 49,
+    AsDto: 50,
+    DtoProperty: 51,
+    ProjectResultAsDto: 52
   }
 );
 // Annotate the CommonJS export names for ESM import in node:

package/dist/utils/Type.cjs

@@ -36,7 +36,8 @@ const Type = (
     JAVONET_UNSIGNED_LONG_LONG: 9,
     JAVONET_UNSIGNED_INTEGER: 10,
     JAVONET_NULL: 11,
-    JAVONET_VOID: 12
+    JAVONET_UNDEFINED: 12,
+    JAVONET_VOID: 13
   }
 );
 // Annotate the CommonJS export names for ESM import in node:

package/lib/core/handler/ArraySetItemHandler.js

@@ -21,29 +21,30 @@ class ArraySetItemHandler extends AbstractHandler {
                 throw new Error('Array Set Item parameters mismatch')
             }
 
-            let array = command.payload[0]
+            let data = command.payload[0]
+            let indexes_from_payload = command.payload[1]
             let value = command.payload[2]
 
             /** @type {number[]} */
             let indexes
-            if (Array.isArray(command.payload[1])) {
-                indexes = command.payload[1]
+            if (Array.isArray(indexes_from_payload)) {
+                indexes = indexes_from_payload
             } else {
-                indexes = [command.payload[1]]
+                indexes = [indexes_from_payload]
             }
 
             if (indexes.length === 1) {
-                // one-dimensional array
-                array[indexes[0]] = value
+                // one-dimensional data
+                data[indexes[0]] = value
             } else {
-                // multi-dimensional array
+                // multi-dimensional data
                 for (let i = 0; i < indexes.length - 1; i++) {
-                    array = array[indexes[i]]
+                    data = data[indexes[i]]
                 }
-                array[indexes[indexes.length - 1]] = value
+                data[indexes[indexes.length - 1]] = value
             }
 
-            return 0
+            return data
         } catch (error) {
             throw this.process_stack_trace(error, this.constructor.name)
         }

package/lib/core/handler/AsDtoHandler.js

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

package/lib/core/handler/AsKwargsHandler.js

@@ -5,7 +5,7 @@ export class AsKwargsHandler extends AbstractHandler {
     /**
      * @param {any} command
      */
-    handleCommand(command) {
+    process(command) {
         throw new Error(`${this.constructor.name} is not implemented in Node.js`)
     }
 }

package/lib/core/handler/DtoPropertyHandler.js

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

package/lib/core/handler/Handler.js

@@ -57,6 +57,9 @@ import { GetResultTypeHandler } from './GetResultTypeHandler.js'
 import { GetGlobalFieldHandler } from './GetGlobalFieldHandler.js'
 import { RegisterForUpdateHandler } from './RegisterForUpdateHandler.js'
 import { ValueForUpdateHandler } from './ValueForUpdateHandler.js'
+import { AsDtoHandler } from './AsDtoHandler.js'
+import { DtoPropertyHandler } from './DtoPropertyHandler.js'
+import { ProjectResultAsDtoHandler } from './ProjectResultAsDtoHandler.js'
 
 /**
  * @typedef {import('../../types.d.ts').RuntimeName} RuntimeName
@@ -116,6 +119,9 @@ const handlers = {
     [CommandType.GetGlobalField]: new GetGlobalFieldHandler(),
     [CommandType.RegisterForUpdate]: new RegisterForUpdateHandler(),
     [CommandType.ValueForUpdate]: new ValueForUpdateHandler(),
+    [CommandType.AsDto]: new AsDtoHandler(),
+    [CommandType.DtoProperty]: new DtoPropertyHandler(),
+    [CommandType.ProjectResultAsDto]: new ProjectResultAsDtoHandler(),
 }
 
 class Handler {
@@ -146,7 +152,7 @@ class Handler {
      */
     static handleCommand(command) {
         Handler._initialize()
-        
+
         try {
             if (command.commandType === CommandType.RetrieveArray) {
                 /** @type {any} */
@@ -156,6 +162,11 @@ class Handler {
 
             /** @type {any} */
             const response = handlers[command.commandType].handleCommand(command)
+
+            if (command.commandType === CommandType.ProjectResultAsDto) {
+                return Command.createArrayResponse(response, command.runtimeName)
+            }
+
             return Handler.parseCommand(response, command.runtimeName)
         } catch (e) {
             return Handler.resolveException(e, command)
@@ -200,12 +211,10 @@ class Handler {
             for (const [contextKey, instance] of invocationContexts.entries()) {
                 const instanceGuid = refCache.cacheReference(instance)
 
-                const updateContextCommand = new Command(
-                    runtimeName,
-                    CommandType.ValueForUpdate,
-                    [contextKey.toString(),
-                    instanceGuid]
-                )
+                const updateContextCommand = new Command(runtimeName, CommandType.ValueForUpdate, [
+                    contextKey.toString(),
+                    instanceGuid,
+                ])
 
                 if (typeof responseCommand.addArgToPayload === 'function') {
                     responseCommand = responseCommand.addArgToPayload(updateContextCommand)

package/lib/core/handler/PassDelegateHandler.js

@@ -112,7 +112,8 @@ class PassDelegateHandler extends AbstractHandler {
      */
     async createExecuteCall(command) {
         const { Interpreter } = await import('../interpreter/Interpreter.js')
-        return Interpreter.execute(command, new InMemoryConnectionData())
+        // TODO: get runtimeContextId from command
+        return Interpreter.execute('runtimeContextId', command, new InMemoryConnectionData())
     }
 
     /**

package/lib/core/handler/ProjectResultAsDtoHandler.js

@@ -0,0 +1,47 @@
+// @ts-check
+import { AbstractHandler } from './AbstractHandler.js'
+import { GetInstanceFieldHandler } from './GetInstanceFieldHandler.js'
+import { Command } from '../../utils/Command.js'
+import { CommandType } from '../../utils/CommandType.js'
+
+export class ProjectResultAsDtoHandler extends AbstractHandler {
+    constructor() {
+        super()
+        this.requiredParametersCount = 1
+    }
+
+    /**
+     * @param {Command} command
+     */
+    process(command) {
+        if (command.payload.length < this.requiredParametersCount) {
+            throw new Error(`${this.constructor.name} parameters mismatch`)
+        }
+
+        const instance = command.payload[0]
+        const responseArray = new Array(command.payload.length + 1)
+        responseArray[0] = instance
+
+        let typeName = 'Object'
+        if (instance !== null && instance !== undefined) {
+             typeName = instance.constructor ? instance.constructor.name : 'Object'
+        }
+
+        responseArray[1] = new Command(command.runtimeName, CommandType.GetType, [typeName])
+
+        const getInstanceFieldHandler = new GetInstanceFieldHandler()
+        for (let i = 1; i < command.payload.length; i++) {
+            const propertyName = command.payload[i]
+            const propertyValue = getInstanceFieldHandler.process(
+                new Command(command.runtimeName, CommandType.GetInstanceField, [instance, propertyName])
+            )
+            responseArray[i + 1] = new Command(
+                command.runtimeName,
+                CommandType.DtoProperty,
+                [propertyName, propertyValue]
+            )
+        }
+
+        return responseArray
+    }
+}

package/lib/core/handler/SetInstanceFieldHandler.js

@@ -32,7 +32,7 @@ class SetInstanceFieldHandler extends AbstractHandler {
                 throw new Error(message)
             }
             instance[field] = value
-            return 0
+            return instance
         } catch (error) {
             throw this.process_stack_trace(error, this.constructor.name)
         }

package/lib/core/handler/SetStaticFieldHandler.js

@@ -21,17 +21,17 @@ class SetStaticFieldHandler extends AbstractHandler {
                 throw new Error('Set static field parameters mismatch')
             }
             const { payload } = command
-            let [obj, field, value] = payload
-            if (typeof obj[field] === 'undefined') {
-                let fields = Object.keys(obj)
-                let message = `Field ${field} not found in class ${obj.constructor.name}. Available fields:\n`
+            let [type, field, value] = payload
+            if (typeof type[field] === 'undefined') {
+                let fields = Object.keys(type)
+                let message = `Field ${field} not found in class ${type.constructor.name}. Available fields:\n`
                 fields.forEach((fieldIter) => {
                     message += `${fieldIter}\n`
                 })
                 throw new Error(message)
             }
-            obj[field] = value
-            return 0
+            type[field] = value
+            return type
         } catch (error) {
             throw this.process_stack_trace(error, this.constructor.name)
         }

package/lib/core/interpreter/Interpreter.js

@@ -7,11 +7,14 @@ import { CommandSerializer } from '../protocol/CommandSerializer.js'
 import { TransmitterWebsocketBrowser } from '../transmitter/TransmitterWebsocketBrowser.js'
 import { TransmitterWebsocket } from '../transmitter/TransmitterWebsocket.js'
 import { Handler } from '../handler/Handler.js'
-
+import { PluginRegistry } from '../../plugins/PluginRegistry.js'
+import { PluginPayloadBuilder } from '../../plugins/PluginPayloadBuilder.js'
+import { Command } from '../../utils/Command.js'
+import { CommandType } from '../../utils/CommandType.js'
+ 
 /**
  * @typedef {import('../../utils/connectionData/IConnectionData.js').IConnectionData} IConnectionData
  * @typedef {typeof import('../../types.d.ts').RuntimeName} RuntimeNameType
- * @typedef {import('../../utils/Command.js').Command} Command
  */
 
 /** @type {typeof import('../receiver/Receiver.js').Receiver} */
@@ -26,13 +29,24 @@ const requireDynamic = getRequire(import.meta.url)
 export class Interpreter {
 
     /**
-     *
+     * @param {string} runtimeContextId    
      * @param {Command} command
      * @param {IConnectionData} connectionData
      * @returns {Promise<Command>}
      */
-    static async execute(command, connectionData) {
+    static async execute(runtimeContextId, command, connectionData) {
         try {
+            if (PluginRegistry.arePluginsRegisteredForRuntime(runtimeContextId)) {
+                const serializedPlugins = PluginPayloadBuilder.buildPluginsPayload(runtimeContextId)
+                
+                // Wrap the command with PluginWrapper
+                command = new Command(
+                    command.runtimeName, 
+                    CommandType.PluginWrapper, 
+                    [serializedPlugins, command]
+                )
+            }
+
             let messageByteArray = CommandSerializer.serialize(command, connectionData)
 
             if (!(messageByteArray instanceof Uint8Array)) {

package/lib/core/protocol/CommandDeserializer.js

@@ -60,6 +60,8 @@ export class CommandDeserializer {
                 return this.readUInt()
             case 'JAVONET_NULL':
                 return this.readNull()
+            case 'JAVONET_UNDEFINED':
+                return this.readUndefined()
             default:
                 throw 'Unknown type - not supported in JavaScript'
         }
@@ -186,4 +188,11 @@ export class CommandDeserializer {
         this.position += size
         return TypeDeserializer.deserializeNull()
     }
+
+    readUndefined() {
+        const size = 1
+        this.position += 2
+        this.position += size
+        return TypeDeserializer.deserializeUndefined()
+    }
 }

package/lib/core/protocol/TypeDeserializer.js

@@ -114,4 +114,9 @@ export class TypeDeserializer {
     static deserializeNull(encodedNull = null) {
         return null
     }
+
+    // eslint-disable-next-line no-unused-vars
+    static deserializeUndefined(encodedUndefined = null) {
+        return undefined
+    }
 }

package/lib/core/protocol/TypeSerializer.js

@@ -15,6 +15,9 @@ class TypeSerializer {
         if (payload_item === null) {
             return TypeSerializer.serializeNull()
         }
+        if (payload_item === undefined) {
+            return TypeSerializer.serializeUndefined()
+        }
         if (payload_item instanceof Command) {
             return TypeSerializer.serializeCommand(payload_item)
         } else if (typeof payload_item === 'number') {
@@ -36,14 +39,6 @@ class TypeSerializer {
                     payload_item
                 throw new CustomError(message, 'JAVONET_PROMISE')
             }
-            if (payload_item === undefined) {
-                throw Error(
-                    'Unsupported payload item type: ' +
-                        typeof payload_item +
-                        ' for payload item: ' +
-                        payload_item
-                )
-            }
             throw Error(
                 'Unsupported payload item type: ' +
                     (payload_item?.constructor?.name || typeof payload_item) +
@@ -185,6 +180,14 @@ class TypeSerializer {
         return buffer
     }
 
+    static serializeUndefined() {
+        const buffer = Buffer.alloc(3)
+        buffer.writeUInt8(Type.JAVONET_UNDEFINED, 0)
+        buffer.writeUInt8(1, 1)
+        buffer.writeUInt8(0, 2)
+        return buffer
+    }
+
     /**
      * @param {number} int_value
      */