javonet-nodejs-sdk 2.6.2 → 2.6.4

package/lib/sdk/RuntimeFactory.js

@@ -12,7 +12,7 @@ import { RuntimeContext } from './RuntimeContext.js'
  */
 export class RuntimeFactory {
     /**
-     * @param {IConnectionData} connectionData 
+     * @param {IConnectionData} connectionData
      */
     constructor(connectionData) {
         this.connectionData = connectionData
@@ -81,6 +81,15 @@ export class RuntimeFactory {
         return RuntimeContext.getInstance(RuntimeName.Nodejs, this.connectionData)
     }
 
+    /**
+     * Creates RuntimeContext instance to interact with the PHP runtime.
+     * @return {RuntimeContext} a RuntimeContext instance for the PHP runtime
+     * @see [Javonet Guides](https://www.javonet.com/guides/v2/javascript/foundations/runtime-context)
+     */
+    php() {
+        return RuntimeContext.getInstance(RuntimeName.Php, this.connectionData)
+    }
+
     /**
      * Creates RuntimeContext instance to interact with the Python runtime.
      * @return {RuntimeContext} a RuntimeContext instance for the Python runtime
@@ -89,4 +98,43 @@ export class RuntimeFactory {
     python27() {
         return RuntimeContext.getInstance(RuntimeName.Python27, this.connectionData)
     }
+
+    /**
+     * @param {{ runtime: import("../types.js").RuntimeName; connectionData: import("../utils/connectionData/IConnectionData.js").IConnectionData; modules: any; }} config
+     */
+    static initializeRuntimeContext(config) {
+        const rtmCtx = RuntimeContext.getInstance(config.runtime, config.connectionData)
+
+        const modules = (config.modules || '')
+            .split(',')
+            .map((/** @type {string} */ m) => m.trim())
+            .filter((/** @type {string} */ m) => m !== '')
+
+        // try to get Node's path module; if unavailable, fall back to simple checks
+        let pathModule = null
+        try {
+            // eslint-disable-next-line no-eval
+            const _require = typeof require !== 'undefined' ? require : eval('require')
+            pathModule = _require('path')
+        } catch (e) {
+            pathModule = null
+        }
+
+        modules.forEach((/** @type {string} */ module) => {
+            const isAbsolute = pathModule
+                ? pathModule.isAbsolute(module)
+                : module.startsWith('/') || /^[A-Za-z]:\\/.test(module)
+
+            if (isAbsolute) {
+                rtmCtx.loadLibrary(module)
+            } else {
+                const resolved = pathModule
+                    ? pathModule.join(process.cwd(), module)
+                    : `${process.cwd()}/${module}`
+                rtmCtx.loadLibrary(resolved)
+            }
+        })
+
+        return rtmCtx
+    }
 }

package/lib/sdk/configuration/Config.js

@@ -0,0 +1,37 @@
+// @ts-check
+
+class Config {
+    /**
+     * @param {*} runtime
+     * @param {*} connectionData
+     * @param {string} [plugins=""]
+     * @param {string} [modules=""]
+     */
+    constructor(runtime, connectionData, plugins = '', modules = '') {
+        this.runtime = runtime
+        this.connectionData = connectionData
+        this.plugins = plugins ?? ''
+        this.modules = modules ?? ''
+    }
+
+    toString() {
+        const parts = []
+        parts.push(`Runtime: ${this.runtime}`)
+
+        if (this.connectionData != null) {
+            parts.push(`Host: ${this.connectionData}`)
+        }
+
+        if (String(this.plugins).trim()) {
+            parts.push(`Plugins: ${this.plugins}`)
+        }
+
+        if (String(this.modules).trim()) {
+            parts.push(`Modules: ${this.modules}`)
+        }
+
+        return parts.join(', ')
+    }
+}
+
+export { Config }

package/lib/sdk/configuration/ConfigPriority.js

@@ -0,0 +1,9 @@
+// @ts-check
+export const ConfigPriority = /** @type {const} */ ({
+    RuntimeSpecificEnv: 1,
+    GlobalEnv: 2,
+    RuntimeSpecificFile: 3,
+    GlobalFile: 4,
+    User: 5,
+    DefaultLibrary: 6,
+})

package/lib/sdk/configuration/ConfigSourceResolver.js

@@ -0,0 +1,84 @@
+// lib/sdk/configuration/ConfigSourceResolver.js
+// lib/sdk/configuration/ConfigSourceResolver.js
+import fs from 'fs'
+import process from 'process'
+
+import { ConfigsDictionary } from './ConfigsDictionary.js'
+import { JsonConfigResolver } from './configResolvers/JsonConfigResolver.js'
+import { YamlConfigResolver } from './configResolvers/YamlConfigResolver.js'
+import { ConnectionStringConfigResolver } from './configResolvers/ConnectionStringConfigResolver.js'
+
+class ConfigSourceResolver {
+    static addConfigs(priority, configSource) {
+        console.log(`Adding config from source: ${configSource} with priority '${priority}'`)
+        const configString = ConfigSourceResolver._getConfigSourceAsString(configSource)
+        ConfigSourceResolver._parseConfigsAndAddToCollection(priority, configString)
+    }
+
+    static getConfig(configName) {
+        console.log(`Retrieving config ${configName}`)
+        return ConfigsDictionary.getConfig(configName)
+    }
+
+    static clearConfigs() {
+        ConfigsDictionary.clearConfigs()
+    }
+
+    static _getConfigSourceAsString(configSource) {
+        if (!configSource || configSource.trim() === '') {
+            throw new Error('Config source cannot be null or whitespace.')
+        }
+
+        const envValue = process.env[configSource]
+        if (envValue && envValue.trim() !== '') {
+            configSource = envValue
+        }
+
+        if (fs.existsSync(configSource) && fs.statSync(configSource).isFile()) {
+            configSource = fs.readFileSync(configSource, { encoding: 'utf-8' })
+        }
+
+        return configSource.trim()
+    }
+
+    static _parseConfigsAndAddToCollection(priority, configString) {
+        // JSON
+        try {
+            const jsonObject = JSON.parse(configString)
+            JsonConfigResolver.addConfigs(priority, jsonObject)
+            return
+        } catch (ex) {
+            if (ex instanceof SyntaxError) {
+                // not JSON
+            } else {
+                console.log('Failed to parse config source as JSON: ' + ex)
+            }
+        }
+
+        // YAML
+        try {
+            YamlConfigResolver.addConfigs(priority, configString)
+            return
+        } catch (ex) {
+            if (ex.name === 'SyntaxError') {
+                // not YAML
+            } else {
+                console.log('Failed to parse config source as YAML: ' + ex)
+            }
+        }
+
+        // Connection string
+        try {
+            ConnectionStringConfigResolver.addConfigs(priority, configString)
+            return
+        } catch (ex) {
+            console.log('Failed to parse config source as connection string: ' + ex)
+        }
+
+        throw new Error(
+            'Config source is not valid JSON, YAML, or connection string format:\n' + configString
+        )
+    }
+}
+
+export { ConfigSourceResolver }

package/lib/sdk/configuration/ConfigsDictionary.js

@@ -0,0 +1,118 @@
+// @ts-check
+
+class ConfigsDictionary {
+    /** @type {Map<string, Map<number, any>>} */
+    static _configurations_collection = new Map()
+
+    /**
+     * Normalize priority to a numeric value.
+     * Accepts either a number or an object with a numeric `value` property.
+     * @param {any} priority
+     * @returns {number|undefined}
+     */
+    static _normalizePriority(priority) {
+        if (typeof priority === 'number' && Number.isFinite(priority)) {
+            return priority
+        }
+        if (
+            priority &&
+            typeof priority === 'object' &&
+            'value' in priority &&
+            typeof priority.value === 'number'
+        ) {
+            return priority.value
+        }
+        return undefined
+    }
+
+    /**
+     * Add a configuration for a given name and priority.
+     * If the same name+priority already exists, it will not be overwritten.
+     * @param {string} name
+     * @param {number|{value:number}} priority
+     * @param {*} config
+     */
+    static addConfig(name, priority, config) {
+        if (!name || String(name).trim() === '') {
+            console.log('Config name cannot be null or whitespace. Skipping add.')
+            return
+        }
+        if (config == null) {
+            console.log('Config instance is null. Skipping add.')
+            return
+        }
+
+        const key = ConfigsDictionary._normalizePriority(priority)
+        if (typeof key !== 'number') {
+            console.log(
+                'Priority must be a numeric value or an object with a numeric `value` property. Skipping add.'
+            )
+            return
+        }
+
+        let perPriority = ConfigsDictionary._configurations_collection.get(name)
+        if (!perPriority) {
+            perPriority = new Map()
+            ConfigsDictionary._configurations_collection.set(name, perPriority)
+        }
+
+        if (perPriority.has(key)) {
+            console.log(
+                `Config with name \`${name}\` and priority \`${key}\` already exists. It will not be added or updated.`
+            )
+            return
+        }
+
+        perPriority.set(key, config)
+
+        let serialized
+        try {
+            serialized = JSON.stringify(config)
+        } catch {
+            serialized = String(config)
+        }
+
+        console.log(`Added configuration \`${name}\` with priority \`${key}\` and parameters ${serialized}`)
+    }
+
+    /**
+     * Retrieve the configuration with the numerically smallest priority for the given name.
+     * Throws if name is invalid or no configuration is found.
+     * @param {string} name
+     * @returns {*}
+     */
+    static getConfig(name) {
+        if (!name || String(name).trim() === '') {
+            throw new Error('Config name cannot be null or whitespace')
+        }
+
+        const perPriority = ConfigsDictionary._configurations_collection.get(name)
+        if (!perPriority || perPriority.size === 0) {
+            throw new Error(`Configuration ${name} not found`)
+        }
+
+        // keys are numeric priorities; pick the smallest numeric key
+        const keysArray = [...perPriority.keys()]
+        const smallest = keysArray.reduce((min, k) => (k < min ? k : min), keysArray[0])
+        const config = perPriority.get(smallest)
+
+        let serialized
+        try {
+            serialized = JSON.stringify(config)
+        } catch {
+            serialized = String(config)
+        }
+
+        console.log(
+            `Retrieved configuration \`${name}\` with priority \`${smallest}\` and parameters ${serialized}`
+        )
+        return config
+    }
+
+    /** Clear all stored configurations. */
+    static clearConfigs() {
+        ConfigsDictionary._configurations_collection.clear()
+    }
+}
+
+export { ConfigsDictionary }

package/lib/sdk/configuration/configResolvers/ConfigResolver.js

@@ -0,0 +1,109 @@
+// @ts-check
+
+import { RuntimeNameHandler } from '../../../utils/RuntimeNameHandler.js'
+import { InMemoryConnectionData } from '../../../utils/connectionData/InMemoryConnectionData.js'
+import { WsConnectionData } from '../../../utils/connectionData/WsConnectionData.js'
+import { TcpConnectionData } from '../../../utils/nodejs/connectionData/TcpConnectionData.js'
+
+class ConfigResolver {
+    /**
+     * Parse a runtime string into the runtime enum/name using RuntimeNameHandler.
+     * @param {string} runtime
+     * @returns {*}
+     */
+    static tryParseRuntime(runtime) {
+        if (!runtime || String(runtime).trim() === '') {
+            throw new Error('Runtime string cannot be null or whitespace.')
+        }
+        const normalized = String(runtime).trim().toLowerCase()
+        return RuntimeNameHandler.getRuntime(normalized)
+    }
+
+    /**
+     * 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
+     * @param {string} hostValue
+     * @returns {InMemoryConnectionData|WsConnectionData|TcpConnectionData}
+     */
+    static buildConnectionData(hostValue) {
+        if (!hostValue || String(hostValue).trim() === '') {
+            return new InMemoryConnectionData()
+        }
+
+        const hv = String(hostValue).trim()
+        const lower = hv.toLowerCase()
+
+        if (lower === 'inmemory' || lower === 'in-memory') {
+            return new InMemoryConnectionData()
+        }
+
+        if (lower.startsWith('ws://') || lower.startsWith('wss://')) {
+            return new WsConnectionData(hv)
+        }
+
+        if (lower.startsWith('tcp://')) {
+            try {
+                // slice off 'tcp://'
+                return ConfigResolver.parseTcp(hv.slice(6))
+            } catch (e) {
+                return new InMemoryConnectionData()
+            }
+        }
+
+        const colon = hv.indexOf(':')
+        if (colon > 0 && colon < hv.length - 1) {
+            let portPart = hv.substring(colon + 1)
+            const slash = portPart.indexOf('/')
+            if (slash >= 0) {
+                portPart = portPart.substring(0, slash)
+            }
+            try {
+                const port = parseInt(portPart, 10)
+                if (!Number.isFinite(port) || Number.isNaN(port)) {
+                    throw new Error('invalid port')
+                }
+                const hostOnly = hv.substring(0, colon)
+                if (String(hostOnly).trim()) {
+                    try {
+                        return new TcpConnectionData(hostOnly, port)
+                    } catch (e) {
+                        return new InMemoryConnectionData()
+                    }
+                }
+            } catch (e) {
+                // fall through to in-memory
+            }
+        }
+
+        return new InMemoryConnectionData()
+    }
+
+    /**
+     * Parse tcp address portion (after tcp://) into TcpConnectionData.
+     * Expected formats: host:port or host:port/...
+     * Throws Error on invalid format or port.
+     * @param {string} address
+     * @returns {TcpConnectionData}
+     */
+    static parseTcp(address) {
+        const slash = address.indexOf('/')
+        const hostPort = slash >= 0 ? address.substring(0, slash) : address
+        const colon = hostPort.lastIndexOf(':')
+        if (colon <= 0 || colon >= hostPort.length - 1) {
+            throw new Error('Invalid tcp:// format.')
+        }
+        const host = hostPort.substring(0, colon)
+        const portStr = hostPort.substring(colon + 1)
+        const port = parseInt(portStr, 10)
+        if (!Number.isFinite(port) || Number.isNaN(port)) {
+            throw new Error('Invalid port in tcp:// address.')
+        }
+        return new TcpConnectionData(host, port)
+    }
+}
+
+export { ConfigResolver }

package/lib/sdk/configuration/configResolvers/ConnectionStringConfigResolver.js

@@ -0,0 +1,119 @@
+// @ts-check
+
+import { Config } from '../Config.js'
+import { ConfigsDictionary } from '../ConfigsDictionary.js'
+import { ActivationHelper } from '../../tools/ActivationHelper.js'
+import { ConfigResolver } from './ConfigResolver.js'
+
+class ConnectionStringConfigResolver extends ConfigResolver {
+    /**
+     * Parse and add multiple configuration lines from a connection string source.
+     * @param {any} priority
+     * @param {string} connectionStringSource
+     */
+    static addConfigs(priority, connectionStringSource) {
+        if (!connectionStringSource || String(connectionStringSource).trim() === '') {
+            throw new Error('Connection string source cannot be null or empty.')
+        }
+
+        const normalized = String(connectionStringSource).replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+
+        const lines = normalized
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0)
+
+        for (const line of lines) {
+            if (line.startsWith('#') || line.startsWith('//')) {
+                continue
+            }
+            if (line.toLowerCase().startsWith('licensekey')) {
+                ConnectionStringConfigResolver._setLicenseKey(line)
+                continue
+            }
+
+            try {
+                const keyValues = ConnectionStringConfigResolver._parseKeyValues(line)
+                const configName = keyValues.name
+                const runtimeValue = keyValues.runtime
+
+                if (!configName || String(configName).trim() === '') {
+                    throw new Error('Missing or empty config name.')
+                }
+                if (!runtimeValue || String(runtimeValue).trim() === '') {
+                    throw new Error('Missing or empty runtime.')
+                }
+
+                const runtimeName = ConfigResolver.tryParseRuntime(runtimeValue)
+                const hostValue = keyValues.host
+                const connectionData = ConfigResolver.buildConnectionData(hostValue)
+                const plugins = keyValues.plugins || ''
+                const modules = keyValues.modules || ''
+
+                const config = new Config(runtimeName, connectionData, plugins, modules)
+                ConfigsDictionary.addConfig(configName, priority, config)
+            } catch (ex) {
+                console.log(`Failed to parse config line: '${line}'. Reason: ${ex}`)
+                throw ex
+            }
+        }
+    }
+
+    /**
+     * Extract and set temporary license key from a line like "licensekey=VALUE;..."
+     * @param {string} line
+     * @private
+     */
+    static _setLicenseKey(line) {
+        const eq = line.indexOf('=')
+        if (eq > 0 && eq < line.length - 1) {
+            let valuePortion = line.substring(eq + 1).trim()
+            const semicolon = valuePortion.indexOf(';')
+            if (semicolon >= 0) {
+                valuePortion = valuePortion.substring(0, semicolon).trim()
+            }
+            const hashIdx = valuePortion.indexOf('#')
+            if (hashIdx >= 0) {
+                valuePortion = valuePortion.substring(0, hashIdx).trim()
+            }
+            const slashes = valuePortion.indexOf('//')
+            if (slashes >= 0) {
+                valuePortion = valuePortion.substring(0, slashes).trim()
+            }
+            ActivationHelper.setTemporaryLicenseKey(valuePortion)
+        }
+    }
+
+    /**
+     * Parse semicolon-separated key=value tokens into an object.
+     * Ignores malformed tokens and logs them.
+     * @param {string} line
+     * @returns {Record<string, string>}
+     * @private
+     */
+    static _parseKeyValues(line) {
+        /** @type {Record<string, string>} */
+        const result = {}
+        const segments = line
+            .split(';')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+
+        for (const segment of segments) {
+            const eq = segment.indexOf('=')
+            if (eq <= 0 || eq === segment.length - 1) {
+                console.log(`Ignoring malformed token '${segment}' in line: ${line}`)
+                continue
+            }
+            const key = segment.substring(0, eq).trim().toLowerCase()
+            const value = segment.substring(eq + 1).trim()
+            if (key) {
+                result[key] = value
+            }
+        }
+
+        return result
+    }
+}
+
+export { ConnectionStringConfigResolver }

