node-opcua-packet-assembler 2.153.0 → 2.162.0

package/README.md

@@ -0,0 +1,195 @@
+# 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

package/dist/packet_assembler.d.ts

@@ -1,22 +1,51 @@
 import { EventEmitter } from "events";
+/**
+ * Message header information extracted from packet data.
+ */
 export interface MessageHeader {
+    /** Message type identifier (e.g., "MSG", "OPN", "CLO") */
     msgType: string;
+    /** Final chunk indicator ("F" for final, "C" for continuation) */
     isFinal: string;
+    /** Total message length in bytes */
     length: number;
 }
+/**
+ * Packet metadata extracted from incoming data.
+ */
 export interface PacketInfo {
+    /** Total expected packet length in bytes */
     length: number;
+    /** Message header information */
     messageHeader: MessageHeader;
+    /** Additional protocol-specific metadata */
     extra: string;
 }
+/**
+ * Function type for extracting packet metadata from buffer data.
+ *
+ * @param data - Buffer containing at least minimumSizeInBytes of data
+ * @returns Packet metadata including expected length and headers
+ */
 export type ReadChunkFuncType = (data: Buffer) => PacketInfo;
+/**
+ * Configuration options for PacketAssembler.
+ */
 export interface PacketAssemblerOptions {
+    /** Function to extract packet metadata from incoming data */
     readChunkFunc: ReadChunkFuncType;
+    /** Minimum bytes required before readChunkFunc can be called (typically header size) */
     minimumSizeInBytes: number;
+    /** Maximum allowed chunk size in bytes (chunks exceeding this will trigger an error) */
     maxChunkSize: number;
 }
