event-storage 1.2.0 → 1.3.0

package/src/utils/metadataUtil.js

@@ -1,20 +1,132 @@
 import crypto from 'crypto';
-import { assert, assertEqual } from './util.js';
-import { BYTE_OPEN_OBJECT, indexOfSameLevel } from './jsonUtil.js';
+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 (Array.isArray(matcherValue)) {
-        return matcherValue.includes(documentValue);
-    } else if (matcherValue && typeof matcherValue === 'object') {
+    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.
  *
@@ -42,10 +154,10 @@ function buildMetadataHeader(magic, metadata) {
  * @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');
-    };
+    const hmac = crypto.createHmac('sha256', secret);
+    hmac.update(string);
+    return hmac.digest('hex');
+};
 
 /**
  * @typedef {object|function(object):boolean} Matcher
@@ -76,14 +188,15 @@ function matches(document, matcher) {
  * @returns {{matcher: string|object, hmac?: string}}
  */
 function buildMetadataForMatcher(matcher, hmac) {
-    if (!matcher) {
-        return undefined;
-    }
+     /* c8 ignore next 2 */
+     if (!matcher) {
+         return undefined;
+     }
     if (typeof matcher === 'object') {
-        return { matcher };
+        return {matcher};
     }
     const matcherString = matcher.toString();
-    return { matcher: matcherString, hmac: hmac(matcherString) };
+    return {matcher: matcherString, hmac: hmac(matcherString)};
 }
 
 /**
@@ -92,11 +205,12 @@ function buildMetadataForMatcher(matcher, hmac) {
  * @returns {Matcher} The matcher object or function.
  */
 function buildMatcherFromMetadata(matcherMetadata, hmac) {
-    let matcher;
-    if (typeof matcherMetadata.matcher === 'object') {
-        matcher = matcherMetadata.matcher;
-    } else {
-        assert(matcherMetadata.hmac === hmac(matcherMetadata.matcher), 'Invalid HMAC for matcher.');
+     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
     }
@@ -112,33 +226,35 @@ function buildMatcherFromMetadata(matcherMetadata, hmac) {
  */
 function buildTypeMatcherFn(payloadPath) {
     const parts = payloadPath.split('.');
-    return function(typeValue) {
+    return function (typeValue) {
         let obj = typeValue;
         for (let i = parts.length - 1; i >= 0; i--) {
-            obj = { [parts[i]]: obj };
+            obj = {[parts[i]]: obj};
         }
-        return { payload: obj };
+        return {payload: obj};
     };
 }
 
 /**
- * Builds a raw-buffer matcher.
- * It expects the Buffer to contain compact stringified JSON
- * and supports matcher objects with sub properties and multi-value matches (OR/any of).
+ * 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.
- * @returns {function(Buffer): boolean}
+ * @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 = {}) {
-    assert(matcher && typeof matcher ==='object' && !Array.isArray(matcher), 'Matcher must be an object.', TypeError);
+function buildRawBufferMatcher(matcher = {}, options = {}) {
+    assert(isPlainObject(matcher), 'Matcher must be an object.', TypeError);
+    const enableOperatorBufferMatcher = options.enableOperatorBufferMatcher !== false;
 
-    const root = buildMatcherTree(matcher);
+    const root = buildMatcherTree(matcher, enableOperatorBufferMatcher);
+    /* c8 ignore next 3 */
     if (root.children.length === 0) {
         return () => true;
     }
 
     return function matchesRawBuffer(buffer) {
-        if (buffer[0] !== BYTE_OPEN_OBJECT) {
+        if (!isOpeningObject(buffer[0])) {
             return false;
         }
         if (!preCheck(buffer, 1, root)) {
@@ -149,93 +265,247 @@ function buildRawBufferMatcher(matcher = {}) {
 }
 
 /**
- * Optimization pass: check that every required byte pattern is present anywhere in the buffer
- * before spending the more expensive per-depth scan in `matchesNode`.
- */
-function preCheck(buffer, startOffset, node) {
-    for (const child of node.children) {
-        if (child.valuePatterns && !child.valuePatterns.some((pattern, i) => {
-            child.valueMatches[i] = buffer.indexOf(pattern, startOffset);
-            return child.valueMatches[i] !== -1;
-        })) {
-            return false;
-        }
-        if (child.objectPattern) {
-            const objectMatch = buffer.indexOf(child.objectPattern, startOffset);
-            if (objectMatch === -1) {
-                return false;
-            }
-            child.objMatch = objectMatch;
-            if (!preCheck(buffer, objectMatch, child.node)) {
-                return false;
-            }
-        }
-    }
-    return true;
-}
-
-/**
- * Pre-compile a plain object matcher into a tree of byte patterns so `matchesNode` can scan
- * raw JSON buffers without deserializing them.
+ * 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 node = { children: [] };
+    const fast = [];
+    const slow = [];
 
     for (const [key, value] of Object.entries(matcher)) {
-        node.children.push(buildMatcherTreeChild(key, value));
+        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 node;
+    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 = { objectPattern: null, valuePatterns: null, node: null, objMatch: null, valueMatches: [] };
-    if (Array.isArray(value)) {
-        if (value.some(item => item && typeof item === 'object')) {
-            throw new TypeError('Array matcher values must be scalars.');
+    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);
         }
-        child.valuePatterns = value.map(item => buildValuePattern(keyPrefix, item));
-        return child;
-    } else if (value && typeof value === 'object') {
-        child.objectPattern = Buffer.concat([keyPrefix, Buffer.from('{', 'utf8')]);
-        child.node = buildMatcherTree(value);
-        return child;
+    } else {
+        child.pattern = buildKeyValuePattern(keyPrefix, value);
     }
-    child.valuePatterns = [buildValuePattern(keyPrefix, value)];
     return child;
 }
 
-function buildValuePattern(keyPrefix, value) {
+/**
+ * @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')]);
 }
 
 /**
- * Verify that each required byte pattern in the tree is present at the correct JSON nesting
- * depth so values inside nested objects don't satisfy a top-level match requirement.
+ * 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) {
-        if (child.valuePatterns && !child.valuePatterns.some((pattern, i) => {
-            return indexOfSameLevel(buffer, pattern, startOffset, child.valueMatches[i]) !== -1;
-        })) {
+        const matchPosition = indexOfSameLevel(buffer, child.pattern, startOffset, child.lastMatch, child.isKeyPattern);
+        if (matchPosition === -1) {
             return false;
         }
 
-        if (child.node) {
-            const objectIndex = indexOfSameLevel(buffer, child.objectPattern, startOffset, child.objMatch);
-            if (objectIndex === -1) {
-                return false;
-            }
-            if (!matchesNode(buffer, objectIndex + child.objectPattern.length, child.node)) {
-                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,

package/src/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;
     }
@@ -115,8 +117,9 @@ function wrapAndCheck(index, length) {
 /**
  * Iterate an array-like list in forward or reverse order.
  *
- * @param {Iterable} entries
- * @param {boolean} forwards
+ * @param {Iterable|ArrayLike<any>} entries Entries to iterate.
+ * @param {boolean} forwards Iteration direction.
+ * @returns {Generator<any>}
  */
 function* iterate(entries, forwards) {
     if (forwards) {
@@ -141,7 +144,7 @@ function* iterate(entries, forwards) {
  * @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<*>}
+ * @returns {Generator<*>} Merged sequence in key order.
  */
 function *kWayMerge(iterables, getSortKey, ascending = true, visit = v => v) {
     const states = [];
@@ -175,9 +178,9 @@ function *kWayMerge(iterables, getSortKey, ascending = true, visit = v => v) {
  * 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;