Buflux NPM | npm.io

Buflux 🚀

Buflux is a high-performance buffer library for Node.js and browsers. It’s designed to efficiently manage fixed-capacity data with powerful overflow strategies, perfect for high-throughput systems.

🌟 Features

Fixed-Capacity Buffer: Manage data up to a defined limit with ease.
Overflow Strategies:
- REJECT: Safely block new additions when full.
- EVICT: Automatically remove the oldest item to make room, mimicking circular buffer behavior.
Event-Driven: React to enqueue, dequeue, overflow, and reject events effortlessly.
Zero Dependencies: Lightweight and fast.
Universal Compatibility: Works seamlessly in Node.js (16+) and modern browsers.

🚀 Installation

Install Buflux via Yarn or npm:

yarn add buflux

npm install buflux

🔧 Usage

Basic Example

import { Buflux, OverflowMode } from 'buflux';

// Create a buffer with capacity 3 and eviction overflow strategy
const buffer = new Buflux<number>({
  capacity: 3,
  overflow: OverflowMode.EVICT,
});

buffer.enqueue(1); // [1]
buffer.enqueue(2); // [1, 2]
buffer.enqueue(3); // [1, 2, 3]

buffer.enqueue(4); // Evicts 1, buffer becomes [2, 3, 4]

console.log(buffer.toArray()); // [2, 3, 4]
console.log(buffer.peek()); // 2

Events Example

// Subscribe to events
const unsubscribeEnqueue = buffer.on('enqueue', (item) => {
  console.log(`Item added: ${item}`);
});

const unsubscribeOverflow = buffer.on('overflow', (evicted) => {
  console.log(`Item evicted: ${evicted}`);
});

buffer.enqueue(5); // Triggers 'enqueue'

// Unsubscribe
unsubscribeEnqueue(); // Remove enqueue listener
unsubscribeOverflow(); // Remove overflow listener

// Subscribe to other events
buffer.on('dequeue', (item) => {
  console.log(`Item removed: ${item}`);
});

buffer.on('reject', (item) => {
  console.log(`Item rejected: ${item}`);
});

📚 API Reference

Buflux

Constructor

new Buflux<T>({ capacity: number, overflow?: OverflowMode });

capacity: Maximum number of items the buffer can hold.
overflow (optional): Overflow strategy (REJECT or EVICT). Defaults to REJECT.

Methods

enqueue(item): Adds an item to the buffer. Returns true if successful, false otherwise.
dequeue(): Removes and returns the oldest item.
peek(): Returns the oldest item without removing it.
size(): Returns the current number of items.
isFull(): Checks if the buffer is full.
clear(): Removes all items from the buffer.