{"id":18049,"library":"node-opcua-client-proxy","title":"OPC UA Client Proxy for Node.js","description":"The `node-opcua-client-proxy` package is a specialized module within the comprehensive `node-opcua` pure Node.js OPC UA SDK, currently at version 2.169.0. It provides functionalities for creating client-side proxies to interact with OPC UA servers, facilitating streamlined machine-to-machine (M2M) and Internet of Things (IoT) communication patterns. The `node-opcua` project maintains an active release cadence, with frequent updates focusing on stability, performance, and OPC UA specification compliance (e.g., full support for OPC UA 1.05 subtyped structures and unions). Recent releases have introduced features like advertised endpoints for Docker/NAT deployments and a global method-call interceptor API, alongside significant internal migrations from older libraries (`async`/`lodash`) to native modern JavaScript. Key differentiators include its robust TypeScript support, comprehensive certificate management capabilities, and continuous optimization for memory and throughput, particularly in its secure channel and transport layers. This specific module is designed to provide a structured and potentially higher-level abstraction for client interactions with the OPC UA address space, simplifying common operations.","status":"active","version":"2.169.0","language":"javascript","source_language":"en","source_url":"git://github.com/node-opcua/node-opcua","tags":["javascript","OPCUA","opcua","m2m","iot","opc ua","internet of things","typescript"],"install":[{"cmd":"npm install node-opcua-client-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add node-opcua-client-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-opcua-client-proxy","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary client entry point; typically imported from the main `node-opcua` package, as `node-opcua-client-proxy` usually builds upon it. ESM is the recommended import style.","wrong":"const OPCUAClient = require('node-opcua').OPCUAClient","symbol":"OPCUAClient","correct":"import { OPCUAClient } from 'node-opcua'"},{"note":"Represents an active, authenticated session with an OPC UA server. Similar to `OPCUAClient`, it's usually imported from the core `node-opcua` package.","wrong":"import { ClientSession } from 'node-opcua-client-proxy'","symbol":"ClientSession","correct":"import { ClientSession } from 'node-opcua'"},{"note":"The main class or interface provided by this specific `client-proxy` package, offering abstracted interaction with the OPC UA server via a session.","wrong":"const { ClientProxy } = require('node-opcua-client-proxy')","symbol":"ClientProxy","correct":"import { ClientProxy } from 'node-opcua-client-proxy'"},{"note":"A representative example of a utility function or method potentially exposed by the `ClientProxy` for simplified reading of OPC UA variable values.","symbol":"readVariableValue","correct":"import { readVariableValue } from 'node-opcua-client-proxy'"}],"quickstart":{"code":"import { OPCUAClient, MessageSecurityMode, SecurityPolicy, ClientSession, TimestampsToReturn, AttributeIds } from 'node-opcua';\nimport { ClientProxy } from 'node-opcua-client-proxy';\n\nconst endpointUrl = process.env.OPCUA_ENDPOINT_URL ?? 'opc.tcp://localhost:4840';\nconst userIdentity = {\n    userName: process.env.OPCUA_USERNAME ?? 'user',\n    password: process.env.OPCUA_PASSWORD ?? 'password'\n};\n\nasync function connectAndRead() {\n    const client = OPCUAClient.create({\n        endpointUrl: endpointUrl,\n        securityMode: MessageSecurityMode.None, // For demo purposes, consider stronger security in production\n        securityPolicy: SecurityPolicy.None,\n        // clientCertificateManager: provide a proper cert manager in production\n        connectionStrategy: { maxRetry: 5, initialDelay: 500, maxDelay: 3000 }\n    });\n\n    client.on('backoff', (retry, delay) => {\n        console.log(`Connection attempt failed. Retrying in ${delay / 1000}s (attempt ${retry})`);\n    });\n\n    let session: ClientSession | null = null;\n\n    try {\n        console.log(`Connecting to ${endpointUrl}...`);\n        await client.connect(endpointUrl);\n        console.log('Connected to OPC UA server.');\n\n        session = await client.createSession(userIdentity);\n        console.log(`Session created with id: ${session.sessionId.toString()}`);\n\n        // Instantiate the ClientProxy with the established session\n        const proxy = new ClientProxy(session); \n\n        // Example: Reading a specific node's value via the proxy (assuming proxy has a 'read' method)\n        const nodeIdToRead = 'ns=2;s=MyDevice/Temperature'; // Replace with a valid NodeId from your server\n        console.log(`Attempting to read NodeId: ${nodeIdToRead}`);\n\n        // Using session.read directly for now as proxy API is inferred\n        const dataValue = await session.read({\n            nodeId: nodeIdToRead,\n            attributeId: AttributeIds.Value,\n            timestampsToReturn: TimestampsToReturn.Both\n        });\n\n        if (dataValue.statusCode.isGood()) {\n            console.log(`Value of ${nodeIdToRead}: ${dataValue.value?.value} (Source Timestamp: ${dataValue.sourceTimestamp?.toISOString()})`);\n        } else {\n            console.error(`Failed to read ${nodeIdToRead}: ${dataValue.statusCode.toString()}`);\n        }\n\n    } catch (err) {\n        console.error('An error occurred during OPC UA communication:', err);\n    } finally {\n        if (session) {\n            await session.close();\n            console.log('Session closed.');\n        }\n        if (client) {\n            await client.disconnect();\n            console.log('Disconnected from OPC UA server.');\n        }\n    }\n}\n\nconnectAndRead();\n","lang":"typescript","description":"This quickstart demonstrates how to establish a connection to an OPC UA server, create a client session, and perform a basic read operation on a variable. It shows the setup of the `OPCUAClient`, session creation, and how `ClientProxy` might be instantiated, along with error handling and graceful disconnection. Remember to set `OPCUA_ENDPOINT_URL`, `OPCUA_USERNAME`, and `OPCUA_PASSWORD` environment variables."},"warnings":[{"fix":"Review any custom client implementations or extensions that might have implicitly relied on `async`/`lodash` internals. Refactor code to use standard ES features (e.g., `Promise`, `Array.prototype` methods). Ensure no internal typings from these deprecated libraries are still being used.","message":"Core packages in `node-opcua` have undergone a significant migration from relying on external libraries like `async` and `lodash` to utilizing native modern JavaScript patterns. While `node-opcua-client-proxy` primarily exposes a higher-level API, direct reliance on or interaction with any underlying `async`/`lodash` utilities (e.g., for internal data structures or callbacks) might require code adjustments.","severity":"breaking","affected_versions":">=2.168.0"},{"fix":"Ensure client-side certificate trust list management is up-to-date and correctly configured to process certificate chains. Consult the `node-opcua-pki` documentation for the latest certificate management APIs if building custom certificate handling solutions. Always test certificate-based connections thoroughly after upgrading.","message":"The certificate management architecture has been extensively refactored, particularly for server-side components like `PushCertificateManagerServerImpl` and `OPCUACertificateManager`. While `node-opcua-client-proxy` is client-focused, clients interacting with servers using the updated certificate handling, especially via GDS push models or requiring full certificate chain trust, should verify their trust list configuration.","severity":"gotcha","affected_versions":">=2.164.2"},{"fix":"Monitor resource usage (CPU, memory) and connection/data throughput in production environments after upgrading. Review any custom transport layer parameters, buffer management, or memory allocation strategies if unexpected behavior or resource issues arise.","message":"Significant performance and memory optimizations have been applied to core transport, secure channel, and chunk manager layers. While these generally improve efficiency, custom low-level client configurations, or those relying on specific memory usage profiles or timing characteristics of older versions, might experience subtle behavioral changes or require re-tuning.","severity":"gotcha","affected_versions":">=2.162.0"},{"fix":"Clients consuming `historyRead` results, especially for complex data types or those containing `ExtensionObject`s, must verify their data parsing logic to correctly handle the now-promoted `ExtensionObject` structures. Update any casting or type-checking logic as necessary.","message":"A bug fix in `v2.161.0` ensures that `historyRead` results correctly promote `OpaqueStructure` to `ExtensionObject` within `HistoryData`. If previous client logic had workarounds or incorrectly parsed `OpaqueStructure` from `historyRead` results, it will now receive the corrected `ExtensionObject` types, which could break existing data parsing.","severity":"breaking","affected_versions":">=2.161.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"To resolve this, you must configure the client's `clientCertificateManager` to explicitly trust the server's certificate. For development, you might temporarily set security mode to `None`, but this is not recommended for production environments.","cause":"The OPC UA client is attempting to establish a secure connection with a server that presents a self-signed certificate, which is not implicitly trusted by the client's certificate store.","error":"Error: self-signed certificate in certificate chain"},{"fix":"Verify that the `endpointUrl` is exact and corresponds to one advertised by the server. Use `OPCUAClient.getEndpoints()` to programmatically inspect available server endpoints and ensure your client's security settings (mode, policy) match a supported configuration.","cause":"The client attempted to connect to an endpoint URL with a security mode, security policy, or transport protocol that the target OPC UA server does not advertise or support. This can also indicate an incorrect endpoint URL format.","error":"Error: The provided endpoint is not supported"},{"fix":"Ensure you are using ES Module `import` syntax (`import { OPCUAClient } from 'node-opcua';`) and that your Node.js project is configured to run ES Modules (e.g., by adding `\"type\": \"module\"` to your `package.json` or using `.mjs` file extensions).","cause":"This error typically occurs when attempting to use CommonJS `require` syntax (`const { OPCUAClient} = require('node-opcua')`) with an ESM-only package or when mixing module systems incorrectly. The `node-opcua` library ecosystem primarily uses ES Modules.","error":"TypeError: OPCUAClient is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}