@marianmeres/batch

A lightweight, generic batch processor that collects items and flushes them based on configurable triggers.

Features

• Interval mode - flush at fixed time intervals
• Amount mode - flush when item count reaches threshold
• Combined mode - flush on whichever trigger fires first
• Safety cap - prevents unbounded memory growth
• Graceful shutdown - drain() flushes remaining items before stopping
• Debug logging - optional verbose logging with custom logger support
• Svelte store compatible - reactive subscriptions for UI binding
• TypeScript - fully typed with generics

Installation

# Deno
deno add jsr:@marianmeres/batch

# Node.js
npm install @marianmeres/batch

Quick Start

import { BatchFlusher } from "@marianmeres/batch";

// Create a batcher that flushes every 5 seconds
const batcher = new BatchFlusher<string>(
  async (items) => {
    console.log("Flushing:", items);
    await sendToServer(items);
    return true;
  },
  {
    flushIntervalMs: 5000,
    maxBatchSize: 1000,
  }
);

// Add items - they'll be batched and flushed automatically
batcher.add("event-1");
batcher.add("event-2");

// When done, gracefully shutdown (flushes remaining items and stops)
await batcher.drain();

Flush Modes

// Interval mode: flush every 5 seconds
{ flushIntervalMs: 5000, maxBatchSize: 100 }

// Amount mode: flush when 50 items collected
{ flushIntervalMs: 0, flushThreshold: 50, maxBatchSize: 100 }

// Combined mode: flush every 5s OR when 50 items collected
{ flushIntervalMs: 5000, flushThreshold: 50, maxBatchSize: 100 }

Use Cases

• Log aggregation
• Metrics collection
• Event batching
• Database write batching
• API request batching

State Awareness

The batcher exposes two readonly properties for monitoring its internal state:

• isRunning - Whether automatic interval-based flushing is active. Useful for verifying the batcher has started/stopped correctly, or for conditional logic based on batcher state.

• isFlushing - Whether a flush operation is currently in progress. Useful for debugging, logging, or UI indicators showing when data is being sent.

if (batcher.isRunning) {
  console.log("Batcher is active");
}

if (batcher.isFlushing) {
  console.log("Flush in progress...");
}

Reactive Subscriptions (Svelte Store Compatible)

The batcher implements the Svelte store contract, allowing reactive subscriptions to state changes:

// state.size, state.isRunning, state.isFlushing
const unsubscribe = batcher.subscribe((state) => {
  console.log(state);
});
// Later: unsubscribe();

State updates are emitted on:

• Item added (size changes)
• Buffer reset (size changes)
• Flush start/end (isFlushing changes, size changes)
• Start/stop (isRunning changes)

API

See API.md for full API documentation.

License

MIT