An optimized embedded event store for modern node.js, written in ES6.
📖 Full documentation on readthedocs.io
There is currently only a single other embedded event store for node/javascript: node-eventstore. It has a few drawbacks:
- Its API requires loading a full Event Stream before committing, making it unfit for frequently-restarting client applications.
- Its embeddable backends (TingoDB, NeDB) do not persist indexes and are slow on initial load.
- Events are fixed to one stream — creating overlapping projection streams is not possible.
node-event-storage is built from first principles for append-only workloads, giving you near-optimal write speed with no unnecessary overhead.
npm install event-storageCommonJS /
require()users: version 1.0 is ESM-only. If your project usesrequire()and migrating to ESM is not an option, install the 0.x series (npm install event-storage@0) which is functionally equivalent and retains full CJS support.
import { EventStore } from 'event-storage';
const eventstore = new EventStore('my-event-store', { storageDirectory: './data' });
eventstore.on('ready', () => {
// Write events
eventstore.commit('my-stream', [{ type: 'SomethingHappened', value: 42 }], 0, () => {
console.log('Written!');
});
// Read events
const stream = eventstore.getEventStream('my-stream');
for (const event of stream) {
console.log(event);
}
});| Feature | Summary |
|---|---|
| Optimistic concurrency | Pass expectedVersion to commit() to guarantee conflict-free writes. |
| Flexible stream reading | Range queries, reverse iteration, and a fluent builder API. |
| Derived streams | Filter or combine events into new read-only streams. |
| Multi-value matchers | Object matchers support array values (OR semantics) and still benefit from O(1) discriminant routing on writes. |
DCB / typeAccessor |
Configure typeAccessor to have per-type stream indexes maintained automatically, and use query() / Condition for fine-grained, query-scoped optimistic concurrency (Dynamic Consistency Boundaries). |
| Stream categories | Name streams <category>-<id> and query the whole category at once. |
| Durable consumers | At-least-once (and exactly-once with setState) event delivery with automatic position tracking. |
| Consistency guards | Build aggregates that enforce business invariants with built-in snapshotting. |
| Read-only mode | Open the store from a second process to build projections without touching the writer. |
| Crash safety | Torn writes detected and truncated on startup; automatic index repair via LOCK_RECLAIM; bounded, predictable data loss validated by a dedicated stress test. |
| Custom serialization | Plug in msgpack, protobuf, or any other codec. |
| Compression | Apply LZ4, zstd, or any other compression via the serializer option. |
| Access control hooks | preCommit / preRead hooks with per-stream metadata for authorization. |
The full documentation is hosted at https://node-event-storage.readthedocs.io/en/latest/ and covers:
- Getting Started — installation, constructor options, basic usage.
- Event Streams — writing, reading, optimistic concurrency, fluent API, joining streams, categories, and event metadata.
- Dynamic Consistency Boundaries (DCB) —
typeAccessor, multi-value matchers, consistency tokens, and the full DCB workflow. - Consumers — at-least-once and exactly-once delivery, consumer state, consistency guards, and read-only mode.
- Advanced Topics — ACID properties, reliability and crash-safety guarantees, storage configuration, partitioning, custom serialization, compression, security, and access control hooks.
npm test