re2js 2.3.0 → 2.3.2

package/README.md

@@ -562,8 +562,7 @@ console.log(RE2JS.compile('(a+b?)').programSize()); // Outputs: 8
 
 ### Translating Regular Expressions
 
-The `translateRegExp()` method preprocesses a given regular expression string to ensure compatibility with RE2JS.
-It applies necessary transformations, such as escaping special characters, adjusting Unicode sequences, and converting named capture groups
+The `translateRegExp()` method preprocesses a given regular expression string or native RegExp object to ensure compatibility with RE2JS. It applies necessary transformations, such as escaping special characters, adjusting Unicode sequences, converting named capture groups, and mapping native execution flags
 
 ```js
 import { RE2JS } from 're2js'
@@ -579,7 +578,11 @@ RE2JS.matches(unicodeRegexp, '😀') // true
 RE2JS.matches(unicodeRegexp, '😃') // false
 
 // also support native Regex
-RE2JS.translateRegExp(/foo/ims) // '(?ims)foo'
+const translatedNative = RE2JS.translateRegExp(/foo/ims) // '(?ims)foo'
+
+const re = RE2JS.compile(translatedNative)
+re.test('FOO') // true
+
 RE2JS.translateRegExp(/bar/giy) // '(?i)bar'
 ```
 
@@ -612,23 +615,23 @@ Because RE2JS's Lazy DFA, Prefilter, and OnePass engines operate efficiently wit
 
 Here is a benchmark running 30,000 items through both engines using their respective `.test()` fast-paths (averages of multiple runs):
 
-| Benchmark Scenario        | Pattern Example            | RE2JS (Pure JS) | RE2-Node (C++) | Result                       |
-|:--------------------------|:---------------------------|:----------------|:---------------|:-----------------------------|
-| **Simple Literal**        | `/damage/`                 | **~5.82 ms**    | ~14.08 ms      | `re2js` is **~2.42x faster** |
-| **Greedy Wildcard**       | `/enters.*battlefield/`    | **~8.44 ms**    | ~13.32 ms      | `re2js` is **~1.58x faster** |
-| **Lazy Wildcard**         | `/enters.*?battlefield/`   | **~8.43 ms**    | ~13.33 ms      | `re2js` is **~1.58x faster** |
-| **Deep State Machine**    | `/([0-9]+(/[0-9]+)+)/`     | **~7.71 ms**    | ~16.08 ms      | `re2js` is **~2.09x faster** |
-| **Massive Alternation**   | `/White\|Blue\|Black.../`  | **~11.62 ms**   | ~14.99 ms      | `re2js` is **~1.29x faster** |
-| **Bounded Repetition**    | `/[A-Z][a-z]{5,15}/`       | **~12.20 ms**   | ~13.77 ms      | `re2js` is **~1.13x faster** |
-| **ReDoS Attempt**         | `/(a+)+!/`                 | **~5.68 ms**    | ~16.25 ms      | `re2js` is **~2.86x faster** |
-| **Case Insensitive**      | `/(?i)swamp/`              | ~18.71 ms       | **~16.22 ms**  | `re2-node` is ~1.15x faster  |
-| **Word Boundaries (NFA)** | `/\b(Flying\|First...)\b/` | ~57.24 ms       | **~15.66 ms**  | `re2-node` is ~3.66x faster  |
+| Benchmark Scenario        | Pattern Example            | RE2JS (Pure JS) | RE2-Node (C++) | Result                      |
+|:--------------------------|:---------------------------|:----------------|:---------------|:----------------------------|
+| **ReDoS Attempt**         | `/(a+)+!/`                 | **7.28 ms**     | 12.74 ms       | `re2js` is **1.75x** faster |
+| **Deep State Machine**    | `/([0-9]+(/[0-9]+)+)/`     | **8.78 ms**     | 12.56 ms       | `re2js` is **1.43x** faster |
+| **Simple Literal**        | `/damage/`                 | **7.04 ms**     | 9.59 ms        | `re2js` is **1.36x** faster |
+| **Lazy Wildcard**         | `/enters.*?battlefield/`   | **9.36 ms**     | 10.27 ms       | `re2js` is **1.10x** faster |
+| **Greedy Wildcard**       | `/enters.*battlefield/`    | **9.47 ms**     | 10.03 ms       | `re2js` is **1.06x** faster |
+| **Massive Alternation**   | `/White\|Blue\|Black.../`  | 11.69 ms        | **11.28 ms**   | `re2-node` is 1.04x faster  |
+| **Bounded Repetition**    | `/[A-Z][a-z]{5,15}/`       | 12.68 ms        | **10.64 ms**   | `re2-node` is 1.19x faster  |
+| **Case Insensitive**      | `/(?i)swamp/`              | 18.58 ms        | **12.64 ms**   | `re2-node` is 1.47x faster  |
+| **Word Boundaries (NFA)** | `/\b(Flying\|First...)\b/` | 30.45 ms        | **12.22 ms**   | `re2-node` is 2.49x faster  |
 
 **Takeaways:**
