re2js 2.7.1 → 2.8.0

package/build/index.esm.d.ts

@@ -21,6 +21,12 @@
  * @author rsc@google.com (Russ Cox)
  */
 export 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: number;
     /**
      * Quotes '\' and '$' in {@code s}, so that the returned string could be used in
      * {@link #appendReplacement} as a literal replacement of {@code s}.
@@ -210,31 +216,51 @@ export 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
      */
-    replaceAll(replacement: string, javaMode?: boolean): string;
+    replaceAll(replacement: string | Function, javaMode?: boolean): string;
     /**
      * 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
      */
-    replaceFirst(replacement: string, javaMode?: boolean): string;
+    replaceFirst(replacement: string | Function, javaMode?: boolean): string;
     /**
      * 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}
      * @private
      */
     private replace;
+    /**
+     * 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
+     */
+    private appendReplacementFunc;
+    /**
+     * 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
+     */
+    private buildReplacerArgs;
 }
 /**
  * A compiled representation of an RE2 regular expression

package/build/index.esm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.d.ts","sourceRoot":"","sources":["index.esm.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.esm.d.ts","sourceRoot":"","sources":["index.esm.js"],"names":[],"mappings":"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"}

package/build/index.esm.js

@@ -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
@@ -1409,6 +1409,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}.
@@ -1705,16 +1712,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;
   }
@@ -1967,7 +1972,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
@@ -1980,7 +1985,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
@@ -1991,7 +1996,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}
@@ -2000,8 +2005,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;
       }
@@ -2009,6 +2027,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;
+  }
 }
 
 /**