package/lib/sdk/configuration/configResolvers/JsonConfigResolver.js

@@ -0,0 +1,99 @@
+// @ts-check
+
+import { Config } from '../Config.js'
+import { ConfigsDictionary } from '../ConfigsDictionary.js'
+import { ConfigResolver } from './ConfigResolver.js'
+import { ActivationHelper } from '../../tools/ActivationHelper.js'
+
+class JsonConfigResolver extends ConfigResolver {
+    /**
+     * Parse and add configurations from a JSON object.
+     * @param {any} priority
+     * @param {Record<string, unknown>} jsonObject
+     */
+    static addConfigs(priority, jsonObject) {
+        if (jsonObject == null) {
+            throw new Error('json_object cannot be None')
+        }
+        if (typeof jsonObject !== 'object' || Array.isArray(jsonObject)) {
+            throw new Error('Root JSON element must be a dict/object.')
+        }
+
+        const licenseKey = /** @type {Record<string, unknown>} */ (jsonObject).licenseKey
+        if (typeof licenseKey === 'string') {
+            ActivationHelper.setTemporaryLicenseKey(licenseKey.trim())
+        }
+
+        const configs = /** @type {Record<string, unknown>} */ (jsonObject).configurations
+        if (typeof configs !== 'object' || configs == null || Array.isArray(configs)) {
+            throw new Error("JSON must contain 'configurations' object.")
+        }
+
+        for (const [configName, cfg] of Object.entries(/** @type {Record<string, unknown>} */ (configs))) {
+            try {
+                if (typeof cfg !== 'object' || cfg == null || Array.isArray(cfg)) {
+                    throw new Error('Configuration value must be an object/dict.')
+                }
+
+                const runtimeValue = JsonConfigResolver._getRequiredString(
+                    /** @type {Record<string, unknown>} */ (cfg),
+                    'runtime'
+                )
+                const runtimeName = ConfigResolver.tryParseRuntime(runtimeValue)
+
+                const host = JsonConfigResolver._getOptionalString(
+                    /** @type {Record<string, unknown>} */ (cfg),
+                    'host'
+                )
+                const connectionData = ConfigResolver.buildConnectionData(host)
+
+                const plugins = JsonConfigResolver._getOptionalString(
+                    /** @type {Record<string, unknown>} */ (cfg),
+                    'plugins'
+                )
+                const modules = JsonConfigResolver._getOptionalString(
+                    /** @type {Record<string, unknown>} */ (cfg),
+                    'modules'
+                )
+
+                const config = new Config(runtimeName, connectionData, plugins, modules)
+                ConfigsDictionary.addConfig(configName, priority, config)
+            } catch (ex) {
+                console.log(`Failed to add config '${configName}': ${ex}`)
+            }
+        }
+    }
+
+    /**
+     * Get a required string property from an object, trimmed.
+     * Throws if missing or empty.
+     * @param {Record<string, unknown>} obj
+     * @param {string} property
+     * @returns {string}
+     * @private
+     */
+    static _getRequiredString(obj, property) {
+        const value = obj[property]
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new Error(`Missing or invalid '${property}' property.`)
+        }
+        return value.trim()
+    }
+
+    /**
+     * Get an optional string property; return empty string when missing or not a string.
+     * @param {Record<string, unknown>} obj
+     * @param {string} property
+     * @returns {string}
+     * @private
+     */
+    static _getOptionalString(obj, property) {
+        const value = obj[property]
+        if (typeof value === 'string') {
+            return value
+        }
+        return ''
+    }
+}
+
+export { JsonConfigResolver }