{"id":11491,"library":"oniguruma-to-es","title":"Oniguruma to JavaScript RegExp Converter","description":"Oniguruma-To-ES is a JavaScript library designed to accurately translate Oniguruma regular expression patterns into equivalent native JavaScript RegExp objects. Currently at v4.3.5, the library maintains an active release cadence, frequently delivering bug fixes and feature enhancements. A key differentiator is its ability to support approximately 99.99% of Oniguruma regex features, making it a robust alternative to WASM-based Oniguruma implementations like `vscode-oniguruma`, offering a significantly smaller bundle size and often faster execution by leveraging native JavaScript regex engines. It deeply understands and compensates for the numerous syntactic and behavioral disparities between Oniguruma and JavaScript, including differences in flag support, group naming rules, and Unicode handling. The library is built upon `oniguruma-parser` and `Regex+`, ensuring battle-tested reliability from extensive use in TextMate grammars. Developers can also precompile regexes to further optimize bundle size and runtime performance, though the `EmulatedRegExp` class may still be required for advanced feature emulation.","status":"active","version":"4.3.5","language":"javascript","source_language":"en","source_url":"https://github.com/slevithan/oniguruma-to-es","tags":["javascript","regex","regexp","oniguruma","textmate-grammar","transpiler","typescript"],"install":[{"cmd":"npm install oniguruma-to-es","lang":"bash","label":"npm"},{"cmd":"yarn add oniguruma-to-es","lang":"bash","label":"yarn"},{"cmd":"pnpm add oniguruma-to-es","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core parsing logic for Oniguruma patterns, foundational to the translation process. The functionality was split out into this separate package starting from oniguruma-to-es v4.0.0.","package":"oniguruma-parser","optional":false}],"imports":[{"note":"Primary function for converting an Oniguruma pattern string to a native JavaScript RegExp object. CommonJS `require` is generally not recommended as the library is ESM-first.","wrong":"const toRegExp = require('oniguruma-to-es').toRegExp;","symbol":"toRegExp","correct":"import { toRegExp } from 'oniguruma-to-es';"},{"note":"Provides a more detailed output object including the compiled RegExp and metadata about the conversion.","wrong":"const { toRegExpDetails } = require('oniguruma-to-es');","symbol":"toRegExpDetails","correct":"import { toRegExpDetails } from 'oniguruma-to-es';"},{"note":"A custom RegExp subclass used internally for advanced feature emulation. It's needed at runtime if precompiled regexes use certain features. Must be imported as a named export from the main package.","wrong":"import EmulatedRegExp from 'oniguruma-to-es/EmulatedRegExp';","symbol":"EmulatedRegExp","correct":"import { EmulatedRegExp } from 'oniguruma-to-es';"}],"quickstart":{"code":"import { toRegExp } from 'oniguruma-to-es';\n\nconst onigurumaPattern = String.raw`(?x)\n  (?<n>\\d) (?<n>\\p{greek}) \\k<n>\n  ([0a-z&&\\h]){,2}\n`;\n\ntry {\n  const jsRegExp = toRegExp(onigurumaPattern, { target: 'ES2018' });\n  console.log('Converted RegExp:', jsRegExp.source);\n  console.log('Flags:', jsRegExp.flags);\n\n  // Example usage (note: the converted regex is /(?<n>\\p{Nd})(\\p{sc=Greek})(?>\\2|\\1)(?:[[0a-z]&&\\p{AHex}]){0,2}/v)\n  const testString = '1α1';\n  const match = testString.match(jsRegExp);\n  if (match) {\n    console.log('Match found:', match[0]);\n    console.log('Named capture group 'n':', match.groups?.n);\n  } else {\n    console.log('No match found.');\n  }\n\n} catch (error) {\n  console.error('Error converting regex:', error);\n}","lang":"typescript","description":"Demonstrates converting an Oniguruma pattern with 'x' flag, duplicate named capture groups, Unicode properties, and character class intersection into a native JavaScript RegExp, then tests it."},"warnings":[{"fix":"If direct AST access is needed, import and use functions from 'oniguruma-parser' directly. Otherwise, use `toRegExp` from `oniguruma-to-es` for pattern translation.","message":"The `toOnigurumaAst` function was removed in v4.0.0. Its parsing functionality has been migrated to the separate `oniguruma-parser` library. Direct users of `toOnigurumaAst` must update their code to use `oniguruma-parser` instead.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always use `oniguruma-to-es` to translate Oniguruma patterns before using them in a JavaScript environment to ensure correct behavior and semantics.","message":"While `oniguruma-to-es` aims for full emulation, Oniguruma's default behaviors (e.g., `\\d` as Unicode, backreferences to duplicate group names, implicit non-capturing groups with named groups) are transparently translated. Direct comparison of raw Oniguruma patterns with native JavaScript RegExp behavior will show differences. The library handles these internally, producing functionally equivalent JavaScript regexes.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `oniguruma-to-es` is updated to at least v4.3.3 to benefit from bug workarounds. Thoroughly test complex regexes in all target browser environments.","message":"Specific Safari (WebKit) versions exhibited bugs related to nested negated character classes and escaped hyphens within character classes. While versions >=4.3.2 and >=4.3.3 include workarounds, complex regexes might still behave unexpectedly on very old or non-standard WebKit-based browsers.","severity":"gotcha","affected_versions":"<4.3.3"},{"fix":"Update `oniguruma-to-es` to at least v4.3.1 when working with Bun, or ensure Bun itself is updated to a version greater than 1.1.34.","message":"Bun versions <= 1.1.34 contained a parser bug that could affect `oniguruma-to-es`. Version 4.3.1 of this library includes a workaround. Users running on affected Bun runtimes might experience issues without the update.","severity":"gotcha","affected_versions":"<4.3.1"},{"fix":"Precompile regexes during your build process. If `EmulatedRegExp` is required for some patterns, ensure it's properly imported and bundled. Consider whether less complex patterns can avoid `EmulatedRegExp` entirely.","message":"For optimal bundle size and runtime performance, precompiling Oniguruma regexes at build time is recommended. However, regexes utilizing certain advanced features will still require the runtime dependency on the `EmulatedRegExp` class (approx. 3 kB minzipped) to maintain full Oniguruma behavior.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"This functionality has moved to the `oniguruma-parser` library. If you need AST access, use `oniguruma-parser`. Otherwise, use `toRegExp` from `oniguruma-to-es` to get a JavaScript RegExp object.","cause":"Attempting to call the `toOnigurumaAst` function which was removed in version 4.0.0.","error":"TypeError: toOnigurumaAst is not a function"},{"fix":"Pass your Oniguruma pattern string through `oniguruma-to-es.toRegExp(pattern)` to translate it into a valid JavaScript RegExp object before use.","cause":"This error often occurs when an Oniguruma pattern, particularly one using duplicate named capture groups or other non-standard JavaScript regex features, is directly used to create a `RegExp` in JavaScript without prior translation by `oniguruma-to-es`.","error":"SyntaxError: Invalid regular expression: /.../: Invalid group name"},{"fix":"Ensure you `import { EmulatedRegExp } from 'oniguruma-to-es';` in your module where the precompiled regexes are being used.","cause":"This typically happens when using precompiled regexes that rely on the `EmulatedRegExp` class, but the class itself has not been imported or is not available in the current scope.","error":"ReferenceError: EmulatedRegExp is not defined"}],"ecosystem":"npm"}