FrameBuffer

Defined in: packages/protocol/src/frame-buffer.ts:234

High-Performance FrameBuffer with Streaming Support.

TWO MODES OF OPERATION:

1. BATCH MODE (default):

   • Accumulates chunks in memory (zero-copy list)
   • Returns Frame[] when complete frame(s) available
   • Good for small/medium payloads
   • Simple API: frames = buffer.push(chunk)

2. STREAMING MODE:

   • Delivers payload chunks via callbacks AS THEY ARRIVE
   • Minimal memory footprint (only one chunk at a time)
   • Good for large payloads (100MB+), file transfers
   • Callback API: buffer.setStreamHandler(handler)

PERFORMANCE:

• Accumulation is O(1) per chunk (no Buffer.concat!)
• Memory usage in batch mode: O(payload size)
• Memory usage in streaming mode: O(chunk size) = ~64KB

Examples

const buffer = new FrameBuffer();

socket.on('data', (chunk) => {
  const frames = buffer.push(chunk);
  for (const frame of frames) {
    // Process complete frame
    const data = codec.deserialize(frame.payload);
  }
});

const buffer = new FrameBuffer();

buffer.setStreamHandler({
  onFrameStart(header) {
    this.fd = fs.openSync('output.bin', 'w');
  },
  onPayloadChunk(chunk, offset, isLast) {
    fs.writeSync(this.fd, chunk);  // Write immediately!
  },
  onFrameEnd(header) {
    fs.closeSync(this.fd);
  },
});

socket.on('data', (chunk) => buffer.push(chunk));

Constructors

Constructor

new FrameBuffer(options): FrameBuffer

Defined in: packages/protocol/src/frame-buffer.ts:273

Create a new FrameBuffer.

Parameters

options

FrameBufferOptions = {}

Configuration options

Returns

FrameBuffer

Example

// Default 1GB limit
const buffer = new FrameBuffer();

// Custom limit for large transfers
const buffer = new FrameBuffer({ maxPayloadSize: 2 * 1024 * 1024 * 1024 - 1 });

// Strict limit for control channel
const buffer = new FrameBuffer({ maxPayloadSize: 1024 * 1024 }); // 1MB

Accessors

bufferedBytes

Get Signature

get bufferedBytes(): number

Defined in: packages/protocol/src/frame-buffer.ts:589

Number of bytes currently buffered.

Returns

number

---

hasPartialFrame

Get Signature

get hasPartialFrame(): boolean

Defined in: packages/protocol/src/frame-buffer.ts:596

Check if there’s a partial frame in the buffer.

Returns

boolean

---

isStreaming

Get Signature

get isStreaming(): boolean

Defined in: packages/protocol/src/frame-buffer.ts:309

Check if streaming mode is enabled.

Returns

boolean

Methods

clear()

clear(): void

Defined in: packages/protocol/src/frame-buffer.ts:603

Clear the buffer. Use when connection resets.

Returns

void

---

push()

push(chunk): Frame[]

Defined in: packages/protocol/src/frame-buffer.ts:322

Push a chunk of bytes and extract any complete frames.

BATCH MODE: Returns Frame[] when complete frame(s) available. STREAMING MODE: Calls handler callbacks, always returns [].

Parameters

chunk

Buffer

Bytes received from socket

Returns

Frame[]

Array of complete frames (empty in streaming mode)

---

setStreamHandler()

setStreamHandler(handler): void

Defined in: packages/protocol/src/frame-buffer.ts:296

Enable streaming mode.

In streaming mode:

• Payload chunks are delivered via callbacks AS THEY ARRIVE
• Memory footprint is minimal (one chunk at a time)
• push() always returns [] (frames delivered via callbacks)

Call with null to disable streaming mode and return to batch mode.

Parameters

handler

Streaming callbacks, or null to disable

FrameStreamHandler | null

Returns

void