Oniguruma (鬼車) to ES

“I think \[Oniguruma-To-ES] is very wonderful”

— K. Kosako, creator of Oniguruma

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

Oniguruma is a regular expression engine written in C that's used in Ruby (via a fork named Onigmo), PHP (mb_ereg, etc.), TextMate grammars (used by VS Code, Shiki, etc. for syntax highlighting), and many other tools.

Oniguruma-To-ES is an advanced Oniguruma to JavaScript regex translator that runs in the browser or the server, with support for ~99.99% of Oniguruma regexes (more details below). Use it to:

- Take advantage of Oniguruma's many extended regex features in JavaScript.
- Run regexes written for Oniguruma from JavaScript.
- Share regexes across your Ruby or PHP and JavaScript code.

Compared to running the Oniguruma C library via WASM using vscode-oniguruma, this library is ~4% of the size and its regexes often run much faster (even including transpilation time) since they run as native JavaScript.

> [!TIP]
> You can further reduce bundle size (and increase run-time performance) by precompiling your regexes. In many cases, that avoids the need for any run-time dependency. Conversions for regexes that use certain advanced features rely on a RegExp subclass, in which case the tree-shakable EmulatedRegExp (3 kB minzip) is still needed after precompilation.

Oniguruma-To-ES deeply understands the hundreds of large and small differences between Oniguruma and JavaScript regex syntax and behavior, across multiple JavaScript version targets. It's obsessive about ensuring that the emulated features it supports have exactly the same behavior, even in extreme edge cases. And it's been battle-tested on tens of thousands of real-world Oniguruma regexes used in TextMate grammars. It's built on top of oniguruma-parser and Regex+, both by the same author as this library.

🧪 Try the demo REPL

📜 Contents

- Examples
- Install and use
- API: toRegExp, toRegExpDetails, EmulatedRegExp
- Options: accuracy, avoidSubclass, flags, global, hasIndices, lazyCompileLength, rules, target, verbose
- Supported features
- Unsupported features
- Unicode

🪧 Examples

``js
import {toRegExp} from 'oniguruma-to-es';

toRegExp(String.raw(?x)
(?\d) (?\p{greek}) \k
([0a-z&&\h]){,2}
);
// → /(?\p{Nd})(\p{sc=Greek})(?>\2|\1)(?:[[0a-z]&&\p{AHex}]){0,2}/v
`

Although the example above is fairly straightforward, it shows several kinds of differences being translated:

- New flags: JavaScript regexes don't support flag x for insignificant whitespace and comments.
- New syntax: JavaScript doesn't include standalone flag modifiers like (?x) or the \h hex-digit shorthand. Note: ES2025 added support for flag groups like (?i:…).
- Different syntax rules: JavaScript doesn't allow duplicate group names in the same alternation path, requires a prefix and specific casing for Unicode scripts like Greek, requires nested character classes for intersection of union and ranges, and doesn't allow an implicit 0 min for {…} quantifiers.
- Different behavior: Oniguruma's \d is Unicode based by default, backreferences to duplicate group names match the captured value of any of the groups, and (…) groups are noncapturing by default if named groups are present.

Many advanced features are supported that would produce more complicated transformations.

> [!NOTE]
> The (?>…) atomic group shown in the result was a simplification for readability. Since JavaScript doesn't support atomic groups, the actual result uses (?=(\2|\1))\3 for the same effect, and then uses a RegExp subclass to automatically remove the added capturing group from reported matches.

This next example shows support for Unicode case folding with mixed case-sensitivity. Notice that code points ſ (U+017F) and K (U+212A) are added to the second, case-insensitive range if using a target prior to ES2025, and that modern JavaScript regex features (like flag groups) are used if supported by the target.

`js
toRegExp('a-z[a-z]', {target: 'ES2018'});
// → /[a-z][a-zA-ZſK]/u
toRegExp('a-z[a-z]', {target: 'ES2025'});
// → /a-z/v
`

🕹️ Install and use

`sh
npm install oniguruma-to-es
`

`js
import {toRegExp} from 'oniguruma-to-es';

