RegExp Tree: Regular Expression Processor

Common errors

• Error: Cannot find module 'regexp-tree'

  cause The `regexp-tree` package has not been installed or is not resolvable in the current environment.
  fix Run `npm install regexp-tree` or `yarn add regexp-tree` in your project directory.

• TypeError: regexpTree.parse is not a function

  cause This usually occurs when attempting to destructure `parse` directly from a CommonJS `require` call, or when `import { parse } from 'regexp-tree'` is used in an environment where named ESM exports are not directly supported by the module's `package.json`.
  fix For CommonJS, use `const regexpTree = require('regexp-tree');` and then `regexpTree.parse(...)`. For ESM, use `import * as regexpTree from 'regexp-tree';` and then `regexpTree.parse(...)`.

• SyntaxError: Invalid regular expression: /pattern/: Malformed regular expression.

  cause The input string provided to `regexpTree.parse()` is not a valid regular expression according to the ECMAScript grammar or `regexp-tree`'s supported extensions.
  fix Verify the syntax of your regular expression string. Ensure all special characters are correctly escaped, character classes are properly formed, and quantifiers are used correctly. Consider testing your regex with online tools or simpler examples.

Warnings

• breaking As a package in `0.x.x` version, `regexp-tree` does not guarantee API stability. Minor or patch releases may introduce breaking changes without a major version bump, requiring careful review of changelogs during upgrades.
  Fix: Always review the package's GitHub releases or changelog when upgrading `regexp-tree` to identify any breaking changes. Consider pinning to exact versions to avoid unexpected issues.
• gotcha The command-line interface (CLI) for `regexp-tree` is not included in the main `regexp-tree` package. It is distributed as a separate npm module named `regexp-tree-cli`.
  Fix: To use the CLI, install it separately via `npm install -g regexp-tree-cli` or `npm install --save-dev regexp-tree-cli`.
• gotcha While `regexp-tree` bases its parser on the ECMAScript regular expression grammar, it also supports 'RegExp extensions'. Using these extensions will result in regular expressions that may not be compatible with standard JavaScript RegExp engines without prior transpilation.
  Fix: Be mindful when using RegExp extensions; if the output regex needs to run in standard environments, ensure you utilize the `compat-transpiler` API or Babel plugins provided by `regexp-tree` to transform them into standard ECMAScript regexes.

Install

• npm install regexp-tree npm
• yarn add regexp-tree yarn
• pnpm add regexp-tree pnpm

Imports

• regexpTree
  wrong:

  import regexpTree from 'regexp-tree';

  correct:

  import * as regexpTree from 'regexp-tree';

  The primary export is an object containing all APIs. Use `import * as` for ESM or `require` for CommonJS to access functions like `parse`, `transform`, and `optimize`.
• regexpTree
  wrong:

  const { parse } = require('regexp-tree');

  correct:

  const regexpTree = require('regexp-tree');

  For CommonJS, the package exports an object. Destructuring directly from `require` might not work as intended if the main module doesn't explicitly export named functions this way.
• AST
  wrong:

  import { AST } from 'regexp-tree';

  correct:

  import type { AST } from 'regexp-tree';

  When importing types like `AST` or other interface definitions, use `import type` to ensure they are correctly resolved by TypeScript and stripped during compilation.

Quickstart

Demonstrates parsing a regular expression into an Abstract Syntax Tree (AST), then applying a custom transformation to modify a character, and finally optimizing the regex for improved performance or conciseness.

import * as regexpTree from 'regexp-tree';

// Example: Parse, transform, and optimize a regular expression
const regexString = '/a[bc]d|efg+/gi';

try {
  // 1. Parse the regular expression to get its AST
  const ast = regexpTree.parse(regexString);
  console.log('Original AST (partial):', JSON.stringify(ast, null, 2).substring(0, 100) + '...');

  // 2. Transform the AST (e.g., replace a character)
  const transformedAst = regexpTree.transform(regexString, {
    char(path) {
      if (path.node.value === 'b') {
        path.node.value = 'x'; // Change 'b' to 'x'
      }
    }
  });
  console.log('Transformed Regexp:', transformedAst.toString()); // Outputs transformed regex string

  // 3. Optimize the regular expression
  const optimizedAst = regexpTree.optimize(regexString);
  console.log('Optimized Regexp:', optimizedAst.toString());

} catch (error) {
  if (error instanceof Error) {
    console.error('Error processing regex:', error.message);
  } else {
    console.error('An unknown error occurred:', error);
  }
}