Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/faizanu94/buflux
A high-performance, event-driven buffer library for Node.js and browsers, with configurable overflow strategies
https://github.com/faizanu94/buflux
browser buffer circular-buffer eviction fixed-capacity isomorphic javascript nodejs npm overflow queue
Last synced: 11 days ago
JSON representation
A high-performance, event-driven buffer library for Node.js and browsers, with configurable overflow strategies
- Host: GitHub
- URL: https://github.com/faizanu94/buflux
- Owner: faizanu94
- License: mit
- Created: 2024-12-08T12:33:53.000Z (18 days ago)
- Default Branch: main
- Last Pushed: 2024-12-09T12:27:14.000Z (17 days ago)
- Last Synced: 2024-12-09T12:39:10.778Z (17 days ago)
- Topics: browser, buffer, circular-buffer, eviction, fixed-capacity, isomorphic, javascript, nodejs, npm, overflow, queue
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/buflux
- Size: 38.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```bash
yarn add buflux
npm install buflux
```
## 🔧 Usage
### Basic Example
```typescript
import { Buflux, OverflowMode } from 'buflux';
// Create a buffer with capacity 3 and eviction overflow strategy
const buffer = new Buflux({
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
```typescript
// 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
```typescript
new Buflux({ 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.
## 📦 Use Cases
- Task Queues: Efficiently manage job queues with predictable size.
- Rate Limiting: Buffer API calls or events to prevent overloads.
- Caching: In-memory storage with automatic eviction.
- Data Streams: Process and buffer incoming data streams efficiently.