re2js 1.3.0 → 1.3.2

package/README.md

@@ -100,7 +100,9 @@ RE2JS.LONGEST_MATCH
 
 ### Checking for Matches
 
-RE2JS allows you to check if a string matches a given regex pattern using the `matches()` function
+RE2JS allows you to check if a string matches a given regex pattern using the `matches()` function.
+
+***Performance Note:** The `matches()` method is highly optimized. It performs a strict anchored check and runs directly on the high-speed DFA (Deterministic Finite Automaton) engine without tracking capture groups or instantiating a stateful `Matcher` object.*
 
 ```js
 import { RE2JS } from 're2js'
@@ -161,6 +163,42 @@ matchString.group() // 'e'
 matchString.find(7) // false
 ```
 
+### High-Performance Boolean Testing
+
+If you only need to know **whether** a string matches a pattern (without extracting capture groups), you should use the `test()`, `testExact()`, or `matches()` methods. Unlike `.matcher()`, these methods do not instantiate stateful `Matcher` objects and request exactly `0` capture groups. This guarantees that execution is securely routed to the high-speed DFA (Deterministic Finite Automaton) engine whenever possible in linear `O(n)` time
+
+#### `test(input)`
+
+Tests if the regular expression matches **any part** of the provided input (unanchored). This method mirrors the standard JavaScript `RegExp.prototype.test()` API
+
+```js
+import { RE2JS } from 're2js';
+
+// Compile once, reuse often
+const re = RE2JS.compile('error|warning|critical');
+
+// Extremely fast, unanchored DFA search
+if (re.test('The system encountered a critical failure')) {
+  console.log('Log needs attention!');
+}
+```
+
+#### `testExact(input)`
+
+Tests if the regular expression matches the entire input string (anchored to both start and end).
+
+*Note: `RE2JS.matches()` delegates to this method, so they provide the exact same performance and behavior.*
+
+```js
+import { RE2JS } from 're2js';
+
+const isHex = RE2JS.compile('[0-9A-Fa-f]+');
+
+// Fast, anchored DFA validation
+console.log(isHex.testExact('1A4F'));      // true
+console.log(isHex.testExact('1A4F-xyz'));  // false
+```
+
 ### Checking Initial Match
 
 The `lookingAt()` method determines whether the start of the given string matches the pattern

package/build/index.cjs.cjs

@@ -2,7 +2,7 @@
  * re2js
  * RE2JS is the JavaScript port of RE2, a regular expression engine that provides linear time matching
  *
- * @version v1.3.0
+ * @version v1.3.2
  * @author Alexey Vasiliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -843,6 +843,181 @@ class MatcherInput {
   }
 }
 
