ringbud

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