re2js 1.2.2 → 1.3.0

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 v1.2.2
+ * @version v1.3.0
  * @author Alexey Vasiliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -844,6 +844,7 @@ class MatcherInput {
 }
 
 class RE2JSException extends Error {
+  /** @param {string} message */
   constructor(message) {
     super(message);
     this.name = 'RE2JSException';
@@ -854,6 +855,10 @@ class RE2JSException extends Error {
  * An exception thrown by the parser if the pattern was invalid.
  */
 class RE2JSSyntaxException extends RE2JSException {
+  /**
+   * @param {string} error
+   * @param {string|null} [input=null]
+   */
   constructor(error, input = null) {
     let message = `error parsing regexp: ${error}`;
     if (input) {
@@ -862,12 +867,15 @@ class RE2JSSyntaxException extends RE2JSException {
     super(message);
     this.name = 'RE2JSSyntaxException';
     this.message = message;
+    /** @type {string} */
     this.error = error;
+    /** @type {string|null} */
     this.input = input;
   }
 
   /**
    * Retrieves the description of the error.
+   * @returns {string}
    */
   getDescription() {
     return this.error;
@@ -875,6 +883,7 @@ class RE2JSSyntaxException extends RE2JSException {
 
   /**
    * Retrieves the erroneous regular-expression pattern.
+   * @returns {string|null}
    */
   getPattern() {
     return this.input;
@@ -885,6 +894,7 @@ class RE2JSSyntaxException extends RE2JSException {
  * An exception thrown by the compiler
  */
 class RE2JSCompileException extends RE2JSException {
+  /** @param {string} message */
   constructor(message) {
     super(message);
     this.name = 'RE2JSCompileException';
@@ -895,6 +905,7 @@ class RE2JSCompileException extends RE2JSException {
  * An exception thrown by using groups
  */
 class RE2JSGroupException extends RE2JSException {
+  /** @param {string} message */
   constructor(message) {
     super(message);
     this.name = 'RE2JSGroupException';
@@ -905,12 +916,24 @@ class RE2JSGroupException extends RE2JSException {
  * An exception thrown by flags
  */
 class RE2JSFlagsException extends RE2JSException {
+  /** @param {string} message */
   constructor(message) {
     super(message);
     this.name = 'RE2JSFlagsException';
   }
 }
 
+/**
+ * An exception thrown by DFA
+ */
+class RE2JSDfaMemoryException extends RE2JSException {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'RE2JSDfaMemoryException';
+  }
+}
+
 /**
  * A stateful iterator that interprets a regex {@code RE2JS} on a specific input.
  *
@@ -966,10 +989,14 @@ class Matcher {
     this.patternInput = pattern;
     const re2 = this.patternInput.re2();
     // The number of submatches (groups) in the pattern.
+    /** @type {number} */
     this.patternGroupCount = re2.numberOfCapturingGroups();
     // The group indexes, in [start, end) pairs.  Zeroth pair is overall match.
+    /** @type {number[]} */
     this.groups = [];
+    /** @type {Record<string, number>} */
     this.namedGroups = re2.namedGroups;
+    /** @type {number} */
     this.numberOfInstructions = re2.numberOfInstructions();
     if (input instanceof MatcherInputBase) {
       this.resetMatcherInput(input);
@@ -995,8 +1022,10 @@ class Matcher {
    */
   reset() {
     // The input length in UTF16 codes.
+    /** @type {number} */
     this.matcherInputLength = this.matcherInput.length();
     // The append position: where the next append should start.
+    /** @type {number} */
     this.appendPos = 0;
     // Is there a current match?
     this.hasMatch = false;
@@ -1010,6 +1039,7 @@ class Matcher {
 
   /**
    * Resets the {@code Matcher} and changes the input.
+   * @param {Utf8MatcherInput|Utf16MatcherInput} input
    * @returns {Matcher} the {@code Matcher} itself, for chained method calls
    */
   resetMatcherInput(input) {
@@ -1152,7 +1182,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 {string|number} [start=null] the input position where the search begins
+   * @param {number} [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
    */
@@ -2093,6 +2123,160 @@ class Machine {
   }
 }
 
+class DFAState {
+  constructor(id, nfaStates, isMatch) {
+    this.id = id; // Stringified NFA state list (e.g., "1,4,7")
+    this.nfaStates = nfaStates; // Array of Instruction PCs
+    this.isMatch = isMatch; // Boolean
+    this.nextAscii = new Array(Unicode.MAX_ASCII + 1).fill(null); // Flat array for blisteringly fast ASCII lookups (unanchored)
+    this.nextMap = new Map(); // Cache of Char -> DFAState
+  }
+}
+class DFA {
+  constructor(prog) {
+    this.prog = prog;
+    this.stateCache = new Map(); // id -> DFAState
+    this.startState = null;
+    this.stateLimit = 10000; // Prevent memory explosion (ReDoS protection), like RE2 max_mem
+  }
+
+  // Follows epsilon (empty) transitions to find all reachable states without consuming a char
+  computeClosure(pcs) {
+    const closure = new Set();
+    const stack = [...pcs];
+    let isMatch = false;
+    while (stack.length > 0) {
+      const pc = stack.pop();
+      if (closure.has(pc)) continue;
+      closure.add(pc);
+      const inst = this.prog.getInst(pc);
+      switch (inst.op) {
+        case Inst.MATCH:
+          isMatch = true;
+          break;
+        case Inst.ALT:
+        case Inst.ALT_MATCH:
+          stack.push(inst.out);
+          stack.push(inst.arg);
+          break;
+        case Inst.NOP:
+        case Inst.CAPTURE:
+          stack.push(inst.out);
+          break;
+        // Bailing out on complex empty-width assertions to keep DFA fast.
+        // Engine will seamlessly fall back to the NFA.
+        case Inst.EMPTY_WIDTH:
+          return null;
+      }
+    }
+    const sortedPCs = Int32Array.from(closure).sort();
+    return {
+      pcs: sortedPCs,
+      isMatch
+    };
+  }
+
+  // Get or create a DFA state from a list of NFA PCs
+  getState(pcs) {
+    const closureResult = this.computeClosure(pcs);
+    if (!closureResult) return null; // Bailout to NFA required
+
+    const id = closureResult.pcs.join(',');
+    if (this.stateCache.has(id)) {
+      return this.stateCache.get(id);
+    }
+
+    // Safety: prevent memory exhaustion from state explosion
+    if (this.stateCache.size > this.stateLimit) {
+      throw new RE2JSDfaMemoryException('dfa error: Out of memory exception');
+    }
+    const state = new DFAState(id, closureResult.pcs, closureResult.isMatch);
+    this.stateCache.set(id, state);
+    return state;
+  }
+
+  // Compute the next DFA state given a current state and a character
+  step(state, charCode, anchor) {
+    // OPTIMIZATION: ASCII Fast-Path
+    if (anchor === RE2Flags.UNANCHORED && charCode <= Unicode.MAX_ASCII) {
+      const next = state.nextAscii[charCode];
+      if (next !== null) {
+        return next;
+      }
+    } else {
+      const key = charCode + (anchor === RE2Flags.UNANCHORED ? 0 : Unicode.MAX_RUNE + 1);
+      if (state.nextMap.has(key)) {
+        return state.nextMap.get(key);
+      }
+    }
+    const nextPCs = [];
+    for (let i = 0; i < state.nfaStates.length; i++) {
+      const pc = state.nfaStates[i];
+      const inst = this.prog.getInst(pc);
+      if (Inst.isRuneOp(inst.op) && inst.matchRune(charCode)) {
+        nextPCs.push(inst.out);
+      }
+    }
+    if (anchor === RE2Flags.UNANCHORED) {
+      nextPCs.push(this.prog.start);
+    }
+    const nextState = this.getState(nextPCs);
+
+    // Cache the result
+    if (anchor === RE2Flags.UNANCHORED && charCode <= Unicode.MAX_ASCII) {
+      state.nextAscii[charCode] = nextState;
+    } else {
+      const key = charCode + (anchor === RE2Flags.UNANCHORED ? 0 : Unicode.MAX_RUNE + 1);
+      state.nextMap.set(key, nextState);
+    }
+    return nextState;
+  }
+
+  // The hot loop: Execute the Lazy DFA
+  match(input, pos, anchor) {
+    if ((anchor === RE2Flags.ANCHOR_START || anchor === RE2Flags.ANCHOR_BOTH) && pos !== 0) {
+      return false;
+    }
+    if (!this.startState) {
+      this.startState = this.getState([this.prog.start]);
+      if (!this.startState) return null; // Fallback to NFA
+    }
+    let endPos = input.endPos();
+    let currentState = this.startState;
+    if (currentState.isMatch) {
+      if (anchor === RE2Flags.ANCHOR_BOTH) {
+        if (pos === endPos) return true;
+      } else {
+        return true;
+      }
+    }
+    let i = pos;
+    while (i < endPos) {
+      const r = input.step(i);
+      const rune = r >> 3;
+      const width = r & 7;
+      currentState = this.step(currentState, rune, anchor);
+
+      // If we hit an unrecoverable DFA error or bailout, signal fallback
+      if (currentState === null) return null;
+      if (currentState.isMatch) {
+        if (anchor === RE2Flags.ANCHOR_BOTH) {
+          if (i + width === endPos) return true;
+        } else {
+          return true;
+        }
+      }
+
+      // If we hit a dead end, and anchored, fail early
+      if (currentState.nfaStates.length === 0) {
+        if (anchor !== RE2Flags.UNANCHORED) return false;
+      }
+      i += width;
+    }
+    return false;
+  }
+}
+
 /**
  * Regular expression abstract syntax tree. Produced by parser, used by compiler. NB, this
  * corresponds to {@code syntax.regexp} in the Go implementation; Go's {@code regexp} is called
@@ -5225,6 +5409,30 @@ class RE2 {
     this.prefixComplete = false; // true if prefix is the entire regexp
     this.prefixRune = 0; // first rune in prefix
     this.pooled = new AtomicReference(); // Cache of machines for running regexp. Forms a Treiber stack.
+    this.dfa = new DFA(prog); // Initialize the Lazy DFA
+  }
+  executeEngine(input, pos, anchor, ncap) {
+    // If the user wants capturing groups (ncap > 0), the DFA mathematically CANNOT do it.
+    // We must use the NFA.
+    if (ncap > 0) {
+      return this.doExecuteNFA(input, pos, anchor, ncap);
+    }
+    try {
+      const dfaResult = this.dfa.match(input, pos, anchor);
+      if (dfaResult !== null) {
+        // DFA succeeded (returned true or false)
+        return dfaResult ? [] : null; // Return empty array to signify "matched but no captures"
+      }
+    } catch (e) {
+      if (e instanceof RE2JSDfaMemoryException) {
+        this.dfa = new DFA(this.prog); // flush cache
+      } else {
+        throw e;
+      }
+    }
+
+    // Fallback to NFA
+    return this.doExecuteNFA(input, pos, anchor, ncap);
   }
 
   /**
@@ -5309,10 +5517,10 @@ class RE2 {
     return this.expr;
   }
 
-  // doExecute() finds the leftmost match in the input and returns
+  // doExecuteNFA() finds the leftmost match in the input and returns
   // the position of its subexpressions.
   // Derived from exec.go.
-  doExecute(input, pos, anchor, ncap) {
+  doExecuteNFA(input, pos, anchor, ncap) {
     let m = this.get();
     // The Treiber stack cannot reuse nodes, unless the node to be reused has only ever been at
     // the bottom of the stack (i.e., next == null).
@@ -5330,7 +5538,7 @@ class RE2 {
     return cap;
   }
   match(s) {
-    return this.doExecute(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, 0) !== null;
+    return this.executeEngine(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, 0) !== null;
   }
 
   /**
@@ -5358,7 +5566,7 @@ class RE2 {
       return [false, null];
     }
     const machineInput = input.isUTF16Encoding() ? MachineInput.fromUTF16(input.asCharSequence(), 0, end) : MachineInput.fromUTF8(input.asBytes(), 0, end);
-    const groupMatch = this.doExecute(machineInput, start, anchor, 2 * ngroup);
+    const groupMatch = this.executeEngine(machineInput, start, anchor, 2 * ngroup);
     if (groupMatch === null) {
       return [false, null];
     }
@@ -5370,7 +5578,7 @@ class RE2 {
    */
   // This is visible for testing.
   matchUTF8(b) {
-    return this.doExecute(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, 0) !== null;
+    return this.executeEngine(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, 0) !== null;
   }
 
   /**
@@ -5407,7 +5615,7 @@ class RE2 {
     const input = MachineInput.fromUTF16(src);
     let numReplaces = 0;
     while (searchPos <= src.length) {
-      const a = this.doExecute(input, searchPos, RE2Flags.UNANCHORED, 2);
+      const a = this.executeEngine(input, searchPos, RE2Flags.UNANCHORED, 2);
       if (a === null || a.length === 0) {
         break;
       }
@@ -5465,7 +5673,7 @@ class RE2 {
     let i = 0;
     let prevMatchEnd = -1;
     while (i < n && pos <= end) {
-      const matches = this.doExecute(input, pos, RE2Flags.UNANCHORED, this.prog.numCap);
+      const matches = this.executeEngine(input, pos, RE2Flags.UNANCHORED, this.prog.numCap);
       if (matches === null || matches.length === 0) {
         break;
       }
@@ -5536,7 +5744,7 @@ class RE2 {
    */
   // This is visible for testing.
   findUTF8(b) {
-    const a = this.doExecute(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, 2);
+    const a = this.executeEngine(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, 2);
     if (a === null) {
       return null;
     }
@@ -5551,7 +5759,7 @@ class RE2 {
    */
   // This is visible for testing.
   findUTF8Index(b) {
-    const a = this.doExecute(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, 2);
+    const a = this.executeEngine(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, 2);
     if (a === null) {
       return null;
     }
@@ -5568,7 +5776,7 @@ class RE2 {
    */
   // This is visible for testing.
   find(s) {
-    const a = this.doExecute(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, 2);
+    const a = this.executeEngine(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, 2);
     if (a === null) {
       return '';
     }
@@ -5584,7 +5792,7 @@ class RE2 {
    */
   // This is visible for testing.
   findIndex(s) {
-    return this.doExecute(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, 2);
+    return this.executeEngine(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, 2);
   }
 
   /**
@@ -5596,7 +5804,7 @@ class RE2 {
    */
   // This is visible for testing.
   findUTF8Submatch(b) {
-    const a = this.doExecute(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, this.prog.numCap);
+    const a = this.executeEngine(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, this.prog.numCap);
     if (a === null) {
       return null;
     }
@@ -5618,7 +5826,7 @@ class RE2 {
    */
   // This is visible for testing.
   findUTF8SubmatchIndex(b) {
-    return this.pad(this.doExecute(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, this.prog.numCap));
+    return this.pad(this.executeEngine(MachineInput.fromUTF8(b), 0, RE2Flags.UNANCHORED, this.prog.numCap));
   }
 
   /**
@@ -5630,7 +5838,7 @@ class RE2 {
    */
   // This is visible for testing.
   findSubmatch(s) {
-    const a = this.doExecute(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, this.prog.numCap);
+    const a = this.executeEngine(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, this.prog.numCap);
     if (a === null) {
       return null;
     }
@@ -5652,7 +5860,7 @@ class RE2 {
    */
   // This is visible for testing.
   findSubmatchIndex(s) {
-    return this.pad(this.doExecute(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, this.prog.numCap));
+    return this.pad(this.executeEngine(MachineInput.fromUTF16(s), 0, RE2Flags.UNANCHORED, this.prog.numCap));
   }
 
   /**
@@ -6200,7 +6408,7 @@ class RE2JS {
   /**
    * Return a map of the capturing groups in this matcher's pattern, where key is the name and value
    * is the index of the group in the pattern.
-   * @returns {*}
+   * @returns {Record<string, number>}
    */
   namedGroups() {
     return this.re2Input.namedGroups;
@@ -6222,8 +6430,10 @@ class RE2JS {
   }
 }
 
+exports.Matcher = Matcher;
 exports.RE2JS = RE2JS;
 exports.RE2JSCompileException = RE2JSCompileException;
+exports.RE2JSDfaMemoryException = RE2JSDfaMemoryException;
 exports.RE2JSException = RE2JSException;
 exports.RE2JSFlagsException = RE2JSFlagsException;
 exports.RE2JSGroupException = RE2JSGroupException;