+/**
+ * Error codes for packet assembly failures.
+ */
 export declare enum PacketAssemblerErrorCode {
+    /** Chunk size exceeds configured maxChunkSize */
     ChunkSizeExceeded = 1,
+    /** Chunk size is smaller than minimumSizeInBytes */
     ChunkTooSmall = 2
 }
 export interface PacketAssembler {
@@ -25,8 +54,64 @@ export interface PacketAssembler {
     on(eventName: "error", eventHandler: (err: Error, errCode: PacketAssemblerErrorCode) => void): this;
 }
 /**
- * this class is used to assemble partial data from the transport layer
- * into message chunks
+ * Assembles fragmented data from transport layers into complete message chunks.
+ *
+ * ## Zero-Copy Optimization
+ *
+ * The PacketAssembler uses zero-copy optimization for performance:
+ * - **Single-chunk messages**: Returns a view of the input buffer (no allocation, no copy)
+ * - **Multi-chunk messages**: Creates a new buffer via Buffer.concat() (safe copy)
+ *
+ * ## Buffer Lifetime Management
+ *
+ * **Important**: When receiving single-chunk messages, the returned buffer is a view of the
+ * input buffer. Consumers are responsible for creating copies if they need buffers that
+ * survive beyond immediate processing or if the transport layer reuses buffers.
+ *
+ * ### Safe Usage:
+ * ```typescript
+ * assembler.on("chunk", (chunk) => {
+ *   // Option 1: Process immediately (safe)
+ *   const value = chunk.readUInt32LE(0);
+ *
+ *   // Option 2: Create a copy for later use
+ *   const copy = Buffer.from(chunk);
+ *   queue.push(copy);
+ * });
+ * ```
+ *
+ * ### Unsafe Usage:
+ * ```typescript
+ * const chunks = [];
+ * assembler.on("chunk", (chunk) => {
+ *   // UNSAFE: chunk may be reused by transport layer
+ *   chunks.push(chunk);
+ * });
+ * ```
+ *
+ * @fires PacketAssembler#startChunk - Emitted when a new chunk begins
+ * @fires PacketAssembler#chunk - Emitted when a complete chunk is assembled
+ * @fires PacketAssembler#error - Emitted on assembly errors
+ *
+ * @example
+ * ```typescript
+ * const assembler = new PacketAssembler({
+ *   readChunkFunc: (data) => ({
+ *     length: data.readUInt32LE(4),
+ *     messageHeader: { msgType: "MSG", isFinal: "F", length: data.readUInt32LE(4) },
+ *     extra: ""
+ *   }),
+ *   minimumSizeInBytes: 8,
+ *   maxChunkSize: 65536
+ * });
+ *
+ * assembler.on("chunk", (chunk) => {
+ *   console.log("Complete chunk:", chunk.length, "bytes");
+ * });
+ *
+ * // Feed data from transport
+ * socket.on("data", (data) => assembler.feed(data));
+ * ```
  */
 export declare class PacketAssembler extends EventEmitter {
     static defaultMaxChunkCount: number;
@@ -38,8 +123,63 @@ export declare class PacketAssembler extends EventEmitter {
     private readonly readChunkFunc;
     private readonly minimumSizeInBytes;
     private packetInfo?;
+    /**
+     * Creates a new PacketAssembler instance.
+     *
+     * @param options - Configuration options for the assembler
+     * @param options.readChunkFunc - Function to extract packet metadata from buffer
+     * @param options.minimumSizeInBytes - Minimum bytes needed to read packet header (default: 8)
+     * @param options.maxChunkSize - Maximum allowed chunk size (default: 65529)
+     *
+     * @throws {Error} If readChunkFunc is not a function
+     * @throws {Error} If maxChunkSize is less than minimumSizeInBytes
+     */
     constructor(options: PacketAssemblerOptions);
+    /**
+     * Feeds incoming data to the assembler for processing.
+     *
+     * This method can be called multiple times with partial data. The assembler will
+     * buffer incomplete chunks and emit the "chunk" event when a complete message
+     * has been assembled.
+     *
+     * ## Zero-Copy Behavior
+     *
+     * - If the data contains a complete single chunk, it returns a **view of the input buffer**
+     *   (zero-copy optimization)
+     * - If multiple fragments are needed, it creates a **new buffer** via Buffer.concat()
+     *   (safe copy)
+     *
+     * @param data - Buffer containing incoming data (can be partial or complete chunks)
+     *
+     * @fires startChunk - When a new chunk header is detected
+     * @fires chunk - When a complete chunk has been assembled
+     * @fires error - If chunk size validation fails
+     *
+     * @example
+     * ```typescript
+     * // Feed data as it arrives from transport
+     * socket.on("data", (data) => {
+     *   assembler.feed(data);
+     * });
+     * ```
+     */
     feed(data: Buffer): void;
     private _readPacketInfo;
+    /**
+     * Builds the final chunk buffer from accumulated fragments.
+     *
+     * ## Zero-Copy Implementation
+     *
+     * This method implements the zero-copy optimization:
+     * - **Single chunk** (data provided, stack empty): Returns the input buffer directly (zero-copy)
+     * - **Single buffered chunk** (no data, one item in stack): Returns the stacked buffer
+     * - **Multiple fragments**: Concatenates all fragments into a new buffer (safe copy)
+     *
+     * @param data - Current buffer fragment (may be null)
+     * @returns Complete chunk buffer (either view or new buffer)
+     *
+     * @private
+     * @internal
+     */
     private _buildData;
 }

package/dist/packet_assembler.js

@@ -6,16 +6,97 @@ const node_opcua_assert_1 = require("node-opcua-assert");
 const node_opcua_debug_1 = require("node-opcua-debug");
 const doDebug = false;
 const warningLog = (0, node_opcua_debug_1.make_warningLog)("PacketAssembler");
+/**
+ * Error codes for packet assembly failures.
+ */
 var PacketAssemblerErrorCode;
 (function (PacketAssemblerErrorCode) {
+    /** Chunk size exceeds configured maxChunkSize */
     PacketAssemblerErrorCode[PacketAssemblerErrorCode["ChunkSizeExceeded"] = 1] = "ChunkSizeExceeded";
+    /** Chunk size is smaller than minimumSizeInBytes */
     PacketAssemblerErrorCode[PacketAssemblerErrorCode["ChunkTooSmall"] = 2] = "ChunkTooSmall";
 })(PacketAssemblerErrorCode || (exports.PacketAssemblerErrorCode = PacketAssemblerErrorCode = {}));
 /**
- * this class is used to assemble partial data from the transport layer
- * into message chunks
+ * Assembles fragmented data from transport layers into complete message chunks.
+ *
+ * ## Zero-Copy Optimization
+ *
+ * The PacketAssembler uses zero-copy optimization for performance:
+ * - **Single-chunk messages**: Returns a view of the input buffer (no allocation, no copy)
+ * - **Multi-chunk messages**: Creates a new buffer via Buffer.concat() (safe copy)
+ *
+ * ## Buffer Lifetime Management
+ *
+ * **Important**: When receiving single-chunk messages, the returned buffer is a view of the
+ * input buffer. Consumers are responsible for creating copies if they need buffers that
+ * survive beyond immediate processing or if the transport layer reuses buffers.
+ *
+ * ### Safe Usage:
+ * ```typescript
+ * assembler.on("chunk", (chunk) => {
+ *   // Option 1: Process immediately (safe)
+ *   const value = chunk.readUInt32LE(0);
+ *
+ *   // Option 2: Create a copy for later use
+ *   const copy = Buffer.from(chunk);
+ *   queue.push(copy);
+ * });
+ * ```
+ *
+ * ### Unsafe Usage:
+ * ```typescript
+ * const chunks = [];
+ * assembler.on("chunk", (chunk) => {
+ *   // UNSAFE: chunk may be reused by transport layer
+ *   chunks.push(chunk);
+ * });
+ * ```
+ *
+ * @fires PacketAssembler#startChunk - Emitted when a new chunk begins
+ * @fires PacketAssembler#chunk - Emitted when a complete chunk is assembled
+ * @fires PacketAssembler#error - Emitted on assembly errors
+ *
+ * @example
+ * ```typescript
+ * const assembler = new PacketAssembler({
+ *   readChunkFunc: (data) => ({
+ *     length: data.readUInt32LE(4),
+ *     messageHeader: { msgType: "MSG", isFinal: "F", length: data.readUInt32LE(4) },
+ *     extra: ""
+ *   }),
+ *   minimumSizeInBytes: 8,
+ *   maxChunkSize: 65536
+ * });
+ *
+ * assembler.on("chunk", (chunk) => {
+ *   console.log("Complete chunk:", chunk.length, "bytes");
+ * });
+ *
+ * // Feed data from transport
+ * socket.on("data", (data) => assembler.feed(data));
+ * ```
  */
 class PacketAssembler extends events_1.EventEmitter {
+    static defaultMaxChunkCount = 777;
+    static defaultMaxMessageSize = 1024 * 64 - 7;
+    _stack;
+    expectedLength;
+    currentLength;
+    maxChunkSize;
+    readChunkFunc;
+    minimumSizeInBytes;
+    packetInfo;
+    /**
+     * Creates a new PacketAssembler instance.
+     *
+     * @param options - Configuration options for the assembler
+     * @param options.readChunkFunc - Function to extract packet metadata from buffer
+     * @param options.minimumSizeInBytes - Minimum bytes needed to read packet header (default: 8)
+     * @param options.maxChunkSize - Maximum allowed chunk size (default: 65529)
+     *
+     * @throws {Error} If readChunkFunc is not a function
+     * @throws {Error} If maxChunkSize is less than minimumSizeInBytes
+     */
     constructor(options) {
         super();
         this._stack = [];
@@ -29,6 +110,34 @@ class PacketAssembler extends events_1.EventEmitter {
         this.maxChunkSize = options.maxChunkSize || PacketAssembler.defaultMaxMessageSize;
         (0, node_opcua_assert_1.assert)(this.maxChunkSize >= this.minimumSizeInBytes);
     }
+    /**
+     * Feeds incoming data to the assembler for processing.
+     *
+     * This method can be called multiple times with partial data. The assembler will
+     * buffer incomplete chunks and emit the "chunk" event when a complete message
+     * has been assembled.
+     *
+     * ## Zero-Copy Behavior
+     *
+     * - If the data contains a complete single chunk, it returns a **view of the input buffer**
+     *   (zero-copy optimization)
+     * - If multiple fragments are needed, it creates a **new buffer** via Buffer.concat()
+     *   (safe copy)
+     *
+     * @param data - Buffer containing incoming data (can be partial or complete chunks)
+     *
+     * @fires startChunk - When a new chunk header is detected
+     * @fires chunk - When a complete chunk has been assembled
+     * @fires error - If chunk size validation fails
+     *
+     * @example
+     * ```typescript
+     * // Feed data as it arrives from transport
+     * socket.on("data", (data) => {
+     *   assembler.feed(data);
+     * });
+     * ```
+     */
     feed(data) {
         let messageChunk;
         if (this.expectedLength === 0 && this.currentLength + data.length >= this.minimumSizeInBytes) {
@@ -91,6 +200,22 @@ class PacketAssembler extends events_1.EventEmitter {
     _readPacketInfo(data) {
         return this.readChunkFunc(data);
     }
+    /**
+     * Builds the final chunk buffer from accumulated fragments.
+     *
+     * ## Zero-Copy Implementation
+     *
+     * This method implements the zero-copy optimization:
+     * - **Single chunk** (data provided, stack empty): Returns the input buffer directly (zero-copy)
+     * - **Single buffered chunk** (no data, one item in stack): Returns the stacked buffer
+     * - **Multiple fragments**: Concatenates all fragments into a new buffer (safe copy)
+     *
+     * @param data - Current buffer fragment (may be null)
+     * @returns Complete chunk buffer (either view or new buffer)
+     *
+     * @private
+     * @internal
+     */
     _buildData(data) {
         if (data && this._stack.length === 0) {
             return data;
@@ -107,6 +232,4 @@ class PacketAssembler extends events_1.EventEmitter {
     }
 }
 exports.PacketAssembler = PacketAssembler;
-PacketAssembler.defaultMaxChunkCount = 777;
-PacketAssembler.defaultMaxMessageSize = 1024 * 64 - 7;
 //# sourceMappingURL=packet_assembler.js.map

package/dist/packet_assembler.js.map

@@ -1 +1 @@
-{"version":3,"file":"packet_assembler.js","sourceRoot":"","sources":["../source/packet_assembler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"packet_assembler.js","sourceRoot":"","sources":["../source/packet_assembler.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-opcua-packet-assembler",
-    "version": "2.153.0",
+    "version": "2.162.0",
     "description": "pure nodejs OPCUA SDK - module packet-assembler",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
@@ -12,8 +12,8 @@
     "author": "Etienne Rossignon",
     "license": "MIT",
     "dependencies": {
-        "node-opcua-assert": "2.139.0",
-        "node-opcua-debug": "2.153.0"
+        "node-opcua-assert": "2.157.0",
+        "node-opcua-debug": "2.157.0"
     },
     "repository": {
         "type": "git",
@@ -28,7 +28,7 @@
         "internet of things"
     ],
     "homepage": "http://node-opcua.github.io/",
-    "gitHead": "2193ed025bc9aaded76338c1c76cbc0524b3a37f",
+    "gitHead": "78989e867fc6c2009002f6db4b7cbf8fb95161ae",
     "files": [
         "dist",
         "source"

package/source/packet_assembler.ts

@@ -5,29 +5,57 @@ import { make_warningLog } from "node-opcua-debug";
 const doDebug = false;
 const warningLog = make_warningLog("PacketAssembler");
 
+/**
+ * Message header information extracted from packet data.
+ */
 export interface MessageHeader {
+    /** Message type identifier (e.g., "MSG", "OPN", "CLO") */
     msgType: string;
+    /** Final chunk indicator ("F" for final, "C" for continuation) */
     isFinal: string;
+    /** Total message length in bytes */
     length: number;
 }
 
+/**
+ * Packet metadata extracted from incoming data.
+ */
 export interface PacketInfo {
+    /** Total expected packet length in bytes */
     length: number;
+    /** Message header information */
     messageHeader: MessageHeader;
+    /** Additional protocol-specific metadata */
     extra: string;
 }
 
+/**
+ * Function type for extracting packet metadata from buffer data.
+ * 
+ * @param data - Buffer containing at least minimumSizeInBytes of data
+ * @returns Packet metadata including expected length and headers
+ */
 export type ReadChunkFuncType = (data: Buffer) => PacketInfo;
 
+/**
+ * Configuration options for PacketAssembler.
+ */
 export interface PacketAssemblerOptions {
+    /** Function to extract packet metadata from incoming data */
     readChunkFunc: ReadChunkFuncType;
-    // the minimum number of bytes that need to be received before the readChunkFunc can be called
+    /** Minimum bytes required before readChunkFunc can be called (typically header size) */
     minimumSizeInBytes: number;
+    /** Maximum allowed chunk size in bytes (chunks exceeding this will trigger an error) */
     maxChunkSize: number;
 }
 
+/**
+ * Error codes for packet assembly failures.
+ */
 export enum PacketAssemblerErrorCode {
+    /** Chunk size exceeds configured maxChunkSize */
     ChunkSizeExceeded = 1,
+    /** Chunk size is smaller than minimumSizeInBytes */
     ChunkTooSmall = 2
 }
 export interface PacketAssembler {
@@ -36,8 +64,64 @@ export interface PacketAssembler {
     on(eventName: "error", eventHandler: (err: Error, errCode: PacketAssemblerErrorCode) => void): this;
 }
 /**
- * this class is used to assemble partial data from the transport layer
- * into message chunks
+ * Assembles fragmented data from transport layers into complete message chunks.
+ * 
+ * ## Zero-Copy Optimization
+ * 
+ * The PacketAssembler uses zero-copy optimization for performance:
+ * - **Single-chunk messages**: Returns a view of the input buffer (no allocation, no copy)
+ * - **Multi-chunk messages**: Creates a new buffer via Buffer.concat() (safe copy)
+ * 
+ * ## Buffer Lifetime Management
+ * 
+ * **Important**: When receiving single-chunk messages, the returned buffer is a view of the
+ * input buffer. Consumers are responsible for creating copies if they need buffers that
+ * survive beyond immediate processing or if the transport layer reuses buffers.
+ * 
+ * ### Safe Usage:
+ * ```typescript
+ * assembler.on("chunk", (chunk) => {
+ *   // Option 1: Process immediately (safe)
+ *   const value = chunk.readUInt32LE(0);
+ *   
+ *   // Option 2: Create a copy for later use
+ *   const copy = Buffer.from(chunk);
+ *   queue.push(copy);
+ * });
+ * ```
+ * 
+ * ### Unsafe Usage:
+ * ```typescript
+ * const chunks = [];
+ * assembler.on("chunk", (chunk) => {
+ *   // UNSAFE: chunk may be reused by transport layer
+ *   chunks.push(chunk);
+ * });
+ * ```
+ * 
+ * @fires PacketAssembler#startChunk - Emitted when a new chunk begins
+ * @fires PacketAssembler#chunk - Emitted when a complete chunk is assembled
+ * @fires PacketAssembler#error - Emitted on assembly errors
+ * 
+ * @example
+ * ```typescript
+ * const assembler = new PacketAssembler({
+ *   readChunkFunc: (data) => ({
+ *     length: data.readUInt32LE(4),
+ *     messageHeader: { msgType: "MSG", isFinal: "F", length: data.readUInt32LE(4) },
+ *     extra: ""
+ *   }),
+ *   minimumSizeInBytes: 8,
+ *   maxChunkSize: 65536
+ * });
+ * 
+ * assembler.on("chunk", (chunk) => {
+ *   console.log("Complete chunk:", chunk.length, "bytes");
+ * });
+ * 
+ * // Feed data from transport
+ * socket.on("data", (data) => assembler.feed(data));
+ * ```
  */
 export class PacketAssembler extends EventEmitter {
     public static defaultMaxChunkCount = 777;
@@ -53,6 +137,17 @@ export class PacketAssembler extends EventEmitter {
     private readonly minimumSizeInBytes: number;
     private packetInfo?: PacketInfo;
 
+    /**
+     * Creates a new PacketAssembler instance.
+     * 
+     * @param options - Configuration options for the assembler
+     * @param options.readChunkFunc - Function to extract packet metadata from buffer
+     * @param options.minimumSizeInBytes - Minimum bytes needed to read packet header (default: 8)
+     * @param options.maxChunkSize - Maximum allowed chunk size (default: 65529)
+     * 
+     * @throws {Error} If readChunkFunc is not a function
+     * @throws {Error} If maxChunkSize is less than minimumSizeInBytes
+     */
     constructor(options: PacketAssemblerOptions) {
         super();
         this._stack = [];
@@ -69,6 +164,34 @@ export class PacketAssembler extends EventEmitter {
         assert(this.maxChunkSize >= this.minimumSizeInBytes);
     }
 
+    /**
+     * Feeds incoming data to the assembler for processing.
+     * 
+     * This method can be called multiple times with partial data. The assembler will
+     * buffer incomplete chunks and emit the "chunk" event when a complete message
+     * has been assembled.
+     * 
+     * ## Zero-Copy Behavior
+     * 
+     * - If the data contains a complete single chunk, it returns a **view of the input buffer**
+     *   (zero-copy optimization)
+     * - If multiple fragments are needed, it creates a **new buffer** via Buffer.concat()
+     *   (safe copy)
+     * 
+     * @param data - Buffer containing incoming data (can be partial or complete chunks)
+     * 
+     * @fires startChunk - When a new chunk header is detected
+     * @fires chunk - When a complete chunk has been assembled  
+     * @fires error - If chunk size validation fails
+     * 
+     * @example
+     * ```typescript
+     * // Feed data as it arrives from transport
+     * socket.on("data", (data) => {
+     *   assembler.feed(data);
+     * });
+     * ```
+     */
     public feed(data: Buffer) {
         let messageChunk;
 
@@ -139,6 +262,22 @@ export class PacketAssembler extends EventEmitter {
         return this.readChunkFunc(data);
     }
 
+    /**
+     * Builds the final chunk buffer from accumulated fragments.
+     * 
+     * ## Zero-Copy Implementation
+     * 
+     * This method implements the zero-copy optimization:
+     * - **Single chunk** (data provided, stack empty): Returns the input buffer directly (zero-copy)
+     * - **Single buffered chunk** (no data, one item in stack): Returns the stacked buffer
+     * - **Multiple fragments**: Concatenates all fragments into a new buffer (safe copy)
+     *
+     * @param data - Current buffer fragment (may be null)
+     * @returns Complete chunk buffer (either view or new buffer)
+     * 
+     * @private
+     * @internal
+     */
     private _buildData(data: Buffer): Buffer {
         if (data && this._stack.length === 0) {
             return data;