super-regex

Make a regular expression time out if it takes too long to execute

This can be used to prevent ReDoS vulnerabilities when running a regular expression against untrusted user input.

This package also has a better API than the built-in regular expression methods. For example, none of the methods mutate the regex.

Synchronous methods (isMatch, firstMatch, matches) use a timeout mechanism that only works in Node.js. In the browser, they will not time out.

Asynchronous methods (isMatchAsync, firstMatchAsync, matchesAsync) run the regex in a worker thread and support timeout in both Node.js and browsers. They are especially useful for preventing ReDoS attacks in browser environments and for non-blocking execution in servers.

Install

npm install super-regex

Usage

import {isMatch} from 'super-regex';

console.log(isMatch(/\d+/, getUserInput(), {timeout: 1000}));

import {isMatchAsync} from 'super-regex';

console.log(await isMatchAsync(/\d+/, getUserInput(), {timeout: 1000}));

API

isMatch(regex, string, options?)

Returns a boolean for whether the given regex matches the given string.

If the regex takes longer to match than the given timeout, it returns false.

This method is similar to RegExp#test, but differs in that the given regex is never mutated, even when it has the /g flag.

firstMatch(regex, string, options?)

Returns the first Match or undefined if there was no match.

If the regex takes longer to match than the given timeout, it returns undefined.

matches(regex, string, options?)

Returns an iterable of Matches.

If the regex takes longer to match than the given timeout, it returns an empty array.

The regex must have the /g flag.

isMatchAsync(regex, string, options?)

Returns a promise that resolves to a boolean for whether the given regex matches the given string.

If the regex takes longer to match than the given timeout, it returns false.

This method runs the regex in a worker thread, which allows it to time out in both Node.js and browsers. This is especially useful for preventing ReDoS attacks in browser environments.

This method is similar to RegExp#test, but differs in that the given regex is never mutated, even when it has the /g flag.

import {isMatchAsync} from 'super-regex';

console.log(await isMatchAsync(/\d+/, getUserInput(), {timeout: 1000}));

firstMatchAsync(regex, string, options?)

Returns a promise that resolves to the first match or undefined if there was no match.

If the regex takes longer to match than the given timeout, it returns undefined.

This method runs the regex in a worker thread, which allows it to time out in both Node.js and browsers. This is especially useful for preventing ReDoS attacks in browser environments.

import {firstMatchAsync} from 'super-regex';

console.log(await firstMatchAsync(/\d+/, getUserInput(), {timeout: 1000}));

matchesAsync(regex, string, options?)

Returns an async iterable of matches.

If the regex takes longer to match than the given timeout, it returns an empty iterable.

This method runs the regex in a worker thread, which allows it to time out in both Node.js and browsers. This is especially useful for preventing ReDoS attacks in browser environments.

The regex must have the /g flag.

import {matchesAsync} from 'super-regex';

for await (const match of matchesAsync(/\d+/g, getUserInput(), {timeout: 1000})) {
	console.log(match);
}

options

Type: object

timeout?

Type: number (integer)

The time in milliseconds to wait before timing out.

throwOnTimeout?

Type: boolean
Default: false

Throw a timeout error instead of returning a default value when the timeout is reached.

This lets you distinguish between “no match” and “timeout”.

By default, when a timeout occurs:

• isMatch() returns false
• firstMatch() returns undefined
• matches() returns an empty array
• isMatchAsync() returns false
• firstMatchAsync() returns undefined
• matchesAsync() returns an empty iterable

matchTimeout?

Type: number (integer)

Only works in matches().

The time in milliseconds to wait before timing out when searching for each match.

Match

{
	match: string;
	index: number;
	groups: string[];
	namedGroups: {string: string}; // object with string values
	input: string;
}

Related

• function-timeout - Make a synchronous function have a timeout