Skip to content
CAI
Software that uses CAICheck a score

albe/node-event-storage

59.6

Adequate · 8 November 2026

8.3k

lines of production code

JavaScript

primary language

7

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

This system is an embedded, append-only event store library for Node.js designed for event-sourced architectures. It provides core capabilities for committing and querying events via streams, managing durable consumer positions, and maintaining index-backed metadata matching. The implementation emphasizes crash safety with automatic torn-write repair and supports concurrent access through file-watcher synchronization and read-only modes.

Features

Add performance benchmarking suite for storage, indexing, and matching

Added a new \bench/\ directory containing JavaScript benchmark scripts that compare the current implementation against the previous stable version. The suite includes benchmarks for event store commit/read performance, index add/range operations, metadata matcher throughput (including raw buffer matching optimizations), read scenarios (full scans, range scans, stream joins), and scalability metrics (startup time, write/read latency as partitions and indexes grow).

bench · high confidence

Initial release of node-event-storage with ESM support and comprehensive documentation

This entry introduces the initial version of the event-storage library, providing an embedded, append-only event store for Node.js. The codebase is converted to ES Modules (ESM) only, with a CJS fallback available for version 0.x users. The public API includes EventStore for committing and querying events, EventStream for reading streams with fluent range/direction options, Consumer for durable position tracking, and CommitCondition for Dynamic Consistency Boundaries (DCB). The release also includes extensive documentation (README, mkdocs site, AGENTS.md), configuration files for ReadTheDocs and GitHub Actions, and a .gitignore tailored to the project's build and test artifacts.

(repo-wide) · high confidence

Initial release of the event-sourced storage and consumer API

This change introduces the core event-sourcing library, providing a persistent, index-backed event store with durable consumer support. Users can now commit events to streams, query them using a flexible selector and matcher system (including hierarchical stream names and type/tag accessors), and consume events via durable consumers that persist their state and position. The implementation includes a monotonic clock for event ordering, an LRU file handle pool for performance, and a directory watcher for real-time stream updates.

src · high confidence

New read-only index with file change monitoring

The index module now includes a ReadOnlyIndex class that extends ReadableIndex to monitor the underlying index file for external modifications. When the file is appended to or truncated by another process, the index automatically updates its internal state and emits 'append' or 'truncate' events, allowing consumers to react to changes without manual polling. This complements the existing ReadableIndex and WritableIndex classes, providing a robust way to handle concurrent access scenarios where the index file might be modified externally.

src/Index · high confidence

New read-only storage mode with automatic file-watcher sync and torn-write repair

The storage layer now includes a dedicated ReadOnlyStorage class that enables append-only, read-only access to existing data directories. This mode uses a file watcher to automatically detect and sync new partitions and index files as they appear on disk, emitting events for changes without requiring manual rescans. Additionally, the WritableStorage component now features automatic torn-write repair: on open, it scans partitions for incomplete writes, truncates corrupted data, and rebuilds lagging indexes to ensure data consistency before becoming ready.

src/Storage · high confidence

New utility modules for API normalization, file scanning, and metadata matching

The src/utils directory now includes several new helper modules that standardize and optimize core operations. apiHelpers.js normalizes constructor overloads and argument types for commit and consumer APIs, ensuring consistent behavior across different call signatures. fsUtil.js introduces robust file-system utilities, including support for resolving paths with the \~/ home-directory shorthand and recursive directory scanning with regex-based file matching. metadataUtil.js provides a high-performance, pre-compiled matcher engine that uses WeakMap caching to efficiently evaluate document properties against operator-based queries (such as $eq, $gt, and $has). Additionally, dcbUtil.js adds support for compiling DcbQuery objects into selector-algebra arrays, while deprecations.js centralizes one-time deprecation warning emissions to reduce console noise.

src/utils · high confidence

Behavioural changes

Introduce read-only partition support and refine read/write buffer behavior

Added ReadOnlyPartition, a new class that extends ReadablePartition to automatically sync its size with the underlying file and emit 'append' or 'truncate' events when the file changes, enabling safe monitoring of externally modified partition files. The underlying ReadablePartition and WritablePartition implementations were refactored to improve buffer handling: the default read buffer size was increased to 64KB, dirty reads are now explicitly configurable (defaulting to true for WritablePartition), and internal methods like prepareReadBufferBackwards were fixed to correctly consider the write buffer for unflushed data. Additionally, partition metadata is now read from the file header upon opening, and file handle pooling semantics were tightened to avoid processing watcher events after closure.

src/Partition · high confidence

Test coverage

Added crash-safety and memory consumption stress tests; Initial test suite for core storage and eventing components.

Dependencies

Update dependencies and add benchmarking infrastructure

The project updates its core dependencies, including Mocha to 12.0.0, c8 to 12.0.0, and mkdirp to 3.0.1, while raising the minimum Node.js engine requirement to 20.0. A new benchmarking suite (event-storage-bench) has been added to the repository, utilizing the benchmark and beautify-benchmark libraries to measure performance against the event-storage package.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 60 → 60 (-0.5)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 48 → 48 (+0.0)
  • Architecture 85 → 85 (+0.0)
  • Maturity 73 → 74 (+1.0)
  • Readiness 62 → 62 (+0.0)
  • Security 81 → 74 (-7.6)
  • Performance 94 → 94 (+0.0)

Resolved (5)

  • Ambiguous preposition usage. fromStart and toStart likely represent opposite operations (starting iteration from the beginning vs. moving the cursor to the beginning), but the naming is not immediately intuitive. Similarly for fromEnd/toEnd. This forces users to memorize which preposition implies 'start iteration' vs 'move cursor'.
  • Confusing directional naming conventions. forwards/backwards use adverbial forms, while previous/following use participial forms. Furthermore, previous and backwards likely perform the same operation (moving to earlier events), as do following and forwards. This creates ambiguity about which pair to use.
  • Documentation: no project overview (README.md)
  • Duplicate intent for filtering. where and filter are semantically identical in most fluent APIs (LINQ style). Having both allows users to achieve the same result with different method names, leading to confusion about whether options in filter provides unique functionality or if where is just a simpler alias.
  • Redundant iteration interfaces. The class exposes both a standard callback-based iteration method and the ES6 Symbol.iterator, allowing for both forEach loops and for...of loops. While not strictly an error, it creates API surface bloat where one canonical iteration strategy (typically Symbol.iterator for modern JS) should suffice, with forEach being a convenience wrapper or vice versa.

New (3)

  • Medium CVE: [GHSA redacted] (package-lock.json)
  • Medium CVE: [GHSA redacted] (package-lock.json)
  • doc comments repeat the names (src/JoinEventStream.js)

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

albe/node-event-storage was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 8 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 587f94bb1f522dba98b34e32dc12532ebad77750 — the exact code this score is about.
  • Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-bb0cb800cd0f.