Make matches() return an iterator (#3)

index.d.ts

@@ -8,6 +8,13 @@ export type Match = {
 	input: string;
 };
 
+export interface MatchesOptions extends Options {
+	/**
+	The time in milliseconds to wait before timing out when searching for each match.
+	*/
+	readonly matchTimeout?: number;
+}
+
 /**
 Returns a boolean for whether the given `regex` matches the given `string`.
 
@@ -39,7 +46,7 @@ console.log(firstMatch(/\d+/, getUserInput(), {timeout: 1000}));
 export function firstMatch(regex: RegExp, string: string, options?: Options): Match | undefined;
 
 /**
-Returns an array of matches.
+Returns an iterable of matches.
 
 If the regex takes longer to match than the given timeout, it returns an empty array.
 
@@ -49,9 +56,9 @@ __The `regex` must have the `/g` flag.__
 ```
 import {matches} from 'super-regex';
 
-console.log(matches(/\d+/, getUserInput(), {timeout: 1000}));
+console.log([...matches(/\d+/, getUserInput(), {timeout: 1000})]);
 ```
 */
-export function matches(regex: RegExp, string: string, options?: Options): Match[];
+export function matches(regex: RegExp, string: string, options?: MatchesOptions): Iterable<Match>;
 
 export {Options} from 'function-timeout';

index.js

@@ -1,4 +1,5 @@
 import functionTimeout, {isTimeoutError} from 'function-timeout';
+import timeSpan from 'time-span';
 import cloneRegexp from 'clone-regexp'; // TODO: Use `structuredClone` instead when targeting Node.js 18.
 
 const resultToMatch = result => ({
@@ -39,15 +40,30 @@ export function firstMatch(regex, string, {timeout} = {}) {
 	}
 }
 
-export function matches(regex, string, {timeout} = {}) {
-	try {
-		return functionTimeout(() => [...string.matchAll(regex)], {timeout})()
-			.map(result => resultToMatch(result));
-	} catch (error) {
-		if (isTimeoutError(error)) {
-			return [];
-		}
+export function matches(regex, string, {timeout = Number.POSITIVE_INFINITY, matchTimeout = Number.POSITIVE_INFINITY} = {}) {
+	return {
+		* [Symbol.iterator]() {
+			try {
+				const matches = string.matchAll(regex); // The regex is only executed when iterated over.
 
-		throw error;
-	}
+				while (true) {
+					const nextMatch = functionTimeout(() => matches.next(), {timeout: (timeout !== Number.POSITIVE_INFINITY || matchTimeout !== Number.POSITIVE_INFINITY) ? Math.min(timeout, matchTimeout) : undefined}); // `matches.next` must be called within an arrow function so that it doesn't loose its context.
+
+					const end = timeSpan();
+					const {value, done} = nextMatch();
+					timeout -= Math.ceil(end());
+
+					if (done) {
+						break;
+					}
+
+					yield resultToMatch(value);
+				}
+			} catch (error) {
+				if (!isTimeoutError(error)) {
+					throw error;
+				}
+			}
+		},
+	};
 }

index.test-d.ts

@@ -3,4 +3,4 @@ import {isMatch, firstMatch, matches, Match} from './index.js';
 
 expectType<boolean>(isMatch(/\d/, '1', {timeout: 1000}));
 expectType<Match | undefined>(firstMatch(/\d/, '1', {timeout: 1000}));
-expectType<Match[]>(matches(/\d/, '1', {timeout: 1000}));
+expectType<Iterable<Match>>(matches(/\d/, '1', {timeout: 1000, matchTimeout: 1000}));

package.json

@@ -41,7 +41,8 @@
 	],
 	"dependencies": {
 		"clone-regexp": "^3.0.0",
-		"function-timeout": "^0.1.0"
+		"function-timeout": "^0.1.0",
+		"time-span": "^5.1.0"
 	},
 	"devDependencies": {
 		"ava": "^4.3.0",

readme.md

@@ -40,7 +40,7 @@ If the regex takes longer to match than the given timeout, it returns `undefined
 
 ### matches(regex, string, options?)
 
-Returns an array of `Match`'es.
+Returns an iterable of `Match`'es.
 
 If the regex takes longer to match than the given timeout, it returns an empty array.
 
@@ -56,6 +56,14 @@ Type: `number` *(integer)*
 
 The time in milliseconds to wait before timing out.
 
+##### matchTimeout?
+
+Type: `number` *(integer)*
+
+Only works in `matches()`.
+
+The time in milliseconds to wait before timing out when searching for each match.
+
 ### Match
 
 ```ts

test.js

@@ -19,8 +19,9 @@ test('firstMatch', t => {
 });
 
 test('matches', t => {
-	t.deepEqual(matches(fixtureRegex(), fixtureString, {timeout: 10}), []);
-	t.is(matches(fixtureRegex(), 'v1.1.3', {timeout: 10})[0].match, '1.1.3');
-	t.is(matches(/^v\d+/g, fixtureString, {timeout: 1000})[0].match, 'v1');
-	t.is(matches(/^v\d+/g, fixtureString)[0].match, 'v1');
+	t.deepEqual([...matches(fixtureRegex(), fixtureString, {timeout: 10})], []);
+	t.is([...matches(fixtureRegex(), 'v1.1.3', {timeout: 10})][0].match, '1.1.3');
+	t.is([...matches(/^v\d+/g, fixtureString, {timeout: 1000})][0].match, 'v1');
+	t.is([...matches(/^v\d+/g, fixtureString, {timeout: 1000, matchTimeout: 1000})][0].match, 'v1');
+	t.is([...matches(/^v\d+/g, fixtureString)][0].match, 'v1');
 });