Awesome
estree-util-visit
estree (and esast) utility to visit nodes.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Types
- Compatibility
- Related
- Contribute
- License
What is this?
This package is a utility that helps you walk the tree.
When should I use this?
This package helps when dealing with JavaScript ASTs.
Use unist-util-visit
for other unist ASTs.
Install
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>
Use
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
API
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.
Parameters
tree
(Node
) — tree to traversevisitor
(Visitor
) — same as passing{enter: visitor}
visitors
(Visitors
) — handle each node
Returns
Nothing (undefined
).
CONTINUE
Continue traversing as normal (symbol
).
EXIT
Stop traversing immediately (symbol
).
SKIP
Do not traverse this node’s children (symbol
).
Action
Union of the action types (TypeScript type).
Type
type Action = typeof CONTINUE | typeof EXIT | typeof SKIP
ActionTuple
List with one or two values, the first an action, the second an index (TypeScript type).
Type
type ActionTuple = [
(Action | null | undefined | void)?,
(Index | null | undefined)?
]
Index
Move 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
type Index = number
Visitor
Handle 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
.
Parameters
node
(Node
) — found nodekey
(string
orundefined
) — field at whichnode
lives in its parent (or where a list of nodes lives)index
(number
orundefined
) — index wherenode
lives ifparent[key]
is an arrayancestors
(Array<Node>
) — ancestors ofnode
Returns
What 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.
Visitors
Handle nodes when entering (preorder) and leaving (postorder) (TypeScript type).
Fields
enter
(Visitor
, optional) — handle nodes when entering (preorder)leave
(Visitor
, optional) — handle nodes when leaving (postorder)
Types
This package is fully typed with TypeScript.
It exports the additional types Action
,
ActionTuple
,
Index
,
Visitor
, and
Visitors
.
Compatibility
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.
Related
unist-util-visit
— walk any unist tree
Contribute
See 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.