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 supports CommonJS but lacks the features added in 1.x.
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. |
| Joined and derived streams | Combine any number of streams with a nested OR/AND selector tree into one globally-ordered virtual stream; filter events into reusable derived projection streams. |
| Object matchers | Support nested equality, array values (OR semantics), scalar operators ($gt / $gte / $lt / $lte / $eq / $ne), string prefixes ($startsWith), plus array-containment operators ($has / $hasAny), while still benefiting from O(1) discriminant routing on writes. |
| DCB | 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. |
- event-storage-http exposes a store over HTTP (NDJSON streams, consumer management,
HttpEventStreamclient). - event-storage-ui is an admin dashboard for inspecting a running store on the same machine.
The full documentation is hosted at https://node-event-storage.readthedocs.io/en/stable/:
- New to event sourcing? Event Sourcing in 5 Minutes, When to Use, Getting Started.
- Guides: Writing and Reading Events, Organizing Streams, Matchers, DCB, Consumers, Multiple Processes, Customization, Operations.
- Evaluating the implementation? Guarantees, Implementation Architecture, Performance.
- Reference: API, Configuration, Changelog, Upgrading.
npm test