regex

</div>

regex is a template tag that extends JavaScript regular expressions with features from other leading regex libraries that make regexes more powerful and dramatically more readable. It returns native RegExp instances that run with native performance, and can exceed the performance of regex literals you'd write yourself. It's also lightweight, has no dependencies, supports all ES2025 regex features, has built-in TypeScript declarations, and can be used as a Babel plugin to avoid any runtime dependencies or user runtime cost.

Highlights include support for free spacing and comments, atomic groups via (?>…) that can help you avoid ReDoS, subroutines via \g<name> and subroutine definition groups via (?(DEFINE)…) that enable powerful subpattern composition, and context-aware interpolation of regexes, escaped strings, and partial patterns.

With the regex library, JavaScript steps up as one of the best regex flavors alongside PCRE and Perl, possibly surpassing C++, Java, .NET, Python, and Ruby.

<details> <summary>Table of contents</summary>

Features
Examples
Install and use
Context
Extended regex syntax
Flags
Interpolation
Options
Performance
Compatibility
FAQ

</details>

💎 Features

A modern regex baseline so you don't need to continually opt-in to best practices.
- Always-on flag <kbd>v</kbd> gives you the best level of Unicode support and strict errors.
- New flags:
 - Always-on flag <kbd>x</kbd> allows you to freely add whitespace and comments to your regexes.
 - Always-on flag <kbd>n</kbd> (named capture only mode) improves regex readability and efficiency.
- No unreadable escaped backslashes \\\\ since it's a raw string template tag.
Extended regex syntax.
- Atomic groups via (?>…) can dramatically improve performance and prevent ReDoS.
- Subroutines via \g<name> enable powerful composition, improving readability and maintainability.
- Subroutine definition groups via (?(DEFINE)…) allow groups within them to be used by reference only.
- Recursive matching is enabled by a plugin.
Context-aware and safe interpolation of regexes, strings, and partial patterns.
- Interpolated strings have their special characters escaped.
- Interpolated regexes locally preserve the meaning of their own flags (or their absense), and their numbered backreferences are adjusted to work within the overall pattern.

🪧 Examples

import {regex, pattern} from 'regex';

// Subroutines and subroutine definition group
const record = regex`
  ^ Admitted:\ (?<admitted> \g<date>) \n
    Released:\ (?<released> \g<date>) $

  (?(DEFINE)
    (?<date>  \g<year>-\g<month>-\g<day>)
    (?<year>  \d{4})
    (?<month> \d{2})
    (?<day>   \d{2})
  )
`;

// Atomic group: Avoids ReDoS from the nested, overlapping quantifier
const words = regex`^(?>\w+\s?)+$`;

// Context-aware and safe interpolation
const re = regex('m')`
  # Only the inner regex is case insensitive (flag i)
  # Also, the outer regex's flag m is not applied to it
  ${/^a.b$/i}
  |
  # Strings are contextually escaped and repeated as complete units
  ^ ${'a.b'}+ $
  |
  # This string is contextually sandboxed but not escaped
  ${pattern('^ a.b $')}
`;

// Numbered backreferences in interpolated regexes are adjusted
const double = /(.)\1/;
regex`^ (?<first>.) ${double} ${double} $`;
// → /^(?<first>.)(.)\2(.)\3$/v

🕹️ Install and use

npm install regex

import {regex, pattern} from 'regex';

In browsers:

<script type="module">
  import {regex, pattern} from 'https://cdn.jsdelivr.net/npm/regex@4.0.0/+esm';
  // …
</script>

<details> <summary>Using a global name (no import)</summary>

<script src="https://cdn.jsdelivr.net/npm/regex@4.0.0/dist/regex.min.js"></script>
<script>
  const {regex, pattern} = Regex;
</script>

</details>

❓ Context

Due to years of legacy and backward compatibility, regular expression syntax in JavaScript is a bit of a mess. There are four different sets of incompatible syntax and behavior rules that might apply to your regexes depending on the flags and features you use. The differences are just plain hard to fully grok and can easily create subtle bugs.

