io-buffer-kit

Universal data buffering library for high-traffic I/O operations. Smart batching with configurable triggers, exponential backoff retry, and graceful shutdown support.

Features

• Generic Type Support — Works with any data model <T>
• Dual Triggers — Flush by maxSize (count) or maxTime (milliseconds), whichever comes first
• Agnostic Design — No database dependency; you provide the onFlush callback
• Exponential Backoff Retry — Automatic retry with configurable delays
• Graceful Shutdown — Built-in SIGTERM/SIGINT handling with drain() for data safety
• Zero External Dependencies — Pure TypeScript, lightweight

Installation

npm install io-buffer-kit

Quick Start

import { SmartBuffer } from 'io-buffer-kit';

const buffer = new SmartBuffer({
  maxSize: 1000,
  maxTime: 5000,
  onFlush: async (batch) => {
    await database.insert(batch);
  },
  onError: (error, batch) => {
    console.error('Flush failed:', error, 'Lost batch size:', batch.length);
  }
});

buffer.add({ id: 1, name: 'Alice' });
buffer.add({ id: 2, name: 'Bob' });

Configuration

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | maxSize | number | Yes | — | Max items before auto-flush | | maxTime | number | Yes | — | Max milliseconds before auto-flush | | onFlush | (batch: ReadonlyArray<T>) => Promise<void> | Yes | — | Your custom flush handler | | retry | RetryConfig | No | { maxRetries: 3, minDelay: 1000, maxDelay: 30000 } | Retry settings | | onError | (error: Error, batch: ReadonlyArray<T>) => void | No | No-op | Error callback | | autoDrain | boolean | No | true | Auto-handle SIGTERM/SIGINT |

RetryConfig

| Option | Type | Description | |--------|------|-------------| | maxRetries | number | Max retry attempts | | minDelay | number | Initial retry delay (ms) | | maxDelay | number | Max retry delay cap (ms) |

Manual Drain

const result = await buffer.drain();
console.log(result.success, result.retryCount);

License

MIT