re2js 2.2.3 → 2.3.0

package/build/index.umd.js

@@ -2,7 +2,7 @@
  * re2js
  * RE2JS is the JavaScript port of RE2, a regular expression engine that provides linear time matching
  *
- * @version v2.2.3
+ * @version v2.3.0
  * @author Oleksii Vasyliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -1335,6 +1335,11 @@
    *
    * @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
@@ -1372,14 +1377,17 @@
     }
     /**
      *
-     * @param {RE2JS} pattern
-     * @param {Utf8MatcherInput|Utf16MatcherInput|number[]|string} input
+     * @param {RE2JS_Pattern} pattern
+     * @param {Uint8Array|number[]|string} input
      */
     constructor(pattern, input) {
       if (pattern === null) {
         throw new Error('pattern is null');
       }
-      // The pattern being matched.
+      /**
+       * The pattern being matched.
+       * @type {RE2JS_Pattern}
+       */
       this.patternInput = pattern;
       const re2 = this.patternInput.re2();
       // The number of submatches (groups) in the pattern.
@@ -1403,7 +1411,7 @@
 
     /**
      * Returns the {@code RE2JS} associated with this {@code Matcher}.
-     * @returns {RE2JS}
+     * @returns {RE2JS_Pattern}
      */
     pattern() {
       return this.patternInput;
@@ -1433,7 +1441,7 @@
 
     /**
      * Resets the {@code Matcher} and changes the input.
-     * @param {Utf8MatcherInput|Utf16MatcherInput} input
+     * @param {import('./MatcherInput').MatcherInputBase} input
      * @returns {Matcher} the {@code Matcher} itself, for chained method calls
      */
     resetMatcherInput(input) {
@@ -1498,7 +1506,7 @@
     /**
      * Returns the named group of the most recent match, or {@code null} if the group was not matched.
      * @param {string|number} [group=0]
-     * @returns {?string}
+     * @returns {string|null}
      */
     group(group = 0) {
       if (typeof group === 'string') {
@@ -1590,7 +1598,7 @@
      * Matches the input against the pattern (unanchored), starting at a specified position. If there
      * is a match, {@code find} sets the match state to describe it.
      *
-     * @param {number} [start=null] the input position where the search begins
+     * @param {number|null} [start=null] the input position where the search begins
      * @returns {boolean} if it finds a match
      * @throws IndexOutOfBoundsException if start is not a valid input position
      */
@@ -7941,9 +7949,18 @@
   }
 
   class RE2Set {
+    /** @type {number} */
     static UNANCHORED = RE2Flags.UNANCHORED;
+    /** @type {number} */
     static ANCHOR_START = RE2Flags.ANCHOR_START;
+    /** @type {number} */
     static ANCHOR_BOTH = RE2Flags.ANCHOR_BOTH;
+
+    /**
+     * Constructs a new RE2Set with the specified anchor mode and flags.
+     * @param {number} [anchor=RE2Set.UNANCHORED] - The anchoring mode (e.g., RE2Set.UNANCHORED).
+     * @param {number} [flags=0] - The public flags to apply to all patterns in the set.
+     */
     constructor(anchor = RE2Set.UNANCHORED, flags = 0) {
       this.anchor = anchor;
       this.jsFlags = flags;
@@ -7960,6 +7977,14 @@
       this.dfa = null;
       this.dummyRe2 = null;
     }
+
+    /**
+     * Adds a new regular expression pattern to the set.
+     * Patterns cannot be added after the set has been compiled.
+     * @param {string} pattern - The regular expression pattern to add.
+     * @returns {number} The integer index assigned to the added pattern.
+     * @throws {RE2JSCompileException} If patterns are added after compilation.
+     */
     add(pattern) {
       if (this.prog) {
         throw new RE2JSCompileException('Cannot add patterns after compile');
@@ -7978,6 +8003,12 @@
       this.regexps.push(Simplify.simplify(re));
       return this.regexps.length - 1;
     }
+
+    /**
+     * Compiles the added patterns into a single state machine.
+     * This is automatically called on the first match if not called explicitly.
+     * @returns {void}
+     */
     compile() {
       if (this.prog) return;
       this.prog = Compiler.compileSet(this.regexps);
@@ -7990,6 +8021,12 @@
         longest: false
       };
     }
+
+    /**
+     * Matches the input against the compiled set of regular expressions.
+     * @param {string|number[]|Uint8Array} input - The input string or UTF-8 byte array to match against.
+     * @returns {number[]} An array of indices representing the patterns that successfully matched the input.
+     */
     match(input) {
       if (!this.prog) this.compile();
       const machineInput = Utils.isByteArray(input) ? MachineInput.fromUTF8(input) : MachineInput.fromUTF16(input);
@@ -8015,13 +8052,19 @@
    * Transform JS regex string to RE2 regex string
    */
   class TranslateRegExpString {
-    static isUpperCaseAlpha(ch) {
-      return 'A' <= ch && ch <= 'Z';
-    }
     static isHexadecimal(ch) {
       return '0' <= ch && ch <= '9' || 'A' <= ch && ch <= 'F' || 'a' <= ch && ch <= 'f';
     }
     static translate(data) {
+      let prefixFlags = '';
+      if (data instanceof RegExp) {
+        if (data.ignoreCase) prefixFlags += 'i';
+        if (data.multiline) prefixFlags += 'm';
+        if (data.dotAll) prefixFlags += 's';
+
+        // execution flags ('g', 'y') are safely ignored here.
+        data = data.source;
+      }
       if (typeof data !== 'string') {
         return data;
       }
@@ -8032,6 +8075,7 @@
         result = '(?:)';
         changed = true;
       }
+      let inCharClass = false;
       let i = 0;
       while (i < size) {
         let ch = data[i];
@@ -8070,10 +8114,28 @@
                   if (i + 2 < size) {
                     let nextCh = data[i + 2];
                     if (nextCh === '{') {
-                      result += '\\x';
-                      i += 2;
-                      changed = true;
-                      continue;
+                      // Must have a closing brace and at least one valid hex digit inside
+                      let j = i + 3;
+                      let hasHex = false;
+                      let closed = false;
+                      while (j < size) {
+                        const hexChar = data[j];
+                        if (hexChar === '}') {
+                          closed = true;
+                          break;
+                        }
+                        if (!TranslateRegExpString.isHexadecimal(hexChar)) {
+                          break;
+                        }
+                        hasHex = true;
+                        j++;
+                      }
+                      if (closed && hasHex) {
+                        result += '\\x';
+                        i += 2;
+                        changed = true;
+                        continue;
+                      }
                     } else if (i + 5 < size) {
                       let isHex4 = true;
                       for (let j = 0; j < 4; j++) {
@@ -8090,18 +8152,101 @@
                       }
                     }
                   }
+
+                  // Graceful degradation for invalid/unclosed \u sequences
                   result += 'u';
                   i += 2;
                   changed = true;
                   continue;
                 }
+              case 'x':
+                {
+                  let isValidHex = false;
+                  if (i + 2 < size && data[i + 2] === '{') {
+                    // Must have a closing brace and at least one valid hex digit inside
+                    let j = i + 3;
+                    let hasHex = false;
+                    let closed = false;
+                    while (j < size) {
+                      const hexChar = data[j];
+                      if (hexChar === '}') {
+                        closed = true;
+                        break;
+                      }
+                      if (!TranslateRegExpString.isHexadecimal(hexChar)) {
+                        break;
+                      }
+                      hasHex = true;
+                      j++;
+                    }
+                    if (closed && hasHex) {
+                      isValidHex = true;
+                    }
+                  } else if (i + 3 < size && TranslateRegExpString.isHexadecimal(data[i + 2]) && TranslateRegExpString.isHexadecimal(data[i + 3])) {
+                    isValidHex = true;
+                  }
+                  if (isValidHex) {
+                    result += '\\x';
+                    i += 2;
+                  } else {
+                    result += 'x';
+                    i += 2;
+                    changed = true;
+                  }
+                  continue;
+                }
+              // Whitelist of valid RE2/JS alphanumeric escapes
+              case 'n':
+              case 'r':
+              case 't':
+              case 'a':
+              case 'f':
+              case 'v':
+              case 'd':
+              case 'D':
+              case 's':
+              case 'S':
+              case 'w':
+              case 'W':
+              case 'b':
+              case 'B':
+              case 'p':
+              case 'P':
+              case 'A':
+              case 'z':
+              case 'Q':
+              case 'E':
+              case '0':
+              case '1':
+              case '2':
+              case '3':
+              case '4':
+              case '5':
+              case '6':
+              case '7':
+                {
+                  result += '\\' + ch;
+                  i += 2;
+                  continue;
+                }
               default:
                 {
-                  result += '\\';
                   let cp = data.codePointAt(i + 1);
-                  let symSize = Utils.charCount(cp);
-                  result += data.substring(i + 1, i + 1 + symSize);
-                  i += symSize + 1;
+                  let isAlphaNum = cp >= 48 && cp <= 57 || cp >= 65 && cp <= 90 || cp >= 97 && cp <= 122;
+                  if (isAlphaNum) {
+                    // Invalid JS alphanumeric escape sequence (e.g. \8, \9, \e, \K)
+                    // Gracefully degrade to the literal character to prevent RE2 syntax crashes
+                    let symSize = Utils.charCount(cp);
+                    result += data.substring(i + 1, i + 1 + symSize);
+                    i += symSize + 1;
+                    changed = true;
+                  } else {
+                    // Escaped symbol (e.g. \., \*, \])
+                    result += '\\';
+                    let symSize = Utils.charCount(cp);
+                    result += data.substring(i + 1, i + 1 + symSize);
+                    i += symSize + 1;
+                  }
                   continue;
                 }
             }
@@ -8111,7 +8256,13 @@
           i += 1;
           changed = true;
           continue;
-        } else if (ch === '(' && i + 2 < size && data[i + 1] === '?' && data[i + 2] === '<') {
+        } else if (ch === '[') {
+          // Track entry into a character class (protects syntax inside)
+          inCharClass = true;
+        } else if (ch === ']') {
+          // Track exit of a character class
+          inCharClass = false;
+        } else if (!inCharClass && ch === '(' && i + 2 < size && data[i + 1] === '?' && data[i + 2] === '<') {
           if (i + 3 < size && !'=!>)'.includes(data[i + 3])) {
             result += '(?P<';
             i += 3;
@@ -8124,7 +8275,13 @@
         result += data.substring(i, i + symSize);
         i += symSize;
       }
-      return changed ? result : data;
+      const finalResult = changed ? result : data;
+
+      // Append any extracted inline flags
+      if (prefixFlags.length > 0) {
+        return `(?${prefixFlags})${finalResult}`;
+      }
+      return finalResult;
     }
   }
 
@@ -8202,7 +8359,7 @@
      * RE2JS-compatible syntax, and handling Unicode sequences properly. It ensures that the
      * resulting regex is safe and properly formatted before compilation.
      *
-     * @param {string} expr - The regular expression string to be translated.
+     * @param {string|RegExp} expr - The regular expression string to be translated.
      * @returns {string} - The transformed regular expression string, ready for compilation.
      */
     static translateRegExp(expr) {
@@ -8246,7 +8403,7 @@
      * Matches a string against a regular expression.
      *
      * @param {string} regex the regular expression
-     * @param {string|number[]} input the input
+     * @param {string|number[]|Uint8Array} input the input
      * @returns {boolean} true if the regular expression matches the entire input
      * @throws RE2JSSyntaxException if the regular expression is malformed
      */
@@ -8313,7 +8470,7 @@
     /**
      * Matches a string against a regular expression.
      *
-     * @param {string|number[]} input the input
+     * @param {string|number[]|Uint8Array} input the input
      * @returns {boolean} true if the regular expression matches the entire input
      */
     matches(input) {
@@ -8323,7 +8480,7 @@
     /**
      * Creates a new {@code Matcher} matching the pattern against the input.
      *
-     * @param {string|number[]} input the input string
+     * @param {string|number[]|Uint8Array} input the input string
      * @returns {Matcher}
      */
     matcher(input) {
@@ -8339,7 +8496,7 @@
      * a boolean and does not extract capture groups, it bypasses the `Matcher` overhead
      * and guarantees execution on the high-speed DFA engine whenever possible.
      *
-     * @param {string|number[]} input - The input string or UTF-8 byte array to test against.
+     * @param {string|number[]|Uint8Array} input - The input string or UTF-8 byte array to test against.
      * @returns {boolean} `true` if the pattern is found anywhere in the input, `false` otherwise.
      */
     test(input) {
@@ -8358,7 +8515,7 @@
      * faster because it does not request capture group data. By requesting 0 capture groups,
      * it securely routes execution through the DFA fast-path.
      *
-     * @param {string|number[]} input - The input string or UTF-8 byte array to test against.
+     * @param {string|number[]|Uint8Array} input - The input string or UTF-8 byte array to test against.
      * @returns {boolean} `true` if the exact input string fully matches the pattern, `false` otherwise.
      */
     testExact(input) {