<details> <summary>See the four parsing modes</summary>

Unicode-unaware (legacy) mode is the default and can easily and silently create Unicode-related bugs.
Named capture mode changes the meaning of \k when a named capture appears anywhere in a regex.
Unicode mode with flag <kbd>u</kbd> adds strict errors (for unreserved letter escapes, octal escapes, escaped literal digits, and unescaped special characters in some contexts), switches to code-point-based matching (changing the potential handling of the dot, negated sets like \W, character class ranges, and quantifiers), changes flag <kbd>i</kbd> to apply Unicode case-folding, and adds support for new syntax.
UnicodeSets mode with flag <kbd>v</kbd> (an upgrade to <kbd>u</kbd>) incompatibly changes escaping rules within character classes, fixes case-insensitive matching for \p and \P within negated [^…], and adds support for new features/syntax.

</details>

Additionally, JavaScript regex syntax is hard to write and even harder to read and refactor. But it doesn't have to be that way! With a few key features — raw multiline strings, insignificant whitespace, comments, subroutines, definition groups, interpolation, and named capture only mode — even long and complex regexes can be beautiful, grammatical, and easy to understand.

regex adds all of these features and returns native RegExp instances. It always uses flag <kbd>v</kbd> (already a best practice for new regexes) so you never forget to turn it on and don't have to worry about the differences in other parsing modes (in environments without native <kbd>v</kbd>, flag <kbd>u</kbd> is automatically used instead while applying <kbd>v</kbd>'s escaping rules so your regexes are forward and backward compatible). It also supports atomic groups via (?>…) to help you improve the performance of your regexes and avoid catastrophic backtracking. And it gives you best-in-class, context-aware interpolation of RegExp instances, escaped strings, and partial patterns.

🦾 Extended regex syntax

Historically, JavaScript regexes were not as powerful or readable as other major regex flavors like Java, .NET, PCRE, Perl, Python, and Ruby. With recent advancements and the regex library, those days are over. Modern JavaScript regexes have significantly improved (adding lookbehind, named capture, Unicode properties, character class subtraction and intersection, etc.). The regex library, with its extended syntax and implicit flags, adds the key remaining pieces needed to stand alongside or surpass other major flavors.

Atomic groups

Atomic groups are noncapturing groups with special behavior, and are written as (?>…). After matching the contents of an atomic group, the regex engine automatically throws away all backtracking positions remembered by any tokens within the group. Atomic groups are most commonly used to improve performance, and are a much needed feature that regex brings to native JavaScript regular expressions.

Example:

regex`^(?>\w+\s?)+$`

This matches strings that contain word characters separated by spaces, with the final space being optional. Thanks to the atomic group, it instantly fails to find a match if given a long list of words that end with something not allowed, like 'A target string that takes a long time or can even hang your browser!'.

Try running this without the atomic group (as /^(?:\w+\s?)+$/) and, due to the exponential backtracking triggered by the many ways to divide the work of the inner and outer + quantifiers, it will either take a very long time, hang your browser/server, or throw an internal error after a delay. This is called catastrophic backtracking or ReDoS, and it has taken down major services like Cloudflare and Stack Overflow. regex and atomic groups to the rescue!

<details> <summary>👉 Learn more with examples</summary>

Consider regex`(?>a+)ab` vs regex`(a+)ab`. The former (with an atomic group) doesn't match 'aaaab', but the latter does. The former doesn't match because:

The regex engine starts by using the greedy a+ within the atomic group to match all the as in the target string.
Then, when it tries to match the additional a outside the group, it fails (the next character in the target string is a b), so the regex engine backtracks.
But because it can't backtrack into the atomic group to make the + give up its last matched a, there are no additional options to try and the overall match attempt fails.

For a more useful example, consider how this can affect lazy (non-greedy) quantifiers. Let's say you want to match … tags that are followed by !. You might try this:

const re = regex('gis')`<b>.*?</b>!`;

// This is OK
'<b>Hi</b>! <b>Bye</b>.'.match(re);
// → ['<b>Hi</b>!']