-* **The Literal & Prefilter Advantage (JS wins):** For simple text searches like literals and wildcards, RE2JS's Literal Fast-Path and Prefilter Engine leverage highly optimized native JavaScript `indexOf` string scanning. By bypassing the regex state machines completely, pure JavaScript now outperforms native C++ bindings by **~1.5x to 2.4x**.
-* **State-Heavy Tasks (JS wins):** For complex state machines, massive alternations, and catastrophic backtracking (ReDoS) attempts, RE2JS operates entirely within V8's highly optimized JIT. Avoiding the JS-to-C++ N-API bridge overhead allows pure JavaScript to beat native bindings by **~1.1x to 2.8x**.
-* **Case Insensitivity (C++ wins):** Case-folded literal matching currently skips the prefilter and requires full DFA state-machine evaluation, giving C++ a slight ~1.15x edge due to raw memory scanning speeds.
-* **The Fallback Engines (C++ wins):** Pure DFA engines mathematically cannot track look-behind context like Word Boundaries (`\b`). When RE2JS encounters these, it safely bails out to its NFA engine. As shown in the benchmarks, the pure JS NFA fallback is slower than the C++ NFA. **For maximum performance in RE2JS, avoid `\b` when doing bulk boolean `.test()` matching.**
+* **Pure JS Strengths:** For complex state tracking (nested groups, wildcards) and literal string scanning, `re2js` actually beats the native C++ bindings. V8's Turbofan JIT compiler is able to heavily optimize the Pure JS DFA loop, bypassing the C++ boundary entirely.
+* **C++ Strengths:** For character class evaluations (Case Insensitivity, Bounded Repetitions, Alternations), `re2-node` has a slight edge thanks to highly optimized, hardware-level memory tables.
+* **The NFA Fallback:** Pure DFA engines mathematically cannot track look-behind context like Word Boundaries (`\b`). When RE2JS encounters these, it safely bails out to its NFA engine. As shown in the benchmarks, the pure JS NFA is significantly slower than the C++ NFA.
+* **Optimization Tip:** For maximum absolute performance in RE2JS, avoid `\b` or capture groups when doing bulk boolean `.test()` matching to ensure execution stays on the DFA fast-path.
 
 ### RE2JS vs JavaScript's native RegExp
 

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 v2.3.0
+ * @version v2.3.2
  * @author Oleksii Vasyliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -629,6 +629,31 @@ class Unicode {
   }
 }
 
+/**
+ * Size of the precomputed single-byte lookup table.
+ * Covers standard ASCII and Latin-1 characters for fast-path execution.
+ */
+const FAST_PATH_TABLE_SIZE = 256;
+/**
+ * Precomputed lookup table for Word Boundary (\b, \B) assertions.
+ * * By precomputing the boolean results for standard ASCII word ranges
+ * ('a'-'z', 'A'-'Z', '0'-'9', '_'), we completely eliminate 4 logical
+ * branches from the NFA's hot execution loop. This prevents costly
+ * CPU branch mispredictions when scanning large strings.
+ */
+const WORD_RUNE_TABLE = new Uint8Array(FAST_PATH_TABLE_SIZE);
+for (let i = 0; i < FAST_PATH_TABLE_SIZE; i++) {
+  WORD_RUNE_TABLE[i] = 97 <= i && i <= 122 ||
+  // 'a' - 'z'
+  65 <= i && i <= 90 ||
+  // 'A' - 'Z'
+  48 <= i && i <= 57 ||
+  // '0' - '9'
+  i === 95 // '_'
+  ? 1 : 0;
+}
+let cachedNativeEncoder = null;
+let cachedNativeDecoder = null;
 /**
  * Various constants and helper utilities.
  */
@@ -727,12 +752,21 @@ class Utils {
     return out;
   }
 
-  // Returns the array of runes in the specified Java UTF-16 string.
+  // Returns the array of runes in the specified JS UTF-16 string.
   static stringToRunes(str) {
-    return Array.from(String(str)).map(s => s.codePointAt(0));
+    const string = String(str);
+    const runes = [];
+    let i = 0;
+    while (i < string.length) {
+      const cp = string.codePointAt(i);
+      runes.push(cp);
+      // Surrogate pairs (Emojis, etc.) are > 0xFFFF
+      i += cp > Unicode.MAX_BMP ? 2 : 1;
+    }
+    return runes;
   }
 
