re2js 2.5.0 → 2.6.0

package/README.md

@@ -228,6 +228,33 @@ matchString.group() // 'e'
 matchString.find(7) // false
 ```
 
+### Iterating Over Matches (`matchAll`)
+
+For a more modern, JavaScript-native developer experience, RE2JS provides a `.matchAll()` method. This returns an ES6 `IterableIterator`, allowing you to safely and cleanly iterate over matches using `for...of` loops or the array spread operator `[...]`.
+
+Unlike native `RegExp` objects with the `/g` flag, RE2JS is completely stateless. This means you don't have to worry about `.lastIndex` bugs—you can iterate over the same regex instance as many times as you want safely.
+
+The yielded match arrays perfectly mirror the shape of native JavaScript regex matches. They include `.index`, `.input`, and `.groups` properties, and properly map unmatched capture groups to `undefined`.
+
+```js
+import { RE2JS } from 're2js'
+
+const re2 = RE2JS.compile('(?P<year>\\d{4})-(?P<month>\\d{2})')
+const input = 'Dates: 2024-05 and 2025-11.'
+
+// Native ES6 Iteration
+for (const match of re2.matchAll(input)) {
+  console.log(match[0]); // "2024-05", then "2025-11"
+  console.log(match.index); // 7, then 19
+  console.log(match.groups); // { year: '2024', month: '05' } then { year: '2025', month: '11' }
+  console.log(match.groups.year); // "2024", then "2025"
+}
+
+// Or easily collect all matches into an array
+const allMatches = [...re2.matchAll(input)];
+console.log(allMatches.length); // 2
+```
+
 ### Multi-Pattern Matching (RE2Set)
 
 RE2JS includes a highly optimized `RE2Set` API that allows you to match multiple regular expressions against a single string simultaneously. Instead of running 100 different regexes in a loop ($O(100n)$ time), `RE2Set` compiles them into a single state machine and finds all matches in a single pass ($O(n)$ linear time).
@@ -631,23 +658,23 @@ Should you require maximum absolute performance on the server side when using RE
 
 Because RE2JS's Lazy DFA, Prefilter, and OnePass engines operate efficiently within V8's Just-In-Time (JIT) compiler, they can outperform native C++ bindings (`re2-node`) for many operations by avoiding the cross-boundary serialization costs between JavaScript and C++.
 
-Here is a benchmark running 30,000 items through both engines using their respective `.test()` fast-paths (averages of multiple runs):
+Here is a [benchmark running 30,000 items](src/__tests__/re2.bench.js) through both engines using their respective `.test()` fast-paths (averages of multiple runs):
 
 | 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  |
+| **ReDoS Attempt**         | `/(a+)+!/`                 | **2.16 ms**     | 15.94 ms       | `re2js` is **7.38x** faster |
+| **Simple Literal**        | `/damage/`                 | **2.58 ms**     | 12.39 ms       | `re2js` is **4.80x** faster |
+| **Deep State Machine**    | `/([0-9]+(/[0-9]+)+)/`     | **11.20 ms**    | 15.76 ms       | `re2js` is **1.41x** faster |
+| **Lazy Wildcard**         | `/enters.*?battlefield/`   | **9.78 ms**     | 12.99 ms       | `re2js` is **1.33x** faster |
+| **Greedy Wildcard**       | `/enters.*battlefield/`    | **9.90 ms**     | 12.99 ms       | `re2js` is **1.31x** faster |
+| **Massive Alternation**   | `/White\|Blue\|Black.../`  | **11.31 ms**    | 14.81 ms       | `re2js` is **1.31x** faster |
+| **Bounded Repetition**    | `/[A-Z][a-z]{5,15}/`       | 28.20 ms        | **13.60 ms**   | `re2-node` is 2.07x faster  |
+| **Case Insensitive**      | `/(?i)swamp/`              | 56.41 ms        | **16.13 ms**   | `re2-node` is 3.50x faster  |
+| **Word Boundaries (NFA)** | `/\b(Flying\|First...)\b/` | 107.12 ms       | **15.41 ms**   | `re2-node` is 6.95x faster  |
 
 **Takeaways:**
 * **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.
+* **C++ Strengths:** For character class evaluations (Case Insensitivity, Bounded Repetitions), `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. **For maximum performance in RE2JS, avoid `\b` when doing bulk boolean `.test()` matching.**
 
 

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.5.0
+ * @version v2.6.0
  * @author Oleksii Vasyliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -8654,6 +8654,47 @@ class RE2JS {
     return result;
   }
 
+  /**
+   * Returns an iterator of all results matching a string against the regular expression,
+   * including capturing groups.
+   *
+   * @param {string|number[]|Uint8Array} input the input string or byte array
+   * @returns {IterableIterator<Array>}
+   */
+  *matchAll(input) {
+    const m = this.matcher(input);
+    const inputStr = typeof input === 'string' ? input : m.matcherInput.asCharSequence();
+    while (m.find()) {
+      // Build the match array starting with the full match
+      const result = [m.group(0)];
+
+      // Append all capture groups using void 0 instead of undefined
+      for (let i = 1; i <= m.groupCount(); i++) {
+        const groupVal = m.group(i);
+        result.push(groupVal === null ? void 0 : groupVal);
+      }
+
+      // Attach native RegExp match properties
+      result.index = m.start(0);
+      result.input = inputStr;
+
+      // Attach named capture groups if they exist
+      const namedGroups = this.namedGroups();
+      if (Object.keys(namedGroups).length > 0) {
+        const parsedGroups = m.getNamedGroups();
+        for (const key in parsedGroups) {
+          if (parsedGroups[key] === null) {
+            parsedGroups[key] = void 0;
+          }
+        }
+        result.groups = parsedGroups;
+      } else {
+        result.groups = void 0;
+      }
+      yield result;
+    }
+  }
+
   /**
    *
    * @returns {string}
@@ -8710,6 +8751,8 @@ class RE2JS {
     return this.flagsInput === other.flagsInput && this.patternInput === other.patternInput;
   }
 }
+
+/* Small helper for Tagged Template Literals (No Double-Escaping) */
 const re = (stringsOrFlags, ...values) => {
   if (Array.isArray(stringsOrFlags) && stringsOrFlags.raw) {
     const pattern = String.raw(stringsOrFlags, ...values);