Oniguruma to JavaScript RegExp Converter

Common errors

• TypeError: toOnigurumaAst is not a function

  cause Attempting to call the `toOnigurumaAst` function which was removed in version 4.0.0.
  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.

• SyntaxError: Invalid regular expression: /.../: Invalid group name

  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`.
  fix Pass your Oniguruma pattern string through `oniguruma-to-es.toRegExp(pattern)` to translate it into a valid JavaScript RegExp object before use.

• ReferenceError: EmulatedRegExp is not defined

  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.
  fix Ensure you `import { EmulatedRegExp } from 'oniguruma-to-es';` in your module where the precompiled regexes are being used.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Always use `oniguruma-to-es` to translate Oniguruma patterns before using them in a JavaScript environment to ensure correct behavior and semantics.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install oniguruma-to-es npm
• yarn add oniguruma-to-es yarn
• pnpm add oniguruma-to-es pnpm

Imports

• toRegExp
  wrong:

  const toRegExp = require('oniguruma-to-es').toRegExp;

  correct:

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

  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.
• toRegExpDetails
  wrong:

  const { toRegExpDetails } = require('oniguruma-to-es');

  correct:

  import { toRegExpDetails } from 'oniguruma-to-es';

  Provides a more detailed output object including the compiled RegExp and metadata about the conversion.
• EmulatedRegExp
  wrong:

  import EmulatedRegExp from 'oniguruma-to-es/EmulatedRegExp';

  correct:

  import { EmulatedRegExp } from 'oniguruma-to-es';

  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.

Quickstart

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.

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

const onigurumaPattern = String.raw`(?x)
  (?<n>\d) (?<n>\p{greek}) \k<n>
  ([0a-z&&\h]){,2}
`;

try {
  const jsRegExp = toRegExp(onigurumaPattern, { target: 'ES2018' });
  console.log('Converted RegExp:', jsRegExp.source);
  console.log('Flags:', jsRegExp.flags);

  // Example usage (note: the converted regex is /(?<n>\p{Nd})(\p{sc=Greek})(?>\2|\1)(?:[[0a-z]&&\p{AHex}]){0,2}/v)
  const testString = '1α1';
  const match = testString.match(jsRegExp);
  if (match) {
    console.log('Match found:', match[0]);
    console.log('Named capture group 'n':', match.groups?.n);
  } else {
    console.log('No match found.');
  }

} catch (error) {
  console.error('Error converting regex:', error);
}