sindresorhus/super-regex

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

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.

The timeout only works in Node.js. In the browser, it will simply not time out.

Install

npm install super-regex

Usage

import {isMatch} from 'super-regex';

console.log(isMatch(/\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.

options

Type: object

timeout?

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

{
	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

super-regex's Issues

Not able to use it CommonJs Environment

Hi, My project is created in Common Js env. So it doesn't support to import statement, and super-regex doesn't support require statement to import it. so can you please change it to support commonJs env

Async methods

I think it could be useful with async methods too, when you not only want to prevent abuse, but also don't want the regex matching to block other work, which can be important in a server context.

We could do the matching on a worker thread and then send the result back to the main process. This should be possible on both Node.js and the browser.

This is not something I plan to work on, but a good pull request would be welcomed if you need this.

See https://github.com/sindresorhus/crypto-hash/blob/main/index.js for an example of how it could be done.

Idea for browser support

It might be possible to create and spawn a temporary web worker from a datauri, execute the regex within and then terminate it on timeout.

(Not really interested in implementing this, but it may be a nice exercise for someone 😉)

Make `matches()` return an iterator

String#matchAll returns an iterator, so the matching is lazy and you can stop it at any time.

The difficulty is ensuring it still times out. We may have to add something to function-timeout for this.

`firstMatch` and `matches` are too slow for large string

The execution time of firstMatch and matches seems too slow, compared to native str.match and str.matchAll. The larger the data provided, the longer the execution time.

I have tested both of them with a large string data (24151 characters), with 363 matches expected. To test firstMatch VS str.match, the data is splitted into 404 rows and then performs matching on each row. For matches VS str.matchAll, the global and multiline flags are added to the regex and then performs matching against the whole data.

Function	Execution Time (ms)
str.matchAll	0.547
matches	290.974
matches with timeout 500 ms	276.913
str.match	0.226
firstMatch	262.436
firstMatch with timeout 500 ms	354.058

The reproduction is available here:

Throw when regex is not global

super-regex/readme.md

Line 47 in 6902355

**The `regex` must have the `/g` flag.**

What if we threw an error as well? This way, we could reduce the amount of future support requests unknowing of this message.

Add `throw` option?

Some user may want to differentiate when a regex timed out and when it just didn't match. We could add a throw option (better name suggestion welcome!) that makes it throw a RegexTimeout error instead returning an empty value.