node-source-walk

What is node-source-walk?

The node-source-walk package is a tool for traversing the abstract syntax tree (AST) of JavaScript code. It allows developers to analyze and manipulate the source code by providing an easy way to walk through the tree structure generated from the code.

What are node-source-walk's main functionalities?

Walking the AST of JavaScript code

This feature allows you to walk through the AST of a given JavaScript code snippet and perform actions based on the type of node encountered. In the code sample, the function logs a message whenever it encounters a variable declaration.

const walk = require('node-source-walk');

const sourceCode = 'var x = 1; console.log(x);';

walk(sourceCode, function(node) {
  if (node.type === 'VariableDeclaration') {
    console.log('Found a variable declaration!');
  }
});

Support for different parsers

node-source-walk supports various parsers like Esprima, Acorn, and Babel. This allows for flexibility in handling different JavaScript syntaxes, including experimental features and JSX. The code sample demonstrates how to specify a custom parser and its options.

const walk = require('node-source-walk');
const babelParser = require('@babel/parser');

const sourceCode = 'let x = 1;';

walk(sourceCode, {
  parser: babelParser,
  parserOptions: {
    sourceType: 'module',
    plugins: ['jsx']
  }
}, function(node) {
  // Analyze the node
});

Other packages similar to node-source-walk

estraverse

Estraverse is a simple and flexible library for traversing and manipulating the AST of ECMAScript 5.1. It is similar to node-source-walk but focuses on ECMAScript 5.1 and does not have built-in support for JSX or experimental JavaScript features.

acorn-walk

Acorn-walk is a tiny, fast JavaScript parser, built on Acorn. It provides a simple interface for walking the AST and is similar to node-source-walk but is tightly coupled with the Acorn parser.

babel-traverse

Babel-traverse is part of the Babel toolchain and provides the ability to traverse and update the AST. It is more powerful and complex than node-source-walk, with a focus on transforming code to work with Babel's plugin system.

README

node-source-walk

Synchronously execute a callback on every node of a file's AST and stop walking whenever you see fit.

npm install node-source-walk

Usage

const Walker = require('node-source-walk');

const walker = new Walker();

// Assume src is the string contents of myfile.js
// or the AST of an outside parse of myfile.js
walker.walk(src, node => {
  if (node.type === whateverImLookingFor) {
    // No need to keep traversing since we found what we wanted
    walker.stopWalking();
  }
});

By default, Walker will use @babel/parser (supporting ES6, JSX, Flow, and all other available @babel/parser plugins) and the sourceType: module, but you can change any of the defaults as follows:

const walker = new Walker({
  sourceType: 'script',
  // If you don't like experimental plugins
  plugins: [
    'jsx',
    'flow'
  ]
});

• The supplied options are passed through to the parser, so you can configure it according to @babel/parser's documentation.

Swap out the parser

If you want to supply your own parser, you can do:

const walker = new Walker({
  parser: mySweetParser
});

• The custom parser must have a .parse method that takes in a string and returns an object/AST.
• All of the other options supplied to the Walker constructor will be passed along as parser options to your chosen parser.

API

walk(src, callback)

• Recursively walks the given src from top to bottom
• src: the contents of a file or its (already parsed) AST
• callback: a function that is called for every visited node
  • The argument passed to callback will be the currently visited node.

moonwalk(node, callback)

• Recursively walks up an AST starting from the given node. This is a traversal that's in the opposite direction of walk and traverse
• node: a valid AST node
• callback: a function that is called for every node (specifically via visiting the parent(s) of every node recursively)
  • The argument passed to callback will be the currently visited node.

stopWalking()

• Halts further walking of the AST until another manual call of walk or moonwalk
• This is super-beneficial when dealing with large source files (or ASTs)

traverse(node, callback)

• Allows you to traverse an AST node and execute a callback on it
• Callback should expect the first argument to be an AST node, similar to walk's callback

parse(src)

• Uses the options supplied to Walker to parse the given source code string and return its AST using the configured parser (or @babel/parser by default).

License

MIT