Oniguruma-To-ES

An Oniguruma to JavaScript regex transpiler that runs in the browser and on your server. Use it to:

• Take advantage of Oniguruma's many extended regex features in JavaScript.
• Run regexes written for Oniguruma from JavaScript, such as those used in TextMate grammars (used by VS Code, Shiki syntax highlighter, etc.).
• Share regexes across your Ruby and JavaScript code.

Compared to running the Oniguruma C library via WASM bindings using vscode-oniguruma, this library is less than 4% of the size and its regexes often run much faster since they run as native JavaScript.

Try the demo REPL

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 thousands of real-world Oniguruma regexes used in TextMate grammars (via the Shiki library). A few uncommon features can't be perfectly emulated and allow rare differences, but if you don't want to allow this, you can set the accuracy option to throw for such patterns (see details below).

📜 Contents

• Install and use
• API
• Options
• Supported features
• Unsupported features
• Unicode / mixed case-sensitivity

🕹️ Install and use

1npm install oniguruma-to-es

1import {toRegExp} from 'oniguruma-to-es';
2
3const str = '…';
4const pattern = '…';
5// Works with all string/regexp methods since it returns a native regexp
6str.match(toRegExp(pattern));

1<script src="https://cdn.jsdelivr.net/npm/oniguruma-to-es/dist/index.min.js"></script>
2<script>
3  const {toRegExp} = OnigurumaToES;
4</script>

🔑 API

toRegExp

Accepts an Oniguruma pattern and returns an equivalent JavaScript RegExp.

[!TIP] Try it in the demo REPL.

1function toRegExp(
2  pattern: string,
3  options?: OnigurumaToEsOptions
4): RegExp | EmulatedRegExp;

Type OnigurumaToEsOptions

1type OnigurumaToEsOptions = {
2  accuracy?: 'default' | 'strict';
3  avoidSubclass?: boolean;
4  flags?: string;
5  global?: boolean;
6  hasIndices?: boolean;
7  maxRecursionDepth?: number | null;
8  rules?: {
9    allowOrphanBackrefs?: boolean;
10    allowUnhandledGAnchors?: boolean;
11    asciiWordBoundaries?: boolean;
12  };
13  target?: 'auto' | 'ES2025' | 'ES2024' | 'ES2018';
14  verbose?: boolean;
15};

See Options for more details.

toDetails

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

1function toDetails(
2  pattern: string,
3  options?: OnigurumaToEsOptions
4): {
5  pattern: string;
6  flags: string;
7  subclass?: EmulatedRegExpOptions;
8};

Note that the returned flags might also be different than those provided, as a result of the emulation process. The returned pattern, flags, and subclass 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, by throwing an error for any patterns that rely on EmulatedRegExp's additional handling.

toOnigurumaAst

Returns an Oniguruma AST generated from an Oniguruma pattern.

1function toOnigurumaAst(
2  pattern: string,
3  options?: {
4    flags?: string;
5  }
6): OnigurumaAst;

EmulatedRegExp

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

1class EmulatedRegExp extends RegExp {
2  constructor(
3    pattern: string | EmulatedRegExp,
4    flags?: string,
5    options?: EmulatedRegExpOptions
6  );
7};

🔩 Options

The following options are shared by functions toRegExp and toDetails.

accuracy

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.

avoidSubclass

Default: false.

Disables advanced emulation that relies on returning a RegExp subclass, resulting in certain patterns not being emulatable.

flags

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

Flags 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).

global

Default: false.

Include JavaScript flag g (global) in the result.

hasIndices

Default: false.

Include JavaScript flag d (hasIndices) in the result.

maxRecursionDepth

Default: 5.

Specifies the recursion depth limit. Supported values are integers 2–100 and null. If null, any use of recursion results in an error.

Since recursion isn't infinite-depth like in Oniguruma, use of recursion also results in an error if using strict accuracy.

rules

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

• allowOrphanBackrefs: Useful with TextMate grammars that merge backreferences across patterns.
• allowUnhandledGAnchors: Applies flag y for unsupported uses of \G, rather than erroring.
  • Oniguruma-To-ES uses a variety of strategies to accurately emulate many common uses of \G. When using this option, if a \G is found that doesn't have a known emulation strategy, the \G is simply removed and JavaScript's y (sticky) flag is added. This might lead to some false positives and negatives, but is useful for non-critical matching (like syntax highlighting) when having some mismatches is better than not working.
• asciiWordBoundaries: Use ASCII-based \b and \B, which increases performance.

target

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

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

verbose

Default: false.

Disables optimizations that simplify the pattern when it doesn't change the meaning.

✅ 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.

Notice that nearly every feature below has at least subtle differences from JavaScript. Some features listed as unsupported are not emulatable using native JavaScript regexes, but support for others might be added in future versions of this library. Unsupported features throw an error.

The table above doesn't include all aspects that Oniguruma-To-ES emulates (including error handling, 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).

Footnotes

1. Target ES2018 doesn't allow using Unicode property names added in JavaScript specifications after ES2018.
2. Unicode blocks (which in Oniguruma are used with an In… prefix) are easily emulatable but their character data would significantly increase library weight. They're also a flawed and arguably unuseful feature, given the ability to use Unicode scripts and other properties.
3. With target ES2018, the specific POSIX classes [:graph:] and [:print:] use ASCII-based versions rather than the Unicode versions available for target ES2024 and later, and they result in an error if using strict accuracy.
4. Target ES2018 doesn't support nested negated character classes.
5. 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 (1) most placements are mistakes and can never match (based on the Oniguruma behavior for backreferences to nonparticipating groups), (2) erroring matches the behavior of named backreferences, and (3) 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).
6. The recursion depth limit is specified by option maxRecursionDepth. Use of backreferences when the recursed subpattern contains captures isn't yet supported. Patterns that would error in Oniguruma due to triggering infinite recursion might find a match in Oniguruma-To-ES since recursion is bounded (future versions will detect this and error at transpilation time).

❌ Unsupported features

The following don't yet have any support, and throw errors. They're all infrequently-used features, with most being extremely rare.

• Grapheme boundaries: \y, \Y.
• Flags P (POSIX is ASCII) and y{g}/y{w} (grapheme boundary modes).
• Whole-pattern modifiers: Don't capture (?C), ignore-case is ASCII (?I), find longest (?L).
• Absence functions: (?~…), etc.
• Conditionals: (?(…)…), etc.
• Rarely-used character specifiers: Non-A-Za-z with \cx, \C-x; meta \M-x, \M-\C-x; bracketed octals \o{…}; octal UTF-8 encoded bytes (≥ \200).
• Code point sequences: \x{H H …}, \o{O O …}.
• Callout functions: (?{…}), etc.

㊗️ Unicode / mixed case-sensitivity

Oniguruma-To-ES fully supports mixed case-sensitivity (and handles the Unicode edge cases) regardless of JavaScript target. It also restricts Unicode properties to those supported by Oniguruma and the target JavaScript version.

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 couple of minor/rare restrictions:

• Character class intersection and nested negated character classes are unsupported with target ES2018. Use target ES2024 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.

👀 Similar projects

JsRegex transpiles Onigmo regexes to JavaScript (Onigmo is a fork of Oniguruma with mostly shared syntax and behavior). It's written in Ruby and relies on the Regexp::Parser Ruby gem, which means regexes must be pre-transpiled on the server to use them in JavaScript. Note that JsRegex doesn't always translate edge case behavior differences.

🏷️ About

Oniguruma-To-ES was created by Steven Levithan.

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.