@tier0/opcua-client 0.1.0

package/BENCHMARK.md

@@ -0,0 +1,83 @@
+# OPC UA client benchmark
+
+Recorded on 2026-08-05 in the Node-RED 4.1.2 container used for development, with Node.js 20.19.6, open62541 1.4.16, security mode `None`, and a Python OPC UA server running in the same container over loopback.
+
+The benchmark uses real OPC UA service calls. It browses every variable, reads and writes the full point set in batches of 500, creates one Subscription containing all MonitoredItems, waits for the final value of every point, and removes all MonitoredItems during cleanup.
+
+| Scenario | Browse | Read P50 | Write P50 / P95 | Subscribe | Notifications | Peak RSS |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| 1,000 points, 3 reads, 2 writes | 431 ms | 60 ms | 77 / 77 ms | 79 ms | 3,000 | 54.9 MB |
+| 5,000 points, 5 reads, 2 writes | 2,143 ms | 301 ms | 374 / 374 ms | 397 ms | 15,000 | 73.4 MB |
+| 5,000 points, 5 reads, 20 writes | 2,085 ms | 300 ms | 375 / 494 ms | 450 ms | 105,000 | 88.6 MB |
+| 10,000 points, 5 reads, 5 writes | 4,150 ms | 618 ms | 766 / 998 ms | 867 ms | 60,000 | 95.6 MB |
+
+All scenarios completed without bad OPC UA status codes. The sustained scenario converged to the final value for 5,000/5,000 points; the capacity scenario converged for 10,000/10,000 points.
+
+The 10,000-point throughput was approximately 2,410 browsed points/s, 16,183 read points/s, 13,063 written points/s, and 11,534 monitored items/s. Event-loop delay P95 was 20.7 ms and maximum delay was 56.2 ms.
+
+## Reproduce
+
+```bash
+OPCUA_STRESS_POINTS=10000 \
+OPCUA_STRESS_READ_ROUNDS=5 \
+OPCUA_STRESS_WRITE_ROUNDS=5 \
+OPCUA_STRESS_NOTIFY_TIMEOUT=180000 \
+npm run test:stress
+```
+
+These are local-loopback engineering baselines, not guarantees for a customer network. Production acceptance should repeat the same test against the target server, network latency, security policy, server OperationLimits, sampling interval, and expected value-change rate.
+
+## Node-RED deployed Flow baseline
+
+`npm run test:nodered` deploys a temporary isolated Flow into the running Node-RED editor. Requests travel through Node-RED HTTP In/Response, Function, Browse, Read, Write, and Subscribe node instances. Read receives an imported JSON point list and Write receives CSV directly, without a separate normalization node. The controller verifies final subscription convergence, clears the subscription, removes the temporary Flow, and asserts that the original Flow set is restored.
+
+| Scenario | Browse | Read P50 / P95 | Write P50 / P95 | Subscribe | Final convergence | Node-RED peak RSS |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| 100 points, smoke | 65 ms | 18 / 18 ms | 20 / 20 ms | 23 ms | 100/100 | 111.0 MB |
+| 1,000 points, direct JSON Read / CSV Write | 471 ms | 56 / 56 ms | 68 / 68 ms | 75 ms | 1,000/1,000 | 112.4 MB |
+| 5,000 points, 5 reads, 20 writes | 1,939 ms | 301 / 327 ms | 377 / 535 ms | 391 ms | 5,000/5,000 | 202.9 MB |
+| 10,000 points, 5 reads, 5 writes | 4,131 ms | 635 / 671 ms | 764 / 1,069 ms | 806 ms | 10,000/10,000 | 188.3 MB |
+
+The 5,000-point sustained Flow performed 100,000 writes. Its collector processed 101,001 post-setup data-change messages and converged every point to the final round. The 10,000-point Flow processed 51,000 post-setup messages and also converged every point. Initial subscription notifications can arrive before the collector receives the subscription-status message, so the reported notification total is not used as a loss assertion; final value convergence is the correctness gate.
+
+The Node-RED editor was opened during the 5,000-point run. The temporary tab showed the real nodes with `5000 points`, `5000 read`, and `5000 written` statuses before automatic cleanup.
+
+The selectable Browse tree endpoint was also exercised against the real fixture. The 1,000-point run returned 1,002 tree nodes containing exactly 1,000 variables. A saved three-variable selection produced exactly those three NodeIds from the deployed Browse node. In the editor, selecting the 100-point root selected 100/100 variables; clearing one leaf changed the count to 99/100 and placed both the area and root checkboxes into the half-selected state. Reopening the node retained all 99 selections.
+
+## Automatic reconnect and subscription reconstruction
+
+The fault-injection test deploys the same real Node-RED Flow, creates a 1,000-item subscription, stops the OPC UA fixture, waits while the connection supervisor replaces terminal clients with bounded backoff, restarts the server on the same endpoint, and requires the Subscribe node to validate and rebuild its lost server-side subscription before writes continue.
+
+The recorded run used three reconnect attempts and recovered in 3,458 ms. The Subscribe node rebuilt all 1,000/1,000 MonitoredItems. Two subsequent 1,000-point write rounds delivered all 3,000 notifications (including initial values), converged 1,000/1,000 final values, dropped zero changes, and reached a maximum native queue depth of 944. The temporary Flow was removed and the original Node-RED flow set was verified unchanged.
+
+## Native notification batching optimization
+
+The P0 optimization replaced one C++/JavaScript callback per value with a bounded native queue, batched callbacks, queue diagnostics, and zero-copy reuse of the native JavaScript change object in the Subscribe node. Both comparisons use Node-RED `batch` output mode.
+
+| Scenario | Metric | Before | After | Change |
+| --- | --- | ---: | ---: | ---: |
+| 5,000 points, 20 writes | Node-RED CPU | 4,110 ms | 2,050 ms | -50.1% |
+| 5,000 points, 20 writes | Peak RSS | 202.9 MB | 143.1 MB | -29.5% |
+| 5,000 points, 20 writes | Native callbacks | about 105,000 | 279 batches | -99.7% |
+| 10,000 points, 5 writes | Node-RED CPU | 3,540 ms | 2,570 ms | -27.4% |
+| 10,000 points, 5 writes | Peak RSS | 188.3 MB | 151.6 MB | -19.5% |
+| 10,000 points, 5 writes | Native callbacks | about 60,000 | 160 batches | -99.7% |
+
+In the optimized 5,000-point test, all 105,000 native notifications were delivered with zero drops, maximum native queue depth 1,667, and reported maximum batch lag 0.45 ms. In the optimized 10,000-point test, all 60,000 notifications were delivered with zero drops, maximum depth 1,526, and maximum lag 0.29 ms. Both tests converged every point to its final value.
+
+The native queue integration test also intentionally uses capacity 5 and batch size 2 while blocking JavaScript. It verifies a hard maximum depth of 5 and an explicit dropped count of 15. A separate `latest` test coalesces repeated values to one 20-item batch with zero drops.
+
+## OperationLimits and NodeId cache optimization
+
+The P1 optimization reads the four standard server limits in one request and adds a bounded per-connection native parsed-NodeId cache. The 5,000-point standalone test recorded 5,011 cache entries, 65,001 hits, 5,011 misses, zero bypasses, and approximately 92.8% hit rate. Browse improved from 2,143 ms to 1,991 ms in the recorded local run; Read P50 remained 301 ms and Write P50 remained within local-run variance at 376 ms.
+
+The optimized Node-RED Flow results were:
+
+| Scenario | Result | Cache | Node-RED CPU | Peak RSS |
+| --- | --- | --- | ---: | ---: |
+| 5,000 points, 5 reads, 20 writes | 105,000/105,000 notifications, 0 dropped, final 5,000/5,000 | 5,011 entries, 155,001 hits, 0 evictions | 1,990 ms | 139.1 MB |
+| 10,000 points, 5 reads, 5 writes | 60,000/60,000 notifications, 0 dropped, final 10,000/10,000 | 10,021 entries, 160,001 hits, 0 evictions | 2,120 ms | 155.3 MB warm process |
+
+Against the immediately preceding P0 runs, 5,000-point Node-RED CPU changed from 2,050 ms to 1,990 ms and peak RSS from 143.1 MB to 139.1 MB. The 10,000-point CPU changed from 2,570 ms to 2,120 ms. The 10,000-point P1 run followed the sustained 5,000-point run in the same Node-RED process, so its 155.3 MB peak is a warmed-process regression value and should not be compared directly with the fresh-process memory baseline.
+
+The native integration fixture also advertises all four OperationLimits as 7 and verifies that the client reads those exact values. Its cache capacity is intentionally reduced to 32; the test remains bounded at 32 entries and reports 118 FIFO evictions while Browse, Read, Write, Subscribe, and cleanup all pass.

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 loliuy/opcua-client contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,141 @@
+# @tier0/opcua-client
+
+High-scale OPC UA client nodes for Node-RED, backed by open62541 and designed for address spaces with thousands of points.
+
+## Nodes
+
+- `tier0-opcua-connection`: shared client session and credentials.
+- `tier0-opcua-browse`: recursive Browse plus a searchable, selectable address-space tree.
+- `tier0-opcua-read`: scalar-compatible batch Read with a manual/imported point list.
+- `tier0-opcua-write`: scalar-compatible batch Write with a manual/imported point list.
+- `tier0-opcua-subscribe`: one Subscription with many MonitoredItems.
+
+The OPC UA server remains a separate service. This package contains client and collection nodes only.
+
+## Point contract
+
+Browse output can be wired directly into Read or Subscribe. In the Read and Write editors, manually added and imported points appear in one editable list. Import accepts JSON/CSV, merges by NodeId, and immediately shows the parsed rows. Both nodes also accept arrays, JSON strings/buffers, or CSV strings/buffers dynamically:
+
+```json
+{
+  "payload": [
+    {
+      "nodeId": "ns=2;s=Line1.Temperature",
+      "alias": "line1.temperature",
+      "dataType": "Double",
+      "samplingInterval": 1000,
+      "queueSize": 10
+    }
+  ],
+  "opcua": {
+    "command": "replace"
+  }
+}
+```
+
+Subscription commands are `replace`, `add`, `remove`, and `clear`. Read and Write split large arrays into configurable service batches; they do not loop over scalar OPC UA requests.
+
+Subscription notifications use a bounded native C++ queue and cross into JavaScript in batches. The default mode preserves all changes, batches up to 500 values, and caps pending changes at 10,000. Queue options are:
+
+- `callbackBatchSize`: maximum changes per C++ to JavaScript callback.
+- `callbackQueueSize`: hard native queue capacity.
+- `queueMode`: `all` preserves pending changes; `latest` coalesces by MonitoredItem.
+- `overflowPolicy`: `drop-oldest` or `drop-newest` when the hard capacity is reached.
+- `outputMode`: `batch` sends one Node-RED message per native batch; `single` preserves one message per change compatibility.
+
+Every batch includes queue diagnostics in `msg.opcua.queue`, including depth, capacity, maximum depth, enqueued, delivered, dropped, coalesced, batch sequence, and maximum queue lag. Queue overflow is also reported through the node status and warning log; it is never silent.
+
+## Adaptive batching and NodeId cache
+
+Each connection reads the server's standard OperationLimits in one OPC UA Read request after the session is activated. Read, Write, monitored-item creation/removal, and Browse attribute reads automatically use the smaller of the configured batch size and the advertised server limit. A missing or zero limit means unknown/unlimited and preserves the configured batch size. Browse attribute requests are flattened before batching, so even a `MaxNodesPerRead` smaller than the five requested metadata attributes is respected exactly.
+
+Parsed NodeIds are cached per connection in native code. The default capacity is 100,000 entries and is configurable as `NodeId cache size` on the Connection node. The cache uses bounded FIFO eviction, is cleared naturally on reconnect, and can be disabled with capacity `0`. Read and Write batch outputs expose live data through `msg.opcua.clientDiagnostics`; library users can call `client.getDiagnostics()`. Diagnostics include OperationLimits plus cache size, capacity, hits, misses, bypasses, and evictions.
+
+## Connection and subscription recovery
+
+The native client reports secure-channel, session, connectivity-check, and subscription-inactivity transitions to a JavaScript connection supervisor. Recoverable channel interruptions keep the native client alive. Terminal failures replace the native client and retry with exponential backoff, 20% jitter, and the configured maximum interval. Operations fail fast with `OPCUA_RECONNECTING` while the connection is unavailable instead of building an unbounded request queue.
+
+Subscribe nodes retain a desired point map independently from the live server subscription. After reconnection they serialize reconciliation, validate the old subscription, rebuild it when the server session was lost, and recreate missing MonitoredItems in service-sized batches. A recovery status message has `msg.opcua.operation = "subscription-status"`, `recovered`, `rebuilt`, `reason`, and `dataGapPossible`. `dataGapPossible` is true after a subscription rebuild because values may have changed while the server was unavailable.
+
+Connection diagnostics also expose the current channel/session state and supervisor counters: client generation, reconnect attempts/successes, terminal replacements, and last recovery duration.
+
+Read CSV point lists require a `nodeId` header. Write CSV uses `nodeId,value,dataType`; `dataType` is optional when the Write node supplies a default. Other supported descriptor columns include `alias`, `samplingInterval`, `queueSize`, `deadbandType`, and `deadbandValue`.
+
+```csv
+nodeId,value,dataType
+ns=2;s=Line1.Speed,1200,Double
+ns=2;s=Line1.Enabled,true,Boolean
+```
+
+An incoming point list takes priority over the point list saved in the node. Existing flows that stored a single static NodeId are migrated into the visible list when their editor is opened. A migrated Write item keeps using its incoming `msg.payload`; imported Write rows normally carry `nodeId`, `value`, and optional `dataType`.
+
+## Browse tree selection
+
+The Browse editor loads the address space through the deployed Connection node. Object nodes act as folders and Variable nodes are selectable outputs. Checking a parent selects every variable below it; clearing an individual child changes every affected ancestor to the half-selected state. The editor shows the selected/total variable count and provides branch expansion, name/path/NodeId filtering, Select all, and Clear actions.
+
+The selected Variable descriptors are saved with the Browse node. Each input message outputs the full saved selection so it can be wired directly into Read or Subscribe. Send `msg.opcua.liveBrowse = true` when a flow needs to ignore the saved selection and perform a new live Browse.
+
+Node editors show only the standard settings by default. Connection security/timeouts/cache, Browse limits/paging, Read/Write batching/output, and Subscribe queue/deadband tuning remain available under a closed **Advanced settings** section. Existing flows retain their stored advanced values.
+
+## Build
+
+Linux build prerequisites are a C/C++ compiler, CMake, Python, and Git.
+
+```bash
+npm install
+npm test
+```
+
+`npm install` builds the pinned open62541 release first and then compiles the N-API addon. To rebuild only the native layer after changing C++ code, run `npm run build`.
+
+The open62541 build is static and position-independent so the resulting N-API addon does not need a runtime open62541 shared library.
+
+Security mode `None` is supported in the first implementation slice. Sign and SignAndEncrypt are visible in the connection model but require an encryption-enabled open62541 build and certificate trust-store integration before production use.
+
+## Native integration test
+
+The fixture requires Python package `opcua==0.98.13`:
+
+```bash
+python3 -m venv .build/test-venv
+.build/test-venv/bin/pip install opcua==0.98.13
+PATH="$PWD/.build/test-venv/bin:$PATH" npm run test:native
+```
+
+## Stress test
+
+The stress test starts a real writable OPC UA server, browses the complete address space, performs repeated batched reads and writes, creates one Subscription containing all MonitoredItems, verifies change delivery for every point, and reports latency, throughput, memory, CPU, and event-loop delay.
+
+```bash
+OPCUA_STRESS_POINTS=5000 \
+OPCUA_STRESS_READ_ROUNDS=5 \
+OPCUA_STRESS_WRITE_ROUNDS=2 \
+npm run test:stress
+```
+
+The point count, read/write rounds, service batch size, port, and notification timeout are configurable with the `OPCUA_STRESS_*` environment variables used in `test/stress.js`.
+
+For a strict Node-RED runtime test, `test:nodered` deploys a temporary isolated Flow into a running editor, triggers the real nodes through HTTP, records Node-RED process memory/CPU, and removes the Flow afterward while verifying that the original flow set is unchanged:
+
+```bash
+OPCUA_NODERED_POINTS=5000 npm run test:nodered
+```
+
+To inject a real server outage after subscription creation, restart the fixture, require automatic subscription reconstruction, and then verify every point converges through the deployed Node-RED nodes:
+
+```bash
+OPCUA_NODERED_POINTS=1000 npm run test:nodered:reconnect
+```
+
+See [BENCHMARK.md](BENCHMARK.md) for the recorded 1,000, 5,000, sustained 5,000, and 10,000 point baselines.
+
+## Scale defaults
+
+- Browse limit: 10,000 returned points.
+- Attribute read batch: 200 points.
+- Read/Write service batch: 500 points.
+- MonitoredItem creation batch: 500 points.
+- Subscription callback queue: 10,000 pending changes.
+- Parsed NodeId cache: 100,000 entries per connection.
+
+Configured service batches are automatically clamped to the server's advertised OperationLimits.