-  // Returns the Java UTF-16 string containing the single rune |r|.
+  // Returns the JS UTF-16 string containing the single rune |r|.
   static runeToString(r) {
     return String.fromCodePoint(r);
   }
@@ -741,7 +775,7 @@ class Utils {
   // during the evaluation of the \b and \B zero-width assertions.
   // These assertions are ASCII-only: the word characters are [A-Za-z0-9_].
   static isWordRune(r) {
-    return Codepoint.CODES.get('a') <= r && r <= Codepoint.CODES.get('z') || Codepoint.CODES.get('A') <= r && r <= Codepoint.CODES.get('Z') || Codepoint.CODES.get('0') <= r && r <= Codepoint.CODES.get('9') || r === Codepoint.CODES.get('_');
+    return r < FAST_PATH_TABLE_SIZE ? WORD_RUNE_TABLE[r] === 1 : false;
   }
 
   // emptyOpContext returns the zero-width assertions satisfied at the position
@@ -754,21 +788,24 @@ class Utils {
   static emptyOpContext(r1, r2) {
     let op = 0;
     if (r1 < 0) {
-      op |= this.EMPTY_BEGIN_TEXT | this.EMPTY_BEGIN_LINE;
+      op |= Utils.EMPTY_BEGIN_TEXT | Utils.EMPTY_BEGIN_LINE;
     }
-    if (r1 === Codepoint.CODES.get('\n')) {
-      op |= this.EMPTY_BEGIN_LINE;
+    // Hardcode 10 for '\n'
+    if (r1 === 10) {
+      op |= Utils.EMPTY_BEGIN_LINE;
     }
     if (r2 < 0) {
-      op |= this.EMPTY_END_TEXT | this.EMPTY_END_LINE;
+      op |= Utils.EMPTY_END_TEXT | Utils.EMPTY_END_LINE;
     }
-    if (r2 === Codepoint.CODES.get('\n')) {
-      op |= this.EMPTY_END_LINE;
+
+    // Hardcode 10 for '\n'
+    if (r2 === 10) {
+      op |= Utils.EMPTY_END_LINE;
     }
-    if (this.isWordRune(r1) !== this.isWordRune(r2)) {
-      op |= this.EMPTY_WORD_BOUNDARY;
+    if (Utils.isWordRune(r1) !== Utils.isWordRune(r2)) {
+      op |= Utils.EMPTY_WORD_BOUNDARY;
     } else {
-      op |= this.EMPTY_NO_WORD_BOUNDARY;
+      op |= Utils.EMPTY_NO_WORD_BOUNDARY;
     }
     return op;
   }
@@ -792,9 +829,23 @@ class Utils {
   static charCount(codePoint) {
     return codePoint > Unicode.MAX_BMP ? 2 : 1;
   }
+
+  /**
+   * High-speed conversion from TypedArrays to standard JS Arrays.
+   * Bypasses the expensive Symbol.iterator overhead of Array.from()
+   */
+  static toArray(typedArray) {
+    const len = typedArray.length;
+    const res = new Array(len);
+    for (let i = 0; i < len; i++) {
+      res[i] = typedArray[i];
+    }
+    return res;
+  }
   static stringToUtf8ByteArray(str) {
     if (globalThis.TextEncoder) {
-      return Array.from(new TextEncoder().encode(str));
+      if (!cachedNativeEncoder) cachedNativeEncoder = new TextEncoder();
+      return Utils.toArray(cachedNativeEncoder.encode(str));
     } else {
       // fallback, if no TextEncoder
       let out = [],
@@ -824,7 +875,9 @@ class Utils {
   }
   static utf8ByteArrayToString(bytes) {
     if (globalThis.TextDecoder) {
-      return new TextDecoder('utf-8').decode(new Uint8Array(bytes));
+      if (!cachedNativeDecoder) cachedNativeDecoder = new TextDecoder('utf-8');
+      const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+      return cachedNativeDecoder.decode(view);
     } else {
       // fallback, if no TextDecoder
       let out = [],
@@ -1121,15 +1174,34 @@ class MachineUTF8Input extends MachineInputBase {
     if (targetLength === 0) {
       return fromIndex <= this.end ? fromIndex : -1;
     }
+    const firstByte = target[0];
     let limit = this.end - targetLength;
-    for (let i = fromIndex; i <= limit; i++) {
-      for (let j = 0; j < targetLength; j++) {
+    // Feature detection: Native TypedArray indexOf (ES2015)
+    const hasNativeIndexOf = typeof source.indexOf === 'function';
+    let i = fromIndex;
+    while (i <= limit) {
+      // Fast-forward to the first matching byte using C++ bindings if available
+      if (hasNativeIndexOf) {
+        i = source.indexOf(firstByte, i);
+        if (i === -1 || i > limit) return -1;
+      } else {
+        // Fallback: Manual loop
+        while (i <= limit && source[i] !== firstByte) i++;
+        if (i > limit) return -1;
+      }
+
+      // First byte matches, verify the rest of the target sequence
+      let match = true;
+      for (let j = 1; j < targetLength; j++) {
         if (source[i + j] !== target[j]) {
+          match = false;
           break;
-        } else if (j === targetLength - 1) {
-          return i;
         }
       }
+      if (match) {
+        return i;
+      }
+      i++;
     }
     return -1;
   }
@@ -1201,8 +1273,10 @@ class MachineUTF16Input extends MachineInputBase {
   // Returns a bitmask of EMPTY_* flags.
   context(pos) {
     pos += this.start;
-    const r1 = pos > this.start && pos <= this.end ? this.charSequence.codePointAt(pos - 1) : -1;
-    const r2 = pos < this.end ? this.charSequence.codePointAt(pos) : -1;
+
+    // We only care about ASCII word runes and newlines for context boundaries
+    const r1 = pos > this.start && pos <= this.end ? this.charSequence.charCodeAt(pos - 1) : -1;
+    const r2 = pos < this.end ? this.charSequence.charCodeAt(pos) : -1;
     return Utils.emptyOpContext(r1, r2);
   }
   prefixLength(re2) {
@@ -1332,10 +1406,6 @@ class RE2JSInternalException extends RE2JSException {
  * @author rsc@google.com (Russ Cox)
  */
 
-/**
- * @typedef {import('./index').RE2JS} RE2JS_Pattern
- */
-
 class Matcher {
   /**
    * Quotes '\' and '$' in {@code s}, so that the returned string could be used in
@@ -1373,8 +1443,8 @@ class Matcher {
   }
   /**
    *
-   * @param {RE2JS_Pattern} pattern
-   * @param {Uint8Array|number[]|string} input
+   * @param {RE2JS} pattern
+   * @param {string|number[]|Uint8Array} input
    */
   constructor(pattern, input) {
     if (pattern === null) {
@@ -1382,7 +1452,7 @@ class Matcher {
     }
     /**
      * The pattern being matched.
-     * @type {RE2JS_Pattern}
+     * @type {RE2JS}
      */
     this.patternInput = pattern;
     const re2 = this.patternInput.re2();
@@ -1407,7 +1477,7 @@ class Matcher {
 
   /**
    * Returns the {@code RE2JS} associated with this {@code Matcher}.
-   * @returns {RE2JS_Pattern}
+   * @returns {RE2JS}
    */
   pattern() {
     return this.patternInput;
@@ -1437,7 +1507,7 @@ class Matcher {
 
   /**
    * Resets the {@code Matcher} and changes the input.
-   * @param {import('./MatcherInput').MatcherInputBase} input
+   * @param {MatcherInputBase} input
    * @returns {Matcher} the {@code Matcher} itself, for chained method calls
    */
   resetMatcherInput(input) {
@@ -2213,7 +2283,7 @@ class Machine {
       return Utils.emptyInts();
     }
     // Use subarray() to create a zero-allocation view before converting
-    return Array.from(this.matchcap.subarray(0, this.ncap));
+    return Utils.toArray(this.matchcap.subarray(0, this.ncap));
   }
 
   // alloc() allocates a new thread with the given instruction.
@@ -3175,7 +3245,7 @@ class Backtracker {
     }
 
     // Must slice so we don't accidentally leak trailing arrays from previously recycled typed arrays
-    const result = ncap === 0 ? [] : Array.from(b.matchcap.subarray(0, ncap));
+    const result = ncap === 0 ? [] : Utils.toArray(b.matchcap.subarray(0, ncap));
     bitStatePool.push(b);
     return result;
   }
@@ -3551,7 +3621,7 @@ class OnePass {
               matchcap[0] = 0;
               matchcap[1] = pos;
             }
-            return ncap === 0 ? [] : Array.from(matchcap);
+            return ncap === 0 ? [] : Utils.toArray(matchcap);
           }
         case Inst.RUNE:
           if (!inst.matchRune(rune)) return null;
@@ -3600,7 +3670,7 @@ class OnePass {
       }
     }
     if (!matched) return null;
-    return ncap === 0 ? [] : Array.from(matchcap);
+    return ncap === 0 ? [] : Utils.toArray(matchcap);
   }
 }
 
@@ -5354,7 +5424,7 @@ class StringIterator {
     return r;
   }
   lookingAt(s) {
-    return this.rest().startsWith(s);
+    return this.str.startsWith(s, this.position);
   }
 
   // Returns the rest of the pattern as a Java UTF-16 string.