const str = '…';
const pattern = '…';
// Works with all string/regexp methods since it returns a native regexp
str.match(toRegExp(pattern));
`

🔑 API

$3

Accepts an Oniguruma pattern and returns an equivalent JavaScript RegExp.

> [!TIP]
> Try it in the demo REPL.

`ts
function toRegExp(
pattern: string,
options?: ToRegExpOptions
): RegExp | EmulatedRegExp;
`

#### Type ToRegExpOptions

`ts
type ToRegExpOptions = {
accuracy?: 'default' | 'strict';
avoidSubclass?: boolean;
flags?: string;
global?: boolean;
hasIndices?: boolean;
lazyCompileLength?: number;
rules?: {
allowOrphanBackrefs?: boolean;
asciiWordBoundaries?: boolean;
captureGroup?: boolean;
recursionLimit?: number;
singleline?: boolean;
};
target?: 'auto' | 'ES2025' | 'ES2024' | 'ES2018';
verbose?: boolean;
};
`

See Options for more details.

$3

Accepts an Oniguruma pattern and returns the details needed to construct an equivalent JavaScript RegExp.

`ts
function toRegExpDetails(
pattern: string,
options?: ToRegExpOptions
): {
pattern: string;
flags: string;
options?: EmulatedRegExpOptions;
};
`

Note that the returned flags might also be different than those provided, as a result of the emulation process. The returned pattern, flags, and options properties can be provided as arguments to the EmulatedRegExp constructor to produce the same result as toRegExp.

If the only keys returned are pattern and flags, they can optionally be provided to JavaScript's RegExp constructor instead. Setting option avoidSubclass to true ensures that this is always the case (resulting in an error for any patterns that require EmulatedRegExp's additional handling).

$3

Works the same as JavaScript's native RegExp constructor in all contexts, but can be given results from toRegExpDetails to produce the same result as toRegExp.

`ts
class EmulatedRegExp extends RegExp {
constructor(pattern: string, flags?: string, options?: EmulatedRegExpOptions);
constructor(pattern: EmulatedRegExp, flags?: string);
rawOptions: EmulatedRegExpOptions;
}
`

The rawOptions property of EmulatedRegExp instances can be used for serialization.

#### Type EmulatedRegExpOptions

`ts
type EmulatedRegExpOptions = {
hiddenCaptures?: Array;
lazyCompile?: boolean;
strategy?: string | null;
transfers?: Array<[number, Array]>;
};
`

🔩 Options

The following options are shared by functions toRegExp and toRegExpDetails.

$3

One of 'default' (default) or 'strict'.

Sets the level of emulation rigor/strictness.

- Default: Permits a few close approximations in order to support additional features.
- Strict: Error if the pattern can't be emulated with identical behavior (even in rare edge cases) for the given target.

$3

Default: false.

Disables advanced emulation that relies on returning a RegExp subclass. In cases when a subclass would otherwise have been used, this results in one of the following:

- An error is thrown for patterns that are not emulatable without a subclass.
- Some patterns can still be emulated accurately without a subclass, but in this case subpattern match details might differ from Oniguruma.
- This is only relevant if you access the subpattern details of match results in your code (via subpattern array indices, groups, and indices).

$3

Oniguruma flags; a string with i, m, x, D, S, W, y{g} in any order (all optional).

Flags i, m, x can also be specified via modifiers in the pattern.

> [!IMPORTANT]
> Oniguruma and JavaScript both have an m flag but with different meanings. Oniguruma's m is equivalent to JavaScript's s (dotAll).

$3

Default: false.

Include JavaScript flag g (global) in the result.

$3

Default: false.

Include JavaScript flag d (hasIndices) in the result.

$3

Default: Infinity. In other words, lazy compilation is off by default.

Delay regex construction until first use if the transpiled pattern is at least this length.

Although regex construction in JavaScript is fast, it can sometimes be helpful to defer the cost for extremely long patterns. Lazy compilation defers the time JavaScript spends inside the RegExp constructor (building the transpiled pattern into a regex object) until the first time the regex is used in a search. The regex object is outwardly identical before and after deferred compilation.

Lazy compilation relies on the EmulatedRegExp class.

$3

Advanced options that override standard behavior, error checking, and flags when enabled.

- allowOrphanBackrefs: Useful with TextMate grammars that merge backreferences across patterns.
- asciiWordBoundaries: Use ASCII \b and \B, which increases search performance of generated regexes.
- captureGroup: Allow unnamed captures and numbered calls (backreferences and subroutines) when using named capture.
- This is Oniguruma option ONIG_OPTION_CAPTURE_GROUP; on by default in vscode-oniguruma.
- recursionLimit: Change the recursion depth limit from Oniguruma's 20 to an integer 2–20.
- singleline: ^ as \A; $ as \Z. Improves search performance of generated regexes without changing the meaning if searching line by line.
- This is Oniguruma option ONIG_OPTION_SINGLELINE.

$3

One of 'auto' (default), 'ES2025', 'ES2024', or 'ES2018'.

JavaScript version used for generated regexes. Using auto detects the best value for your environment. Later targets enable faster transpilation, simpler generated source, and support for additional features.

$3

Default: false.

Disables minifications that simplify the pattern without changing the meaning.

Example: By default, unneeded noncapturing groups might be removed during transpilation. Setting this option to true disables such changes.

> [!TIP]
> The oniguruma-parser library includes a regex optimizer that goes far beyond the basic, built-in minifications. If desired, you can call the optimizer first, and then use its result for transpilation. That isn't appropropriate in all cases (since it adds performance overhead and increases bundle size), but the benefits of optimization do pass through to the transpiled, JavaScript version of a regex.

✅ Supported features

Following are the supported features by target. The official Oniguruma syntax doc doesn't cover many of the finer details described here.

> [!NOTE]
> Targets ES2024 and ES2025 have the same emulation capabilities. Resulting regexes might have different source and flags, but they match the same strings. See target.

🆕 = Syntax not available in JavaScript.

🆚 = JavaScript uses slightly different syntax for the same concept; ex: \x{…} → \u{…}.

Even for features not marked with one of the above symbols, notice that nearly every feature below has at least subtle differences from JavaScript. Unsupported features throw an error.

The table above doesn't include all aspects that Oniguruma-To-ES emulates (including error handling, subpattern details on match results, most aspects that work the same as in JavaScript, and many aspects of non-JavaScript features that work the same in the other regex flavors that support them). Where applicable, Oniguruma-To-ES follows the latest version of Oniguruma (6.9.10).

$3

1. Unicode blocks (which in Oniguruma are specified with an In prefix) are easily emulatable but their character data would significantly increase library weight. They're also rarely used, fundamentally flawed, and arguably unuseful given the availability of Unicode scripts and other properties.
2. With target ES2018, the specific POSIX classes [:graph:] and [:print:] use ASCII versions rather than the Unicode versions available for target ES2024 and later, and they result in an error if using strict accuracy.
3. Target ES2018 has limited support for nested, negated character classes.
4. It's not an error for numbered backreferences to come before their referenced group in Oniguruma, but an error is the best path for Oniguruma-To-ES because ① most placements are mistakes and can never match (based on the Oniguruma behavior for backreferences to nonparticipating groups), ② erroring matches the behavior of named backreferences, and ③ the edge cases where they're matchable rely on rules for backreference resetting within quantified groups that are different in JavaScript and aren't emulatable. Note that it's not a backreference in the first place if using \10 or higher and not as many capturing groups are defined to the left (it's an octal or identity escape).
5. Oniguruma's recursion depth limit is 20. Oniguruma-To-ES uses the same limit by default but allows customizing it via the rules.recursionLimit option. Two rare uses of recursion aren't yet supported: overlapping recursions, and use of backreferences when a recursed subpattern contains captures. Patterns that would trigger an infinite recursion error in Oniguruma might find a match in Oniguruma-To-ES (since recursion is bounded), but future versions will detect this and error at transpilation time.
6. Other absence function types aren't yet supported. They start with (?~| and are extremely rare. Note that absence functions behave differently in Oniguruma and Onigmo.
7. Other named callouts aren't yet supported. They use the syntax (*…) and are extremely rare.
8. When using flag i, in rare cases Oniguruma can change the length of certain matches based on Unicode case conversion rules. That behavior isn't reproduced in this library because ① the rules are applied inconsistently (report) and ② Oniguruma planned to disable case conversion length changes by default in future versions.
9. Combining flags W and i can result in edge case Oniguruma bugs (report) that aren't reproduced in this library.

❌ Unsupported features

The following throw errors since they aren't yet supported. They're all extremely rare.

- Supportable:
- Rarely-used character specifiers: Non-A-Za-z with \cx \C-x, meta \M-x \M-\C-x, octal code points \o{…}, and octal encoded bytes ≥ \200.
- Code point sequences: \x{H H …} \o{O O …}.
- Flags P (POSIX is ASCII) and y{w} (text segment mode is word), and whole-pattern flag C (don't capture group).
- Supportable for some uses:
- Conditionals: (?(…)…), etc.
- Whole-pattern flags I (ignore-case is ASCII) and L (find longest).
- Named callout (*SKIP).
- Not supportable:
- Text segment boundaries: \y \Y.
- Callouts via (?{…}), and most named callouts.

See also the supported features table (above), which describes some additional, rarely-used sub-features that aren't yet supported.

Despite these gaps, ~99.99% of real-world Oniguruma regexes are supported, based on a sample of ~55k regexes used in TextMate grammars. Conditionals were used in three regexes, overlapping recursions in three regexes, and other unsupported features weren't used at all. Some Oniguruma features are so exotic that they aren't used in any public code on GitHub.

🌏 Unicode

Oniguruma-To-ES fully supports mixed case-sensitivity (ex: (?i)a(?-i)a) and handles the Unicode edge cases regardless of JavaScript target.

Oniguruma-To-ES focuses on being lightweight to make it better for use in browsers. This is partly achieved by not including heavyweight Unicode character data, which imposes a few minor/rare restrictions:

- Character class intersection and some uses of nested, negated character classes are unsupported with target ES2018. Use target ES2024 (supported by Node.js 20 and 2023-era browsers) or later if you need support for these features.
- With targets before ES2025, a handful of Unicode properties that target a specific character case (ex: \p{Lower}) can't be used case-insensitively in patterns that contain other characters with a specific case that are used case-sensitively.
- In other words, almost every usage is fine, including A\p{Lower}, (?i)A\p{Lower}, (?i:A)\p{Lower}, (?i)A(?-i)\p{Lower}, and \w(?i)\p{Lower}, but not A(?i)\p{Lower}.
- Using these properties case-insensitively is basically never done intentionally, so you're unlikely to encounter this error unless it's catching a mistake.
- Oniguruma-To-ES uses the version of Unicode supported natively by your JavaScript environment. Using Unicode properties via \p{…}` that were added in a later version of Unicode than the environment supports results in a runtime error. This is an extreme edge case since modern JavaScript environments support recent versions of Unicode.

🧩 Contributing

Contributions are welcome. See the guide to help you get started.

👀 Similar projects

JsRegex transpiles Ruby regexes to JavaScript. Ruby uses Onigmo, a fork of Oniguruma. Although JsRegex and this library have important differences, JsRegex might be a better fit for some Ruby projects.

🏷️ About

Oniguruma-To-ES was created by Steven Levithan and contributors.

$3

$3

$3

- Anthony Fu for inspiring the project and adopting it in Shiki.
- RedCMD and tonco-miyazawa for their deep Oniguruma expertise and frequent advice.
- K. Kosako for creating Oniguruma and maintaining it for 23 years.

If you use or want to support this project, I'd love your help by contributing improvements (guide), sharing it with others, or sponsoring maintenance and development.

MIT License.

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