# node-opcua-packet-assembler

> pure nodejs OPCUA SDK - module packet-assembler

Latest version **2.187.0** (published 2026-10-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-opcua-packet-assembler
pnpm add node-opcua-packet-assembler
yarn add node-opcua-packet-assembler
bun add node-opcua-packet-assembler
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.187.0 |
| Published | 2026-10-08 |
| First published | 2017-09-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.13.0 |
| Dependencies | 2 |
| Unpacked size | 42.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1664 |
| Author | Etienne Rossignon |
| Maintainers | erossignon |
| Keywords | OPCUA, opcua, m2m, iot, opc ua, internet of things |

## Links

- npm: https://www.npmjs.com/package/node-opcua-packet-assembler
- Repository: https://github.com/node-opcua/node-opcua
- Homepage: http://node-opcua.github.io/
- Issues: https://github.com/node-opcua/node-opcua/issues
- npm.io page: https://npm.io/package/node-opcua-packet-assembler

## Dependencies (2)

- [node-opcua-debug](https://npm.io/package/node-opcua-debug.md) 2.186.7
- [node-opcua-assert](https://npm.io/package/node-opcua-assert.md) 2.186.7

## Recent versions

- 2.187.0 (latest) — 2026-10-08
- 0.1.0-alpha.a272cdc2 (canary) — 2017-09-13
- 2.186.10 — 2026-09-29
- 2.186.7 — 2026-09-28
- 2.186.4 — 2026-09-25
- 2.186.1 — 2026-09-21
- 2.185.0 — 2026-09-19
- 2.184.1 — 2026-09-14
- 2.184.0 — 2026-09-14
- 2.183.0 — 2026-09-10
- 2.182.0 — 2026-09-08
- 2.181.0 — 2026-09-05
- 2.179.0 — 2026-08-27
- 2.175.6 — 2026-07-30
- 2.175.1 — 2026-07-13
- … 95 more at https://npm.io/package/node-opcua-packet-assembler/versions

## README

# node-opcua-packet-assembler

A high-performance packet assembler for reassembling fragmented data from transport layers into complete message chunks. Features **zero-copy optimization** for maximum performance.

## Installation

```bash
npm install node-opcua-packet-assembler
```

## Quick Start

```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));
```

## Key Features

### Zero-Copy Performance

- **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

### Event-Driven API

```typescript
// Track chunk assembly progress
assembler.on("startChunk", (packetInfo, partial) => {
    console.log(`Starting chunk: ${packetInfo.length} bytes`);
});

// Process complete chunks
assembler.on("chunk", (chunk) => {
    handleMessage(chunk);
});

// Handle errors
assembler.on("error", (error, errorCode) => {
    console.error("Assembly error:", error.message);
});
```

## Important: Buffer Lifetime

⚠️ **When using zero-copy buffers, YOU are responsible for buffer lifetime management.**

### ✅ Safe Usage

```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);
});
```

### ❌ Unsafe Usage

```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)`.

## API Overview

For complete API documentation with TypeScript types and detailed examples, see the source code JSDoc comments.

### Constructor

```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      |

### Methods

- **`feed(data: Buffer)`**: Feed incoming data to the assembler

### Events

- **`"startChunk"`**: `(packetInfo, partial) => void` - New chunk detected
- **`"chunk"`**: `(chunk: Buffer) => void` - Complete chunk assembled
- **`"error"`**: `(error, errorCode) => void` - Assembly error occurred

## Common Patterns

### TCP Socket Integration

```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));
});
```

### With Progress Tracking

```typescript
assembler.on("startChunk", (packetInfo) => {
    console.log(`📦 Expecting ${packetInfo.length} bytes`);
});

assembler.on("chunk", (chunk) => {
    console.log(`✅ Received ${chunk.length} bytes`);
});
```

## Error Handling

```typescript
import { PacketAssemblerErrorCode } from "node-opcua-packet-assembler";

assembler.on("error", (error, errorCode) => {
    if (errorCode === PacketAssemblerErrorCode.ChunkSizeExceeded) {
        console.error("Chunk too large:", error.message);
    }
});
```

## Performance Tips

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

## TypeScript Support

Full TypeScript definitions included. All interfaces, types, and methods are fully documented with JSDoc comments in the source code.

## Testing

```bash
npm test
```

## License

MIT

## Related Packages

- [node-opcua](https://github.com/node-opcua/node-opcua) - Main package
- `node-opcua-transport` - Transport layer
- `node-opcua-chunkmanager` - Message chunk management

---
_Source: https://npm.io/package/node-opcua-packet-assembler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._