event-storage 1.0.0 → 1.1.0

package/README.md

@@ -62,6 +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). |
 | **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. |
@@ -79,6 +81,7 @@ The full documentation is hosted at **<https://node-event-storage.readthedocs.io
 
 - [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.
 - [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

@@ -1,4 +1,4 @@
-export { default as EventStore, default, ExpectedVersion, OptimisticConcurrencyError, LOCK_THROW, LOCK_RECLAIM } from './src/EventStore.js';
+export { default as EventStore, default, ExpectedVersion, OptimisticConcurrencyError, CommitCondition, LOCK_THROW, LOCK_RECLAIM } from './src/EventStore.js';
 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "event-storage",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "An optimized embedded event store for node.js",
   "keywords": [
@@ -44,6 +44,7 @@
     "src/Storage/*.js",
     "src/WatchesFile.js",
     "src/util.js",
+    "src/fsUtil.js",
     "src/metadataUtil.js",
     "index.js"
   ],

package/src/Consumer.js

@@ -1,7 +1,8 @@
 import stream from 'stream';
 import fs from 'fs';
 import path from 'path';
-import { assert, ensureDirectory } from './util.js';
+import { assert } from './util.js';
+import { ensureDirectory } from './fsUtil.js';
 import Storage from './Storage/ReadableStorage.js';
 const MAX_CATCHUP_BATCH = 10;
 

package/src/EventStore.js

@@ -6,15 +6,47 @@ import events from 'events';
 import Storage, { ReadOnly as ReadOnlyStorage, LOCK_THROW, LOCK_RECLAIM } from './Storage.js';
 import Index from './Index.js';
 import Consumer from './Consumer.js';
-import { assert, scanForFiles } from './util.js';
+import { assert, getPropertyAtPath } from './util.js';
+import { ensureDirectory, scanForFiles } from './fsUtil.js';
+import { buildTypeMatcherFn } from './metadataUtil.js';
 
 const ExpectedVersion = {
     Any: -1,
     EmptyStream: 0
 };
 
+/**
+ * Default matcher property paths mirroring the Storage default, used for index optimization.
+ */
+const DEFAULT_MATCHER_PROPERTIES = ['stream', 'payload.type'];
+
 class OptimisticConcurrencyError extends Error {}
 
+/**
+ * An accept condition that captures the global event-log position at the time a {@link EventStore#query}
+ * call was made.  Pass it as the `expectedVersion` argument to {@link EventStore#commit} to enforce
+ * DCB-style (Dynamic Consistency Boundary) optimistic concurrency: the commit is rejected only when
+ * one or more events that match the original query (types + optional matcher) have been appended to
+ * the store between the `query` call and the `commit` call.
+ *
+ * @property {string[]} types   The event types included in the query.
+ * @property {function(object, object): boolean|null} matcher An optional function `(payload, metadata) => boolean`
+ *   used to narrow the conflict check.  When `null`, any new event of a listed type causes a conflict.
+ * @property {number}   noneMatchAfter The global store length (total event count) at the time the query was made.
+ */
+class CommitCondition {
+    /**
+     * @param {string[]} types
+     * @param {function(object, object): boolean|null} [matcher]
+     * @param {number}   noneMatchAfter
+     */
+    constructor(types, matcher = null, noneMatchAfter) {
+        this.types = types;
+        this.matcher = matcher;
+        this.noneMatchAfter = noneMatchAfter;
+    }
+}
+
 /**
  * An event store optimized for working with many streams.
  * An event stream is implemented as an iterator over an index on the storage, therefore indexes need to be lightweight
@@ -29,6 +61,9 @@ class EventStore extends events.EventEmitter {
      * @param {string} [config.streamsDirectory] The directory where the streams should be stored. Default '{storageDirectory}/streams'.
      * @param {object} [config.storageConfig] Additional config options given to the storage backend. See `Storage`.
      * @param {boolean} [config.readOnly] If the storage should be mounted in read-only mode.
+     * @param {string|function(object): string} [config.typeAccessor] Dot-notation path (e.g. `'type'`) or
+     *   function `(event) => string` identifying the event type. Enables type-based queries via
+     *   {@link EventStore#query} and ensures proper index routing for those queries.
      * @param {object|function(string): object} [config.streamMetadata] A metadata object or a function `(streamName) => object`
      *   that is called whenever a new stream partition is created. The returned object is stored once in the partition
      *   file header and surfaced to `preCommit` / `preRead` hooks. Takes precedence only when
@@ -41,6 +76,15 @@ class EventStore extends events.EventEmitter {
             storeName = 'eventstore';
         }
 
+        if (typeof config.typeAccessor === 'string' && config.typeAccessor) {
+            const accessorPath = config.typeAccessor;
+            this.typeAccessor = (event) => getPropertyAtPath(event, accessorPath);
+            this.typeMatcherFn = buildTypeMatcherFn(accessorPath);
+        } else {
+            this.typeAccessor = typeof config.typeAccessor === 'function' ? config.typeAccessor : null;
+            this.typeMatcherFn = null;
+        }
+
         this.storageDirectory = path.resolve(config.storageDirectory || /* istanbul ignore next */ './data');
         let defaults = {
             dataDirectory: this.storageDirectory,
@@ -50,6 +94,17 @@ class EventStore extends events.EventEmitter {
         };
         const storageConfig = Object.assign(defaults, config.storageConfig);
 
+        // When typeAccessor is a string path, ensure the corresponding full document path
+        // (payload.<path>) is present in matcherProperties so the IndexMatcher discriminant
+        // table can route type-stream lookups in O(1) on every write.
+        if (this.typeMatcherFn) {
+            const fullPath = `payload.${config.typeAccessor}`;
+            const currentProps = storageConfig.matcherProperties || DEFAULT_MATCHER_PROPERTIES;
+            if (!currentProps.includes(fullPath)) {
+                storageConfig.matcherProperties = [...currentProps, fullPath];
+            }
+        }
+
         // Translate the high-level streamMetadata option into the storage-level metadata function,
         // but only when the caller has not already provided a lower-level storageConfig.metadata.
         if (config.streamMetadata !== undefined && storageConfig.metadata === undefined) {
@@ -75,18 +130,17 @@ class EventStore extends events.EventEmitter {
         this.storage = (storageConfig.readOnly === true) ?
                         new ReadOnlyStorage(storeName, storageConfig)
                         : new Storage(storeName, storageConfig);
-        this.storage.open();
         this.streams = Object.create(null);
         this.streams._all = { index: this.storage.index };
 
-        this.scanStreams((err) => {
-            if (err) {
-                this.storage.close();
-                throw err;
-            }
+        this.storage.on('index-created', this.registerStream.bind(this));
+
+        this.storage.on('opened', () => {
             this.checkUnfinishedCommits();
             this.emit('ready');
         });
+
+        this.storage.open();
     }
 
     /**
@@ -121,22 +175,6 @@ class EventStore extends events.EventEmitter {
         }
     }
 
-    /**
-     * Scan the streams directory for existing streams so they are ready for `getEventStream()`.
-     *
-     * @private
-     * @param {function} callback A callback that will be called when all existing streams are found.
-     */
-    scanStreams(callback) {
-        /* istanbul ignore if */
-        if (typeof callback !== 'function') {
-            callback = () => {};
-        }
-        // Find existing streams by scanning dir for filenames starting with 'stream-'
-        scanForFiles(this.streamsDirectory, /(stream-.*)\.index$/, this.registerStream.bind(this), callback);
-        this.storage.on('index-created', this.registerStream.bind(this));
-    }
-
     /**
      * @private
      * @param {string} name The full stream name, including the `stream-` prefix (and optional `.closed` suffix).
@@ -299,16 +337,16 @@ class EventStore extends events.EventEmitter {
      *
      * @private
      * @param {Array<object>|object} events
-     * @param {number} [expectedVersion]
+     * @param {number|CommitCondition} [expectedVersion]
      * @param {object|function} [metadata]
      * @param {function} [callback]
-     * @returns {{events: Array<object>, metadata: object, callback: function, expectedVersion: number}}
+     * @returns {{events: Array<object>, metadata: object, callback: function, expectedVersion: number|CommitCondition}}
      */
     static fixArgumentTypes(events, expectedVersion, metadata, callback) {
         if (!(events instanceof Array)) {
             events = [events];
         }
-        if (typeof expectedVersion !== 'number') {
+        if (typeof expectedVersion !== 'number' && !(expectedVersion instanceof CommitCondition)) {
             callback = metadata;
             metadata = expectedVersion;
             expectedVersion = ExpectedVersion.Any;
@@ -323,6 +361,58 @@ class EventStore extends events.EventEmitter {
         return { events, expectedVersion, metadata, callback };
     }
 
+    /**
+     * Check a {@link CommitCondition} against the current state of the store.
+     * Iterates a join stream over all condition type streams starting from
+     * `condition.noneMatchAfter` (the global position captured at query time), and throws an
+     * {@link OptimisticConcurrencyError} when a new event of a listed type satisfies
+     * `condition.matcher(payload, metadata)` (or any such event when no matcher is provided).
+     *
+     * @param {CommitCondition} condition
+     * @throws {OptimisticConcurrencyError}
+     */
+    checkCondition(condition) {
+        if (this.storage.length <= condition.noneMatchAfter) return; // no new events since condition was obtained
+
+        const existingTypes = condition.types.filter(t => t in this.streams);
+        if (existingTypes.length === 0) return;
+
+        // Only events after condition.noneMatchAfter can be conflicts.
+        const stream = this.fromStreams(
+            '_check_' + condition.types.join('_'),
+            existingTypes,
+            condition.noneMatchAfter + 1
+        );
+
+        let next;
+        while ((next = stream.next()) !== false) {
+            if (!condition.matcher || condition.matcher(next.payload, next.metadata)) {
+                throw new OptimisticConcurrencyError(
+                    `Optimistic Concurrency error. A conflicting event was committed since the condition was obtained.`
+                );
+            }
+        }
+    }
+
+    /**
+     * Ensure a dedicated type stream exists for each event's type, creating it if needed.
+     * Must be called before the entity stream is created to guarantee correct index routing.
+     *
+     * @param {Array<object>} events The events to process.
+     */
+    ensureTypeStreams(events) {
+        if (!this.typeAccessor) return;
+        for (const event of events) {
+            const type = this.typeAccessor(event);
+            if (type && !(type in this.streams)) {
+                const matcher = this.typeMatcherFn
+                    ? this.typeMatcherFn(type)
+                    : (doc) => this.typeAccessor(doc.payload) === type;
+                this.createEventStream(type, matcher, false);
+            }
+        }
+    }
+
     /**
      * Commit a list of events for the given stream name, which is expected to be at the given version.
      * Note that the events committed may still appear in other streams too - the given stream name is only
@@ -331,10 +421,12 @@ class EventStore extends events.EventEmitter {
      * @api
      * @param {string} streamName The name of the stream to commit the events to.
      * @param {Array<object>|object} events The events to commit or a single event.
-     * @param {number} [expectedVersion] One of ExpectedVersion constants or a positive version number that the stream is supposed to be at before commit.
+     * @param {number|CommitCondition} [expectedVersion] One of the `ExpectedVersion` constants, a positive
+     *   stream version number, or a {@link CommitCondition} obtained from {@link EventStore#query}.
      * @param {object} [metadata] The commit metadata to use as base. Useful for replication and adding storage metadata.
      * @param {function} [callback] A function that will be executed when all events have been committed.
-     * @throws {OptimisticConcurrencyError} if the stream is not at the expected version.
+     * @throws {OptimisticConcurrencyError} if the stream is not at the expected version, or if a
+     *   {@link CommitCondition} was provided and conflicting events have been committed since it was obtained.
      */
     commit(streamName, events, expectedVersion = ExpectedVersion.Any, metadata = {}, callback = null) {
         assert(!(this.storage instanceof ReadOnlyStorage), 'The storage was opened in read-only mode. Can not commit to it.');
@@ -343,8 +435,18 @@ class EventStore extends events.EventEmitter {
 
         ({ events, expectedVersion, metadata, callback } = EventStore.fixArgumentTypes(events, expectedVersion, metadata, callback));
 
+        // Perform DCB-style concurrency check when a CommitCondition is provided.
+        if (expectedVersion instanceof CommitCondition) {
+            this.checkCondition(expectedVersion);
+            expectedVersion = ExpectedVersion.Any;
+        }
+
+        // When typeAccessor is configured, ensure a dedicated type stream exists for each event
+        // before the entity stream write so the type stream index is never incomplete.
+        this.ensureTypeStreams(events);
+
         if (!(streamName in this.streams)) {
-            this.createEventStream(streamName, { stream: streamName });
+            this.createEventStream(streamName, { stream: streamName }, false);
         }
         assert(!this.streams[streamName].closed, `Stream "${streamName}" is closed and cannot be written to.`);
         let streamVersion = this.streams[streamName].index.length;
@@ -394,6 +496,56 @@ class EventStore extends events.EventEmitter {
         return this.streams[streamName].index.length;
     }
 
+    /**
+     * Query the event store for events matching a set of event types and an optional filter function.
+     * Returns a pre-filtered event stream and a {@link CommitCondition} that can be passed to
+     * {@link EventStore#commit} to enforce optimistic concurrency.
+     *
+     * A conflict occurs when at least one event appended between the `query` call and the `commit` call
+     * belongs to one of the listed types and (when `matcher` is provided) also satisfies
+     * `matcher(payload, metadata)`.  Events written before the `query` call are never treated as conflicts.
+     *
+     * **Behaviour when a type stream does not exist:**
+     * - Without `typeAccessor` configured: throws an error, because the store cannot guarantee that no
+     *   events of that type exist (the stream was never created).  Create the stream explicitly first,
+     *   or configure `typeAccessor` to have streams created automatically on commit.
+     * - With `typeAccessor` configured: treats the missing stream as empty (0-length).  The stream will
+     *   be created automatically the first time an event of that type is committed.
+     *
+     * @api
+     * @param {string[]} types A non-empty array of event-type names to query.
+     * @param {function(object, object): boolean|null} [matcher] An optional filter function `(payload, metadata) => boolean`
+     *   passed to the returned {@link CommitCondition}.
+     * @param {number} [minRevision=1] The 1-based minimum global revision to include in the returned stream (inclusive).
+     * @returns {{ condition: CommitCondition, stream: EventStream }} An object with:
+     *   - `condition` — the {@link CommitCondition} to pass to {@link EventStore#commit}.
+     *   - `stream` — a read-only event stream containing all matching events.
+     * @throws {Error} if `types` is not a non-empty array.
+     * @throws {Error} if `typeAccessor` is not configured and any of the listed type streams do not exist.
+     */
+    query(types, matcher = null, minRevision = 1) {
+        assert(Array.isArray(types) && types.length > 0, 'Must specify a non-empty array of event types for query.');
+
+        const queryTypes = [];
+        for (const type of types) {
+            if (!(type in this.streams)) {
+                if (this.typeAccessor) {
+                    // typeAccessor is configured: type streams are created on commit, so a missing
+                    // stream simply means no event of this type has been committed yet — treat as empty.
+                    continue;
+                }
+                // No typeAccessor: the stream was never created; we cannot know whether events of
+                // this type exist in the store, so throw to avoid an unintentional full-store scan.
+                throw new Error(`Type stream "${type}" does not exist. Create it with createEventStream() first, or configure typeAccessor to have type streams created automatically on commit.`);
+            }
+            queryTypes.push(type);
+        }
+
+        const condition = new CommitCondition(types, matcher, this.storage.length);
+        const stream = this.fromStreams('_query_' + types.join('_'), queryTypes, minRevision, -1, matcher);
+        return { stream, condition };
+    }
+
     /**
      * Get an event stream for the given stream name within the revision boundaries.
      *
@@ -430,25 +582,39 @@ class EventStore extends events.EventEmitter {
      * @param {Array<string>} streamNames An array of the stream names to join.
      * @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 predicate
+     *   `(payload, metadata) => boolean`. Only events for which this returns truthy are yielded.
      * @returns {EventStream} The joined event stream.
      * @throws {Error} if any of the streams doesn't exist.
      */
-    fromStreams(streamName, streamNames, minRevision = 1, maxRevision = -1) {
+    fromStreams(streamName, streamNames, minRevision = 1, maxRevision = -1, predicate = null) {
         assert(streamNames instanceof Array, 'Must specify an array of stream names.');
 
+        if (streamNames.length === 0) {
+            return new EventStream(streamName, this);
+        }
+
         for (let stream of streamNames) {
             assert(stream in this.streams, `Stream "${stream}" does not exist.`);
         }
-        return new JoinEventStream(streamName, streamNames, this, minRevision, maxRevision);
+
+        if (streamNames.length === 1) {
+            const stream = new EventStream(streamNames[0], this, minRevision, maxRevision, predicate);
+            stream.name = streamName;
+            return stream;
+        }
+
+        return new JoinEventStream(streamName, streamNames, this, minRevision, maxRevision, predicate);
     }
 
     /**
      * Get a stream for a category of streams. This will effectively return a joined stream of all streams that start
-     * with the given `categoryName` followed by a dash.
+     * with the given `categoryName` followed by a dash (flat layout, e.g. `users-123`) or a slash (hierarchical
+     * layout, e.g. `users/123`).
      * If you frequently use this for a category consisting of a lot of streams (e.g. `users`), consider creating a
      * dedicated physical stream for the category:
      *
-     *    `eventstore.createEventStream('users', e => e.stream.startsWith('users-'))`
+     *    `eventstore.createEventStream('users', e => e.stream.startsWith('users-') || e.stream.startsWith('users/'))`
      *
      * @api
      * @param {string} categoryName The name of the category to get a stream for. A category is a stream name prefix.
@@ -461,7 +627,10 @@ class EventStore extends events.EventEmitter {
         if (categoryName in this.streams) {
             return this.getEventStream(categoryName, minRevision, maxRevision);
         }
-        const categoryStreams = Object.keys(this.streams).filter(streamName => streamName.startsWith(categoryName + '-'));
+        const categoryStreams = Object.keys(this.streams).filter(streamName =>
+            streamName.startsWith(categoryName + '-') ||
+            streamName.startsWith(categoryName + '/')
+        );
 
         if (categoryStreams.length === 0) {
             throw new Error(`No streams for category '${categoryName}' exist.`);
@@ -475,16 +644,21 @@ class EventStore extends events.EventEmitter {
      * @api
      * @param {string} streamName The name of the stream to create.
      * @param {object|function(event)} matcher A matcher object, denoting the properties that need to match on an event a function that takes the event and returns true if the event should be added.
+     * @param {boolean} [reindex=true] Whether to scan existing documents and populate the new index. Set to false when it is known that no existing documents can match the matcher (e.g. when creating a brand-new write stream).
      * @returns {EventStream} The EventStream with all existing events matching the matcher.
      * @throws {Error} If a stream with that name already exists.
      * @throws {Error} If the stream could not be created.
      */
-    createEventStream(streamName, matcher) {
+    createEventStream(streamName, matcher, reindex = true) {
         assert(!(this.storage instanceof ReadOnlyStorage), 'The storage was opened in read-only mode. Can not create new stream on it.');
         assert(!(streamName in this.streams), 'Can not recreate stream!');
 
         const streamIndexName = 'stream-' + streamName;
-        const index = this.storage.ensureIndex(streamIndexName, matcher);
+        if (streamName.includes('/')) {
+            const subDir = path.join(this.streamsDirectory, this.storeName + '.stream-' + path.dirname(streamName));
+            ensureDirectory(subDir);
+        }
+        const index = this.storage.ensureIndex(streamIndexName, matcher, reindex);
         assert(index !== null, `Error creating stream index ${streamName}.`);
 
         // deepcode ignore PrototypePollutionFunctionParams: streams is a Map
@@ -543,7 +717,7 @@ class EventStore extends events.EventEmitter {
         fs.renameSync(index.fileName, closedFileName);
 
         // Remove from secondary indexes so that new writes are no longer indexed into this stream
-        delete this.storage.secondaryIndexes[indexName];
+        this.storage.removeSecondaryIndex(indexName);
 
         // Reopen the renamed index for read access, outside the secondary indexes write path
         const closedIndexName = indexName + '.closed';
@@ -594,4 +768,4 @@ EventStore.Storage = Storage;
 EventStore.Index = Index;
 
 export default EventStore;
-export { ExpectedVersion, OptimisticConcurrencyError, LOCK_THROW, LOCK_RECLAIM };
+export { ExpectedVersion, OptimisticConcurrencyError, CommitCondition, LOCK_THROW, LOCK_RECLAIM };

package/src/EventStream.js

@@ -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

package/src/Index/WritableIndex.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import ReadableIndex, { Entry, CorruptedIndexError, HEADER_MAGIC } from './ReadableIndex.js';
-import { assertEqual, buildMetadataHeader, ensureDirectory } from '../util.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