estree-toolkit

Tools for working with ESTree AST

Installation

1npm i estree-toolkit
2# or
3yarn add estree-toolkit

Usage

1// Supports both CommonJS and ES Modules
2// ES Module
3import { traverse, builders as b } from 'estree-toolkit';
4// CommonJS
5const { traverse, builders: b } = require('estree-toolkit');

Basic operations

Traversing an AST

1const { traverse } = require('estree-toolkit');
2
3traverse(ast, {
4  Program(path) {
5    // Do something with the path
6  }
7});

Building Nodes

1const { builders: b } = require('estree-toolkit');
2
3b.identifier('x'); // => { type: 'Identifier', name: 'x' }

Checking node types

1const { traverse, is } = require('estree-toolkit');
2const { parseModule } = require('meriyah');
3
4const ast = parseModule(`x = 0`);
5
6traverse(ast, {
7  AssignmentExpression(path) {
8    if (is.identifier(path.node.left, { name: 'x' })) {
9      // `left` is an identifier with name `x`
10    }
11  }
12});

Replacing a node

1const { traverse, builders: b } = require('estree-toolkit');
2const { parseModule } = require('meriyah');
3
4const ast = parseModule('a = b');
5
6traverse(ast, {
7  Identifier(path) {
8    if (path.node.name === 'a') {
9      path.replaceWith(b.identifier('c'));
10    }
11  }
12});
13
14// Now the AST represents - `c = b`

Collecting scope information

1const { traverse } = require('estree-toolkit');
2
3traverse(ast, {
4  // Enable scope
5  $: { scope: true },
6  Program(path) {
7    // `path.scope` is now available in all paths
8  }
9});

Checking if a binding is available

1const { traverse } = require('estree-toolkit');
2const { parseModule } = require('meriyah');
3
4const ast = parseModule(`
5import { a } from 'source';
6
7const { b, c: [d, { e }] } = a;
8`);
9
10traverse(ast, {
11  $: { scope: true },
12  Program(path) {
13    path.scope.hasBinding('a') // => true
14    path.scope.hasBinding('b') // => true
15    path.scope.hasBinding('c') // => false
16    path.scope.hasBinding('d') // => true
17    path.scope.hasBinding('e') // => true
18  }
19});

Getting all references of a binding

1const { traverse } = require('estree-toolkit');
2const { parseModule } = require('meriyah');
3
4const ast = parseModule(`
5import { a } from 'source';
6
7fn(a);
8s = a;
9let obj = { a };
10`);
11
12traverse(ast, {
13  $: { scope: true },
14  Program(path) {
15    // Returns all the paths that reference the binding `a`
16    path.scope.getBinding('a').references // => [NodePath, NodePath, NodePath]
17  }
18});

Checking if a global has been used

1const { traverse } = require('estree-toolkit');
2const { parseModule } = require('meriyah');
3
4const ast = parseModule(`
5const fx = require('fx-mod');
6`);
7
8traverse(ast, {
9  $: { scope: true },
10  Program(path) {
11    path.scope.hasGlobalBinding('require') // => true
12  }
13});

Renaming a binding

1const { traverse } = require('estree-toolkit');
2const { parseModule } = require('meriyah');
3
4const ast = parseModule(`
5const a = 0
6
7a.reload()
8while (a.ok) a.run()
9`);
10
11traverse(ast, {
12  $: { scope: true },
13  Program(path) {
14    // `a` -> `b`
15    path.scope.renameBinding('a', 'b')
16  }
17});
18
19// Output code:
20// const b = 0
21//
22// b.reload()
23// while (b.ok) b.run()

Utilities

There are several static utilities that you can use.

• evaluate
  Evaluates the given path.

  1const { utils: u, traverse } = require('estree-toolkit');
  2// We are using `meriyah` but you can use any parser (like `acorn`)
  3const { parseModule } = require('meriyah');
  4
  5traverse(parseModule(`1 + 2`), {
  6  BinaryExpression(path) {
  7    u.evaluate(path) // => { value: 3 }
  8  }
  9});
  10
  11traverse(parseModule(`1 === 2`), {
  12  BinaryExpression(path) {
  13    u.evaluate(path) // => { value: false }
  14  }
  15});
  16
  17traverse(parseModule(`iDoNotKnowWhatThisIs === 55`), {
  18  BinaryExpression(path) {
  19    u.evaluate(path) // => undefined
  20  }
  21});
  22
  23traverse(parseModule(`
  24  ({
  25    text: 'This is an object',
  26    data: [1, 'two']
  27  })
  28`), {
  29  ObjectExpression(path) {
  30    u.evaluate(path) // => { value: { text: 'This is an object', data: [1, 'two'] } }
  31  }
  32});
  33
  34traverse(parseModule(`1 > 5 ? 'YES' : 'NO'`), {
  35  ConditionalExpression(path) {
  36    u.evaluate(path) // => { value: 'NO' }
  37  }
  38});

• evaluateTruthy
  Evaluates the path for truthiness and returns true, false or undefined depending on evaluation result.

There's more functionalities, please read the documentation.

Documentation

You can find the documentation at https://estree-toolkit.netlify.app/

Why another traverser?

I know there is Babel. But there are other tools which are faster than Babel. For example, meriyah is 3x faster than @babel/parser, astring is up to 50x faster than @babel/generator. But these tool only work with ESTree AST. I wanted to use these faster alternatives for one of my projects but could not find any traverser with batteries-included. So I built one myself, with awesome scope analysis, it has all the things that you would need for traversing an ESTree AST. Also, a little bit faster than Babel.

Need help?

If you need help in any kind of ESTree AST modification, then don't hesitate to open a new discussion in Q&A Discussions. I will try my best to help you :)

License

Licensed under the MIT License.