package/binding.gyp

@@ -0,0 +1,24 @@
+{
+  "targets": [
+    {
+      "target_name": "opcua_open62541",
+      "sources": ["src/addon.cc"],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "<!(node -e \"const path=require('path');console.log(process.env.OPEN62541_PREFIX||path.join(process.cwd(),'.build','open62541'))\")/include"
+      ],
+      "libraries": [
+        "-L<!(node -e \"const path=require('path');console.log(process.env.OPEN62541_PREFIX||path.join(process.cwd(),'.build','open62541'))\")/lib",
+        "-lopen62541"
+      ],
+      "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"],
+      "defines": ["NAPI_CPP_EXCEPTIONS"],
+      "cflags!": ["-fno-exceptions"],
+      "cflags_cc!": ["-fno-exceptions"],
+      "cflags_cc": ["-std=c++20"],
+      "conditions": [
+        ["OS=='linux'", {"libraries": ["-lpthread", "-lm"]}]
+      ]
+    }
+  ]
+}

package/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = {
+  points: require('./lib/points'),
+};

package/lib/browse-tree.js

@@ -0,0 +1,55 @@
+'use strict';
+
+function cleanBrowseNode(item) {
+  const node = { ...(item || {}) };
+  delete node.children;
+  return node;
+}
+
+function buildBrowseTree(items, rootNodeId = 'ns=0;i=85') {
+  if (!Array.isArray(items)) throw new Error('Browse result must be an array');
+  const root = {
+    nodeId: rootNodeId,
+    parentNodeId: '',
+    browseName: rootNodeId,
+    displayName: rootNodeId,
+    browsePath: '',
+    nodeClass: 'Root',
+    children: [],
+  };
+  const byId = new Map([[rootNodeId, root]]);
+
+  for (const item of items) {
+    if (!item?.nodeId || item.nodeId === rootNodeId || byId.has(item.nodeId)) continue;
+    byId.set(item.nodeId, { ...cleanBrowseNode(item), children: [] });
+  }
+  for (const node of byId.values()) {
+    if (node === root) continue;
+    const parent = byId.get(node.parentNodeId);
+    (parent && parent !== node ? parent : root).children.push(node);
+  }
+  return root;
+}
+
+function flattenBrowseTree(root) {
+  const output = [];
+  const visit = (node) => {
+    if (node.nodeClass !== 'Root') output.push(cleanBrowseNode(node));
+    for (const child of node.children || []) visit(child);
+  };
+  visit(root);
+  return output;
+}
+
+function selectedVariables(items) {
+  if (!Array.isArray(items)) return [];
+  const selected = new Map();
+  for (const item of items) {
+    if (item?.nodeId && item.nodeClass === 'Variable') {
+      selected.set(item.nodeId, cleanBrowseNode(item));
+    }
+  }
+  return [...selected.values()];
+}
+
+module.exports = { buildBrowseTree, cleanBrowseNode, flattenBrowseTree, selectedVariables };

