re2js 2.8.3 → 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.3
+* @version v2.8.5
 * @author Oleksii Vasyliev
 * @homepage https://github.com/le0pard/re2js#readme
 * @repository github:le0pard/re2js
@@ -57,7 +57,7 @@ for (let i = 0; i < ASCII_SIZE; i++) {
 	else ASCII_TO_LOWER[i] = i;
 }
 var Codepoint = class {
-	static CODES = new Map([
+	static CODES = /* @__PURE__ */ new Map([
 		["\x07", 7],
 		["\b", 8],
 		["	", 9],
@@ -168,7 +168,7 @@ var UnicodeRangeTable = class {
 };
 //#endregion
 //#region src/UnicodeTables.js
-const B64_MAP = new Uint8Array(256);
+const B64_MAP = /* @__PURE__ */ new Uint8Array(256);
 for (let i = 0, b = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+-"; i < 64; i++) B64_MAP[b.charCodeAt(i)] = i;
 const decodeVLQ = (str) => {
 	const res = [];
@@ -1246,11 +1246,13 @@ 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) {
 		if (input === null) throw new Error("input is null");
+		if (!(input instanceof MatcherInputBase)) if (Utils.isByteArray(input)) input = MatcherInput.utf8(input);
+		else input = MatcherInput.utf16(input);
 		this.matcherInput = input;
 		this.reset();
 		return this;
@@ -2426,14 +2428,14 @@ const MAX_BACKTRACK_VECTOR = 256 * 1024;
 var BitState = class {
 	constructor() {
 		this.end = 0;
-		this.cap = new Int32Array(0);
-		this.matchcap = new Int32Array(0);
+		this.cap = /* @__PURE__ */ new Int32Array(0);
+		this.matchcap = /* @__PURE__ */ new Int32Array(0);
 		this.ncap = 0;
 		this.jobPc = new Int32Array(INITIAL_JOB_CAPACITY);
 		this.jobArg = new Uint8Array(INITIAL_JOB_CAPACITY);
 		this.jobPos = new Int32Array(INITIAL_JOB_CAPACITY);
 		this.jobLen = 0;
-		this.visited = new Uint32Array(0);
+		this.visited = /* @__PURE__ */ new Uint32Array(0);
 	}
 	reset(prog, end, ncap) {
 		this.end = end;
@@ -3943,7 +3945,7 @@ const code3 = [
 	97,
 	122
 ];
-const PERL_GROUPS = new Map([
+const PERL_GROUPS = /* @__PURE__ */ new Map([
 	["\\d", new CharGroup(1, code1)],
 	["\\D", new CharGroup(-1, code1)],
 	["\\s", new CharGroup(1, code2)],
@@ -4017,7 +4019,7 @@ const code17 = [
 	97,
 	102
 ];
-const POSIX_GROUPS = new Map([
+const POSIX_GROUPS = /* @__PURE__ */ new Map([
 	["[:alnum:]", new CharGroup(1, code4)],
 	["[:^alnum:]", new CharGroup(-1, code4)],
 	["[:alpha:]", new CharGroup(1, code5)],
@@ -6364,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.
 	*
@@ -6415,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.3
+* @version v2.8.5
 * @author Oleksii Vasyliev
 * @homepage https://github.com/le0pard/re2js#readme
 * @repository github:le0pard/re2js
@@ -56,7 +56,7 @@ for (let i = 0; i < ASCII_SIZE; i++) {
 	else ASCII_TO_LOWER[i] = i;
 }
 var Codepoint = class {
-	static CODES = new Map([
+	static CODES = /* @__PURE__ */ new Map([
 		["\x07", 7],
 		["\b", 8],
 		["	", 9],
@@ -167,7 +167,7 @@ var UnicodeRangeTable = class {
 };
 //#endregion
 //#region src/UnicodeTables.js
-const B64_MAP = new Uint8Array(256);
+const B64_MAP = /* @__PURE__ */ new Uint8Array(256);
 for (let i = 0, b = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+-"; i < 64; i++) B64_MAP[b.charCodeAt(i)] = i;
 const decodeVLQ = (str) => {
 	const res = [];
@@ -1245,11 +1245,13 @@ 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) {
 		if (input === null) throw new Error("input is null");
+		if (!(input instanceof MatcherInputBase)) if (Utils.isByteArray(input)) input = MatcherInput.utf8(input);
+		else input = MatcherInput.utf16(input);
 		this.matcherInput = input;
 		this.reset();
 		return this;
@@ -2425,14 +2427,14 @@ const MAX_BACKTRACK_VECTOR = 256 * 1024;
 var BitState = class {
 	constructor() {
 		this.end = 0;
-		this.cap = new Int32Array(0);
-		this.matchcap = new Int32Array(0);
+		this.cap = /* @__PURE__ */ new Int32Array(0);
+		this.matchcap = /* @__PURE__ */ new Int32Array(0);
 		this.ncap = 0;
 		this.jobPc = new Int32Array(INITIAL_JOB_CAPACITY);
 		this.jobArg = new Uint8Array(INITIAL_JOB_CAPACITY);
 		this.jobPos = new Int32Array(INITIAL_JOB_CAPACITY);
 		this.jobLen = 0;
-		this.visited = new Uint32Array(0);
+		this.visited = /* @__PURE__ */ new Uint32Array(0);
 	}
 	reset(prog, end, ncap) {
 		this.end = end;
@@ -3942,7 +3944,7 @@ const code3 = [
 	97,
 	122
 ];
-const PERL_GROUPS = new Map([
+const PERL_GROUPS = /* @__PURE__ */ new Map([
 	["\\d", new CharGroup(1, code1)],
 	["\\D", new CharGroup(-1, code1)],
 	["\\s", new CharGroup(1, code2)],
@@ -4016,7 +4018,7 @@ const code17 = [
 	97,
 	102
 ];
-const POSIX_GROUPS = new Map([
+const POSIX_GROUPS = /* @__PURE__ */ new Map([
 	["[:alnum:]", new CharGroup(1, code4)],
 	["[:^alnum:]", new CharGroup(-1, code4)],
 	["[:alpha:]", new CharGroup(1, code5)],
@@ -6363,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.
 	*
@@ -6414,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.3
+* @version v2.8.5
 * @author Oleksii Vasyliev
 * @homepage https://github.com/le0pard/re2js#readme
 * @repository github:le0pard/re2js
@@ -60,7 +60,7 @@
 		else ASCII_TO_LOWER[i] = i;
 	}
 	var Codepoint = class {
-		static CODES = new Map([
+		static CODES = /* @__PURE__ */ new Map([
 			["\x07", 7],
 			["\b", 8],
 			["	", 9],
@@ -171,7 +171,7 @@
 	};
 	//#endregion
 	//#region src/UnicodeTables.js
-	const B64_MAP = new Uint8Array(256);
+	const B64_MAP = /* @__PURE__ */ new Uint8Array(256);
 	for (let i = 0, b = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+-"; i < 64; i++) B64_MAP[b.charCodeAt(i)] = i;
 	const decodeVLQ = (str) => {
 		const res = [];
@@ -1249,11 +1249,13 @@
 		}
 		/**
 		* 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) {
 			if (input === null) throw new Error("input is null");
+			if (!(input instanceof MatcherInputBase)) if (Utils.isByteArray(input)) input = MatcherInput.utf8(input);
+			else input = MatcherInput.utf16(input);
 			this.matcherInput = input;
 			this.reset();
 			return this;
@@ -2429,14 +2431,14 @@
 	var BitState = class {
 		constructor() {
 			this.end = 0;
-			this.cap = new Int32Array(0);
-			this.matchcap = new Int32Array(0);
+			this.cap = /* @__PURE__ */ new Int32Array(0);
+			this.matchcap = /* @__PURE__ */ new Int32Array(0);
 			this.ncap = 0;
 			this.jobPc = new Int32Array(INITIAL_JOB_CAPACITY);
 			this.jobArg = new Uint8Array(INITIAL_JOB_CAPACITY);
 			this.jobPos = new Int32Array(INITIAL_JOB_CAPACITY);
 			this.jobLen = 0;
-			this.visited = new Uint32Array(0);
+			this.visited = /* @__PURE__ */ new Uint32Array(0);
 		}
 		reset(prog, end, ncap) {
 			this.end = end;
@@ -3946,7 +3948,7 @@
 		97,
 		122
 	];
-	const PERL_GROUPS = new Map([
+	const PERL_GROUPS = /* @__PURE__ */ new Map([
 		["\\d", new CharGroup(1, code1)],
 		["\\D", new CharGroup(-1, code1)],
 		["\\s", new CharGroup(1, code2)],
@@ -4020,7 +4022,7 @@
 		97,
 		102
 	];
-	const POSIX_GROUPS = new Map([
+	const POSIX_GROUPS = /* @__PURE__ */ new Map([
 		["[:alnum:]", new CharGroup(1, code4)],
 		["[:^alnum:]", new CharGroup(-1, code4)],
 		["[:alpha:]", new CharGroup(1, code5)],
@@ -6367,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.
 		*
@@ -6418,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.3",
+  "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,
@@ -56,24 +56,24 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
-    "@unicode/unicode-17.0.0": "^1.6.16",
-    "@vitest/browser": "^4.1.6",
-    "@vitest/browser-playwright": "^4.1.6",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@unicode/unicode-17.0.0": "^1.6.17",
+    "@vitest/browser": "^4.1.9",
+    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/coverage-v8": "^4.1.9",
     "@yarnpkg/pnpify": "^4.1.6",
     "dts-bundle-generator": "^9.5.1",
     "eslint": "9.39.4",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-import-resolver-node": "^0.3.10",
+    "eslint-import-resolver-node": "^0.4.0",
     "eslint-plugin-import": "^2.32.0",
-    "globals": "^17.6.0",
+    "globals": "^17.7.0",
     "lodash": "^4.18.1",
-    "playwright": "^1.60.0",
-    "prettier": "^3.8.3",
-    "rolldown": "^1.0.1",
+    "playwright": "^1.61.1",
+    "prettier": "^3.8.4",
+    "rolldown": "^1.1.3",
     "typescript": "^6.0.3",
     "unicode-property-value-aliases": "^3.9.0",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.9"
   },
-  "packageManager": "yarn@4.14.1"
+  "packageManager": "yarn@4.17.0"
 }