event-storage 1.1.0 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-![event-storage](logo/color.png)
+![event-storage](logo/color.svg)
 
 [![build](https://github.com/albe/node-event-storage/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/albe/node-event-storage/actions/workflows/build.yml)
 [![npm version](https://badge.fury.io/js/event-storage.svg)](https://badge.fury.io/js/event-storage)
@@ -62,8 +62,8 @@ eventstore.on('ready', () => {
 | **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). |
+| **Object matchers** | Support nested equality, array values (OR semantics), and scalar operators like `$gt` / `$gte` / `$lt` / `$lte` / `$eq` / `$ne`, 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. |
@@ -75,13 +75,58 @@ eventstore.on('ready', () => {
 
 ---
 
+## DCB Example
+
+```javascript
+const { stream, condition } = store.query(['OrderPlaced'], { payload: { customerId: 'cust-1' } });
+const hasOpenOrder = stream.some((event) => event.status === 'open');
+
+if (!hasOpenOrder) {
+    store.commit('orders-cust-1', [{ type: 'OrderPlaced', customerId: 'cust-1' }], condition);
+}
+```
+
+---
+
+## Object Matcher Syntax
+
+Object matchers support nested equality, array values, and scalar operators like `$gt`, `$gte`, `$lt`, `$lte`, `$eq`, and `$ne`.
+
+```javascript
+{ payload: { type: ['OrderPlaced', 'OrderCancelled'] } }
+{ payload: { amount: { $gte: 100, $lt: 1000 } } }
+```
+
+---
+
+## HTTP API
+
+To expose an event store over HTTP, see the companion package **[event-storage-http](https://github.com/albe/node-event-storage-http)**:
+
+```bash
+npm install event-storage-http
+```
+
+```javascript
+import EventStore from 'event-storage';
+import { createEventStoreHttpServer } from 'event-storage-http';
+
+const eventStore = new EventStore('my-store', { storageDirectory: './data' });
+const server = createEventStoreHttpServer(eventStore);
+server.listen(3000);
+```
+
+The package exposes NDJSON stream endpoints, durable consumer management, and an `HttpEventStream` client helper for consuming event streams over fetch.
+
+---
+
 ## Documentation
 
 The full documentation is hosted at **<https://node-event-storage.readthedocs.io/en/latest/>** and covers:
 
 - [Getting Started](https://node-event-storage.readthedocs.io/en/latest/getting-started/) — installation, constructor options, basic usage.
 - [Event Streams](https://node-event-storage.readthedocs.io/en/latest/streams/) — writing, reading, optimistic concurrency, fluent API, joining streams, categories, and event metadata.
-- [Dynamic Consistency Boundaries (DCB)](https://node-event-storage.readthedocs.io/en/latest/dcb/) — `typeAccessor`, multi-value matchers, consistency tokens, and the full DCB workflow.
+- [Dynamic Consistency Boundaries (DCB)](https://node-event-storage.readthedocs.io/en/latest/dcb/) — `typeAccessor`, query matchers, consistency tokens, and the full DCB workflow.
 - [Consumers](https://node-event-storage.readthedocs.io/en/latest/consumers/) — at-least-once and exactly-once delivery, consumer state, consistency guards, and read-only mode.
 - [Advanced Topics](https://node-event-storage.readthedocs.io/en/latest/advanced/) — ACID properties, reliability and crash-safety guarantees, storage configuration, partitioning, custom serialization, compression, security, and access control hooks.
 

package/index.js

@@ -3,3 +3,4 @@ export { default as EventStream } from './src/EventStream.js';
 export { default as Storage, StorageLockedError } from './src/Storage.js';
 export { default as Index } from './src/Index.js';
 export { default as Consumer } from './src/Consumer.js';
+export { matches, buildRawBufferMatcher } from './src/utils/metadataUtil.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "event-storage",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "An optimized embedded event store for node.js",
   "keywords": [
@@ -26,6 +26,7 @@
   },
   "scripts": {
     "test": "c8 --reporter=lcov --reporter=text mocha test/*.spec.js",
+    "test:grep": "c8 --reporter=lcov --reporter=text mocha test/*.spec.js --grep",
     "coverage": "c8 report --reporter=text-lcov | coveralls"
   },
   "files": [
@@ -43,10 +44,8 @@
     "src/Partition/*.js",
     "src/Storage/*.js",
     "src/WatchesFile.js",
-    "src/util.js",
-    "src/fsUtil.js",
-    "src/metadataUtil.js",
-    "index.js"
+    "index.js",
+    "src/utils/*.js"
   ],
   "license": "MIT",
   "maintainers": [

package/src/Consumer.js

@@ -1,8 +1,9 @@
 import stream from 'stream';
 import fs from 'fs';
 import path from 'path';
-import { assert } from './util.js';
-import { ensureDirectory } from './fsUtil.js';
+import { assert } from './utils/util.js';
+import { ensureDirectory } from './utils/fsUtil.js';
+import { normalizeConsumerStateArgs } from './utils/apiHelpers.js';
 import Storage from './Storage/ReadableStorage.js';
 const MAX_CATCHUP_BATCH = 10;
 
@@ -11,7 +12,7 @@ const MAX_CATCHUP_BATCH = 10;
  * @param {string} filename
  */
 const safeUnlink = (filename) => {
-    /* istanbul ignore next */
+    /* c8 ignore next */
     try {
         fs.unlinkSync(filename);
     } catch (e) {
@@ -30,8 +31,8 @@ class Consumer extends stream.Readable {
      * @param {Storage} storage The storage to create the consumer for.
      * @param {string} indexName The name of the index to consume.
      * @param {string} identifier The unique name to identify this consumer.
-     * @param {object} [initialState] The initial state of the consumer.
-     * @param {number} [startFrom] The revision to start from within the index to consume.
+     * @param {object} [initialState={}] The initial state of the consumer.
+     * @param {number} [startFrom=0] The revision to start from within the index to consume.
      */
     constructor(storage, indexName, identifier, initialState = {}, startFrom = 0) {
         super({ objectMode: true });
@@ -84,14 +85,11 @@ class Consumer extends stream.Readable {
      * @param {number} startFrom The revision to start from within the index to consume.
      */
     restoreState(initialState, startFrom) {
-        /* istanbul ignore if */
+        /* c8 ignore next 3 */
         if (!this.fileName) {
             return;
         }
-        if (typeof initialState === 'number') {
-            startFrom = initialState;
-            initialState = {};
-        }
+        ({ initialState, startFrom } = normalizeConsumerStateArgs(initialState, startFrom));
         try {
             const consumerData = fs.readFileSync(this.fileName);
             this.position = consumerData.readInt32LE(0);
@@ -111,7 +109,7 @@ class Consumer extends stream.Readable {
      * May only be called from within the document handling callback.
      *
      * @param {object|function(object):object} newState
-     * @param {boolean} [persist] Set to false if this state update should not be persisted yet
+     * @param {boolean} [persist=true] Set to false if this state update should not be persisted yet
      * @api
      */
     setState(newState, persist = true) {
@@ -137,7 +135,6 @@ class Consumer extends stream.Readable {
             return;
         }
 
-        /* istanbul ignore if */
         if (this.position !== position - 1) {
             return;
         }
@@ -151,6 +148,7 @@ class Consumer extends stream.Readable {
         if (this.doPersist) {
             this.persist();
         }
+        this.emit('progress', this.position, this.state);
     }
 
     /**
@@ -170,7 +168,7 @@ class Consumer extends stream.Readable {
             consumerData.write(consumerState, 4, consumerState.length, 'utf-8');
             const tmpFile = this.fileName + '.' + this.position;
             this.persisting = null;
-            /* istanbul ignore if */
+            /* c8 ignore next 3 */
             if (fs.existsSync(tmpFile)) {
                 throw new Error(`Trying to update consumer ${this.name} concurrently. Keep each single consumer within a single process.`);
             }
@@ -180,7 +178,7 @@ class Consumer extends stream.Readable {
                 fs.renameSync(tmpFile, this.fileName);
                 this.emit('persisted', consumerState);
             } catch (e) {
-                /* istanbul ignore next */
+                /* c8 ignore next */
                 safeUnlink(tmpFile);
             }
         });
@@ -244,6 +242,7 @@ class Consumer extends stream.Readable {
                 const maxBatchPosition = Math.min(this.position + MAX_CATCHUP_BATCH + 1, this.index.length);
                 const documents = this.storage.readRange(this.position + 1, maxBatchPosition, this.index);
                 this.consumeDocuments(documents);
+                this.emit('progress', this.position, this.state);
                 this.once('persisted', () => catchUpBatch());
                 this.persist();
             });
@@ -267,15 +266,12 @@ class Consumer extends stream.Readable {
     /**
      * Reset this projection to restart processing all documents again.
      * NOTE: This will overwrite the current state of the projection and hence be destructive.
-     * @param {object} [initialState] The initial state of the consumer.
-     * @param {number} [startFrom] The revision to start from within the index to consume.
+     * @param {object} [initialState={}] The initial state of the consumer.
+     * @param {number} [startFrom=0] The revision to start from within the index to consume.
      * @api
      */
     reset(initialState = {}, startFrom = 0) {
-        if (typeof initialState === 'number') {
-            startFrom = initialState;
-            initialState = {};
-        }
+        ({ initialState, startFrom } = normalizeConsumerStateArgs(initialState, startFrom));
         const restart = this.consuming;
         this.stop();
         this.state = Object.freeze(initialState);