Universal events batcher for NodeJS
npm install node-events-batcherUniversal events batcher for NodeJS. Collects events and flushes them in batches via configurable strategies (size-based or time-based) with array or set accumulation.
> [!NOTE]
> It's highly recommended to use with volta.sh.
``bash`
npm install node-events-batcher
`ts
import { EventsBatcher } from 'node-events-batcher';
const batcher = new EventsBatcher
(events) => {
console.log('Flushed:', events);
},
(err) => console.error(err),
{ size: 5, accumulatorType: 'array', timeoutMs: 5000 }
);
batcher.add('a');
batcher.add('b');
batcher.add('c');
batcher.add('d');
batcher.add('e'); // callback runs with ['a','b','c','d','e']
batcher.flush(); // flush any remaining events manually
`
Constructor
`ts`
new EventsBatcher
callback: (events: ReadonlyArray
errorHandler?: ((error: unknown) => void) | null,
options?: SizeOptions | DebounceOptions
)
- callback — Called with the batched events when a flush occurs. May return a Promise; rejections are passed to errorHandler.{ accumulatorType: 'array', timeoutMs: 2000, debounceMs: 50 }
- errorHandler — Optional. If provided, callback errors are passed here; otherwise they are rethrown.
- options — Flush strategy and accumulator. Defaults to (debounce strategy).
Methods
- add(event: EventType): void — Add an event. May trigger a flush depending on the strategy.
- flush(): void — Flush all accumulated events immediately.
Two strategy types:
| Option | Type | Description |
|--------|------|-------------|
| Size strategy | SizeOptions | Flush when the batch reaches size events. |DebounceOptions
| Debounce strategy | | Flush after debounceMs ms of no new events. |
Common options
| Option | Type | Description |
|--------|------|-------------|
| accumulatorType | 'array' \| 'set' | 'array' — order preserved, duplicates allowed. 'set' — unique events only, order not guaranteed. |timeoutMs
| | number \| null | Max wait (ms) before flushing; null disables. |
Size strategy (SizeOptions)
| Option | Type | Description |
|--------|------|-------------|
| size | number | Flush when batch size reaches this value. |
Debounce strategy (DebounceOptions)
| Option | Type | Description |
|--------|------|-------------|
| debounceMs | number | Flush after this many ms without a new event. Must be < timeoutMs when timeoutMs is set. |
Size strategy is preferred if both size and debounceMs is set.
Size-based batching (e.g. send when 10 items):
`ts`
const batcher = new EventsBatcher
sendToServer,
null,
{
size: 10,
accumulatorType: 'array',
timeoutMs: 3000,
}
);
Time-based debounce (e.g. persist after 100 ms idle):
`ts`
const batcher = new EventsBatcher
persistWindowState,
console.error,
{
debounceMs: 100,
timeoutMs: 2000,
accumulatorType: 'set',
}
);
Exports
`ts`
import { EventsBatcher } from 'node-events-batcher';
import type { SizeOptions, DebounceOptions } from 'node-events-batcher';
The example/ folder contains an Electron app that uses the batcher to persist window state when windows are closed. Run it from the repo root:
`bash``
cd example && pnpm install && pnpm start
MIT