ESTree Utility to Visit Nodes

2.0.0 · active · verified Sun Apr 19

estree-util-visit is a core utility within the unified (syntax-tree) ecosystem designed for traversing ESTree (and esast) abstract syntax trees. It enables developers to visit nodes in a depth-first traversal (preorder and/or postorder) for analysis or transformation. The current stable version is 2.0.0. The package distinguishes itself by duck-typing fields for node identification, eliminating the need for a predefined dictionary of node fields, which can simplify usage compared to other walkers. It provides symbolic controls (CONTINUE, EXIT, SKIP) for fine-grained traversal management. Releases are generally tied to ecosystem-wide updates or targeted feature enhancements. Since v2, it is an ESM-only package and requires Node.js 16 or newer.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/estree-util-visit/index.js from /your/file.js not supported.
```
cause Attempting to use `require()` to import `estree-util-visit`, which is an ESM-only package since version 2.0.0.

fix Change your import statement from `const { visit } = require('estree-util-visit')` to `import { visit } from 'estree-util-visit'`. Ensure your project is configured for ESM.
```
TypeError: (0, _estree_util_visit.visit) is not a function
```
cause This error typically occurs when trying to import `visit` as a default export or using an incorrect named import syntax in an ESM environment, or when transpilers misinterpret the import.

fix Verify that you are using `import { visit } from 'estree-util-visit'` and not `import visit from 'estree-util-visit'` (there is no default export). Check your Babel/TypeScript configuration if transpiling.
```
ReferenceError: CONTINUE is not defined
```
cause The control symbols (CONTINUE, EXIT, SKIP) are named exports and must be explicitly imported.

fix Add `CONTINUE` (and any other control symbols you use) to your named import: `import { visit, CONTINUE } from 'estree-util-visit'`.

Warnings

breaking Version 2.0.0 of `estree-util-visit` now requires Node.js 16 or higher.
Fix: Ensure your Node.js environment is version 16 or newer. Update your `package.json` engines field or CI/CD pipelines accordingly.
breaking `estree-util-visit` is now an ESM-only package and utilizes the `exports` field in `package.json`. CommonJS `require()` is no longer supported.
Fix: Refactor your codebase to use ES module `import` statements (e.g., `import { visit } from 'estree-util-visit'`). Adjust build configurations (e.g., Webpack, Rollup) or Jest setups to handle ESM correctly.
breaking The `visit` function's callback arguments now pass `undefined` instead of `null` for certain optional values (e.g., `field`, `index`).
Fix: Update your visitor functions to expect and handle `undefined` instead of `null` for these arguments, e.g., `if (field !== undefined)`.
gotcha The package updated its `@types/unist` dependency. If your project also directly depends on `@types/unist`, you might encounter type conflicts or unexpected type behavior if your versions are incompatible.
Fix: Ensure that your project's `@types/unist` dependency (if any) is updated to a compatible version, or remove it if it's implicitly handled by `estree-util-visit`.

Install

npm install estree-util-visit npm
yarn add estree-util-visit yarn
pnpm add estree-util-visit pnpm

Imports

visit
wrong:
```
const visit = require('estree-util-visit').visit
```
correct:
```
import { visit } from 'estree-util-visit'
```
Package is ESM-only since v2.0.0, so CommonJS `require` is not supported. There is no default export.
CONTINUE
wrong:
```
import CONTINUE from 'estree-util-visit'
```
correct:
```
import { CONTINUE } from 'estree-util-visit'
```
Control symbols like CONTINUE, EXIT, and SKIP are named exports, not default. ESM-only.
Visitor
```
import type { Visitor } from 'estree-util-visit'
```
TypeScript types are shipped with the package. Import types using `import type`.

Quickstart

Demonstrates parsing an ESTree with Acorn and then traversing it with `estree-util-visit` to find and log literal values, showcasing traversal control with `EXIT`.

import { parse } from 'acorn'
import { visit, CONTINUE, EXIT, SKIP } from 'estree-util-visit'

const tree = parse(
  'export function example() { const x = 1 + "2"; console.log(x); if (process.env.DEBUG === "true") { process.exit(3) } }',
  { sourceType: 'module', ecmaVersion: 2020 }
)

let literalsFound = 0;
visit(tree, function (node) {
  if (node.type === 'Literal' && 'value' in node) {
    console.log(`Found literal: ${JSON.stringify(node.value)}`);
    literalsFound++;
  }
  if (literalsFound >= 2) {
    console.log('Enough literals found, exiting traversal.');
    return EXIT;
  }
  return CONTINUE;
})

// Example of using enter/leave visitors
visit(tree, {
  enter(node) {
    // console.log(`Entering: ${node.type}`);
  },
  leave(node) {
    // console.log(`Leaving: ${node.type}`);
  }
});

view raw JSON →