Node Source Walk AST Traversal

7.0.1 · active · verified Sun Apr 19

node-source-walk is a JavaScript utility library designed for synchronously traversing Abstract Syntax Trees (ASTs) or raw source code strings. It allows developers to apply a callback function to every node within the AST, with the crucial capability to halt the traversal prematurely using `stopWalking()`. The current stable version is 7.0.1. Releases tend to align with Node.js LTS updates, primarily dropping support for older Node.js versions. A key differentiator is its flexibility in supporting both top-down (`walk`, `traverse`) and bottom-up (`moonwalk`) traversals, accepting either source code or a pre-parsed AST, and offering the option to replace its default `@babel/parser` with a custom parser.

Common errors

```
TypeError: Walker is not a constructor
```
cause Attempting to import `Walker` using named import syntax (`import { Walker } from '...'`) or destructuring (`const { Walker } = require('...')`) when it is exported as a default.

fix Use default import for ESM (`import Walker from 'node-source-walk';`) or direct `require` assignment for CommonJS (`const Walker = require('node-source-walk');`).
```
SyntaxError: Unexpected token 'import' (or similar parsing errors for modern JS/TS features)
```
cause The default `@babel/parser` might not have the necessary plugins enabled to parse specific syntax (e.g., JSX, Flow, TypeScript).

fix Initialize the `Walker` with `plugins` option to enable required `@babel/parser` plugins, for example: `new Walker({ plugins: ['jsx', 'typescript'] })`.
```
Error: node-source-walk requires Node.js version >= 18.
```
cause Running a version of `node-source-walk` (v7.0.0 or higher) on an unsupported Node.js runtime environment (e.g., Node.js 16).

fix Upgrade your Node.js runtime to version 18 or newer. Check your project's `engines` field in `package.json` for compatibility.

Warnings

breaking Version 7.0.0 and above drop support for Node.js versions older than 18. Projects running on Node.js 16 or earlier must upgrade their Node.js environment or remain on a previous major version of `node-source-walk`.
Fix: Upgrade your Node.js runtime to version 18 or newer. If an upgrade is not possible, pin `node-source-walk` to a version compatible with your Node.js environment (e.g., `<7.0.0` for Node.js 16).
breaking In version 6.0.0, the `shouldStop` and `reverseTraverse` methods were made private. Direct access or usage of these methods in your application logic will now fail.
Fix: Refactor code that directly called `shouldStop` or `reverseTraverse`. Instead, use the public `stopWalking()` method to halt traversal. The `moonwalk` method provides public access to reverse traversal functionality.
breaking Version 6.0.0 dropped support for Node.js 12. If you are migrating from a version below 6.0.0 and still using Node.js 12, an upgrade to Node.js 14 or higher (or eventually Node.js 18 for v7+) is required.
Fix: Upgrade your Node.js runtime to version 14 or newer, ideally to Node.js 18+ to be compatible with the latest major versions.
gotcha When providing a custom parser to `Walker`, ensure it exposes a `.parse` method that accepts a string and returns a valid AST. The library passes all other options to this custom parser.
Fix: Verify that your custom parser adheres to the expected `.parse(sourceString)` signature and returns a compatible AST structure. Consult `@babel/parser`'s documentation for AST shape reference.

Install

npm install node-source-walk npm
yarn add node-source-walk yarn
pnpm add node-source-walk pnpm

Imports

Walker
wrong:
```
import { Walker } from 'node-source-walk';
```
correct:
```
import Walker from 'node-source-walk';
```
The Walker class is the default export for ESM modules. Avoid named import syntax.
Walker
wrong:
```
const { Walker } = require('node-source-walk');
```
correct:
```
const Walker = require('node-source-walk');
```
For CommonJS, the Walker class is the default export. Destructuring will not work as expected.
Walker (Type)
```
import type { WalkerOptions } from 'node-source-walk';
```
For TypeScript projects, import the `WalkerOptions` interface to type the constructor options, if type definitions are available (e.g., via `@types/node-source-walk` or bundled).

Quickstart

This quickstart demonstrates how to instantiate the Walker class, traverse source code, identify specific AST node types (like 'FunctionDeclaration' or 'JSXElement'), and efficiently stop the traversal once a desired node is found. It also shows how to configure the internal parser with custom plugins like 'jsx'.

import Walker from 'node-source-walk';

// Example source code string
const src = `
  const add = (a, b) => a + b;
  function subtract(a, b) {
    return a - b;
  }
  console.log(add(5, 3));
  console.log(subtract(10, 4));
`;

const walker = new Walker();
let foundFunctionDeclaration = false;

console.log('Walking AST for function declarations...');
walker.walk(src, node => {
  if (node.type === 'FunctionDeclaration') {
    console.log(`Found function declaration: ${node.id.name}`);
    foundFunctionDeclaration = true;
    // Stop walking after finding the first one
    walker.stopWalking();
  }
});

if (!foundFunctionDeclaration) {
  console.log('No function declarations found.');
}

// Example with custom parser options (for JSX)
const jsxSrc = `
  import React from 'react';
  function MyComponent() {
    return <div>Hello, JSX!</div>;
  }
`;

const jsxWalker = new Walker({
  plugins: ['jsx'] // Ensure JSX plugin is enabled for parsing
});

console.log('\nWalking AST for JSX elements...');
let foundJsxElement = false;
jsxWalker.walk(jsxSrc, node => {
  if (node.type === 'JSXElement') {
    console.log('Found a JSXElement!');
    foundJsxElement = true;
    jsxWalker.stopWalking();
  }
});

if (!foundJsxElement) {
  console.log('No JSX elements found.');
}

view raw JSON →