re2js 2.7.1 → 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.1
+ * @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;
+  }
 }
 
 /**