re2js 2.7.0 → 2.8.0

package/README.md

@@ -513,7 +513,7 @@ RE2JS.compile('(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)')
 Note that the replacement string can include references to capturing groups from the pattern
 
 Parameters:
-- `replacement (String)`: The string that replaces the substrings found. Capture groups and special characters in the replacement string have special behavior. For example:
+- `replacement (String | Function)`: The string that replaces the substrings found, or a function invoked to create the new substring. When passing a string, capture groups and special characters have special behavior. For example:
   - `$&` refers to the entire matched substring
   - `$1, $2, ...` refer to the corresponding capture groups in the pattern
   - `$$` inserts a literal `$`
@@ -556,7 +556,42 @@ RE2JS.compile('(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)')
   .replaceFirst('$10$20') // 'jb0nopqrstuvwxyz123'
 ```
 
-Function support second argument `javaMode`, which work in the same way, as for `replaceAll` function
+Function support second argument `javaMode`, which work in the same way, as for `replaceAll` function.
+
+#### Using a Replacer Function
+
+For a more modern JavaScript developer experience, RE2JS supports passing a **replacer function** to `replaceAll()` and `replaceFirst()`, perfectly mirroring native `String.prototype.replace(regex, replacer)` behavior while taking advantage of the high-speed linear-time engine.
+
+The replacer function is invoked for each match, and its return value is used as the replacement string. The function receives the following arguments:
+
+1. `match`: The matched substring.
+2. `p1, p2, ...`: The string found by a capture group (if any). Unmatched optional groups evaluate to `undefined`.
+3. `offset`: The offset of the matched substring within the whole string.
+4. `string`: The original input string (or byte array).
+5. `groups`: A dictionary object of named capture groups (if any exist in the pattern).
+
+```js
+import { RE2JS } from 're2js'
+
+// Example 1: Dynamic replacements
+const re1 = RE2JS.compile('\\d+');
+const m1 = re1.matcher('Numbers: 1, 2, 3');
+
+m1.replaceAll((match) => String(Number(match) * 10));
+// 'Numbers: 10, 20, 30'
+
+
+// Example 2: Using named capture groups and function signature
+const re2 = RE2JS.compile('(?P<first>\\w+) (?:(?P<middle>\\w+) )?(?P<last>\\w+)');
+const m2 = re2.matcher('Hello World');
+
+m2.replaceFirst((match, p1, p2, p3, offset, string, groups) => {
+  // 'middle' didn't match, so p2 and groups.middle will be undefined
+  return `${groups.last}, ${groups.first}`;
+});
+// 'World, Hello'
+
+```
 
 ### Safe Replacements
 

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.7.0
+ * @version v2.8.0
  * @author Oleksii Vasyliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -1411,6 +1411,13 @@ class RE2JSInternalException extends RE2JSException {
  */
 
 class Matcher {
+  /**
+   * V8 and WebKit have historical hard limits on the number of arguments
+   * that can be passed to a function. We cap replacer arguments to prevent
+   * Call Stack Overflow (DoS) vulnerabilities on massive ASTs.
+   */
+  static MAX_REPLACER_ARGS = 65535;
+
   /**
    * Quotes '\' and '$' in {@code s}, so that the returned string could be used in
    * {@link #appendReplacement} as a literal replacement of {@code s}.
@@ -1707,16 +1714,14 @@ class Matcher {
    * @private
    */
   genMatch(startByte, anchor) {
-    const hasLookbehinds = this.patternInput.re2().prog.numLb > 0;
-    const ngroup = hasLookbehinds ? 1 + this.patternGroupCount : 1;
-    const res = this.patternInput.re2().matchMachineInput(this.matcherInput, startByte, this.matcherInputLength, anchor, ngroup);
+    const res = this.patternInput.re2().matchMachineInput(this.matcherInput, startByte, this.matcherInputLength, anchor, 1);
     const ok = res[0];
     if (!ok) {
       return false;
     }
     this.groups = res[1];
     this.hasMatch = true;
-    this.hasGroups = hasLookbehinds || this.patternGroupCount === 0;
+    this.hasGroups = this.patternGroupCount === 0;
     this.anchorFlag = anchor;
     return true;
   }
@@ -1969,7 +1974,7 @@ class Matcher {
    * Returns the input with all matches replaced by {@code replacement}, interpreted as for
    * {@code appendReplacement}.
    *
-   * @param {string} replacement - the replacement string
+   * @param {string|Function} replacement - the replacement string or a replacer function
    * @param {boolean} [javaMode=false] - activate java mode (different behaviour for capture groups and special characters)
    * @returns {string} the input string with the matches replaced
    * @throws IndexOutOfBoundsException if replacement refers to an invalid group and javaMode is true
@@ -1982,7 +1987,7 @@ class Matcher {
    * Returns the input with the first match replaced by {@code replacement}, interpreted as for
    * {@code appendReplacement}.
    *
-   * @param {string} replacement - the replacement string
+   * @param {string|Function} replacement - the replacement string or a replacer function
    * @param {boolean} [javaMode=false] - activate java mode (different behaviour for capture groups and special characters)
    * @returns {string} the input string with the first match replaced
    * @throws IndexOutOfBoundsException if replacement refers to an invalid group and javaMode is true
@@ -1993,7 +1998,7 @@ class Matcher {
 
   /**
    * Helper: replaceAll/replaceFirst hybrid.
-   * @param {string} replacement - the replacement string
+   * @param {string|Function} replacement - the replacement string or a replacer function
    * @param {boolean} [all=true] - replace all matches
    * @param {boolean} [javaMode=false] - activate java mode (different behaviour for capture groups and special characters)
    * @returns {string}
@@ -2002,8 +2007,21 @@ class Matcher {
   replace(replacement, all = true, javaMode = false) {
     let res = '';
     this.reset();
+    const isFunc = typeof replacement === 'function';
+
+    // Cache named groups check to avoid GC thrashing on every match
+    const hasNamedGroups = Object.keys(this.namedGroups).length > 0;
+    let originalInput = null;
+    if (isFunc) {
+      // Prevent V8 Call Stack Overflow (DoS vector) on massive capture group counts
+      if (this.groupCount() >= Matcher.MAX_REPLACER_ARGS) {
+        throw new RE2JSGroupException('Too many capture groups to safely invoke replacer function');
+      }
+      // Resolve the original input reference exactly once outside the hot loop
+      originalInput = this.matcherInput.isUTF8Encoding() ? this.matcherInput.asBytes() : this.matcherInput.asCharSequence();
+    }
     while (this.find()) {
-      res += this.appendReplacement(replacement, javaMode);
+      res += isFunc ? this.appendReplacementFunc(replacement, hasNamedGroups, originalInput) : this.appendReplacement(replacement, javaMode);
       if (!all) {
         break;
       }
@@ -2011,6 +2029,66 @@ class Matcher {
     res += this.appendTail();
     return res;
   }
+
+  /**
+   * Evaluates a replacer function for the current match and appends the result,
+   * along with any un-matched preceding text, advancing the append position.
+   * @param {Function} replacer - the replacer function
+   * @param {boolean} hasNamedGroups - cached flag if pattern has named groups
+   * @param {string|Uint8Array|number[]} originalInput - the cached original input reference
+   * @returns {string} the evaluated string to append
+   * @private
+   */
+  appendReplacementFunc(replacer, hasNamedGroups, originalInput) {
+    let res = '';
+    const s = this.start();
+    const e = this.end();
+    if (this.appendPos < s) {
+      res += this.substring(this.appendPos, s);
+    }
+    this.appendPos = e;
+    const args = this.buildReplacerArgs(s, hasNamedGroups, originalInput);
+    res += String(replacer(...args));
+    return res;
+  }
+
+  /**
+   * Builds the argument array for the replacer function matching the standard
+   * JS String.prototype.replace(regex, replacer) signature.
+   * @param {number} matchStart - the start index of the match
+   * @param {boolean} hasNamedGroups - cached flag if pattern has named groups
+   * @param {string|Uint8Array|number[]} originalInput - the cached original input reference
+   * @returns {Array} array of arguments
+   * @private
+   */
+  buildReplacerArgs(matchStart, hasNamedGroups, originalInput) {
+    const args = [this.group(0)]; // match
+
+    const numGroups = this.groupCount();
+    // Fast-path capture group extraction
+    for (let i = 1; i <= numGroups; i++) {
+      const start = this.start(i);
+      if (start < 0) {
+        args.push(void 0);
+      } else {
+        args.push(this.substring(start, this.end(i)));
+      }
+    }
+    args.push(matchStart); // offset
+    args.push(originalInput); // original string (cached)
+
+    // Append named groups object if pattern contains them
+    if (hasNamedGroups) {
+      const parsedGroups = this.getNamedGroups();
+      for (const key in parsedGroups) {
+        if (parsedGroups[key] === null) {
+          parsedGroups[key] = void 0;
+        }
+      }
+      args.push(parsedGroups);
+    }
+    return args;
+  }
 }
 
 /**
@@ -2337,30 +2415,35 @@ class Machine {
     }
     this.matched = false;
     this.matchcap.fill(-1);
+
+    // Lookbehinds must scan from the beginning of the string to build their state table,
+    // even if the main pattern search is requested to start mid-string.
+    let currentPos = this.prog.numLb > 0 ? 0 : pos;
+    let matchStartPos = pos;
     let runq = this.q0;
     let nextq = this.q1;
-    let r = input.step(pos);
+    let r = input.step(currentPos);
     let rune = r >> 3;
     let width = r & 7;
     let rune1 = -1;
     let width1 = 0;
     if (r !== MachineInputBase.EOF()) {
-      r = input.step(pos + width);
+      r = input.step(currentPos + width);
       rune1 = r >> 3;
       width1 = r & 7;
     }
     let flag;
-    if (pos === 0) {
+    if (currentPos === 0) {
       flag = Utils.emptyOpContext(-1, rune);
     } else {
-      flag = input.context(pos);
+      flag = input.context(currentPos);
     }
     while (true) {
       if (runq.isEmpty()) {
-        if ((startCond & Utils.EMPTY_BEGIN_TEXT) !== 0 && pos !== 0) {
+        if ((startCond & Utils.EMPTY_BEGIN_TEXT) !== 0 && currentPos !== 0) {
           break;
         }
-        if ((anchor === RE2Flags.ANCHOR_START || anchor === RE2Flags.ANCHOR_BOTH) && pos !== 0) {
+        if ((anchor === RE2Flags.ANCHOR_START || anchor === RE2Flags.ANCHOR_BOTH) && currentPos !== 0) {
           break;
         }
         if (this.matched) {
@@ -2370,43 +2453,50 @@ class Machine {
         // Fast-forwarding the string pointer will skip over the positions where
         // the parallel lookbehind automata need to be spawned.
         if (this.prog.numLb === 0 && !(this.re2.prefix.length === 0) && rune1 !== this.re2.prefixRune && input.canCheckPrefix()) {
-          const advance = input.index(this.re2, pos);
+          const advance = input.index(this.re2, currentPos);
           if (advance < 0) {
             break;
           }
-          pos += advance;
-          r = input.step(pos);
+          currentPos += advance;
+          r = input.step(currentPos);
           rune = r >> 3;
           width = r & 7;
-          r = input.step(pos + width);
+          r = input.step(currentPos + width);
           rune1 = r >> 3;
           width1 = r & 7;
         }
       }
-      if (!this.matched && (pos === 0 || anchor === RE2Flags.UNANCHORED)) {
-        if (this.ncap > 0) {
-          this.matchcap[0] = pos;
-        }
-        // Spawn Lookbehind threads BEFORE the main pattern
+
+      // Optimize lookbehind spawning. Because lookbehinds are prefixed with `.*` by the compiler,
+      // they only need to be spawned exactly once at the beginning of the string (currentPos === 0).
+      if (currentPos === 0 && this.prog.numLb > 0) {
         for (let i = 0; i < this.prog.lbStarts.length; i++) {
-          this.add(runq, this.prog.lbStarts[i], pos, this.matchcap, flag, null);
+          this.add(runq, this.prog.lbStarts[i], currentPos, this.matchcap, flag, null);
+        }
+      }
+      if (!this.matched && (currentPos === 0 || anchor === RE2Flags.UNANCHORED)) {
+        // ONLY spawn the main pattern if we have reached the requested search start boundary
+        if (currentPos >= matchStartPos) {
+          if (this.ncap > 0) {
+            this.matchcap[0] = currentPos;
+          }
+          this.add(runq, this.prog.start, currentPos, this.matchcap, flag, null);
         }
-        this.add(runq, this.prog.start, pos, this.matchcap, flag, null);
       }
-      const nextPos = pos + width;
+      const nextPos = currentPos + width;
       flag = input.context(nextPos);
-      this.step(runq, nextq, pos, nextPos, rune, flag, anchor, pos === input.endPos());
+      this.step(runq, nextq, currentPos, nextPos, rune, flag, anchor, currentPos === input.endPos());
       if (width === 0) {
         break;
       }
       if (this.ncap === 0 && this.matched) {
         break;
       }
-      pos += width;
+      currentPos += width;
       rune = rune1;
       width = width1;
       if (rune !== -1) {
-        r = input.step(pos + width);
+        r = input.step(currentPos + width);
         rune1 = r >> 3;
         width1 = r & 7;
       }
@@ -2423,35 +2513,46 @@ class Machine {
     if ((anchor === RE2Flags.ANCHOR_START || anchor === RE2Flags.ANCHOR_BOTH) && pos !== 0) {
       return [];
     }
+
+    // Lookbehinds must scan from the beginning of the string to build their state table,
+    // even if the main pattern search is requested to start mid-string.
+    let currentPos = this.prog.numLb > 0 ? 0 : pos;
+    let matchStartPos = pos;
     let runq = this.q0;
     let nextq = this.q1;
-    let r = input.step(pos);
+    let r = input.step(currentPos);
     let rune = r >> 3;
     let width = r & 7;
     let rune1 = -1;
     let width1 = 0;
     if (r !== MachineInputBase.EOF()) {
-      r = input.step(pos + width);
+      r = input.step(currentPos + width);
       rune1 = r >> 3;
       width1 = r & 7;
     }
-    let flag = pos === 0 ? Utils.emptyOpContext(-1, rune) : input.context(pos);
+    let flag = currentPos === 0 ? Utils.emptyOpContext(-1, rune) : input.context(currentPos);
     const matches = new Set();
     while (true) {
       if (runq.isEmpty()) {
-        if ((startCond & Utils.EMPTY_BEGIN_TEXT) !== 0 && pos !== 0) break;
-        if ((anchor === RE2Flags.ANCHOR_START || anchor === RE2Flags.ANCHOR_BOTH) && pos !== 0) {
+        if ((startCond & Utils.EMPTY_BEGIN_TEXT) !== 0 && currentPos !== 0) break;
+        if ((anchor === RE2Flags.ANCHOR_START || anchor === RE2Flags.ANCHOR_BOTH) && currentPos !== 0) {
           break;
         }
       }
-      if (pos === 0 || anchor === RE2Flags.UNANCHORED) {
-        // Spawn Lookbehind threads BEFORE the main pattern
+
+      // Optimize lookbehind spawning to exactly once at BOF
+      if (currentPos === 0 && this.prog.numLb > 0) {
         for (let i = 0; i < this.prog.lbStarts.length; i++) {
-          this.add(runq, this.prog.lbStarts[i], pos, this.matchcap, flag, null);
+          this.add(runq, this.prog.lbStarts[i], currentPos, this.matchcap, flag, null);
         }
-        this.add(runq, this.prog.start, pos, this.matchcap, flag, null);
       }
-      const nextPos = pos + width;
+      if (currentPos === 0 || anchor === RE2Flags.UNANCHORED) {
+        // ONLY spawn the main pattern if we have reached the requested search start boundary
+        if (currentPos >= matchStartPos) {
+          this.add(runq, this.prog.start, currentPos, this.matchcap, flag, null);
+        }
+      }
+      const nextPos = currentPos + width;
       flag = input.context(nextPos);
       for (let j = 0; j < runq.size; j++) {
         let t = runq.denseThreads[j];
@@ -2460,7 +2561,7 @@ class Machine {
         let add = false;
         switch (i.op) {
           case Inst.MATCH:
-            if (anchor === RE2Flags.ANCHOR_BOTH && pos !== input.endPos()) break;
+            if (anchor === RE2Flags.ANCHOR_BOTH && currentPos !== input.endPos()) break;
             matches.add(i.arg); // Record the matched Set ID
             break;
           case Inst.RUNE:
@@ -2488,11 +2589,11 @@ class Machine {
       }
       runq.clear();
       if (width === 0) break;
-      pos += width;
+      currentPos += width;
       rune = rune1;
       width = width1;
       if (rune !== -1) {
-        r = input.step(pos + width);
+        r = input.step(currentPos + width);
         rune1 = r >> 3;
         width1 = r & 7;
       }