event-storage 1.1.0 → 1.3.0

package/src/utils/metadataUtil.js

@@ -0,0 +1,517 @@
+import crypto from 'crypto';
+import {assert, assertEqual} from './util.js';
+import {
+    indexOfSameLevel,
+    findJsonValueEnd,
+    parseJsonValue,
+    matchesAnyValuePattern,
+    isOpeningObject,
+    compareNumeric
+} from './jsonUtil.js';
+
+const compiledOperatorMatcherCache = new WeakMap();
+
+/**
+ * @param {any} value Value to classify.
+ * @returns {boolean} True when `value` is a non-null object.
+ */
+function isObject(value) {
+    return value !== null && typeof value === 'object';
+}
+
+/**
+ * @param {any} value Value to classify.
+ * @returns {boolean} True when `value` is a non-array object.
+ */
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * @param {object} obj Candidate matcher object.
+ * @returns {boolean} True when all keys are operator keys (`$...`).
+ */
+function isOperatorObject(obj) {
+    const keys = Object.keys(obj);
+    return keys.length > 0 && keys.every(key => key.startsWith('$'));
+}
+
+/**
+ * Dispatch between array (OR), operator object, nested object, and scalar equality matching
+ * so callers don't need to know the shape of `matcherValue`.
+ *
+ * @param {any} documentValue Value from the document.
+ * @param {any} matcherValue Value from the matcher definition.
+ * @returns {boolean} True when both values match under matcher semantics.
+ */
+function propertyMatchesValue(documentValue, matcherValue) {
+    if (isObject(matcherValue)) {
+        if (Array.isArray(matcherValue)) {
+            return matcherValue.includes(documentValue);
+        } else if (isOperatorObject(matcherValue)) {
+            const operatorChecks = getCompiledOperatorChecks(matcherValue);
+            return matchesCompiledOperators(documentValue, operatorChecks);
+        }
+        return matches(documentValue, matcherValue);
+    }
+    return typeof matcherValue === 'undefined' || documentValue === matcherValue;
+}
+
+/**
+ * Pre-compile an operator object into an array of comparison closures so the hot path avoids
+ * repeated `Object.entries` + switch dispatch per matched document.
+ *
+ * @param {object} operatorObj Object containing operator/value pairs.
+ * @returns {Array<function(any): boolean>} Compiled predicate checks in evaluation order.
+ */
+function buildOperatorChecks(operatorObj) {
+    const checks = [];
+    for (const [operator, expectedValue] of Object.entries(operatorObj)) {
+        switch (operator) {
+            case '$gt':
+                checks.push(value => value > expectedValue);
+                break;
+            case '$gte':
+                checks.push(value => value >= expectedValue);
+                break;
+            case '$lt':
+                checks.push(value => value < expectedValue);
+                break;
+            case '$lte':
+                checks.push(value => value <= expectedValue);
+                break;
+            case '$eq':
+                checks.push(value => value === expectedValue);
+                break;
+            case '$ne':
+                checks.push(value => value !== expectedValue);
+                break;
+            default:
+                throw new TypeError(`Unknown operator: ${operator}`);
+        }
+    }
+    return checks;
+}
+
+/**
+ * Return cached compiled checks for `operatorObj`, compiling and caching on first access.
+ * Using WeakMap keeps operator objects GC-eligible and avoids mutating user-supplied objects.
+ *
+ * @param {object} operatorObj Object containing operator/value pairs.
+ * @returns {Array<function(any): boolean>} Cached or newly compiled operator checks.
+ */
+function getCompiledOperatorChecks(operatorObj) {
+    const cachedChecks = compiledOperatorMatcherCache.get(operatorObj);
+    if (cachedChecks) {
+        return cachedChecks;
+    }
+    const checks = buildOperatorChecks(operatorObj);
+    compiledOperatorMatcherCache.set(operatorObj, checks);
+    return checks;
+}
+
+/**
+ * @param {any} documentValue Parsed scalar value from the document.
+ * @param {Array<function(any): boolean>} checks Compiled operator checks.
+ * @returns {boolean} True when all checks pass.
+ */
+function matchesCompiledOperators(documentValue, checks) {
+    if (documentValue === undefined) {
+        return false;
+    }
+    for (const check of checks) {
+        if (!check(documentValue)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Build a buffer containing the file magic header and a JSON stringified metadata block, padded to be a multiple of 16 bytes long.
+ *
+ * @param {string} magic
+ * @param {object} metadata
+ * @returns {Buffer} A buffer containing the header data
+ */
+function buildMetadataHeader(magic, metadata) {
+    assertEqual(magic.length, 8, 'The header magic bytes length is wrong.');
+    let metadataString = JSON.stringify(metadata);
+    let metadataSize = Buffer.byteLength(metadataString, 'utf8');
+    // 8 byte MAGIC, 4 byte metadata size, 1 byte line break
+    const pad = (16 - ((8 + 4 + metadataSize + 1) % 16)) % 16;
+    metadataString += ' '.repeat(pad) + "\n";
+    metadataSize += pad + 1;
+    const metadataBuffer = Buffer.allocUnsafe(8 + 4 + metadataSize);
+    metadataBuffer.write(magic, 0, 8, 'utf8');
+    metadataBuffer.writeUInt32BE(metadataSize, 8);
+    metadataBuffer.write(metadataString, 8 + 4, metadataSize, 'utf8');
+    return metadataBuffer;
+}
+
+/**
+ * @param {string} secret The secret to use for calculating further HMACs
+ * @returns {function(string)} A function that calculates the HMAC for a given string
+ */
+const createHmac = secret => string => {
+    const hmac = crypto.createHmac('sha256', secret);
+    hmac.update(string);
+    return hmac.digest('hex');
+};
+
+/**
+ * @typedef {object|function(object):boolean} Matcher
+ */
+
+/**
+ * @param {object} document The document to check against the matcher.
+ * @param {Matcher} matcher An object of properties and their values that need to match in the object or a function that checks if the document matches.
+ * @returns {boolean} True if the document matches the matcher or false otherwise.
+ */
+function matches(document, matcher) {
+    if (typeof document === 'undefined') return false;
+    if (typeof matcher === 'undefined') return true;
+
+    if (typeof matcher === 'function') return matcher(document);
+
+    for (let prop of Object.getOwnPropertyNames(matcher)) {
+        if (!propertyMatchesValue(document[prop], matcher[prop])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * @param {Matcher} matcher The matcher object or function that should be serialized.
+ * @param {function(string)} hmac A function that calculates a HMAC of the given string.
+ * @returns {{matcher: string|object, hmac?: string}}
+ */
+function buildMetadataForMatcher(matcher, hmac) {
+     /* c8 ignore next 2 */
+     if (!matcher) {
+         return undefined;
+     }
+    if (typeof matcher === 'object') {
+        return {matcher};
+    }
+    const matcherString = matcher.toString();
+    return {matcher: matcherString, hmac: hmac(matcherString)};
+}
+
+/**
+ * @param {{matcher: string|object, hmac: string}} matcherMetadata The serialized matcher and its HMAC
+ * @param {function(string)} hmac A function that calculates a HMAC of the given string.
+ * @returns {Matcher} The matcher object or function.
+ */
+function buildMatcherFromMetadata(matcherMetadata, hmac) {
+     let matcher;
+     if (typeof matcherMetadata.matcher === 'object') {
+         matcher = matcherMetadata.matcher;
+     } else {
+         /* c8 ignore next 1 */
+         assert(matcherMetadata.hmac === hmac(matcherMetadata.matcher), 'Invalid HMAC for matcher.');
+
+        matcher = eval('(' + matcherMetadata.matcher + ')').bind({}); // jshint ignore:line
+    }
+    return matcher;
+}
+
+/**
+ * Builds a factory function that, given a type string, returns an object matcher for
+ * documents whose payload contains that type at the given dot-notation path.
+ *
+ * @param {string} payloadPath Dot-notation path relative to the event payload (e.g. `'type'`, `'meta.kind'`).
+ * @returns {function(string): object} A function `(typeValue) => objectMatcher`.
+ */
+function buildTypeMatcherFn(payloadPath) {
+    const parts = payloadPath.split('.');
+    return function (typeValue) {
+        let obj = typeValue;
+        for (let i = parts.length - 1; i >= 0; i--) {
+            obj = {[parts[i]]: obj};
+        }
+        return {payload: obj};
+    };
+}
+
+/**
+ * Compile an object matcher into a raw-buffer predicate so raw-mode reads can filter compact
+ * JSON without parsing every document first.
+ *
+ * @param {object} matcher Object matcher to compile.
+ * @param {{enableOperatorBufferMatcher?: boolean}} [options] Raw matcher build options.
+ * @returns {function(Buffer): boolean} Predicate over compact JSON buffers.
+ */
+function buildRawBufferMatcher(matcher = {}, options = {}) {
+    assert(isPlainObject(matcher), 'Matcher must be an object.', TypeError);
+    const enableOperatorBufferMatcher = options.enableOperatorBufferMatcher !== false;
+
+    const root = buildMatcherTree(matcher, enableOperatorBufferMatcher);
+    /* c8 ignore next 3 */
+    if (root.children.length === 0) {
+        return () => true;
+    }
+
+    return function matchesRawBuffer(buffer) {
+        if (!isOpeningObject(buffer[0])) {
+            return false;
+        }
+        if (!preCheck(buffer, 1, root)) {
+            return false;
+        }
+        return matchesNode(buffer, 1, root);
+    };
+}
+
+/**
+ * Compile a matcher object into a tree whose children each carry one primary byte pattern plus
+ * optional follow-up checks for nested objects, operators, or multi-value scalars.
+ * Fast scalar-equality children are placed first so preCheck and matchesNode short-circuit early.
+ *
+ * @param {object} matcher Matcher object for this tree level.
+ * @returns {{children: Array<object>}} Compiled child descriptors for this level.
+ */
+function buildMatcherTree(matcher) {
+    const fast = [];
+    const slow = [];
+
+    for (const [key, value] of Object.entries(matcher)) {
+        const child = buildMatcherTreeChild(key, value);
+        // A child with only one byte pattern and no follow-up matcher cannot be outperformed by any extra matcher logic.
+        (!child.matches ? fast : slow).push(child);
+    }
+
+    return {children: [...fast, ...slow]};
+}
+
+/**
+ * Normalize one matcher property into the cheapest raw-buffer strategy for that value shape.
+ * Children that compile to a plain byte-equality pattern leave `matches` as null.
+ *
+ * @param {string} key Property name at this matcher level.
+ * @param {any} value Matcher value for `key`.
+ * @returns {{pattern: Buffer, isKeyPattern: boolean, matches: ((function(Buffer, number): boolean)|null), node: ({children: Array<object>}|null), lastMatch: number}} Compiled descriptor consumed by preCheck/matchesNode.
+ */
+function buildMatcherTreeChild(key, value) {
+    const keyPrefix = Buffer.from(`${JSON.stringify(key)}:`, 'utf8');
+    const child = {
+        pattern: null,
+        isKeyPattern: false,
+        matches: null,
+        node: null,
+        lastMatch: -1
+    };
+
+    if (isObject(value)) {
+        if (Array.isArray(value)) {
+            assert(!value.some(isObject), 'Array matcher values must be scalars.', TypeError);
+            if (value.length === 1) {
+                child.pattern = buildKeyValuePattern(keyPrefix, value[0]);
+            } else {
+                child.isKeyPattern = true;
+                child.pattern = keyPrefix;
+                const valuePatterns = value.map(item => Buffer.from(JSON.stringify(item), 'utf8'));
+                child.matches = (buffer, startOffset) => matchesAnyValuePattern(buffer, startOffset, valuePatterns);
+            }
+        } else if ('$eq' in value && Object.keys(value).length === 1) {
+            // A lone $eq is semantically identical to a scalar equality check — fold it into a
+            // value pattern at compile time so the buffer scan takes the same fast path as { key: value }.
+            child.pattern = buildKeyValuePattern(keyPrefix, value['$eq']);
+        } else if ('$ne' in value && Object.keys(value).length === 1) {
+            // A lone $ne is the logical negation of $eq: confirm the key exists at this level,
+            // then reject only when the value byte-matches the excluded pattern.
+            child.isKeyPattern = true;
+            child.pattern = keyPrefix;
+            const nePattern = [Buffer.from(JSON.stringify(value['$ne']), 'utf8')];
+            child.matches = (buffer, valueStart) => !matchesAnyValuePattern(buffer, valueStart, nePattern);
+        } else if (isOperatorObject(value)) {
+            child.isKeyPattern = true;
+            child.pattern = keyPrefix;
+            child.matches = buildOperatorBufferMatcher(value);
+        } else {
+            child.pattern = Buffer.concat([keyPrefix, Buffer.from('{', 'utf8')]);
+            child.node = buildMatcherTree(value);
+            child.matches = (buffer, startOffset) => matchesNode(buffer, startOffset, child.node);
+        }
+    } else {
+        child.pattern = buildKeyValuePattern(keyPrefix, value);
+    }
+    return child;
+}
+
+/**
+ * @param {Buffer} keyPrefix Serialized key prefix (`"key":`).
+ * @param {any} value Scalar value to append.
+ * @returns {Buffer} Full serialized `"key":value` pattern.
+ */
+function buildKeyValuePattern(keyPrefix, value) {
+    return Buffer.concat([keyPrefix, Buffer.from(JSON.stringify(value), 'utf8')]);
+}
+
+/**
+ * Cheap pass: confirm each child's primary pattern exists somewhere and cache that position as a
+ * hint for the depth-aware pass that follows.
+ *
+ * @param {Buffer} buffer Compact JSON document buffer.
+ * @param {number} startOffset Start offset within `buffer`.
+ * @param {{children: Array<object>}} node Compiled matcher node for this level.
+ * @returns {boolean} True when every child pattern exists somewhere from `startOffset`.
+ */
+function preCheck(buffer, startOffset, node) {
+    for (const child of node.children) {
+        child.lastMatch = buffer.indexOf(child.pattern, startOffset);
+        if (child.lastMatch === -1) {
+            return false;
+        }
+        if (child.node && !preCheck(buffer, child.lastMatch, child.node)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Confirm that each prechecked child really matches at the requested JSON level and then run the
+ * optional value-specific follow-up checks from the compiled tree.
+ *
+ * @param {Buffer} buffer Compact JSON document buffer.
+ * @param {number} startOffset Start offset within `buffer`.
+ * @param {{children: Array<object>}} node Compiled matcher node for this level.
+ * @returns {boolean} True when all children match at the requested JSON level.
+ */
+function matchesNode(buffer, startOffset, node) {
+    for (const child of node.children) {
+        const matchPosition = indexOfSameLevel(buffer, child.pattern, startOffset, child.lastMatch, child.isKeyPattern);
+        if (matchPosition === -1) {
+            return false;
+        }
+
+        const valueStart = matchPosition + child.pattern.length;
+        if (child.matches && !child.matches(buffer, valueStart)) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Parse the scalar at a matched key position only when operator objects require a real JavaScript
+ * comparison instead of a pure byte-pattern check.
+ *
+ * @param {Buffer} buffer Compact JSON document buffer.
+ * @param {number} startOffset Offset of the scalar value to parse.
+ * @param {Array<function(any): boolean>} operatorChecks Compiled operator checks.
+ * @returns {boolean} True when the parsed scalar satisfies all operators.
+ */
+function matchesOperatorInBuffer(buffer, startOffset, operatorChecks) {
+     const valueStart = startOffset;
+     const valueEnd = findJsonValueEnd(buffer, valueStart);
+     /* c8 ignore next 2 */
+     if (valueEnd === -1 || valueEnd <= valueStart) {
+         return false;
+     }
+
+    const parsedValue = parseJsonValue(buffer, valueStart, valueEnd);
+
+    return matchesCompiledOperators(parsedValue, operatorChecks);
+}
+
+/**
+ * Map pre-computed ordering information to operator semantics.
+ * ordering: -1 (actual < expected), 0 (equal), 1 (actual > expected)
+ *
+ * @param {string} operator
+ * @param {-1|0|1} ordering
+ * @returns {boolean}
+ */
+function matchesOrdering(operator, ordering) {
+     switch (operator) {
+         case '$gt':
+             return ordering === 1;
+         case '$gte':
+             return ordering >= 0;
+         case '$lt':
+             return ordering === -1;
+         case '$lte':
+             return ordering <= 0;
+         case '$eq':
+             return ordering === 0;
+         case '$ne':
+             return ordering !== 0;
+         /* c8 ignore next 1 */
+         default:
+             return false;
+     }
+ }
+
+/**
+ * @param {Array<[string, any]>} entries
+ * @returns {Array<{operator: string, expectedNumeric: {isNegative: boolean, integerPart: string, fractionPart: string}}>|null}
+ */
+function buildNumericOperatorComparisons(entries) {
+    const comparisons = [];
+    for (const [operator, expectedValue] of entries) {
+        if (typeof expectedValue !== 'number') {
+            return null;
+        }
+        const expectedStr = JSON.stringify(expectedValue);
+        const expectedIsNegative = expectedStr[0] === '-';
+        const intStart = expectedIsNegative ? 1 : 0;
+        const [expectedIntegerPart, expectedFractionPart = ''] = expectedStr.substring(intStart).split('.');
+        comparisons.push({
+            operator,
+            expectedNumeric: {
+                isNegative: expectedIsNegative,
+                integerPart: expectedIntegerPart,
+                fractionPart: expectedFractionPart
+            }
+        });
+    }
+    return comparisons;
+}
+
+/**
+ * Build a specialized buffer-based operator comparator by pre-compiling operator-specific
+ * byte shortcuts at matcher build time. This avoids runtime dispatch and enables aggressive
+ * short-circuit evaluation for sign mismatches and digit-count differences.
+ *
+ * Assumes no scientific notation in the JSON buffer.
+ *
+ * @param {object} operatorObj Operator object (e.g., { $gt: 100 }).
+ * @returns {function(Buffer, number): boolean} Predicate that reads the buffer at given offset.
+ */
+function buildOperatorBufferMatcher(operatorObj) {
+    const entries = Object.entries(operatorObj);
+    const numericComparisons = buildNumericOperatorComparisons(entries);
+    if (numericComparisons) {
+        return (buffer, startOffset) => {
+            for (const comparison of numericComparisons) {
+                const ordering = compareNumeric(buffer, startOffset, comparison.expectedNumeric);
+                /* c8 ignore next 2 */
+                if (ordering === null) {
+                    return false;
+                }
+                if (!matchesOrdering(comparison.operator, ordering)) {
+                    return false;
+                }
+            }
+            return true;
+        };
+    }
+
+    // Non-numeric expected value: use generic operator checks.
+    const operatorChecks = getCompiledOperatorChecks(operatorObj);
+    return (buffer, startOffset) => matchesOperatorInBuffer(buffer, startOffset, operatorChecks);
+}
+
+export {
+    createHmac,
+    matches,
+    buildMetadataHeader,
+    buildMetadataForMatcher,
+    buildMatcherFromMetadata,
+    buildTypeMatcherFn,
+    buildRawBufferMatcher
+};

package/src/{util.js → utils/util.js}

@@ -1,9 +1,10 @@
 /**
  * Assert that actual and expected match or throw an Error with the given message appended by information about expected and actual value.
  *
- * @param {*} actual
- * @param {*} expected
- * @param {string} message
+ * @param {*} actual Actual value.
+ * @param {*} expected Expected value.
+ * @param {string} message Error message prefix.
+ * @returns {void}
  */
 function assertEqual(actual, expected, message) {
     if (actual !== expected) {
@@ -14,9 +15,10 @@ function assertEqual(actual, expected, message) {
 /**
  * Assert that the condition holds and if not, throw an error with the given message.
  *
- * @param {boolean} condition
- * @param {string} message
- * @param {typeof Error} ErrorType
+ * @param {boolean} condition Condition to verify.
+ * @param {string} message Error message when the condition fails.
+ * @param {typeof Error} ErrorType Error class to throw.
+ * @returns {void}
  */
 function assert(condition, message, ErrorType = Error) {
     if (!condition) {
@@ -27,9 +29,9 @@ function assert(condition, message, ErrorType = Error) {
 /**
  * Return the amount required to align value to the given alignment.
  * It calculates the difference of the alignment and the modulo of value by alignment.
- * @param {number} value
- * @param {number} alignment
- * @returns {number}
+ * @param {number} value Source value.
+ * @param {number} alignment Target alignment.
+ * @returns {number} Additional offset needed to reach the next aligned value.
  */
 function alignTo(value, alignment) {
     return (alignment - (value % alignment)) % alignment;
@@ -38,11 +40,11 @@ function alignTo(value, alignment) {
 /**
  * Method for hashing a string (e.g. a partition name) to a 32-bit unsigned integer.
  *
- * @param {string} str
- * @returns {number}
+ * @param {string} str Input string.
+ * @returns {number} 32-bit unsigned hash value.
  */
 function hash(str) {
-    /* istanbul ignore if */
+    /* c8 ignore next 3 */
     if (str.length === 0) {
         return 0;
     }
@@ -113,26 +115,61 @@ function wrapAndCheck(index, length) {
 }
 
 /**
- * Perform a k-way merge over multiple streams, invoking a callback for each item in ascending key order.
- * Each stream object is mutated in place by the `advance` function.
+ * Iterate an array-like list in forward or reverse order.
  *
- * @param {object[]} streams Array of stream state objects; entries are removed when exhausted.
- * @param {function(object): number} getKey Returns the current sort key for a stream state.
- * @param {function(object): boolean} advance Advances the stream to its next item.
- *   Returns true if the stream has more items within range, false if exhausted.
- * @param {function(object): void} visit Called for each stream state in merged order.
+ * @param {Iterable|ArrayLike<any>} entries Entries to iterate.
+ * @param {boolean} forwards Iteration direction.
+ * @returns {Generator<any>}
  */
-function kWayMerge(streams, getKey, advance, visit) {
-    while (streams.length > 0) {
-        let minIdx = 0;
-        for (let i = 1; i < streams.length; i++) {
-            if (getKey(streams[i]) < getKey(streams[minIdx])) {
-                minIdx = i;
-            }
+function* iterate(entries, forwards) {
+    if (forwards) {
+        yield* entries;
+        return;
+    }
+
+    for (let i = entries.length - 1; i >= 0; i--) {
+        yield entries[i];
+    }
+}
+
+/**
+ * Perform a k-way merge over multiple iterables in sort-key order.
+ *
+ * Each iterable is primed by calling `.next()` once at startup. On each merge step the iterable
+ * with the best current value is advanced and its value is yielded (after passing through `visit`).
+ * An iterable is dropped once its iterator reports `done`.
+ *
+ * @param {Iterable[]|Iterator[]} iterables Iterables or bare iterators to merge.
+ * @param {function(*): number} getSortKey Extracts the numeric sort key from an iterable's current value.
+ * @param {boolean} [ascending=true] When true, yields items in ascending key order (min-merge).
+ *   When false, yields in descending key order (max-merge).
+ * @param {function(*): *} [visit] Optional extractor for the yielded value. Defaults to identity.
+ * @returns {Generator<*>} Merged sequence in key order.
+ */
+function *kWayMerge(iterables, getSortKey, ascending = true, visit = v => v) {
+    const states = [];
+    for (const iterable of iterables) {
+        const iterator = typeof iterable[Symbol.iterator] === 'function' ? iterable[Symbol.iterator]() : iterable;
+        const { value, done } = iterator.next();
+        if (!done) {
+            states.push({ iterator, current: value });
+        }
+    }
+
+    while (states.length > 0) {
+        let bestIdx = 0;
+        for (let i = 1; i < states.length; i++) {
+            const better = ascending
+                ? getSortKey(states[i].current) < getSortKey(states[bestIdx].current)
+                : getSortKey(states[i].current) > getSortKey(states[bestIdx].current);
+            if (better) bestIdx = i;
         }
-        visit(streams[minIdx]);
-        if (!advance(streams[minIdx])) {
-            streams.splice(minIdx, 1);
+        yield visit(states[bestIdx].current);
+        const { value, done } = states[bestIdx].iterator.next();
+        if (done) {
+            states.splice(bestIdx, 1);
+        } else {
+            states[bestIdx].current = value;
         }
     }
 }
@@ -141,9 +178,9 @@ function kWayMerge(streams, getKey, advance, visit) {
  * Read a scalar value at a dot-notation path from an object.
  * Returns `undefined` if any path segment is absent or an intermediate value is not an object.
  *
- * @param {object} obj
+ * @param {object} obj Source object.
  * @param {string} dotPath Dot-separated property path, e.g. `'payload.type'`.
- * @returns {*}
+ * @returns {*} Value at the path or `undefined`.
  */
 function getPropertyAtPath(obj, dotPath) {
     let current = obj;
@@ -160,6 +197,7 @@ export {
     assertEqual,
     hash,
     wrapAndCheck,
+    iterate,
     binarySearch,
     alignTo,
     kWayMerge,