ECMAScript Regular Expression Parser

Common errors

• Parsing error: Invalid regular expression pattern.

  cause The input string contains a syntax error in the regular expression or is not compatible with the configured `ecmaVersion`.
  fix Review the regular expression pattern for syntax errors. When using `RegExpParser` or `parseRegExpLiteral`, ensure the `ecmaVersion` option matches the target ECMAScript standard for the regex.

• TypeError: Cannot read properties of undefined (reading 'alternatives')

  cause Code is attempting to access AST properties like `elements` or node types like `Disjunction` that were renamed or removed in `regexpp` v2.0.0 or later.
  fix Update AST traversal or manipulation logic to use the new property names (e.g., `alternatives` instead of `elements`) and current node types as defined in `regexpp` v2.0.0 and above.

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax directly in an ES Module context, or an incorrect import path/symbol for `regexpp` which is primarily an ESM library.
  fix Use ES Module `import` syntax (`import { parseRegExpLiteral } from 'regexpp'`) in modern Node.js environments or with a bundler. Ensure your project is configured for ESM by using `.mjs` files or `"type": "module"` in `package.json`.

• Error: Node.js v6.x is no longer supported

  cause Running `regexpp` v3.0.0+ on an unsupported Node.js version (specifically, older than 8.x).
  fix Upgrade Node.js to version 8 or newer to meet the minimum engine requirements for `regexpp` v3.x.

Warnings

• breaking Node.js 6.x is no longer supported; the minimum required Node.js version is now 8.x.
  Fix: Upgrade Node.js to version 8 or newer.
• breaking The default ECMAScript version for parsing and validation changed to ES2020. This might cause previously valid regular expressions to be parsed differently or throw errors if they rely on older ECMAScript semantics without explicit version options.
  Fix: Explicitly pass `ecmaVersion` in parser/validator options (e.g., `{ ecmaVersion: 2018 }`) if compatibility with older ECMAScript versions is required, or update regex patterns to conform to ES2020.
• breaking The Abstract Syntax Tree (AST) shape underwent significant changes. The `Disjunction` node type was removed, an `Alternative` node type was added, and the `elements` property on `Pattern`, `Group`, `CapturingGroup`, and `Assertion` nodes was renamed to `alternatives`.
  Fix: Update any code that directly traverses or manipulates the AST to reflect the new node types and property names (e.g., use `node.alternatives` instead of `node.elements`).
• gotcha Regular expression patterns ending with an unescaped backslash (`\`) are now disallowed to align with ECMAScript spec updates. Such patterns will throw a syntax error during parsing or validation.
  Fix: Ensure regular expression patterns do not end with an unescaped backslash. Correct the pattern to escape the backslash (`\\`) if it's intended as a literal, or remove it if it's an incomplete escape sequence.
• gotcha Unicode version updates in various releases (e.g., 2.0.0, 3.0.0, 3.1.0) mean that behavior of Unicode property escapes or character classes might subtly change if existing code relied on very specific, older Unicode versions. Always parse with the `u` flag for proper Unicode handling.
  Fix: Verify that regular expressions using Unicode features behave as expected after upgrading. Explicitly set `ecmaVersion` and `unicode` (if applicable) in parser options for consistent behavior if precise historical Unicode conformance is critical.

Install

• npm install vscode-regexpp npm
• yarn add vscode-regexpp yarn
• pnpm add vscode-regexpp pnpm

Imports

• parseRegExpLiteral
  wrong:

  const { parseRegExpLiteral } = require('regexpp')

  correct:

  import { parseRegExpLiteral } from 'regexpp'

  The library primarily uses ES Modules. For CommonJS, bundlers like Webpack or Rollup are recommended, or use dynamic import.
• RegExpParser
  wrong:

  import RegExpParser from 'regexpp'

  correct:

  import { RegExpParser } from 'regexpp'

  This is a named export, not a default export.
• AST

  import type { AST } from 'regexpp'

  Import the `AST` namespace as a type for robust type-checking when working with parsed nodes.
• visitRegExpAST
  wrong:

  const visitRegExpAST = require('regexpp').visitRegExpAST

  correct:

  import { visitRegExpAST } from 'regexpp'

  ES Modules are the standard import mechanism for this library.

Quickstart

Demonstrates parsing a regular expression literal, validating it, and then traversing its Abstract Syntax Tree (AST) using the visitor pattern.

import { parseRegExpLiteral, visitRegExpAST, RegExpValidator } from 'regexpp';

const regexSource = '/^(hello|world)\s+\d{4}$/ui';

try {
  // Parse the regular expression literal
  const ast = parseRegExpLiteral(regexSource, { ecmaVersion: 2021 });
  console.log('Successfully parsed regex:', regexSource);
  console.log('Pattern body:', ast.pattern.raw);
  console.log('Flags:', ast.flags.raw);

  // Validate the regular expression
  const validator = new RegExpValidator({ ecmaVersion: 2021 });
  validator.validateLiteral(regexSource);
  console.log('Successfully validated regex:', regexSource);

  // Visit the AST nodes
  console.log('\nTraversing AST:');
  visitRegExpAST(ast, {
    onPatternEnter(node) { console.log(`  Entering Pattern: ${node.raw}`); },
    onGroupEnter(node) { console.log(`  Entering Group: ${node.raw}`); },
    onCharacterEnter(node) { console.log(`  Entering Character: ${node.raw}`); },
    onQuantifierEnter(node) { console.log(`  Entering Quantifier: ${node.raw}`); }
  });

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