event-storage 0.9.1 → 1.1.0

package/src/EventStream.js

@@ -1,5 +1,5 @@
-const stream = require('stream');
-const { assert } = require('./util');
+import stream from 'stream';
+import { assert } from './util.js';
 
 /**
  * Calculate the actual version number from a possibly relative (negative) version number.
@@ -33,13 +33,16 @@ class EventStream extends stream.Readable {
      * @param {EventStore} eventStore The event store to get the stream from.
      * @param {number} [minRevision] The minimum revision to include in the events (inclusive).
      * @param {number} [maxRevision] The maximum revision to include in the events (inclusive).
+     * @param {function(object, object): boolean|null} [predicate] An optional filter function
+     *   `(payload, metadata) => boolean`.  Only events for which this returns truthy are yielded.
      */
-    constructor(name, eventStore, minRevision = 1, maxRevision = -1) {
+    constructor(name, eventStore, minRevision = 1, maxRevision = -1, predicate = null) {
         super({ objectMode: true });
         assert(typeof name === 'string' && name !== '', 'Need to specify a stream name.');
         assert(typeof eventStore === 'object' && eventStore !== null, `Need to provide EventStore instance to create EventStream ${name}.`);
 
         this.name = name;
+        this.predicate = predicate || null;
         if (eventStore.streams[name]) {
             this.streamIndex = eventStore.streams[name].index;
             this.minRevision = normalizeVersion(minRevision, this.streamIndex.length);
@@ -244,6 +247,23 @@ class EventStream extends stream.Readable {
         return this;
     }
 
+    /**
+     * Apply a filter predicate to this stream.  Only events for which `predicate(payload, metadata)`
+     * returns a truthy value will be yielded.  The predicate is stored as a first-class property
+     * of the stream and applied in {@link EventStream#next}.
+     *
+     * @api
+     * @param {function(object, object): boolean} predicate A function receiving `(payload, metadata)`.
+     *   Events for which the predicate returns falsy are skipped.
+     * @returns {EventStream} `this`
+     */
+    filter(predicate) {
+        this.predicate = predicate || null;
+        this._iterator = null;
+        this._events = null;
+        return this;
+    }
+
     /**
      * @returns {object|boolean} The next event or false if no more events in the stream.
      */
@@ -251,13 +271,17 @@ class EventStream extends stream.Readable {
         if (!this._iterator) {
             this._iterator = this.fetch();
         }
-        let next;
         try {
-            next = this._iterator.next();
+            while (true) {
+                const result = this._iterator.next();
+                if (result.done) return false;
+                if (!this.predicate || this.predicate(result.value.payload, result.value.metadata)) {
+                    return result.value;
+                }
+            }
         } catch(e) {
             return false;
         }
-        return next.done ? false : next.value;
     }
 
     // noinspection JSUnusedGlobalSymbols
@@ -272,4 +296,4 @@ class EventStream extends stream.Readable {
 
 }
 
-module.exports = EventStream;
+export default EventStream;

package/src/Index/ReadOnlyIndex.js

@@ -1,5 +1,5 @@
-const ReadableIndex = require('./ReadableIndex');
-const watchesFile = require('../WatchesFile');
+import ReadableIndex from './ReadableIndex.js';
+import watchesFile from '../WatchesFile.js';
 
 /**
  * A read-only index is a readable index instance that reacts on file changes and triggers events.
@@ -45,4 +45,4 @@ class ReadOnlyIndex extends watchesFile(ReadableIndex) {
 
 }
 
-module.exports = ReadOnlyIndex;
+export default ReadOnlyIndex;

package/src/Index/ReadableIndex.js

@@ -1,8 +1,8 @@
-const fs = require('fs');
-const path = require('path');
-const events = require('events');
-const Entry = require('../IndexEntry');
-const { assert, wrapAndCheck, binarySearch } = require('../util');
+import fs from 'fs';
+import path from 'path';
+import events from 'events';
+import Entry, { assertValidEntryClass } from '../IndexEntry.js';
+import { assert, wrapAndCheck, binarySearch } from '../util.js';
 
 // node-event-store-index V01
 const HEADER_MAGIC = "nesidx01";
@@ -53,7 +53,7 @@ class ReadableIndex extends events.EventEmitter {
             EntryClass: Entry
         };
         options = Object.assign(defaults, options);
-        Entry.assertValidEntryClass(options.EntryClass);
+        assertValidEntryClass(options.EntryClass);
 
         this.name = name;
         this.initialize(options);
@@ -400,7 +400,5 @@ class ReadableIndex extends events.EventEmitter {
     }
 }
 
-module.exports = ReadableIndex;
-module.exports.Entry = Entry;
-module.exports.HEADER_MAGIC = HEADER_MAGIC;
-module.exports.CorruptedIndexError = CorruptedIndexError;
+export default ReadableIndex;
+export { Entry, HEADER_MAGIC, CorruptedIndexError };

package/src/Index/WritableIndex.js

@@ -1,6 +1,8 @@
-const fs = require('fs');
-const ReadableIndex = require('./ReadableIndex');
-const { assertEqual, buildMetadataHeader, ensureDirectory } = require('../util');
+import fs from 'fs';
+import ReadableIndex, { Entry, CorruptedIndexError, HEADER_MAGIC } from './ReadableIndex.js';
+import { assertEqual } from '../util.js';
+import { buildMetadataHeader } from '../metadataUtil.js';
+import { ensureDirectory } from '../fsUtil.js';
 
 /**
  * An index is a simple append-only file that stores an ordered list of entry elements pointing to the actual file position
@@ -71,7 +73,7 @@ class WritableIndex extends ReadableIndex {
             }
             return entries;
         } catch (e) {
-            if (e instanceof ReadableIndex.CorruptedIndexError) {
+            if (e instanceof CorruptedIndexError) {
                 this.truncate(e.size);
                 return e.size;
             }
@@ -107,7 +109,7 @@ class WritableIndex extends ReadableIndex {
         if (!this.metadata) {
             this.metadata = {entryClass: this.EntryClass.name, entrySize: this.EntryClass.size};
         }
-        const metadataBuffer = buildMetadataHeader(ReadableIndex.HEADER_MAGIC, this.metadata);
+        const metadataBuffer = buildMetadataHeader(HEADER_MAGIC, this.metadata);
         fs.writeSync(this.fd, metadataBuffer, 0, metadataBuffer.byteLength, 0);
         this.headerSize = metadataBuffer.byteLength;
     }
@@ -236,5 +238,5 @@ class WritableIndex extends ReadableIndex {
     }
 }
 
-module.exports = WritableIndex;
-module.exports.Entry = ReadableIndex.Entry;
+export default WritableIndex;
+export { Entry };

package/src/Index.js

@@ -1,6 +1,8 @@
-const WritableIndex = require('./Index/WritableIndex');
-const ReadOnlyIndex = require('./Index/ReadOnlyIndex');
+import WritableIndex, { Entry } from './Index/WritableIndex.js';
+import ReadOnlyIndex from './Index/ReadOnlyIndex.js';
 
-module.exports = WritableIndex;
-module.exports.ReadOnly = ReadOnlyIndex;
-module.exports.Entry = WritableIndex.Entry;
+WritableIndex.ReadOnly = ReadOnlyIndex;
+WritableIndex.Entry = Entry;
+
+export default WritableIndex;
+export { ReadOnlyIndex as ReadOnly, Entry };

package/src/IndexEntry.js

@@ -137,6 +137,5 @@ class Entry extends Array {
 
 }
 
-module.exports = Entry;
-module.exports.EntryInterface = EntryInterface;
-module.exports.assertValidEntryClass = assertValidEntryClass;
+export default Entry;
+export { EntryInterface, assertValidEntryClass };

package/src/IndexMatcher.js

@@ -0,0 +1,205 @@
+import { getPropertyAtPath } from './util.js';
+import { matches } from './metadataUtil.js';
+
+/**
+ * @typedef {object|function(object):boolean} Matcher
+ */
+
+/**
+ * Classifies secondary-index matchers into a fast lookup table keyed on a
+ * configurable ordered list of "discriminant" property paths.  This enables O(1)
+ * candidate resolution on write instead of evaluating every registered matcher.
+ *
+ * Object matchers that contain at least one of the discriminant property paths
+ * (in priority order) are stored in a nested Map keyed first by property path and
+ * then by the scalar value found at that path in the matcher.  Function matchers
+ * and object matchers whose discriminant properties all resolve to undefined/object
+ * are kept in separate fallback sets and are always evaluated in full.
+ *
+ * When the discriminant property list is empty, `forEachMatch()` falls back to a
+ * full O(N) scan over all registered indexes.
+ */
+class IndexMatcher {
+
+    /**
+     * @param {string[]} [properties] Ordered list of document property paths (dot-notation)
+     *   used as discriminant keys.  The first path that resolves to a non-null scalar inside
+     *   a given object matcher is used as the key; remaining paths are ignored for that matcher.
+     *   Pass an empty array (the default) to disable the fast path entirely.
+     */
+    constructor(properties = []) {
+        this.properties = properties;
+        /** Map<indexName, Matcher> — stores every registered matcher for full match verification. */
+        this.matchers = new Map();
+        /**
+         * Nested lookup table: Map<propPath, Map<discriminantValue, Set<indexName>>>.
+         * Populated only for object matchers that contain at least one discriminant property.
+         */
+        this.table = new Map();
+        /** Set of index names whose matchers are functions (always evaluated in full). */
+        this.functionMatchers = new Set();
+        /**
+         * Set of index names whose object matchers contain none of the configured
+         * discriminant properties (evaluated in full against every incoming document).
+         */
+        this.unclassifiedMatchers = new Set();
+    }
+
+    /**
+     * Register an index name and its matcher in the lookup structures.
+     *
+     * @param {string} indexName
+     * @param {Matcher} matcher
+     */
+    add(indexName, matcher) {
+        this.matchers.set(indexName, matcher);
+        if (typeof matcher === 'function') {
+            this.functionMatchers.add(indexName);
+            return;
+        }
+        if (!matcher || typeof matcher !== 'object') {
+            this.unclassifiedMatchers.add(indexName);
+            return;
+        }
+
+        const discriminant = this.findDiscriminant(matcher);
+        if (!discriminant) {
+            this.unclassifiedMatchers.add(indexName);
+            return;
+        }
+
+        let propMap = this.table.get(discriminant.propPath);
+        if (!propMap) {
+            propMap = new Map();
+            this.table.set(discriminant.propPath, propMap);
+        }
+        for (const v of discriminant.values) {
+            let indexSet = propMap.get(v);
+            if (!indexSet) {
+                indexSet = new Set();
+                propMap.set(v, indexSet);
+            }
+            indexSet.add(indexName);
+        }
+    }
+
+    /**
+     * Remove an index name from the lookup structures.
+     * The matcher is retrieved from the internal registry, so only the index name
+     * is required.
+     *
+     * @param {string} indexName
+     */
+    remove(indexName) {
+        if (!this.matchers.has(indexName)) {
+            return;
+        }
+        const matcher = this.matchers.get(indexName);
+        this.matchers.delete(indexName);
+        if (typeof matcher === 'function') {
+            this.functionMatchers.delete(indexName);
+            return;
+        }
+        if (!matcher || typeof matcher !== 'object') {
+            this.unclassifiedMatchers.delete(indexName);
+            return;
+        }
+
+        const discriminant = this.findDiscriminant(matcher);
+        if (!discriminant) {
+            this.unclassifiedMatchers.delete(indexName);
+            return;
+        }
+
+        for (const v of discriminant.values) {
+            this.table.get(discriminant.propPath)?.get(v)?.delete(indexName);
+        }
+    }
+
+    /**
+     * Iterate over every registered index whose matcher matches `document`, calling
+     * `iterationHandler` with the index name for each match.
+     *
+     * When `this.properties` is non-empty, an O(1) discriminant lookup narrows the
+     * candidate set before the full `matches()` check is applied.  Each candidate's
+     * matcher is still verified with `matches()` to handle multi-property matchers
+     * where only the first property was used as the discriminant.
+     *
+     * When `this.properties` is empty the method falls back to a full O(N) scan.
+     *
+     * @param {object} document
+     * @param {function(string): void} iterationHandler Called with the index name for each match.
+     */
+    forEachMatch(document, iterationHandler) {
+        if (this.properties.length === 0) {
+            // Fast path disabled: full O(N) scan.
+            for (const [indexName, matcher] of this.matchers) {
+                if (matches(document, matcher)) {
+                    iterationHandler(indexName);
+                }
+            }
+            return;
+        }
+
+        for (const propPath of this.properties) {
+            const docValue = getPropertyAtPath(document, propPath);
+            if (docValue === undefined || docValue === null || typeof docValue === 'object') {
+                continue;
+            }
+
+            const indexSet = this.table.get(propPath)?.get(String(docValue));
+            if (!indexSet) {
+                continue;
+            }
+
+            for (const indexName of indexSet) {
+                if (matches(document, this.matchers.get(indexName))) {
+                    iterationHandler(indexName);
+                }
+            }
+        }
+
+        for (const indexName of this.unclassifiedMatchers) {
+            if (matches(document, this.matchers.get(indexName))) {
+                iterationHandler(indexName);
+            }
+        }
+
+        for (const indexName of this.functionMatchers) {
+            if (matches(document, this.matchers.get(indexName))) {
+                iterationHandler(indexName);
+            }
+        }
+    }
+
+    /**
+     * Find the first usable discriminant for an object matcher.
+     * Returns `{ propPath, values }` for the first entry in `this.properties` that
+     * resolves to a non-null, non-object scalar (or a non-empty array of scalars) inside
+     * `matcher`, or `null` if none.
+     *
+     * For a scalar discriminant `values` contains exactly one element.
+     * For an array-valued discriminant `values` contains all elements of the array.
+     *
+     * @param {object} matcher
+     * @returns {{ propPath: string, values: string[] }|null}
+     */
+    findDiscriminant(matcher) {
+        for (const propPath of this.properties) {
+            const value = getPropertyAtPath(matcher, propPath);
+            if (value !== undefined && value !== null) {
+                if (typeof value !== 'object') {
+                    return { propPath, values: [String(value)] };
+                }
+                if (Array.isArray(value) && value.length > 0 &&
+                    value.every(v => v !== null && v !== undefined && typeof v !== 'object')) {
+                    return { propPath, values: value.map(String) };
+                }
+            }
+        }
+        return null;
+    }
+
+}
+
+export default IndexMatcher;

package/src/JoinEventStream.js

@@ -1,5 +1,8 @@
-const EventStream = require('./EventStream');
-const { wrapAndCheck } = require('./util');
+import EventStream from './EventStream.js';
+import { wrapAndCheck } from './util.js';
+
+/** Reusable sentinel used for missing or empty per-stream iterators. */
+const emptyIterator = Object.freeze({ next() { return { done: true }; } });
 
 /**
  * Calculate the actual version number from a possibly relative (negative) version number.
@@ -24,9 +27,11 @@ class JoinEventStream extends EventStream {
      * @param {EventStore} eventStore The event store to get the stream from.
      * @param {number} [minRevision] The 1-based minimum revision to include in the events (inclusive).
      * @param {number} [maxRevision] The 1-based maximum revision to include in the events (inclusive).
+     * @param {function(object, object): boolean|null} [predicate] An optional filter function
+     *   `(payload, metadata) => boolean`.  Only events for which this returns truthy are yielded.
      */
-    constructor(name, streams, eventStore, minRevision = 1, maxRevision = -1) {
-        super(name, eventStore, minRevision, maxRevision);
+    constructor(name, streams, eventStore, minRevision = 1, maxRevision = -1, predicate = null) {
+        super(name, eventStore, minRevision, maxRevision, predicate);
         if (!(streams instanceof Array) || streams.length === 0) {
             throw new Error(`Invalid list of streams supplied to JoinStream ${name}.`);
         }
@@ -38,12 +43,17 @@ class JoinEventStream extends EventStream {
         this.fetch = function() {
             this._next = new Array(streams.length).fill(undefined);
             return streams.map(streamName => {
-                if (!eventStore.streams[streamName]) {
-                    return { next() { return { done: true }; } };
+                const streamIndex = eventStore.streams[streamName]?.index;
+                if (!streamIndex || streamIndex.length === 0) {
+                    return emptyIterator;
                 }
-                const streamIndex = eventStore.streams[streamName].index;
                 const from = streamIndex.find(this.minRevision, this.minRevision <= this.maxRevision);
                 const until = streamIndex.find(this.maxRevision, this.minRevision > this.maxRevision);
+                if (from === 0 || until === 0) {
+                    // find() returns 0 when the requested revision is outside the stream's range
+                    // (e.g. minRevision > all entries, or maxRevision < all entries).
+                    return emptyIterator;
+                }
                 return eventStore.storage.readRange(from, until, streamIndex);
             });
         }
@@ -78,27 +88,31 @@ class JoinEventStream extends EventStream {
         if (!this._iterator) {
             this._iterator = this.fetch();
         }
-        let nextIndex = -1;
-        this._next.forEach((value, index) => {
-            if (typeof value === 'undefined') {
-                value = this._next[index] = this.getValue(index);
-            }
-            if (value === false) {
-                return;
+        while (true) {
+            let nextIndex = -1;
+            this._next.forEach((value, index) => {
+                if (typeof value === 'undefined') {
+                    value = this._next[index] = this.getValue(index);
+                }
+                if (value === false) {
+                    return;
+                }
+                if (nextIndex === -1 || this.follows(this._next[nextIndex].metadata.commitId, value.metadata.commitId)) {
+                    nextIndex = index;
+                }
+            });
+
+            if (nextIndex === -1) {
+                return false;
             }
-            if (nextIndex === -1 || this.follows(this._next[nextIndex].metadata.commitId, value.metadata.commitId)) {
-                nextIndex = index;
+            const next = this._next[nextIndex];
+            this._next[nextIndex] = undefined;
+            if (!this.predicate || this.predicate(next.payload, next.metadata)) {
+                return next;
             }
-        });
-
-        if (nextIndex === -1) {
-            return false;
         }
-        const next = this._next[nextIndex];
-        this._next[nextIndex] = undefined;
-        return next;
     }
 
 }
 
-module.exports = JoinEventStream;
+export default JoinEventStream;

package/src/Partition/ReadOnlyPartition.js

@@ -1,5 +1,5 @@
-const ReadablePartition = require('./ReadablePartition');
-const WatchesFile = require('../WatchesFile');
+import ReadablePartition from './ReadablePartition.js';
+import WatchesFile from '../WatchesFile.js';
 
 /**
  * A read-only partition is a readable partition that keeps it's size in sync with the underlying file.
@@ -42,4 +42,4 @@ class ReadOnlyPartition extends WatchesFile(ReadablePartition) {
 
 }
 
-module.exports = ReadOnlyPartition;
+export default ReadOnlyPartition;

package/src/Partition/ReadablePartition.js

@@ -1,7 +1,7 @@
-const fs = require('fs');
-const path = require('path');
-const events = require('events');
-const { assert, alignTo, hash, binarySearch } = require('../util');
+import fs from 'fs';
+import path from 'path';
+import events from 'events';
+import { assert, alignTo, hash, binarySearch } from '../util.js';
 
 const DEFAULT_READ_BUFFER_SIZE = 64 * 1024;
 const DOCUMENT_HEADER_SIZE = 16;
@@ -453,11 +453,5 @@ class ReadablePartition extends events.EventEmitter {
     }
 }
 
-module.exports = ReadablePartition;
-module.exports.CorruptFileError = CorruptFileError;
-module.exports.InvalidDataSizeError = InvalidDataSizeError;
-module.exports.HEADER_MAGIC = HEADER_MAGIC;
-module.exports.DOCUMENT_SEPARATOR = DOCUMENT_SEPARATOR;
-module.exports.DOCUMENT_ALIGNMENT = DOCUMENT_ALIGNMENT;
-module.exports.DOCUMENT_HEADER_SIZE = DOCUMENT_HEADER_SIZE;
-module.exports.DOCUMENT_FOOTER_SIZE = DOCUMENT_FOOTER_SIZE;
+export default ReadablePartition;
+export { CorruptFileError, InvalidDataSizeError, HEADER_MAGIC, DOCUMENT_SEPARATOR, DOCUMENT_ALIGNMENT, DOCUMENT_HEADER_SIZE, DOCUMENT_FOOTER_SIZE };

package/src/Partition/WritablePartition.js

@@ -1,10 +1,11 @@
-const fs = require('fs');
-const ReadablePartition = require('./ReadablePartition');
-const { assert, buildMetadataHeader, alignTo, ensureDirectory } = require('../util');
-const Clock = require('../Clock');
+import fs from 'fs';
+import ReadablePartition, { CorruptFileError, HEADER_MAGIC, DOCUMENT_ALIGNMENT, DOCUMENT_SEPARATOR, DOCUMENT_HEADER_SIZE, DOCUMENT_FOOTER_SIZE } from './ReadablePartition.js';
+import { assert, alignTo } from '../util.js';
+import { buildMetadataHeader } from '../metadataUtil.js';
+import { ensureDirectory } from '../fsUtil.js';
+import Clock from '../Clock.js';
 
 const DEFAULT_WRITE_BUFFER_SIZE = 16 * 1024;
-const { DOCUMENT_ALIGNMENT, DOCUMENT_SEPARATOR, DOCUMENT_HEADER_SIZE, DOCUMENT_FOOTER_SIZE } = ReadablePartition;
 const DOCUMENT_PAD = ' '.repeat(DOCUMENT_ALIGNMENT);
 
 /**
@@ -111,7 +112,7 @@ class WritablePartition extends ReadablePartition {
      * @returns void
      */
     writeMetadata() {
-        const metadataBuffer = buildMetadataHeader(ReadablePartition.HEADER_MAGIC, this.metadata);
+        const metadataBuffer = buildMetadataHeader(HEADER_MAGIC, this.metadata);
         fs.writeFileSync(this.fileName, metadataBuffer);
         this.headerSize = metadataBuffer.byteLength;
     }
@@ -387,7 +388,7 @@ class WritablePartition extends ReadablePartition {
         try {
             this.readFrom(after);
         } catch (e) {
-            if (!(e instanceof ReadablePartition.CorruptFileError)) {
+            if (!(e instanceof CorruptFileError)) {
                 throw new Error('Can only truncate on valid document boundaries.');
             }
         }
@@ -419,5 +420,5 @@ class WritablePartition extends ReadablePartition {
     }
 }
 
-module.exports = WritablePartition;
-module.exports.CorruptFileError = ReadablePartition.CorruptFileError;
+export default WritablePartition;
+export { CorruptFileError };

package/src/Partition.js

@@ -1,5 +1,8 @@
-const WritablePartition = require('./Partition/WritablePartition');
-const ReadOnlyPartition = require('./Partition/ReadOnlyPartition');
+import WritablePartition, { CorruptFileError } from './Partition/WritablePartition.js';
+import ReadOnlyPartition from './Partition/ReadOnlyPartition.js';
 
-module.exports = WritablePartition;
-module.exports.ReadOnly = ReadOnlyPartition;
+WritablePartition.ReadOnly = ReadOnlyPartition;
+WritablePartition.CorruptFileError = CorruptFileError;
+
+export default WritablePartition;
+export { ReadOnlyPartition as ReadOnly, CorruptFileError };