re2js 2.2.3 → 2.3.0

package/README.md

@@ -577,6 +577,10 @@ const unicodeRegexp = RE2JS.translateRegExp('\\u{1F600}') // '\\x{1F600}'
 
 RE2JS.matches(unicodeRegexp, '😀') // true
 RE2JS.matches(unicodeRegexp, '😃') // false
+
+// also support native Regex
+RE2JS.translateRegExp(/foo/ims) // '(?ims)foo'
+RE2JS.translateRegExp(/bar/giy) // '(?i)bar'
 ```
 
 ## Performance and Architecture

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.2.3
+ * @version v2.3.0
  * @author Oleksii Vasyliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -1331,6 +1331,11 @@ class RE2JSInternalException extends RE2JSException {
  *
  * @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
@@ -1368,14 +1373,17 @@ class Matcher {
   }
   /**
    *
-   * @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.
@@ -1399,7 +1407,7 @@ class Matcher {
 
   /**
    * Returns the {@code RE2JS} associated with this {@code Matcher}.
-   * @returns {RE2JS}
+   * @returns {RE2JS_Pattern}
    */
   pattern() {
     return this.patternInput;
@@ -1429,7 +1437,7 @@ class Matcher {
 
   /**
    * 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) {
@@ -1494,7 +1502,7 @@ class Matcher {
   /**
    * 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') {
@@ -1586,7 +1594,7 @@ class Matcher {
    * 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
    */
@@ -7937,9 +7945,18 @@ class RE2 {
 }
 
 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;
@@ -7956,6 +7973,14 @@ class RE2Set {
     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');
@@ -7974,6 +7999,12 @@ class RE2Set {
     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);
@@ -7986,6 +8017,12 @@ class RE2Set {
       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);
@@ -8011,13 +8048,19 @@ class RE2Set {
  * 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;
     }
@@ -8028,6 +8071,7 @@ class TranslateRegExpString {
       result = '(?:)';
       changed = true;
     }
+    let inCharClass = false;
     let i = 0;
     while (i < size) {
       let ch = data[i];
@@ -8066,10 +8110,28 @@ class TranslateRegExpString {
                 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++) {
@@ -8086,18 +8148,101 @@ class TranslateRegExpString {
                     }
                   }
                 }
+
+                // 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;
               }
           }
@@ -8107,7 +8252,13 @@ class TranslateRegExpString {
         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;
@@ -8120,7 +8271,13 @@ class TranslateRegExpString {
       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;
   }
 }
 
@@ -8198,7 +8355,7 @@ class RE2JS {
    * 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) {
@@ -8242,7 +8399,7 @@ class RE2JS {
    * 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
    */
@@ -8309,7 +8466,7 @@ class RE2JS {
   /**
    * 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) {
@@ -8319,7 +8476,7 @@ class RE2JS {
   /**
    * 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) {
@@ -8335,7 +8492,7 @@ class RE2JS {
    * 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) {
@@ -8354,7 +8511,7 @@ class RE2JS {
    * 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) {