+/**
+ * MachineInput abstracts different representations of the input text supplied to the Machine. It
+ * provides one-character lookahead.
+ */
+class MachineInputBase {
+  static EOF() {
+    return -1 << 3;
+  }
+
+  // can we look ahead without losing info?
+  canCheckPrefix() {
+    return true;
+  }
+
+  // Returns the end position in the same units as step().
+  endPos() {
+    return this.end;
+  }
+}
+
+// An implementation of MachineInput for UTF-8 byte arrays.
+// |pos| and |width| are byte indices.
+class MachineUTF8Input extends MachineInputBase {
+  constructor(bytes, start = 0, end = bytes.length) {
+    super();
+    this.bytes = bytes;
+    this.start = start;
+    this.end = end;
+  }
+
+  // Returns the rune at the specified index; the units are
+  // unspecified, but could be UTF-8 byte, UTF-16 char, or rune
+  // indices.  Returns the width (in the same units) of the rune in
+  // the lower 3 bits, and the rune (Unicode code point) in the high
+  // bits.  Never negative, except for EOF which is represented as -1
+  // << 3 | 0.
+  step(i) {
+    i += this.start;
+    if (i >= this.end) {
+      return MachineInputBase.EOF();
+    }
+    let x = this.bytes[i++] & 255;
+    if ((x & 128) === 0) {
+      return x << 3 | 1;
+    } else if ((x & 224) === 192) {
+      x = x & 31;
+      if (i >= this.end) {
+        return MachineInputBase.EOF();
+      }
+      x = x << 6 | this.bytes[i++] & 63;
+      return x << 3 | 2;
+    } else if ((x & 240) === 224) {
+      x = x & 15;
+      if (i + 1 >= this.end) {
+        return MachineInputBase.EOF();
+      }
+      x = x << 6 | this.bytes[i++] & 63;
+      x = x << 6 | this.bytes[i++] & 63;
+      return x << 3 | 3;
+    } else {
+      x = x & 7;
+      if (i + 2 >= this.end) {
+        return MachineInputBase.EOF();
+      }
+      x = x << 6 | this.bytes[i++] & 63;
+      x = x << 6 | this.bytes[i++] & 63;
+      x = x << 6 | this.bytes[i++] & 63;
+      return x << 3 | 4;
+    }
+  }
+
+  // Returns the index relative to |pos| at which |re2.prefix| is found
+  // in this input stream, or a negative value if not found.
+  index(re2, pos) {
+    pos += this.start;
+    const i = this.indexOf(this.bytes, re2.prefixUTF8, pos);
+    return i < 0 ? i : i - pos;
+  }
+
+  // Returns a bitmask of EMPTY_* flags.
+  context(pos) {
+    pos += this.start;
+    let r1 = -1;
+    if (pos > this.start && pos <= this.end) {
+      let start = pos - 1;
+      r1 = this.bytes[start--];
+      if (r1 >= 128) {
+        let lim = pos - 4;
+        if (lim < this.start) {
+          lim = this.start;
+        }
+        while (start >= lim && (this.bytes[start] & 192) === 128) {
+          start--;
+        }
+        if (start < this.start) {
+          start = this.start;
+        }
+        r1 = this.step(start) >> 3;
+      }
+    }
+    const r2 = pos < this.end ? this.step(pos) >> 3 : -1;
+    return Utils.emptyOpContext(r1, r2);
+  }
+
+  // Returns the index of the first occurrence of array |target| within
+  // array |source| after |fromIndex|, or -1 if not found.
+  indexOf(source, target, fromIndex = 0) {
+    let targetLength = target.length;
+    if (targetLength === 0) {
+      return -1;
+    }
+    let sourceLength = source.length;
+    for (let i = fromIndex; i <= sourceLength - targetLength; i++) {
+      for (let j = 0; j < targetLength; j++) {
+        if (source[i + j] !== target[j]) {
+          break;
+        } else if (j === targetLength - 1) {
+          return i;
+        }
+      }
+    }
+    return -1;
+  }
+}
+
+// |pos| and |width| are in JS "char" units.
+class MachineUTF16Input extends MachineInputBase {
+  constructor(charSequence, start = 0, end = charSequence.length) {
+    super();
+    this.charSequence = charSequence;
+    this.start = start;
+    this.end = end;
+  }
+
+  // Returns the rune at the specified index; the units are
+  // unspecified, but could be UTF-8 byte, UTF-16 char, or rune
+  // indices.  Returns the width (in the same units) of the rune in
+  // the lower 3 bits, and the rune (Unicode code point) in the high
+  // bits.  Never negative, except for EOF which is represented as -1
+  // << 3 | 0.
+  step(pos) {
+    pos += this.start;
+    if (pos < this.end) {
+      const rune = this.charSequence.codePointAt(pos);
+      return rune << 3 | Utils.charCount(rune);
+    } else {
+      return MachineInputBase.EOF();
+    }
+  }
+
+  // Returns the index relative to |pos| at which |re2.prefix| is found
+  // in this input stream, or a negative value if not found.
+  index(re2, pos) {
+    pos += this.start;
+    const i = this.charSequence.indexOf(re2.prefix, pos);
+    return i < 0 ? i : i - pos;
+  }
+
+  // Returns a bitmask of EMPTY_* flags.
+  context(pos) {
+    pos += this.start;
+    const r1 = pos > 0 && pos <= this.charSequence.length ? this.charSequence.codePointAt(pos - 1) : -1;
+    const r2 = pos < this.charSequence.length ? this.charSequence.codePointAt(pos) : -1;
+    return Utils.emptyOpContext(r1, r2);
+  }
+}
+class MachineInput {
+  static fromUTF8(bytes, start = 0, end = bytes.length) {
+    return new MachineUTF8Input(bytes, start, end);
+  }
+  static fromUTF16(charSequence, start = 0, end = charSequence.length) {
+    return new MachineUTF16Input(charSequence, start, end);
+  }
+}
+
 class RE2JSException extends Error {
   /** @param {string} message */
   constructor(message) {
@@ -923,17 +1098,6 @@ class RE2JSFlagsException extends RE2JSException {
   }
 }
 
-/**
- * An exception thrown by DFA
- */
-class RE2JSDfaMemoryException extends RE2JSException {
-  /** @param {string} message */
-  constructor(message) {
-    super(message);
-    this.name = 'RE2JSDfaMemoryException';
-  }
-}
-
 /**
  * A stateful iterator that interprets a regex {@code RE2JS} on a specific input.
  *
@@ -1490,181 +1654,6 @@ class Matcher {
   }
 }
 
-/**
- * MachineInput abstracts different representations of the input text supplied to the Machine. It
- * provides one-character lookahead.
- */
-class MachineInputBase {
-  static EOF() {
-    return -1 << 3;
-  }
-
-  // can we look ahead without losing info?
-  canCheckPrefix() {
-    return true;
-  }
-
-  // Returns the end position in the same units as step().
-  endPos() {
-    return this.end;
-  }
-}
-
-// An implementation of MachineInput for UTF-8 byte arrays.
-// |pos| and |width| are byte indices.
-class MachineUTF8Input extends MachineInputBase {
-  constructor(bytes, start = 0, end = bytes.length) {
-    super();
-    this.bytes = bytes;
-    this.start = start;
-    this.end = end;
-  }
-
-  // Returns the rune at the specified index; the units are
-  // unspecified, but could be UTF-8 byte, UTF-16 char, or rune
-  // indices.  Returns the width (in the same units) of the rune in
-  // the lower 3 bits, and the rune (Unicode code point) in the high
-  // bits.  Never negative, except for EOF which is represented as -1
-  // << 3 | 0.
-  step(i) {
-    i += this.start;
-    if (i >= this.end) {
-      return MachineInputBase.EOF();
-    }
-    let x = this.bytes[i++] & 255;
-    if ((x & 128) === 0) {
-      return x << 3 | 1;
-    } else if ((x & 224) === 192) {
-      x = x & 31;
-      if (i >= this.end) {
-        return MachineInputBase.EOF();
-      }
-      x = x << 6 | this.bytes[i++] & 63;
-      return x << 3 | 2;
-    } else if ((x & 240) === 224) {
-      x = x & 15;
-      if (i + 1 >= this.end) {
-        return MachineInputBase.EOF();
-      }
-      x = x << 6 | this.bytes[i++] & 63;
-      x = x << 6 | this.bytes[i++] & 63;
-      return x << 3 | 3;
-    } else {
-      x = x & 7;
-      if (i + 2 >= this.end) {
-        return MachineInputBase.EOF();
-      }
-      x = x << 6 | this.bytes[i++] & 63;
-      x = x << 6 | this.bytes[i++] & 63;
-      x = x << 6 | this.bytes[i++] & 63;
-      return x << 3 | 4;
-    }
-  }
-
-  // Returns the index relative to |pos| at which |re2.prefix| is found
-  // in this input stream, or a negative value if not found.
-  index(re2, pos) {
-    pos += this.start;
-    const i = this.indexOf(this.bytes, re2.prefixUTF8, pos);
-    return i < 0 ? i : i - pos;
-  }
-
-  // Returns a bitmask of EMPTY_* flags.
-  context(pos) {
-    pos += this.start;
-    let r1 = -1;
-    if (pos > this.start && pos <= this.end) {
-      let start = pos - 1;
-      r1 = this.bytes[start--];
-      if (r1 >= 128) {
-        let lim = pos - 4;
-        if (lim < this.start) {
-          lim = this.start;
-        }
-        while (start >= lim && (this.bytes[start] & 192) === 128) {
-          start--;
-        }
-        if (start < this.start) {
-          start = this.start;
-        }
-        r1 = this.step(start) >> 3;
-      }
-    }
-    const r2 = pos < this.end ? this.step(pos) >> 3 : -1;
-    return Utils.emptyOpContext(r1, r2);
-  }
-
-  // Returns the index of the first occurrence of array |target| within
-  // array |source| after |fromIndex|, or -1 if not found.
-  indexOf(source, target, fromIndex = 0) {
-    let targetLength = target.length;
-    if (targetLength === 0) {
-      return -1;
-    }
-    let sourceLength = source.length;
-    for (let i = fromIndex; i <= sourceLength - targetLength; i++) {
-      for (let j = 0; j < targetLength; j++) {
-        if (source[i + j] !== target[j]) {
-          break;
-        } else if (j === targetLength - 1) {
-          return i;
-        }
-      }
-    }
-    return -1;
-  }
-}
-
-// |pos| and |width| are in JS "char" units.
-class MachineUTF16Input extends MachineInputBase {
-  constructor(charSequence, start = 0, end = charSequence.length) {
-    super();
-    this.charSequence = charSequence;
-    this.start = start;
-    this.end = end;
-  }
-
-  // Returns the rune at the specified index; the units are
-  // unspecified, but could be UTF-8 byte, UTF-16 char, or rune
-  // indices.  Returns the width (in the same units) of the rune in
-  // the lower 3 bits, and the rune (Unicode code point) in the high
-  // bits.  Never negative, except for EOF which is represented as -1
-  // << 3 | 0.
-  step(pos) {
-    pos += this.start;
-    if (pos < this.end) {
-      const rune = this.charSequence.codePointAt(pos);
-      return rune << 3 | Utils.charCount(rune);
-    } else {
-      return MachineInputBase.EOF();
-    }
-  }
-
-  // Returns the index relative to |pos| at which |re2.prefix| is found
-  // in this input stream, or a negative value if not found.
-  index(re2, pos) {
-    pos += this.start;
-    const i = this.charSequence.indexOf(re2.prefix, pos);
-    return i < 0 ? i : i - pos;
-  }
-
-  // Returns a bitmask of EMPTY_* flags.
-  context(pos) {
-    pos += this.start;
-    const r1 = pos > 0 && pos <= this.charSequence.length ? this.charSequence.codePointAt(pos - 1) : -1;
-    const r2 = pos < this.charSequence.length ? this.charSequence.codePointAt(pos) : -1;
-    return Utils.emptyOpContext(r1, r2);
-  }
-}
-class MachineInput {
-  static fromUTF8(bytes, start = 0, end = bytes.length) {
-    return new MachineUTF8Input(bytes, start, end);
-  }
-  static fromUTF16(charSequence, start = 0, end = charSequence.length) {
-    return new MachineUTF16Input(charSequence, start, end);
-  }
-}
-
 /**
  * A single instruction in the regular expression virtual machine.
  *
@@ -2123,21 +2112,40 @@ class Machine {
   }
 }
 
+// FNV-1a 32-bit hash for an array of integers.
+// Extremely fast, allocates no memory, and produces good distribution.
+const hashPCs = pcs => {
+  let h = -2128831035; // 0x811c9dc5 (32-bit signed offset basis)
+  for (let i = 0; i < pcs.length; i++) {
+    h ^= pcs[i];
+    h = Math.imul(h, 16777619); // 0x01000193 (FNV prime)
+  }
+  return h;
+};
+
+// Zero-allocation array comparison for hash collision resolution
+const arraysEqual = (a, b) => {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+};
 class DFAState {
-  constructor(id, nfaStates, isMatch) {
-    this.id = id; // Stringified NFA state list (e.g., "1,4,7")
-    this.nfaStates = nfaStates; // Array of Instruction PCs
+  constructor(nfaStates, isMatch) {
+    this.nfaStates = nfaStates; // Int32Array of Instruction PCs
     this.isMatch = isMatch; // Boolean
-    this.nextAscii = new Array(Unicode.MAX_ASCII + 1).fill(null); // Flat array for blisteringly fast ASCII lookups (unanchored)
+    this.nextAscii = new Array(Unicode.MAX_ASCII + 1).fill(null); // Flat array for blisteringly fast ASCII lookups
     this.nextMap = new Map(); // Cache of Char -> DFAState
   }
 }
 class DFA {
   constructor(prog) {
     this.prog = prog;
-    this.stateCache = new Map(); // id -> DFAState
+    this.stateCache = new Map(); // hash(number) -> DFAState[]
+    this.stateCount = 0; // Tracks total states for memory limits
     this.startState = null;
-    this.stateLimit = 10000; // Prevent memory explosion (ReDoS protection), like RE2 max_mem
+    this.stateLimit = 10000; // Prevent memory explosion (ReDoS protection)
   }
 
   // Follows epsilon (empty) transitions to find all reachable states without consuming a char
@@ -2181,17 +2189,37 @@ class DFA {
     const closureResult = this.computeClosure(pcs);
     if (!closureResult) return null; // Bailout to NFA required
 
-    const id = closureResult.pcs.join(',');
-    if (this.stateCache.has(id)) {
-      return this.stateCache.get(id);
+    const sortedPCs = closureResult.pcs;
+    const hash = hashPCs(sortedPCs);
+
+    // Lookup hash bucket
+    let bucket = this.stateCache.get(hash);
+    if (bucket) {
+      // Resolve potential hash collisions
+      for (let i = 0; i < bucket.length; i++) {
+        const state = bucket[i];
+        if (arraysEqual(state.nfaStates, sortedPCs)) {
+          return state;
+        }
+      }
+    } else {
+      bucket = [];
+      this.stateCache.set(hash, bucket);
     }
 
     // Safety: prevent memory exhaustion from state explosion
-    if (this.stateCache.size > this.stateLimit) {
-      throw new RE2JSDfaMemoryException('dfa error: Out of memory exception');
+    // We flush the cache and return null, which seamlessly routes execution to the NFA
+    if (this.stateCount >= this.stateLimit) {
+      this.stateCache.clear();
+      this.stateCount = 0;
+      this.startState = null;
+      return null;
     }
-    const state = new DFAState(id, closureResult.pcs, closureResult.isMatch);
-    this.stateCache.set(id, state);
+
+    // State not found, create it and add to bucket
+    const state = new DFAState(sortedPCs, closureResult.isMatch);
+    bucket.push(state);
+    this.stateCount++;
     return state;
   }
 
@@ -2255,6 +2283,11 @@ class DFA {
       const r = input.step(i);
       const rune = r >> 3;
       const width = r & 7;
+
+      // prevent infinite loop on EOF
+      if (width === 0) {
+        break;
+      }
       currentState = this.step(currentState, rune, anchor);
 
       // If we hit an unrecoverable DFA error or bailout, signal fallback
@@ -5417,18 +5450,10 @@ class RE2 {
     if (ncap > 0) {
       return this.doExecuteNFA(input, pos, anchor, ncap);
     }
-    try {
-      const dfaResult = this.dfa.match(input, pos, anchor);
-      if (dfaResult !== null) {
-        // DFA succeeded (returned true or false)
-        return dfaResult ? [] : null; // Return empty array to signify "matched but no captures"
-      }
-    } catch (e) {
-      if (e instanceof RE2JSDfaMemoryException) {
-        this.dfa = new DFA(this.prog); // flush cache
-      } else {
-        throw e;
-      }
+    const dfaResult = this.dfa.match(input, pos, anchor);
+    if (dfaResult !== null) {
+      // DFA succeeded (returned true or false)
+      return dfaResult ? [] : null; // Return empty array to signify "matched but no captures"
     }
 
     // Fallback to NFA
@@ -6230,7 +6255,7 @@ class RE2JS {
    * @throws RE2JSSyntaxException if the regular expression is malformed
    */
   static matches(regex, input) {
-    return RE2JS.compile(regex).matcher(input).matches();
+    return RE2JS.compile(regex).testExact(input);
   }
 
   /**
@@ -6296,7 +6321,7 @@ class RE2JS {
    * @returns {boolean} true if the regular expression matches the entire input
    */
   matches(input) {
-    return this.matcher(input).matches();
+    return this.testExact(input);
   }
 
   /**
@@ -6312,6 +6337,39 @@ class RE2JS {
     return new Matcher(this, input);
   }
 
+  /**
+   * Tests whether the regular expression matches any part of the input string.
+   * Performance Note: This method is highly optimized. Because it only returns
+   * a boolean and does not extract capture groups, it bypasses the `Matcher` overhead
+   * and guarantees execution on the high-speed DFA engine whenever possible.
+   *
+   * @param {string|number[]} input - The input string or UTF-8 byte array to test against.
+   * @returns {boolean} `true` if the pattern is found anywhere in the input, `false` otherwise.
+   */
+  test(input) {
+    if (Array.isArray(input)) {
+      // Reuse the existing UTF-8 fast-path method
+      return this.re2Input.matchUTF8(input);
+    }
+
+    // Reuse the existing UTF-16 fast-path method
+    return this.re2Input.match(input);
+  }
+
+  /**
+   * Tests whether the regular expression matches the ENTIRE input string.
+   * * **Performance Note:** This operates identically to `.matches()`, but is significantly
+   * faster because it does not request capture group data. By requesting 0 capture groups,
+   * it securely routes execution through the DFA fast-path.
+   *
+   * @param {string|number[]} input - The input string or UTF-8 byte array to test against.
+   * @returns {boolean} `true` if the exact input string fully matches the pattern, `false` otherwise.
+   */
+  testExact(input) {
+    const machineInput = Array.isArray(input) ? MachineInput.fromUTF8(input) : MachineInput.fromUTF16(input);
+    return this.re2Input.executeEngine(machineInput, 0, RE2Flags.ANCHOR_BOTH, 0) !== null;
+  }
+
   /**
    * Splits input around instances of the regular expression. It returns an array giving the strings
    * that occur before, between, and after instances of the regular expression.
@@ -6433,7 +6491,6 @@ class RE2JS {
 exports.Matcher = Matcher;
 exports.RE2JS = RE2JS;
 exports.RE2JSCompileException = RE2JSCompileException;
-exports.RE2JSDfaMemoryException = RE2JSDfaMemoryException;
 exports.RE2JSException = RE2JSException;
 exports.RE2JSFlagsException = RE2JSFlagsException;
 exports.RE2JSGroupException = RE2JSGroupException;