re2js 2.8.4 → 2.8.5

package/README.md

@@ -228,6 +228,37 @@ matchString.group() // 'e'
 matchString.find(7) // false
 ```
 
+### Executing a Search (`exec`)
+
+If you want a native, 1:1 drop-in replacement for JavaScript's `RegExp.prototype.exec()`, you can use the `.exec()` method.
+
+Instead of dealing with a stateful `Matcher` object, `exec()` performs a single search and returns a standard `RegExpExecArray`-shaped result, or `null` if no match is found. It includes the `.index`, `.input`, and `.groups` properties, and accurately maps unmatched optional capture groups to `undefined` (just like native JavaScript).
+
+```js
+import { RE2JS } from 're2js'
+
+const re = RE2JS.compile('(?P<first>\\w+) (?:(?P<middle>\\w+) )?(?P<last>\\w+)');
+const result = re.exec('John Doe');
+
+if (result !== null) {
+  console.log(result[0]); // "John Doe" (Full match)
+  console.log(result[1]); // "John" (Group 1)
+  console.log(result[2]); // undefined (Group 2 didn't match)
+  console.log(result[3]); // "Doe" (Group 3)
+
+  console.log(result.index); // 0
+  console.log(result.input); // "John Doe"
+
+  // Named groups dictionary
+  console.log(result.groups.first);  // "John"
+  console.log(result.groups.middle); // undefined
+  console.log(result.groups.last);   // "Doe"
+}
+
+```
+
+***Performance Note:** If you are running `exec()` inside a `while` loop to manually extract multiple matches globally, it is highly recommended to use `.matchAll()` instead, as it is cleaner, strictly stateless, and avoids infinite loop pitfalls.*
+
 ### Iterating Over Matches (`matchAll`)
 
 For a more modern, JavaScript-native developer experience, RE2JS provides a `.matchAll()` method. This returns an ES6 `IterableIterator`, allowing you to safely and cleanly iterate over matches using `for...of` loops or the array spread operator `[...]`.

package/build/index.cjs

@@ -2,7 +2,7 @@
 * re2js
 * RE2JS is the JavaScript port of RE2, a regular expression engine that provides linear time matching
 *
-* @version v2.8.4
+* @version v2.8.5
 * @author Oleksii Vasyliev
 * @homepage https://github.com/le0pard/re2js#readme
 * @repository github:le0pard/re2js
@@ -1246,7 +1246,7 @@ var Matcher = class Matcher {
 	}
 	/**
 	* Resets the {@code Matcher} and changes the input.
-	* @param {MatcherInputBase} input
+	* @param {string|number[]|Uint8Array|MatcherInputBase} input
 	* @returns {Matcher} the {@code Matcher} itself, for chained method calls
 	*/
 	resetMatcherInput(input) {
@@ -6366,6 +6366,33 @@ var RE2JS = class RE2JS {
 		return this.re2Input.executeEngine(machineInput, 0, RE2Flags.ANCHOR_BOTH, 0) !== null;
 	}
 	/**
+	* Executes a search for a match in a specified string.
+	* Returns a result array, or null if no match is found.
+	* The returned array perfectly mirrors standard JavaScript `RegExpExecArray`,
+	* including `.index`, `.input`, and `.groups` properties.
+	*
+	* @param {string|number[]|Uint8Array} input the input string or byte array
+	* @returns {Array|null} the match array with index, input, and groups properties, or null
+	*/
+	exec(input) {
+		const m = this.matcher(input);
+		if (!m.find()) return null;
+		const result = [m.group(0)];
+		for (let i = 1; i <= m.groupCount(); i++) {
+			const val = m.group(i);
+			result.push(val === null ? void 0 : val);
+		}
+		result.index = m.start(0);
+		result.input = input;
+		const namedGroups = this.namedGroups();
+		if (Object.keys(namedGroups).length > 0) {
+			const parsedGroups = m.getNamedGroups();
+			for (const key in parsedGroups) if (parsedGroups[key] === null) parsedGroups[key] = void 0;
+			result.groups = parsedGroups;
+		} else result.groups = void 0;
+		return result;
+	}
+	/**
 	* Splits input around instances of the regular expression. It returns an array giving the strings
 	* that occur before, between, and after instances of the regular expression.
 	*
@@ -6417,7 +6444,7 @@ var RE2JS = class RE2JS {
 	* including capturing groups.
 	*
 	* @param {string|number[]|Uint8Array} input the input string or byte array
-	* @returns {IterableIterator<Array>}
+	* @returns {IterableIterator<RegExpMatchArray>}
 	*/
 	*matchAll(input) {
 		const m = this.matcher(input);

package/build/index.d.cts

@@ -221,10 +221,10 @@ export class Matcher {
 	anchorFlag: number;
 	/**
 	 * Resets the {@code Matcher} and changes the input.
-	 * @param {MatcherInputBase} input
+	 * @param {string|number[]|Uint8Array|MatcherInputBase} input
 	 * @returns {Matcher} the {@code Matcher} itself, for chained method calls
 	 */
-	resetMatcherInput(input: MatcherInputBase): Matcher;
+	resetMatcherInput(input: string | number[] | Uint8Array | MatcherInputBase): Matcher;
 	matcherInput: MatcherInputBase;
 	/**
 	 * Returns the start of the named group of the most recent match, or -1 if the group was not
@@ -873,6 +873,16 @@ export class RE2JS {
 	 * @returns {boolean} `true` if the exact input string fully matches the pattern, `false` otherwise.
 	 */
 	testExact(input: string | number[] | Uint8Array): boolean;
+	/**
+	 * Executes a search for a match in a specified string.
+	 * Returns a result array, or null if no match is found.
+	 * The returned array perfectly mirrors standard JavaScript `RegExpExecArray`,
+	 * including `.index`, `.input`, and `.groups` properties.
+	 *
+	 * @param {string|number[]|Uint8Array} input the input string or byte array
+	 * @returns {Array|null} the match array with index, input, and groups properties, or null
+	 */
+	exec(input: string | number[] | Uint8Array): any[] | null;
 	/**
 	 * Splits input around instances of the regular expression. It returns an array giving the strings
 	 * that occur before, between, and after instances of the regular expression.
@@ -892,9 +902,9 @@ export class RE2JS {
 	 * including capturing groups.
 	 *
 	 * @param {string|number[]|Uint8Array} input the input string or byte array
-	 * @returns {IterableIterator<Array>}
+	 * @returns {IterableIterator<RegExpMatchArray>}
 	 */
-	matchAll(input: string | number[] | Uint8Array): IterableIterator<any[]>;
+	matchAll(input: string | number[] | Uint8Array): IterableIterator<RegExpMatchArray>;
 	/**
 	 *
 	 * @returns {string}

package/build/index.d.ts

@@ -221,10 +221,10 @@ export class Matcher {
 	anchorFlag: number;
 	/**
 	 * Resets the {@code Matcher} and changes the input.
-	 * @param {MatcherInputBase} input
+	 * @param {string|number[]|Uint8Array|MatcherInputBase} input
 	 * @returns {Matcher} the {@code Matcher} itself, for chained method calls
 	 */
-	resetMatcherInput(input: MatcherInputBase): Matcher;
+	resetMatcherInput(input: string | number[] | Uint8Array | MatcherInputBase): Matcher;
 	matcherInput: MatcherInputBase;
 	/**
 	 * Returns the start of the named group of the most recent match, or -1 if the group was not
@@ -873,6 +873,16 @@ export class RE2JS {
 	 * @returns {boolean} `true` if the exact input string fully matches the pattern, `false` otherwise.
 	 */
 	testExact(input: string | number[] | Uint8Array): boolean;
+	/**
+	 * Executes a search for a match in a specified string.
+	 * Returns a result array, or null if no match is found.
+	 * The returned array perfectly mirrors standard JavaScript `RegExpExecArray`,
+	 * including `.index`, `.input`, and `.groups` properties.
+	 *
+	 * @param {string|number[]|Uint8Array} input the input string or byte array
+	 * @returns {Array|null} the match array with index, input, and groups properties, or null
+	 */
+	exec(input: string | number[] | Uint8Array): any[] | null;
 	/**
 	 * Splits input around instances of the regular expression. It returns an array giving the strings
 	 * that occur before, between, and after instances of the regular expression.
@@ -892,9 +902,9 @@ export class RE2JS {
 	 * including capturing groups.
 	 *
 	 * @param {string|number[]|Uint8Array} input the input string or byte array
-	 * @returns {IterableIterator<Array>}
+	 * @returns {IterableIterator<RegExpMatchArray>}
 	 */
-	matchAll(input: string | number[] | Uint8Array): IterableIterator<any[]>;
+	matchAll(input: string | number[] | Uint8Array): IterableIterator<RegExpMatchArray>;
 	/**
 	 *
 	 * @returns {string}

package/build/index.js

@@ -2,7 +2,7 @@
 * re2js
 * RE2JS is the JavaScript port of RE2, a regular expression engine that provides linear time matching
 *
-* @version v2.8.4
+* @version v2.8.5
 * @author Oleksii Vasyliev
 * @homepage https://github.com/le0pard/re2js#readme
 * @repository github:le0pard/re2js
@@ -1245,7 +1245,7 @@ var Matcher = class Matcher {
 	}
 	/**
 	* Resets the {@code Matcher} and changes the input.
-	* @param {MatcherInputBase} input
+	* @param {string|number[]|Uint8Array|MatcherInputBase} input
 	* @returns {Matcher} the {@code Matcher} itself, for chained method calls
 	*/
 	resetMatcherInput(input) {
@@ -6365,6 +6365,33 @@ var RE2JS = class RE2JS {
 		return this.re2Input.executeEngine(machineInput, 0, RE2Flags.ANCHOR_BOTH, 0) !== null;
 	}
 	/**
+	* Executes a search for a match in a specified string.
+	* Returns a result array, or null if no match is found.
+	* The returned array perfectly mirrors standard JavaScript `RegExpExecArray`,
+	* including `.index`, `.input`, and `.groups` properties.
+	*
+	* @param {string|number[]|Uint8Array} input the input string or byte array
+	* @returns {Array|null} the match array with index, input, and groups properties, or null
+	*/
+	exec(input) {
+		const m = this.matcher(input);
+		if (!m.find()) return null;
+		const result = [m.group(0)];
+		for (let i = 1; i <= m.groupCount(); i++) {
+			const val = m.group(i);
+			result.push(val === null ? void 0 : val);
+		}
+		result.index = m.start(0);
+		result.input = input;
+		const namedGroups = this.namedGroups();
+		if (Object.keys(namedGroups).length > 0) {
+			const parsedGroups = m.getNamedGroups();
+			for (const key in parsedGroups) if (parsedGroups[key] === null) parsedGroups[key] = void 0;
+			result.groups = parsedGroups;
+		} else result.groups = void 0;
+		return result;
+	}
+	/**
 	* Splits input around instances of the regular expression. It returns an array giving the strings
 	* that occur before, between, and after instances of the regular expression.
 	*
@@ -6416,7 +6443,7 @@ var RE2JS = class RE2JS {
 	* including capturing groups.
 	*
 	* @param {string|number[]|Uint8Array} input the input string or byte array
-	* @returns {IterableIterator<Array>}
+	* @returns {IterableIterator<RegExpMatchArray>}
 	*/
 	*matchAll(input) {
 		const m = this.matcher(input);

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.8.4
+* @version v2.8.5
 * @author Oleksii Vasyliev
 * @homepage https://github.com/le0pard/re2js#readme
 * @repository github:le0pard/re2js
@@ -1249,7 +1249,7 @@
 		}
 		/**
 		* Resets the {@code Matcher} and changes the input.
-		* @param {MatcherInputBase} input
+		* @param {string|number[]|Uint8Array|MatcherInputBase} input
 		* @returns {Matcher} the {@code Matcher} itself, for chained method calls
 		*/
 		resetMatcherInput(input) {
@@ -6369,6 +6369,33 @@
 			return this.re2Input.executeEngine(machineInput, 0, RE2Flags.ANCHOR_BOTH, 0) !== null;
 		}
 		/**
+		* Executes a search for a match in a specified string.
+		* Returns a result array, or null if no match is found.
+		* The returned array perfectly mirrors standard JavaScript `RegExpExecArray`,
+		* including `.index`, `.input`, and `.groups` properties.
+		*
+		* @param {string|number[]|Uint8Array} input the input string or byte array
+		* @returns {Array|null} the match array with index, input, and groups properties, or null
+		*/
+		exec(input) {
+			const m = this.matcher(input);
+			if (!m.find()) return null;
+			const result = [m.group(0)];
+			for (let i = 1; i <= m.groupCount(); i++) {
+				const val = m.group(i);
+				result.push(val === null ? void 0 : val);
+			}
+			result.index = m.start(0);
+			result.input = input;
+			const namedGroups = this.namedGroups();
+			if (Object.keys(namedGroups).length > 0) {
+				const parsedGroups = m.getNamedGroups();
+				for (const key in parsedGroups) if (parsedGroups[key] === null) parsedGroups[key] = void 0;
+				result.groups = parsedGroups;
+			} else result.groups = void 0;
+			return result;
+		}
+		/**
 		* Splits input around instances of the regular expression. It returns an array giving the strings
 		* that occur before, between, and after instances of the regular expression.
 		*
@@ -6420,7 +6447,7 @@
 		* including capturing groups.
 		*
 		* @param {string|number[]|Uint8Array} input the input string or byte array
-		* @returns {IterableIterator<Array>}
+		* @returns {IterableIterator<RegExpMatchArray>}
 		*/
 		*matchAll(input) {
 			const m = this.matcher(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "re2js",
-  "version": "2.8.4",
+  "version": "2.8.5",
   "description": "RE2JS is the JavaScript port of RE2, a regular expression engine that provides linear time matching",
   "type": "module",
   "sideEffects": false,