// But not this
'<b>Hi</b>. <b>Bye</b>!'.match(re);
// → ['<b>Hi</b>. <b>Bye</b>!'] 👎

What happened with the second string was that, when an ! wasn't found immediately following the first , the regex engine backtracked and expanded the lazy .*? to match an additional character (in this case, the < of the  tag) and then continued onward, all the way to just before the ! at the end.

You can prevent this by wrapping the lazily quantified token and its following delimiter in an atomic group, as follows:

const re = regex('gis')`<b>(?>.*?</b>)!`;

'<b>Hi</b>. <b>Bye</b>!'.match(re);
// → ['<b>Bye</b>!'] 👍

Now, after the regex engine finds the first  and exits the atomic group, it can no longer backtrack into the group and change what the .*? already matched. As a result, the match attempt fails at the beginning of this example string. The regex engine then moves on and starts over at subsequent positions in the string, eventually finding Bye!. Success.

</details>

[!NOTE] Atomic groups are based on the JavaScript proposal for them as well as support in many other regex flavors.

Subroutines

Subroutines are written as \g<name> (where name refers to a named group), and they treat the referenced group as an independent subpattern that they try to match at the current position. This enables subpattern composition and reuse, which improves readability and maintainability.

The following example illustrates how subroutines and backreferences differ:

// A backreference with \k<name>
regex`(?<prefix>sens|respons)e\ and\ \k<prefix>ibility`
/* Matches:
- 'sense and sensibility'
- 'response and responsibility' */

// A subroutine with \g<name>
regex`(?<prefix>sens|respons)e\ and\ \g<prefix>ibility`
/* Matches:
- 'sense and sensibility'
- 'sense and responsibility'
- 'response and sensibility'
- 'response and responsibility' */

Subroutines go beyond the composition benefits of interpolation. Apart from the obvious difference that they don't require variables to be defined outside of the regex, they also don't simply insert the referenced subpattern.

They can reference groups that themselves contain subroutines, chained to any depth.
Any capturing groups that are set during the subroutine call revert to their previous values afterwards.
They don't create named captures that are visible outside of the subroutine, so using subroutines doesn't lead to "duplicate capture group name" errors.

To illustrate points 2 and 3, consider:

regex`
  (?<double> (?<char>.)\k<char>)
  \g<double>
  \k<double>
`

The backreference \k<double> matches whatever was matched by capturing group (?<double>…), regardless of what was matched in between by the subroutine \g<double>. For example, this regex matches 'xx!!xx', but not 'xx!!!!'.

<details> <summary>👉 Show more details</summary>

Subroutines can appear before the groups they reference.
If there are duplicate capture names, subroutines refer to the first instance of the given group (matching the behavior of PCRE and Perl).
Although subroutines can be chained to any depth, a descriptive error is thrown if they're used recursively. Support for recursion can be added via a plugin (see Recursion).
Like backreferences, subroutines can't be used within character classes.
As with all extended syntax in regex, subroutines are applied after interpolation, giving them maximal flexibility.

</details> <details> <summary>👉 Show how to define subpatterns for use by reference only</summary>

The following regex matches an IPv4 address such as "192.168.12.123":

const ipv4 = regex`
  \b \g<byte> (\.\g<byte>){3} \b

  # Define the 'byte' subpattern
  (?<byte> 2[0-4]\d | 25[0-5] | 1\d\d | [1-9]?\d ){0}
`;

Above, the {0} quantifier at the end of the (?<byte>…) group allows defining the group without matching it at that position. The subpattern within it can then be used by reference elsewhere within the pattern.

This next regex matches a record with multiple date fields, and captures each value:

const record = regex`
  ^ Admitted:\ (?<admitted> \g<date>) \n
    Released:\ (?<released> \g<date>) $

  # Define subpatterns
  ( (?<date>  \g<year>-\g<month>-\g<day>)
    (?<year>  \d{4})
    (?<month> \d{2})
    (?<day>   \d{2})
  ){0}
`;

Here, the {0} quantifier at the end once again prevents matching its group at that position, while enabling all of the named groups within it to be used by