estree-util-visit
Advanced tools
Package description
The estree-util-visit package is a utility for visiting nodes in an ESTree-compliant AST (Abstract Syntax Tree). It provides a simple way to traverse and manipulate JavaScript code structures programmatically, which is useful in tasks such as code analysis, transformation, and optimization.
Node Traversal
This feature allows you to traverse the AST nodes. The 'enter' method is called for each node in the tree, where you can perform actions like logging node types or modifying nodes.
import {visit} from 'estree-util-visit';
visit(tree, {
enter(node) {
console.log(node.type);
}
});Selective Traversal
This feature enables traversal of specific types of nodes. In this example, it logs the names of all function declarations, allowing targeted analysis or transformations.
import {visit} from 'estree-util-visit';
visit(tree, {
enter(node) {
if (node.type === 'FunctionDeclaration') {
console.log('Function name:', node.id.name);
}
}
});Skip Subtree
This feature allows you to skip the traversal of a subtree. If a function declaration is encountered, its body is skipped, optimizing traversal by avoiding unnecessary nodes.
import {visit} from 'estree-util-visit';
visit(tree, {
enter(node, ancestors) {
if (node.type === 'FunctionDeclaration') {
return visit.SKIP;
}
}
});Estraverse is another popular package for traversing and manipulating JavaScript ASTs. It offers similar functionalities but differs in API design and extensibility. Estraverse provides more granular control over traversal with separate enter and leave functions.
Acorn-walk, derived from the Acorn JS parser, provides utilities for walking ASTs generated by Acorn. It is tightly coupled with Acorn's AST structure, whereas estree-util-visit is more generic and works with any ESTree-compliant AST.
Readme
estree (and esast) utility to visit nodes.
This package is a utility that helps you walk the tree.
This package helps when dealing with JavaScript ASTs.
Use unist-util-visit for other unist ASTs.
This package is ESM only. In Node.js (version 16+), install with npm:
npm install estree-util-visit
In Deno with esm.sh:
import {visit} from 'https://esm.sh/estree-util-visit@2'
In browsers with esm.sh:
<script type="module">
import {visit} from 'https://esm.sh/estree-util-visit@2?bundle'
</script>
import {parse} from 'acorn'
import {visit} from 'estree-util-visit'
const tree = parse(
'export function x() { console.log(1 + "2"); process.exit(3) }',
{sourceType: 'module', ecmaVersion: 2020}
)
visit(tree, function (node) {
if (node.type === 'Literal' && 'value' in node) console.log(node.value)
})
// Both enter and leave:
walk(tree, {
enter(node, field, index, parents) { /* … */ },
leave(node, field, index, parents) { /* … */ }
})
Yields:
1
"2"
3
This package exports the identifiers CONTINUE,
EXIT,
SKIP, and
visit.
There is no default export.
visit(tree, visitor|visitors)Visit nodes, with ancestral information.
This algorithm performs depth-first tree traversal in preorder (NLR) and/or postorder (LRN).
Compared to other estree walkers, this does not need a dictionary of which fields are nodes, because it ducktypes instead.
Walking the tree is an intensive task.
Make use of the return values of the visitor(s) when possible.
Instead of walking a tree multiple times, walk it once, use
unist-util-is to check if a node matches, and then perform different
operations.
tree (Node)
— tree to traversevisitor (Visitor)
— same as passing {enter: visitor}visitors (Visitors)
— handle each nodeNothing (undefined).
CONTINUEContinue traversing as normal (symbol).
EXITStop traversing immediately (symbol).
SKIPDo not traverse this node’s children (symbol).
ActionUnion of the action types (TypeScript type).
type Action = typeof CONTINUE | typeof EXIT | typeof SKIP
ActionTupleList with one or two values, the first an action, the second an index (TypeScript type).
type ActionTuple = [
(Action | null | undefined | void)?,
(Index | null | undefined)?
]
IndexMove to the sibling at index next (after node itself is completely
traversed), when moving in an array (TypeScript type).
Useful if mutating the tree, such as removing the node the visitor is currently
on, or any of its previous siblings.
Results less than 0 or greater than or equal to children.length stop
traversing the parent.
type Index = number
VisitorHandle a node (TypeScript type).
Visitors are free to transform node.
They can also transform the parent of node (the last of ancestors).
Replacing node itself, if SKIP is not returned, still causes its
descendants to be walked (which is a bug).
When adding or removing previous siblings of node, the Visitor should
return a new Index to specify the sibling to traverse after node is
traversed.
Adding or removing next siblings of node is handled as expected without
needing to return a new Index.
node (Node)
— found nodekey (string or undefined)
— field at which node lives in its parent (or where a list of nodes
lives)index (number or undefined)
— index where node lives if parent[key] is an arrayancestors (Array<Node>)
— ancestors of nodeWhat to do next (Action, Index, or
ActionTuple, optional).
An Index is treated as a tuple of [CONTINUE, Index].
An Action is treated as a tuple of [Action].
Passing a tuple back only makes sense if the Action is SKIP.
When the Action is EXIT, that action can be returned.
When the Action is CONTINUE, Index can be returned.
VisitorsHandle nodes when entering (preorder) and leaving (postorder) (TypeScript type).
enter (Visitor, optional)
— handle nodes when entering (preorder)leave (Visitor, optional)
— handle nodes when leaving (postorder)This package is fully typed with TypeScript.
It exports the additional types Action,
ActionTuple,
Index,
Visitor, and
Visitors.
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, estree-util-visit@^2,
compatible with Node.js 16.
unist-util-visit
— walk any unist treeSee contributing.md in syntax-tree/.github for
ways to get started.
See support.md for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
FAQs
esast (and estree) utility to visit nodes
The npm package estree-util-visit receives a total of 1,135,696 weekly downloads. As such, estree-util-visit popularity was classified as popular.
We found that estree-util-visit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ua-parser-js is set to drop the MIT license and adopt a controversial dual AGPLv3 + PRO licensing model in its upcoming v2.0 release, raising significant concerns among developers and enterprise users.
Security News
Researchers recently demonstrated that the npm Registry is vulnerable to cache poisoning combined with DoS, posing significant risks for package availability.
Security News
The June TC39 meeting wrapped up this week with eight proposals moving on to the next stage. Here's a quick roundup of the features that the committee approved to advance.