oniguruma-to-es
Advanced tools
A lightweight Oniguruma to JavaScript RegExp transpiler that runs in the browser and on your server. Use it to:
Compared to running the actual Oniguruma C library in JavaScript via WASM bindings (e.g. via vscode-oniguruma), this library is much lighter weight (the WASM binary alone is 460+ KB) and its regexes typically run much faster since they run as native JavaScript.
Oniguruma-To-ES deeply understands all of the hundreds of large and small differences in Oniguruma and JavaScript regex syntax and behavior across multiple JavaScript version targets. It's obsessive about precisely following Oniguruma syntax rules and ensuring that the emulated features it supports have exactly the same behavior, even in extreme edge cases. And it's 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).
[!NOTE] This library is currently in beta and has several known bugs. However, it's already quite robust and is ready for use. Please report any issues.
npm install oniguruma-to-es
import {toRegExp} from 'oniguruma-to-es';
const str = 'β¦';
const pattern = 'β¦';
// Works with all string/regexp methods since it returns a native JS regexp
str.match(toRegExp(pattern));
<script src="https://cdn.jsdelivr.net/npm/oniguruma-to-es/dist/index.min.js"></script>
<script>
const {toRegExp} = OnigurumaToES;
</script>
toRegExpTranspiles an Oniguruma pattern and returns a JavaScript RegExp.
[!TIP] Try it in the demo REPL.
function toRegExp(
pattern: string,
options?: Options
): RegExp | EmulatedRegExp;
Optionstype Options = {
accuracy?: 'strict' | 'default' | 'loose';
avoidSubclass?: boolean;
flags?: OnigurumaFlags;
global?: boolean;
hasIndices?: boolean;
maxRecursionDepth?: number | null;
target?: 'ES2018' | 'ES2024' | 'ESNext';
tmGrammar?: boolean;
verbose?: boolean;
};
See Options for more details.
toDetailsTranspiles an Oniguruma pattern to the parts needed to construct a JavaScript RegExp.
function toDetails(
pattern: string,
options?: Options
): {
pattern: string;
flags: string;
strategy?: {
name: string;
subpattern?: string;
};
};
The returned flags (as well as the pattern, of course) might be different than those provided, as a result of the emulation process. The returned pattern, flags, and strategy 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, and any patterns that rely on EmulatedRegExp's additional handling for emulation throw an error.
toOnigurumaAstGenerates an Oniguruma AST from an Oniguruma pattern.
function toOnigurumaAst(
pattern: string,
options?: {
flags?: OnigurumaFlags;
}
): OnigurumaAst;
EmulatedRegExpWorks the same as the native JavaScript RegExp constructor in all contexts, but can be provided results from toDetails to produce the same result as toRegExp.
class EmulatedRegExp extends RegExp {
constructor(
pattern: string | EmulatedRegExp,
flags?: string,
strategy?: {
name: string;
subpattern?: string;
}
);
};
The following options are shared by functions toRegExp and toDetails.
accuracyOne of 'strict', 'default' (default), or 'loose'.
Sets the level of emulation rigor/strictness.
Each level of increased accuracy supports a subset of patterns supported by lower accuracies. If a given pattern doesn't produce an error for a particular accuracy, its generated result will be identical with all lower levels of accuracy (given the same target).
strictSupports slightly fewer features, but the missing features are all relatively uncommon (see below).
defaultSupports all features of strict, plus the following additional features, depending on target:
ESNext and earlier):
\X using a close approximation of a Unicode extended grapheme cluster.\g<0>) with a depth limit specified by option maxRecursionDepth.ES2024 and earlier:
ES2018:
[:graph:] and [:print:] using ASCII-based versions rather than the Unicode versions available for ES2024 and later. Other POSIX classes are always based on Unicode.looseSupports all features of default, plus the following:
\G (a flexible assertion that doesnβt have a direct equivalent in JavaScript).
\G. When using loose accuracy, if a \G assertion 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.avoidSubclassDefault: false.
Disables advanced emulation strategies that rely on returning a RegExp subclass, resulting in certain patterns not being emulatable.
flagsOniguruma flags; a string with i, m, and x in any order (all optional).
Flags can also be specified via modifiers in the pattern.
[!IMPORTANT] Oniguruma and JavaScript both have an
mflag but with different meanings. Oniguruma'smis equivalent to JavaScript'ss(dotAll).
globalDefault: false.
Include JavaScript flag g (global) in the result.
hasIndicesDefault: false.
Include JavaScript flag d (hasIndices) in the result.
maxRecursionDepthDefault: 6.
Specifies the recursion depth limit. Supported values are integers 2 to 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.
Using a high limit has a (usually tiny) impact on transpilation and regex performance. Generally, this is only a problem if the regex has an existing issue with runaway backtracking that recursion exacerbates.
Higher limits have no effect on regexes that don't use recursion, so you should feel free to increase this if helpful.
targetOne of 'ES2018', 'ES2024' (default), or 'ESNext'.
Sets the JavaScript language version for the generated pattern and flags. Later targets allow faster processing, simpler generated source, and support for additional features.
ES2018: Uses JS flag u.
ES2024: Uses JS flag v.
ESNext: Uses JS flag v and allows use of flag groups and duplicate group names.
tmGrammarDefault: false.
Leave disabled unless the regex will be used in a TextMate grammar processor that merges backreferences across begin and end patterns.
verboseDefault: false.
Disables optimizations that simplify the pattern when it doesn't change the meaning.
Following are the supported features by target. The official Oniguruma syntax doc doesn't cover many of the finer details described here.
[!NOTE] Targets
ES2024andESNexthave the same emulation capabilities. Resulting regexes might have different source and flags, but they match the same strings.
Notice that nearly every feature below has at least subtle differences from JavaScript. Some features and subfeatures 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.
| Feature | Example | ES2018 | ES2024+ | Subfeatures & JS differences | |
|---|---|---|---|---|---|
| Flags | i | i | β | β |
β Unicode case folding (same as JS with flag u, v) |
m | m | β | β |
β Equivalent to JS flag s (dotAll) | |
x | x | β | β |
β Unicode whitespace ignored β Line comments with #β Whitespace/comments allowed between a token and its quantifier β Whitespace/comments between a quantifier and the ?/+ that makes it lazy/possessive changes it to a chained quantifierβ Whitespace/comments separate tokens (ex: \1 0)β Whitespace and # not ignored in char classes | |
| Flag modifiers | Group | (?im-x:β¦) | β | β |
β Unicode case folding for iβ Allows enabling and disabling the same flag (priority: disable) β Allows lone or multiple - |
| Directive | (?im-x) | β | β |
β Continues until end of pattern or group (spanning alternatives) | |
| Characters | Literal | E, ! | β | β |
β Code point based matching (same as JS with flag u, v)β Standalone ], {, } don't require escaping |
| Identity escape | \E, \! | β | β |
β Different allowed set than JS β Allows multibyte chars | |
| Escaped metachar | \\, \. | β | β |
β Same as JS | |
| Shorthand | \t | β | β |
β The JS set plus \a, \e | |
\xNN | \x7F | β | β |
β Allows 1 hex digit β Above 7F, is UTF-8 encoded byte (unlike JS)β Error for invalid encoded bytes | |
\uNNNN | \uFFFF | β | β |
β Same as JS with flag u, v | |
\x{β¦} | \x{A} | β | β |
β Allows leading 0s up to 8 total hex digits | |
| Escaped num | \20 | β | β |
β Can be backref, error, null, octal, identity escape, or any of these combined with literal digits, based on complex rules that differ from JS β Always handles escaped single digit 1-9 outside char class as backref β Allows null with 1-3 0s β Error for octal > 177 | |
| Control | \cA, \C-A | β | β |
β With A-Za-z (JS: only \c form) | |
| Other (extremely rare) | β | β |
Not yet supported: β Non-A-Za-z with \cx, \C-xβ Meta \M-x, \M-\C-xβ Octal code point \o{β¦}β UTF-8 encoded bytes in octal | ||
| Character sets | Digit, word | \d, \w, etc. | β | β |
β Same as JS (ASCII) |
| Hex digit | \h, \H | β | β |
β ASCII | |
| Whitespace | \s, \S | β | β |
β ASCII (unlike JS) | |
| Dot | . | β | β |
β Excludes only \n (unlike JS) | |
| Any | \O | β | β |
β Any char (with any flags) β Identity escape in char class | |
| Not newline | \N | β | β |
β Identity escape in char class | |
| Unicode property |
\p{L},\P{L}
| β [1] | β |
β Binary properties β Categories β Scripts β Aliases β POSIX properties β Invert with \p{^β¦}, \P{^β¦}β Insignificant spaces, underscores, and casing in names β \p, \P without { is an identity escapeβ Error for key prefixes β Error for props of strings β Blocks (wontfix[2]) | |
| Variable-length sets | Newline | \R | β | β |
β Matched atomically |
| Grapheme | \X | βοΈ | βοΈ |
β Uses a close approximation β Matched atomically | |
| Character classes | Base | [β¦], [^β¦] | β | β |
β Unescaped - outside of range is literal in some contexts (different than JS rules in any mode)β Fewer chars require escaping than JS β Error for reversed range (same as JS) |
| Empty | [], [^] | β | β |
β Error | |
| Range | [a-z] | β | β |
β Same as JS with flag u, v | |
| POSIX class |
[[:word:]],[[:^word:]]
| βοΈ[3] | β |
β All use Unicode definitions | |
| Nested class | [β¦[β¦]] | βοΈ[4] | β |
β Same as JS with flag v | |
| Intersection | [β¦&&β¦] | β | β |
β Doesn't require nested classes for intersection of union and ranges | |
| Assertions | Line start, end | ^, $ | β | β |
β Always "multiline" β Only \n as newline |
| String start, end | \A, \z | β | β |
β Same as JS ^ $ without JS flag m | |
| String end or before terminating newline | \Z | β | β |
β Only \n as newline | |
| Search start | \G | βοΈ | βοΈ |
β Common uses supported | |
| Word boundary | \b, \B | β | β |
β Unicode based (unlike JS) | |
| Lookaround |
(?=β¦),(?!β¦),(?<=β¦),(?<!β¦)
| β | β |
β Same as JS β Allows variable-length quantifiers and alternation within lookbehind | |
| Quantifiers | Greedy, lazy | *, +?, {2,}, etc. | β | β |
β Includes all JS forms β Adds {,n} for min 0β Explicit bounds have upper limit of 100,000 (unlimited in JS) β Error with assertions (same as JS with flag u, v) |
| Possessive | ?+, *+, ++ | β | β |
β + suffix doesn't make interval ({β¦}) quantifiers possessive (creates a chained quantifier) | |
| Chained | **, ??+*, {2,3}+, etc. | β | β |
β Further repeats the preceding repetition | |
| Groups | Noncapturing | (?:β¦) | β | β |
β Same as JS |
| Atomic | (?>β¦) | β | β |
β Supported | |
| Capturing | (β¦) | β | β |
β Is noncapturing if named capture present | |
| Named capturing |
(?<a>β¦),(?'a'β¦)
| β | β |
β Duplicate names allowed (including within the same alternation path) unless directly referenced by a subroutine β Error for names invalid in Oniguruma or JS | |
| Backreferences | Numbered | \1 | β | β |
β Error if named capture used β Refs the most recent of a capture/subroutine set |
| Enclosed numbered, relative |
\k<1>,\k'1',\k<-1>,\k'-1'
| β | β |
β Error if named capture used β Allows leading 0s β Refs the most recent of a capture/subroutine set β \k without < ' is an identity escape | |
| Named |
\k<a>,\k'a'
| β | β |
β For duplicate group names, rematch any of their matches (multiplex) β Refs the most recent of a capture/subroutine set (no multiplex) β Combination of multiplex and most recent of capture/subroutine set if duplicate name is indirectly created by a subroutine | |
| To nonparticipating groups | βοΈ | βοΈ |
β Error if group to the right[5] β Duplicate names (and subroutines) to the right not included in multiplex β Fail to match (or don't include in multiplex) ancestor groups and groups in preceding alternation paths β Some rare cases are indeterminable at compile time and use the JS behavior of matching an empty string | ||
| Subroutines | Numbered, relative |
\g<1>,\g'1',\g<-1>,\g'-1',\g<+1>,\g'+1'
| β | β |
β Allowed before reffed group β Can be nested (any depth) β Doesn't alter backref nums β Reuses flags from the reffed group (ignores local flags) β Replaces most recent captured values (for backrefs) β \g without < ' is an identity escapeβ Error if named capture used |
| Named |
\g<a>,\g'a'
| β | β |
β Same behavior as numbered β Error if reffed group uses duplicate name | |
| Recursion | Full pattern |
\g<0>,\g'0'
| βοΈ | βοΈ |
β Has depth limit[6] |
| Named, numbered, relative |
(?<a>β¦\g<a>?β¦),(β¦\g<1>?β¦),(β¦\g<-1>?β¦), etc.
| βοΈ | βοΈ |
β Has depth limit[6] | |
| Other | Comment group | (?#β¦) | β | β |
β Allows escaping \), \\β Comments allowed between a token and its quantifier β Comments between a quantifier and the ?/+ that makes it lazy/possessive changes it to a chained quantifier |
| Alternation | β¦|β¦ | β | β |
β Same as JS | |
| Keep | \K | βοΈ | βοΈ |
β Supported if at top level and no top-level alternation is used | |
| Absence operator | (?~β¦) | β | β |
β Some forms are supportable | |
| Conditional | (?(1)β¦) | β | β |
β Some forms are supportable | |
| Char sequence |
\x{1 2 β¦N},\o{1 2 β¦N} | β | β |
β Not yet supported | |
| JS features unknown to Oniguruma are handled using Oniguruma syntax | β | β |
β \u{β¦} is an errorβ [\q{β¦}] matches q, etc.β [a--b] includes the invalid reversed range a to - | ||
| Invalid Oniguruma syntax | β | β |
β 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).
ES2018 doesn't allow using Unicode property names added in JavaScript specifications after ES2018.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.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.ES2018 doesn't support nested negated character classes.\10 or higher and not as many capturing groups are defined to the left (it's an octal or identity escape).maxRecursionDepth. Some forms of recursion (multiple recursions in the same pattern, and recursion with backreferences) aren'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).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:
ES2018. Use target ES2024 or later if you need support for these features.ESNext, 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.
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}).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.
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.
FAQs
Convert Oniguruma patterns to native JavaScript RegExp
The npm package oniguruma-to-es receives a total of 238,284 weekly downloads. As such, oniguruma-to-es popularity was classified as popular.
We found that oniguruma-to-es demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Β It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."