regex

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]

The Regex+ library (package name: regex) provides a template tag named regex. This tag modernizes JavaScript regular expressions with always-on best practices and support for new features that make regexes more powerful and dramatically more readable. The regex tag returns native RegExp instances that run with native performance and can exceed the performance of regex literals you'd write yourself.

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.

Features added to native JavaScript regular expressions include insignificant whitespace and comments for readability, atomic groups and possessive quantifiers that can help you avoid ReDoS, subroutines and subroutine definition groups that enable grammatical patterns with powerful subpattern composition, and context-aware interpolation of regexes, escaped strings, and partial patterns.

Details:

- Lightweight (7 kB minzip)
- Available as a Babel plugin, which avoids any runtime dependencies or user runtime cost
- Supports all ES2025 regex features
- Type definitions included

📜 Contents

- Features
- Install and use
- Examples
- Context
- Extended regex syntax
- Atomic groups
- Possessive quantifiers
- Subroutines
- Subroutine definition groups
- Recursion
- Flags
- Implicit flags
- Flag v
- Flag x
- Flag n
- Interpolation
- RegExp instances
- Escaped strings
- Partial patterns
- Interpolation principles
- Interpolation contexts
- Options
- Returning a string
- Performance
- Compatibility
- FAQ

💎 Features

A modern regex baseline so you don't need to continually opt-in to best practices.

