RingBud

A lightweight, high-performance Ring Buffer for streaming data using JavaScript TypedArrays.

Features

• 🧠 Frame-based buffering (configurable frame size)
• ⚡ Zero dependencies
• 🧵 Supports all major TypedArrays (e.g. Float32Array, Uint8Array, etc.)
• 📦 Memory efficient with optional frame trimming
• 🔁 Sync & async iteration support
• ✅ Fully tested and predictable behavior
• 🧰 Customizable preallocation and cache options

---

Installation

npm install ringbud

---

Quick Start

import { RingBufferU8 } from "ringbud";

// Create a ring buffer with frame size of 100
const rb = new RingBufferU8(100);

// Write 50 bytes (not enough for a full frame)
rb.write(new Uint8Array(50).fill(1));
console.log(rb.empty()); // true

// Write 50 more bytes (now we have a complete frame)
rb.write(new Uint8Array(50).fill(1));
console.log(rb.empty()); // false

// Read one frame of 100 bytes
const frame = rb.read();
console.log(frame); // Uint8Array(100)

// After reading, it becomes empty again
console.log(rb.empty()); // true

---

Supported Types

You can instantiate ring buffers for:

• Uint8Array → RingBufferU8
• Uint16Array → RingBufferU16
• Float32Array → RingBufferF32

Each subclass wraps the base RingBufferBase with preconfigured types.

---

Configuration Options

All constructors accept:

{
  frameSize: number,                // Number of elements per frame (required)
  preallocateFrameCount?: number,  // Default: 10
  frameCacheSize?: number          // Default: 0 (no trim)
}

Frame Cache Size (Clamping)

When frameCacheSize > 0, the ring buffer trims memory usage by shifting unread bytes after every .read(). This reduces buffer growth at the cost of additional memory copying.

---

API Reference

Constructor

new RingBufferU8(frameSize: number, options?: {
  preallocateFrameCount?: number;
  frameCacheSize?: number;
});

Methods

Method	Description
write(data)	Appends a TypedArray to the buffer
read()	Returns the next full frame, or null
drain()	Returns remaining incomplete data
peek()	Returns the entire buffer content (not a copy)
empty()	true if no full frame is available
remainingFrames()	Number of full frames available to read
rewind()	Resets read offset so frames can be re-read
Symbol.iterator()	Enables for (const frame of buffer)
Symbol.asyncIterator()	Enables for await (const frame of buffer)

---

Example: Iteration

for (const frame of rb) {
  console.log(frame); // each is a complete frame
}

// or async
for await (const frame of rb) {
  await process(frame);
}

---

Example: Auto-Trimming

const rb = new RingBufferU8(100, { frameCacheSize: 1 });

rb.write(new Uint8Array(300)); // 3 frames
rb.read();                     // returns 1st frame

// Buffer automatically shifts remaining frames to the front
rb.peek().subarray(0, 200);    // contains frame 2 and 3

---

Validations & Safety

• frameSize must be an integer ≥ 1
• preallocateFrameCount must be ≥ 1 (if set)
• Partial frames are never returned from .read() or iterators
• Trimming only occurs after reads when frameCacheSize > 0
• If iteration is used, all frames are consumed as if .read() was called repeatedly
• Frames can be shared or copied depending on cache config

---

TypedArray Support

Internally, the base class accepts any TypedArray constructor:

new RingBufferBase({
  frameSize: 256,
  TypedArrayConstructor: Uint16Array
});

Built-in classes like RingBufferF32 are wrappers over this API.

---

Examples

Draining Partial Data

const rb = new RingBufferU8(100);

rb.write(new Uint8Array(230));
rb.read();           // reads 1 frame (100 bytes)
rb.read();           // reads 1 more frame (100 bytes)
rb.read();           // null (30 bytes left)

rb.drain();          // returns 30 bytes

Rewind

rb.rewind();         // enables re-reading all written frames
for (const frame of rb) {
  console.log(frame);
}

---