pure nodejs OPCUA SDK - module packet-assembler
npm install node-opcua-packet-assemblerA high-performance packet assembler for reassembling fragmented data from transport layers into complete message chunks. Features zero-copy optimization for maximum performance.
``bash`
npm install node-opcua-packet-assembler
`typescript
import { PacketAssembler } from "node-opcua-packet-assembler";
// Create assembler
const assembler = new PacketAssembler({
readChunkFunc: (data) => ({
length: data.readUInt32LE(4),
messageHeader: {
msgType: data.toString("ascii", 0, 4),
isFinal: "F",
length: data.readUInt32LE(4)
},
extra: ""
}),
minimumSizeInBytes: 8,
maxChunkSize: 65536
});
// Listen for complete chunks
assembler.on("chunk", (chunk) => {
console.log("Complete chunk:", chunk.length, "bytes");
processMessage(chunk);
});
// Feed data from transport
socket.on("data", (data) => assembler.feed(data));
`
- Single-chunk messages: Returns buffer views without copying (fast!)
- Multi-chunk messages: Concatenates fragments safely with Buffer.concat()
- Optimized for the common case where complete messages arrive in one buffer
`typescriptStarting chunk: ${packetInfo.length} bytes
// Track chunk assembly progress
assembler.on("startChunk", (packetInfo, partial) => {
console.log();
});
// Process complete chunks
assembler.on("chunk", (chunk) => {
handleMessage(chunk);
});
// Handle errors
assembler.on("error", (error, errorCode) => {
console.error("Assembly error:", error.message);
});
`
ā ļø When using zero-copy buffers, YOU are responsible for buffer lifetime management.
`typescript
assembler.on("chunk", (chunk) => {
// Option 1: Process immediately
const value = chunk.readUInt32LE(0);
console.log("Value:", value);
// Option 2: Make a copy if storing
const copy = Buffer.from(chunk);
messageQueue.push(copy);
});
`
`typescript
const storedChunks = [];
assembler.on("chunk", (chunk) => {
// UNSAFE! Transport may reuse this buffer
storedChunks.push(chunk);
});
`
Rule of thumb: If you store buffers beyond immediate processing or pass them to async handlers, create a copy with Buffer.from(chunk).
For complete API documentation with TypeScript types and detailed examples, see the source code JSDoc comments.
`typescript`
new PacketAssembler(options: PacketAssemblerOptions)
| Option | Type | Description |
| -------------------- | ------------------------------ | ----------------------- |
| readChunkFunc | (data: Buffer) => PacketInfo | Extract packet metadata |minimumSizeInBytes
| | number | Minimum header size |maxChunkSize
| | number | Maximum chunk size |
- feed(data: Buffer): Feed incoming data to the assembler
- "startChunk": (packetInfo, partial) => void - New chunk detected"chunk"
- : (chunk: Buffer) => void - Complete chunk assembled"error"
- : (error, errorCode) => void - Assembly error occurred
`typescript
import net from "net";
const server = net.createServer((socket) => {
const assembler = new PacketAssembler({
readChunkFunc: readHeader,
minimumSizeInBytes: 8,
maxChunkSize: 65536
});
assembler.on("chunk", handleMessage);
assembler.on("error", (err) => socket.destroy());
socket.on("data", (data) => assembler.feed(data));
});
`
`typescriptš¦ Expecting ${packetInfo.length} bytes
assembler.on("startChunk", (packetInfo) => {
console.log();
});
assembler.on("chunk", (chunk) => {
console.log(ā
Received ${chunk.length} bytes);`
});
`typescript
import { PacketAssemblerErrorCode } from "node-opcua-packet-assembler";
assembler.on("error", (error, errorCode) => {
if (errorCode === PacketAssemblerErrorCode.ChunkSizeExceeded) {
console.error("Chunk too large:", error.message);
}
});
`
1. Avoid unnecessary copies: The assembler already optimizes for zero-copy when possible
2. Set appropriate limits: Configure maxChunkSize based on your protocol needs
3. Process immediately: When safe, process chunks in the event handler for best performance
4. Only copy when needed: Create copies only when storing or passing to async handlers
Full TypeScript definitions included. All interfaces, types, and methods are fully documented with JSDoc comments in the source code.
`bash`
npm test
MIT
- node-opcua - Main package
- node-opcua-transport - Transport layernode-opcua-chunkmanager` - Message chunk management
-