package/lib/client.js

@@ -0,0 +1,321 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const { chunks } = require('./points');
+const { loadAddon } = require('./native');
+
+function normalizeNotificationBatch(notification) {
+  if (notification && Array.isArray(notification.changes)) {
+    if (!notification.diagnostics) notification.diagnostics = {};
+    return notification;
+  }
+  return {
+    changes: notification == null ? [] : [notification],
+    diagnostics: {},
+  };
+}
+
+function effectiveBatchSize(requested, serverLimit) {
+  const configured = Number.isFinite(Number(requested)) && Number(requested) > 0
+    ? Math.floor(Number(requested))
+    : 500;
+  const limit = Number(serverLimit);
+  return Number.isFinite(limit) && limit > 0
+    ? Math.min(configured, Math.floor(limit))
+    : configured;
+}
+
+class OpcUaClient extends EventEmitter {
+  constructor(options) {
+    super();
+    this.options = { ...options };
+    this.handle = null;
+    this.connecting = null;
+    this.closed = false;
+    this.connectionState = 'idle';
+    this.connectionToken = 0;
+    this.reconnectTimer = null;
+    this.reconnectAttempt = 0;
+    this.supervisorDiagnostics = {
+      clientGeneration: 0,
+      reconnectAttempts: 0,
+      reconnectSuccesses: 0,
+      terminalReplacements: 0,
+      reconnectStartedAt: null,
+      lastReconnectDurationMs: 0,
+    };
+    this.lastState = {
+      state: 'idle',
+      connected: false,
+      statusCode: 'Good',
+    };
+    this.diagnostics = {
+      operationLimits: {},
+      nodeIdCache: {},
+      connection: {},
+    };
+  }
+
+  async connect() {
+    if (this.closed) throw new Error('OPC UA client is closed');
+    if (this.handle != null) {
+      if (this.connectionState === 'connected') return this.handle;
+      const error = new Error(`OPC UA client is ${this.connectionState}`);
+      error.code = 'OPCUA_RECONNECTING';
+      throw error;
+    }
+    if (this.connecting) return this.connecting;
+
+    this.connecting = this.#connect();
+    try {
+      return await this.connecting;
+    } finally {
+      this.connecting = null;
+      if (!this.closed && this.handle == null && this.connectionState === 'failed') {
+        this.#scheduleReconnect();
+      }
+    }
+  }
+
+  async #connect() {
+    const addon = loadAddon();
+    const token = ++this.connectionToken;
+    this.connectionState = 'connecting';
+    let handle;
+    try {
+      handle = await addon.connectAsync(
+        this.options,
+        (state) => this.#onNativeState(token, state)
+      );
+    } catch (error) {
+      if (token === this.connectionToken && !this.closed) {
+        this.connectionState = 'failed';
+        this.lastState = {
+          state: 'failed', connected: false, terminal: true,
+          statusCode: error.message, reason: 'connect-failed',
+        };
+        this.emit('state', this.lastState);
+        this.emit('fault', error);
+        this.#scheduleReconnect();
+      }
+      throw error;
+    }
+    if (this.closed || token !== this.connectionToken) {
+      await addon.disconnectAsync(handle).catch(() => {});
+      throw new Error('OPC UA connection attempt was superseded');
+    }
+    this.handle = handle;
+    this.supervisorDiagnostics.clientGeneration = token;
+    if (this.supervisorDiagnostics.reconnectStartedAt != null) {
+      this.supervisorDiagnostics.reconnectSuccesses += 1;
+      this.supervisorDiagnostics.lastReconnectDurationMs =
+        Date.now() - this.supervisorDiagnostics.reconnectStartedAt;
+      this.supervisorDiagnostics.reconnectStartedAt = null;
+    }
+    this.#refreshDiagnostics();
+    if (this.connectionState !== 'connected') {
+      this.connectionState = 'connected';
+      this.lastState = {
+        state: 'connected', connected: true, terminal: false,
+        statusCode: 'Good', reason: 'connect-complete',
+        sessionGeneration: this.diagnostics.connection?.sessionGeneration || 1,
+      };
+      this.emit('state', this.lastState);
+    }
+    this.reconnectAttempt = 0;
+    return handle;
+  }
+
+  async disconnect() {
+    this.closed = true;
+    this.connectionState = 'closing';
+    this.connectionToken += 1;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    const connecting = this.connecting;
+    if (connecting) {
+      try { await connecting; } catch {}
+    }
+    const handle = this.handle;
+    this.handle = null;
+    if (handle != null) {
+      try {
+        await loadAddon().disconnectAsync(handle);
+      } finally {
+        this.connectionState = 'closed';
+      }
+    }
+    this.lastState = { state: 'closed', connected: false, statusCode: 'Good' };
+    this.emit('state', this.lastState);
+  }
+
+  async browse(options) {
+    return this.#invoke('browseAsync', options);
+  }
+
+  async readMany(points, batchSize = 500) {
+    const results = [];
+    await this.connect();
+    const effective = effectiveBatchSize(
+      batchSize, this.diagnostics.operationLimits?.maxNodesPerRead
+    );
+    for (const batch of chunks(points, effective)) {
+      results.push(...await this.#invoke('readManyAsync', batch));
+    }
+    return results;
+  }
+
+  async writeMany(points, batchSize = 500) {
+    const results = [];
+    await this.connect();
+    const effective = effectiveBatchSize(
+      batchSize, this.diagnostics.operationLimits?.maxNodesPerWrite
+    );
+    for (const batch of chunks(points, effective)) {
+      results.push(...await this.#invoke('writeManyAsync', batch));
+    }
+    return results;
+  }
+
+  async createSubscription(options, callback) {
+    return this.#invoke('createSubscriptionAsync', options, (notification) => {
+      callback(normalizeNotificationBatch(notification));
+    });
+  }
+
+  async addMonitoredItems(subscriptionId, points, options, batchSize = 500) {
+    const results = [];
+    await this.connect();
+    const effective = effectiveBatchSize(
+      batchSize, this.diagnostics.operationLimits?.maxMonitoredItemsPerCall
+    );
+    for (const batch of chunks(points, effective)) {
+      results.push(...await this.#invoke(
+        'addMonitoredItemsAsync', subscriptionId, batch, options
+      ));
+    }
+    return results;
+  }
+
+  async removeMonitoredItems(subscriptionId, monitoredItemIds, batchSize = 500) {
+    const results = [];
+    await this.connect();
+    const effective = effectiveBatchSize(
+      batchSize, this.diagnostics.operationLimits?.maxMonitoredItemsPerCall
+    );
+    for (const batch of chunks(monitoredItemIds, effective)) {
+      results.push(...await this.#invoke('removeMonitoredItemsAsync', subscriptionId, batch));
+    }
+    return results;
+  }
+
+  async deleteSubscription(subscriptionId) {
+    return this.#invoke('deleteSubscriptionAsync', subscriptionId);
+  }
+
+  async validateSubscription(subscriptionId) {
+    return this.#invoke('validateSubscriptionAsync', subscriptionId);
+  }
+
+  getState() {
+    return { ...this.lastState };
+  }
+
+  getDiagnostics() {
+    this.#refreshDiagnostics();
+    return this.diagnostics;
+  }
+
+  #refreshDiagnostics() {
+    if (this.handle == null) return;
+    const addon = loadAddon();
+    if (typeof addon.getClientDiagnostics !== 'function') return;
+    try {
+      const nativeDiagnostics = addon.getClientDiagnostics(this.handle) || {};
+      this.diagnostics = {
+        ...nativeDiagnostics,
+        connection: {
+          ...(nativeDiagnostics.connection || {}),
+          supervisor: { ...this.supervisorDiagnostics },
+        },
+      };
+    } catch {
+      // The connection may have closed between reading the handle and querying diagnostics.
+    }
+  }
+
+  #onNativeState(token, state) {
+    if (this.closed || token !== this.connectionToken || !state) return;
+    if (state.state === 'subscription-inactive') {
+      this.emit('state', { ...state, clientGeneration: token });
+      return;
+    }
+    this.connectionState = state.state || (state.connected ? 'connected' : 'reconnecting');
+    this.lastState = { ...state, clientGeneration: token };
+    this.emit('state', this.lastState);
+    if (state.connected) {
+      this.reconnectAttempt = 0;
+      this.#refreshDiagnostics();
+    } else if (state.terminal) {
+      void this.#replaceTerminalClient(token, state);
+    }
+  }
+
+  async #replaceTerminalClient(token, state) {
+    if (this.closed || token !== this.connectionToken) return;
+    this.connectionToken += 1;
+    this.supervisorDiagnostics.terminalReplacements += 1;
+    const handle = this.handle;
+    this.handle = null;
+    this.connectionState = 'failed';
+    if (handle != null) {
+      try { await loadAddon().disconnectAsync(handle); } catch {}
+    }
+    if (!this.closed) {
+      const error = new Error(`OPC UA connection failed: ${state.statusCode || 'Unknown'}`);
+      error.code = 'OPCUA_CONNECTION_FAILED';
+      this.emit('fault', error);
+      this.#scheduleReconnect();
+    }
+  }
+
+  #scheduleReconnect() {
+    if (this.closed || this.reconnectTimer || this.connecting) return;
+    const base = Math.max(100, Number(this.options.reconnectInterval) || 5000);
+    const maximum = Math.max(base, Number(this.options.maxReconnectInterval) || 30000);
+    const exponential = Math.min(maximum, base * (2 ** this.reconnectAttempt));
+    const jitter = 0.8 + Math.random() * 0.4;
+    const delay = Math.max(100, Math.round(exponential * jitter));
+    this.reconnectAttempt += 1;
+    this.supervisorDiagnostics.reconnectAttempts += 1;
+    if (this.supervisorDiagnostics.reconnectStartedAt == null) {
+      this.supervisorDiagnostics.reconnectStartedAt = Date.now();
+    }
+    this.connectionState = 'backoff';
+    this.lastState = {
+      state: 'backoff', connected: false, recoverable: true,
+      reason: 'new-client', attempt: this.reconnectAttempt, delay,
+    };
+    this.emit('state', this.lastState);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect().catch(() => {});
+    }, delay);
+  }
+
+  async #invoke(method, ...args) {
+    const handle = await this.connect();
+    try {
+      return await loadAddon()[method](handle, ...args);
+    } catch (error) {
+      if (/disconnect|connection|session|channel/i.test(error.message)) {
+        this.emit('fault', error);
+      }
+      throw error;
+    }
+  }
+}
+
+module.exports = { OpcUaClient, effectiveBatchSize, normalizeNotificationBatch };