A buffer that batches then flushes

Firing a request for every click, keystroke or log line floods the network. The standard fix is a buffer with two triggers: flush as soon as enough items pile up, and flush anyway once the oldest item has waited long enough.

Implement a BatchBuffer class. new BatchBuffer(onFlush, options) takes a callback and an options object { size, waitMs }, defaulting to size 10 and waitMs 100. add(item) appends an item to the pending batch and returns the number of items pending afterwards. If adding brings the pending count up to size, flush immediately and synchronously, before add returns — so add returns 0 in that case. Otherwise, if this item is the first of a new batch, start a timer for waitMs milliseconds; adds after that must not restart the timer, so the batch is sent waitMs after its first item rather than after its last. flushNow() sends whatever is pending straight away and returns how many items it sent; when nothing is pending it does not call the callback and returns 0. pending() returns how many items are waiting.

Flushing means calling onFlush(items) once with a plain array of the pending items in the order they were added, then clearing the pending list and cancelling any timer. The callback is never called with an empty array.

const sent = [];
const b = new BatchBuffer((items) => sent.push(items), { size: 3, waitMs: 1000 });
b.add(1); b.add(2);
b.add(3);    // triggers a sync flush
sent;        // [[1, 2, 3]]
b.pending(); // 0

const sent = [];
const b = new BatchBuffer((items) => sent.push(items), { size: 10, waitMs: 20 });
b.add("a"); b.add("b");
// 20ms later: sent === [["a", "b"]]