# super-regex

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

Latest version **1.1.0** (published 2025-11-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install super-regex
pnpm add super-regex
yarn add super-regex
bun add super-regex
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2025-11-04 |
| First published | 2022-06-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 3 |
| Unpacked size | 18.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 221 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | regex, regexp, regular, expression, timeout, time, out, cancel, expire, abort, redos, security, script, execute, async, asynchronous, worker, non-blocking |

## Links

- npm: https://www.npmjs.com/package/super-regex
- Repository: https://github.com/sindresorhus/super-regex
- Homepage: https://github.com/sindresorhus/super-regex#readme
- Issues: https://github.com/sindresorhus/super-regex/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/super-regex

## Dependencies (3)

- [time-span](https://npm.io/package/time-span.md) ^5.1.0
- [function-timeout](https://npm.io/package/function-timeout.md) ^1.0.1
- [make-asynchronous](https://npm.io/package/make-asynchronous.md) ^1.0.1

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2025-11-04
- 1.0.0 — 2024-04-03
- 0.3.0 — 2023-11-12
- 0.2.0 — 2022-07-07
- 0.1.0 — 2022-06-03

## README

# super-regex

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

This can be used to prevent [ReDoS vulnerabilities](https://en.wikipedia.org/wiki/ReDoS) 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

```sh
npm install super-regex
```

## Usage

```js
import {isMatch} from 'super-regex';

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

```js
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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test), but differs in that the given `regex` is [never mutated, even when it has the `/g` flag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test#using_test_on_a_regex_with_the_global_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 `Match`es.

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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test), but differs in that the given `regex` is [never mutated, even when it has the `/g` flag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test#using_test_on_a_regex_with_the_global_flag).*

```js
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.

```js
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.**

```js
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

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

## Related

- [function-timeout](https://github.com/sindresorhus/function-timeout) - Make a synchronous function have a timeout

---
_Source: https://npm.io/package/super-regex · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._