- Always-on flag v gives you the best level of Unicode support and strict errors.
- New flags:
- Always-on flag x allows you to freely add whitespace and comments to your regexes.
- Always-on flag n ("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 and possessive quantifiers can dramatically improve performance and prevent ReDoS.
- Subroutines and definition groups enable powerful composition, improving readability and maintainability.
- Recursive matching via an official plugin.
- Custom syntax plugins supported.

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.

🕹️ Install and use

``sh
npm install regex
`

`js
import {regex} from 'regex';

// Works with all string/regexp methods since it returns a native regexp
const str = 'abc';
regex\w.test(str); // → true
str.match(regex('g')\w); // → ['a', 'b', 'c']
`

🪧 Examples

`js
import {regex, pattern} from 'regex';

// Subroutines and a subroutine definition group
// Also shows insignificant whitespace for readability
const record = regex
^ Admitted: \g \n
Released: \g $

(?(DEFINE)
(? \g-\g-\g)
(? \d{4})
(? \d{2})
(? \d{2})
)
;

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

// Context-aware interpolation
// Also shows line comments and insignificant whitespace
const re = regex('m')
# RegExp: Only the inner regex is case insensitive (flag i), and the outer
# regex's flags (including implicit flag x) don't apply to it
${/^a.$/i}
|
# String: Regex special chars are escaped
# Note that quantifying an interpolated value repeats it as a complete unit
${'a|b'}+
|
# Pattern: This string is contextually sandboxed but not escaped
[${pattern('a-z')}]
;

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

❓ Context

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

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, subroutine definition groups, interpolation, and "named capture only" mode — even long and complex regexes can be beautiful, grammatical, and intuitive.

Regex+ adds all of these features and returns native RegExp instances. It always uses flag v (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 v, flag u is automatically used instead while applying v's escaping rules so your regexes are backward compatible.) It also supports atomic groups and possessive quantifiers to help you 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. Those days are over. Regex+ builds on the many regex features added in new JavaScript versions by adding the key remaining pieces (via its extended syntax and implicit flags) that are needed to stand alongside or surpass other major flavors.

The following syntax is added on top of the regex features your JavaScript environment supports natively. Extended syntax works by being transpiled into native syntax, often in complex ways that are impractical to write by hand.

$3

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:

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

> [!NOTE]
> Atomic groups are supported in many other regex flavors. There's a proposal to add them to JavaScript.

$3

Possessive quantifiers are created by adding + to a quantifier, and they're similar to greedy quantifiers except they don't allow backtracking. Although greedy quantifiers start out by matching as much as possible, if the remainder of the regex doesn't find a match, the regex engine will backtrack and try all permutations of how many times the quantifier should repeat. Possessive quantifiers prevent the regex engine from doing so.

> Possessive quantifiers are syntactic sugar for atomic groups when their contents are a single repeated item (which could be a token, character class, or group).

Like atomic groups, possessive quantifiers are mostly useful for performance and preventing ReDoS, but they can also be used to eliminate certain matches. For example, regexa++. matches one or more a followed by a character other than a. Unlike regexa+. , it won't match a sequence of only a characters like 'aaa'. The possessive ++ doesn't give back any of the as it matched, so there's nothing left for the following . to match.

Here's how possessive quantifier syntax compares to the greedy and lazy quantifiers that JavaScript supports natively:

| | Greedy | Lazy | Possessive |
| :- | :-: | :-: | :-: |
| Repeat | As many times as possible,
giving back as needed | As few times as possible,
expanding as needed | As many times as possible,
without giving back
| Zero or one | ? | ?? | ?+ |
| Zero or more | | ? | *+ |
| One or more | + | +? | ++ |
| N or more | {2,} | {2,}? | {2,}+ |
| Between N and M | {0,5} | {0,5}? | {0,5}+ |

> Fixed repetition quantifiers behave the same whether they're greedy {2}, lazy {2}?, or possessive {2}+.

> [!NOTE]
> Possessive quantifiers are supported in many other regex flavors. There's a proposal to add them to JavaScript.

$3

Subroutines are written as \g (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:

`js
// A backreference with \k
regex(?sens|respons)e\ and\ \kibility
// Matches:
// - 'sense and sensibility'
// - 'response and responsibility'

// A subroutine with \g
regex(?sens|respons)e\ and\ \gibility
// 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.

1. They can reference groups that themselves contain subroutines, chained to any depth.
2. Any capturing groups that are set during the subroutine call revert to their previous values afterwards.
3. 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:

`js
regex
(? (?.)\k)
\g
\k

`

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

> [!NOTE]
> Subroutines are based on the feature in PCRE and Perl. PCRE allows several syntax options including the \g used by Regex+, whereas Perl uses (?&name). Ruby also supports subroutines (and uses the \g syntax), but it has behavior differences related to capturing and backreferences that arguably make its subroutines less useful.

$3

The special group (?(DEFINE)…) can be used at the end of a regex to define subpatterns for use by reference only. When combined with subroutines, this enables writing regexes in a grammatical way that can significantly improve readability and maintainability.

> Named groups defined within subroutine definition groups don't appear on the groups object of matches.

Example:

`js
const re = regex
^ Admitted:\ (? \g) \n
Released:\ (? \g) $

(?(DEFINE)
(? \g-\g-\g)
(? \d{4})
(? \d{2})
(? \d{2})
)
;
const record = 'Admitted: 2024-01-01\nReleased: 2024-01-03';
const match = re.exec(record);
console.log(match.groups);
/* → {
admitted: '2024-01-01',
released: '2024-01-03'
} */
`

> [!NOTE]
> Subroutine definition groups are based on the feature in PCRE and Perl. However, Regex+ supports a stricter version since it limits their placement, quantity, and the top-level syntax that can be used within them.

$3

The official Regex+ plugin regex-recursion enables the syntax (?R) and \g to match recursive/balanced patterns up to a specified max depth (2–100).

🚩 Flags

Flags are added like this:

`js
regex('gm')^.+
`

RegExp instances interpolated into the pattern preserve their own flags locally (see Interpolating regexes).

$3

Flag v and emulated flags x and n are always on when using regex, giving your regexes a modern baseline syntax and avoiding the need to continually opt-in to their superior modes.

> For special situations such as when wrapping Regex+ within other tools, implicit flags can be disabled. See: Options.

$3

JavaScript's native flag v (see MDN) gives you the best level of Unicode support, strict errors, and all the latest regex features like multicharacter properties of strings and character class subtraction/intersection. It's always on when using regex, which helps avoid numerous Unicode-related bugs, and means there's only one way to parse a regex instead of four (so you only need to remember one set of regex syntax and behavior).

Flag v is applied to the full pattern after interpolation happens.

> In environments without native support for flag v, flag u is automatically used instead while applying v's escaping rules so your regexes are backward compatible.

$3

Emulated flag x makes whitespace insignificant and adds support for line comments starting with #, allowing you to freely format your regexes for readability. It's always implicitly on, though it doesn't extend into interpolated RegExp instances (to avoid changing their meaning).

Example:

`js
const re = regex
# Match a date in YYYY-MM-DD format
(? \d{4}) - # Year part
(? \d{2}) - # Month part
(? \d{2}) # Day part

# Escape whitespace and hashes to match them literally
\ # space char
\x20 # space char
\# # hash char
\s # any whitespace char

# Since embedded strings are always matched literally, you can also match
# whitespace by embedding it as a string
${' '}+

# Patterns are directly embedded, so they use free spacing
${pattern\d + | [a - z]}

# Interpolated regexes use their own flags, so they preserve their whitespace
${/^Fat cat$/m}
;
`

> [!NOTE]
> Flag x is based on the JavaScript proposal for it as well as support in many other regex flavors. The rules for whitespace within character classes are inconsistent across regex flavors, so Regex+ follows the JavaScript proposal and the flag xx option from Perl and PCRE.

$3

Emulated flag n gives you "named capture only" mode, which turns unnamed groups (…) into noncapturing groups. It's always implicitly on, though it doesn't extend into interpolated RegExp instances (to avoid changing their meaning).

Requiring the syntactically clumsy (?:…) where you could just use (…) hurts readability and encourages adding unneeded captures (which hurt efficiency and refactoring). Flag n fixes this, making your regexes more readable.

Example:

`js
// Doesn't capture
regex\b(ab|cd)\b
// Use standard (?…) to capture as name
`

> [!NOTE]
> Flag n is based on .NET, C++, Oniguruma, PCRE, Perl, and XRegExp. Most of these share the flag letter n, but the option is variously called explicit capture, no auto capture, don't capture group, or nosubs. In Regex+, flag n also prevents using numbered backreferences to named groups, which follows the behavior of C++ and the default handling of Oniguruma and Ruby. Referring to named groups by number is a footgun for multiple reasons including that named groups are numbered differently across regex flavors.

🧩 Interpolation

$3

The meaning of flags (or their absense) on interpolated regexes is preserved. For example, with flag i (ignoreCase):

`js
regexhello-${/world/i}
// Matches 'hello-WORLD' but not 'HELLO-WORLD'

regex('i')hello-${/world/}
// Matches 'HELLO-world' but not 'HELLO-WORLD'
`

This is also true for other flags that can change how an inner regex is matched: m (multiline) and s (dotAll).

> As with all interpolation in regex, embedded regexes are sandboxed and treated as complete units. For example, a following quantifier repeats the entire embedded regex rather than just its last token, and top-level alternation in the embedded regex will not break out to affect the meaning of the outer regex. Numbered backreferences within embedded regexes are adjusted to work within the overall pattern.

$3

The regex tag escapes any regex special characters in interpolated strings (and values coerced to strings). This escaping is done in a context-aware way that prevents changing the meaning or error status of characters outside the interpolated string.

> As with all interpolation in regex, escaped strings are sandboxed and treated as complete units. For example, a following quantifier repeats the entire escaped string rather than just its last character. And if interpolating into a character class, the escaped string is treated as a flag-v-mode nested union if it contains more than one character node.

As a result, the regex tag provides an easy and safe alternative to ES2025's RegExp.escape.

`js
// Instead of
RegExp.escape(str)
// You can say
regex${str}.source

// Instead of
new RegExp(^(?:${RegExp.escape(str)})+$)
// You can say
regex^${str}+$

// Instead of (note: flag u or v required to avoid bugs)
new RegExp([a-${RegExp.escape(str)}], 'u')
// You can say
regex[a-${str}]
// Note: Since it's interpolated at the end of a character range, it throws for
// safety if more than one char in str

// Instead of (note: set subtraction)
new RegExp([\\w--[${RegExp.escape(str)}]], 'v')
// You can say
regex[\w--${str}]
`

$3

As an alternative to interpolating RegExp instances, you might sometimes want to interpolate partial regex patterns as strings. Some example use cases:

- Adding a pattern inside a character class (not allowed for RegExp instances since their top-level syntax context doesn't match).
- When you don't want the pattern to specify its own, local flags.
- Embedding a pre-escaped string, or composing a dynamic number of escaped strings.
- Dynamically adding backreferences without their corresponding captures (which wouldn't be valid as a standalone RegExp).
- Sharing a subroutine definition group across regexes.

For all of these cases, you can import {pattern} from 'regex' and then interpolate pattern(str) to avoid escaping special characters in the string or creating an intermediary RegExp instance. You can also use pattern… as a tag, as shorthand for pattern(String.raw…).

Apart from edge cases, pattern just embeds the provided string or other value directly. But because it handles the edge cases, patterns can safely be interpolated anywhere in a regex without worrying about their meaning being changed by (or making unintended changes in meaning to) the surrounding expression.

> As with all interpolation in regex, patterns are sandboxed and treated as complete units. This is relevant e.g. if a pattern is followed by a quantifier, if it contains top-level alternation, or if it's bordered by a character class range, subtraction, or intersection operator.

If you want to understand the handling of interpolated patterns more deeply, let's look at some edge cases…

> Implementation note: pattern returns an object with a custom toString that simply returns String(value).

> Patterns are not intended as an intermediate regex type. You can think of pattern as a directive to the regex tag: treat this string as a partial pattern rather than a string to be matched literally.

$3

The above descriptions of interpolation might feel complex. But there are three simple rules that guide the behavior in all cases:

1. Interpolation never changes the meaning or error status of characters outside of the interpolation, and vice versa.
2. Interpolated values are always aware of the context of where they're embedded.
3. When relevant, interpolated values are always treated as complete units.

> Examples where rule #3 is relevant: With following quantifiers, if they contain top-level alternation or numbered backreferences, or if they're placed in a character class range or set operation.

$3

🔩 Options

Typically, the regex tag is used as follows:

`js
import {regex} from 'regex';

// Without flags
const re1 = regex…;

// With flags
const re2 = regex('gi')…;
`

However, several options are available that can be provided via an options object in place of the flags argument. These options aren't usually needed, and are primarily intended for use when Regex+ is extended or wrapped by other tools.

Following are the available options and their default values:

`js
regex({
flags: '',
subclass: false,
plugins: [],
unicodeSetsPlugin: ,
disable: {
x: false,
n: false,
v: false,
atomic: false,
subroutines: false,
},
force: {
v: false,
},
})…;
`

$3

Function rewrite returns an object with properties pattern and flags as strings, rather than returning a RegExp instance. This can be useful when you want to apply postprocessing to the output.

`js
import {rewrite} from 'regex';

rewrite('^ (ab | cd)', {flags: 'm'});
// → {pattern: '^(?:ab|cd)', flags: 'mv'}
`

rewrite shares all of regex's options (described above) except subclass. Providing the resulting pattern and flags to the RegExp constructor produces the same result as using the regex tag.

> Since rewrite isn't a template tag, it doesn't provide context-aware interpolation and doesn't automatically handle input as a raw string (you need to escape your backslashes).

⚡ Performance

The regex tag transpiles its input to native RegExp instances, so they operate with native performance. The use of regex can also be transpiled away via a Babel plugin, avoiding the tiny overhead of transpiling at runtime.

For regexes that rely on or have the potential to trigger heavy backtracking, you can dramatically improve beyond native performance via regex's atomic groups and possessive quantifiers.

🪶 Compatibility

Regex+ is supported starting with Node.js 14, 2020-era browsers (except Safari, supported as of v16.4 from 2023-03-27), and React Native 0.74.6/0.75.1.

🙋 FAQ

🏷️ About

Regex+ was created by Steven Levithan and contributors. Inspiration included PCRE, XRegExp, and regexp-make-js.

$3

$3

If you want to support this project, I'd love your help by contributing improvements, sharing it with others, or sponsoring ongoing development.

© 2024–present. MIT License.

[npm-version-src]: https://img.shields.io/npm/v/regex?color=78C372
[npm-version-href]: https://npmjs.com/package/regex
[npm-downloads-src]: https://img.shields.io/npm/dm/regex?color=78C372
[npm-downloads-href]: https://npmjs.com/package/regex
[bundle-src]: https://img.shields.io/bundlejs/size/regex?color=78C372&label=minzip
[bundle-href]: https://bundlejs.com/?q=regex&treeshake=[*]