unist-util-visit-parents
unist utility to walk the tree with a stack of parents.
Contents
What is this?
This is a very important utility for working with unist as it lets you walk the
tree.
When should I use this?
You can use this utility when you want to walk the tree and want to know about
every parent of each node.
You can use unist-util-visit
if you don’t care about the
entire stack of parents.
Install
This package is ESM only.
In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with npm:
npm install unist-util-visit-parents
In Deno with esm.sh
:
import {visitParents} from "https://esm.sh/unist-util-visit-parents@5"
In browsers with esm.sh
:
<script type="module">
import {visitParents} from "https://esm.sh/unist-util-visit-parents@5?bundle"
</script>
Use
import {visitParents} from 'unist-util-visit-parents'
import {fromMarkdown} from 'mdast-util-from-markdown'
const tree = fromMarkdown('Some *emphasis*, **strong**, and `code`.')
visitParents(tree, 'strong', (node, ancestors) => {
console.log(node.type, ancestors.map(ancestor => ancestor.type))
})
Yields:
strong ['root', 'paragraph']
API
This package exports the identifiers visitParents
, SKIP
, CONTINUE
, and
EXIT
.
There is no default export.
visitParents(tree[, test], visitor[, reverse])
Walk the tree
(Node
) and visit inclusive descendants
with ancestral information.
This algorithm performs depth-first tree traversal in
preorder (NLR), or if reverse
is given, in reverse preorder
(NRL).
You can choose for which nodes visitor
is called by passing a test
.
Walking the tree is an intensive task.
Make use of the return values of the visitor when possible.
Instead of walking a tree multiple times with different test
s, walk it once
without a test, and use unist-util-is
to check if a node
matches a test, and then perform different operations.
You can change the tree.
See visitor
below for more info.
Parameters
tree
(Node
)
— tree to traversetest
(Test
, optional)
— unist-util-is
-compatible testvisitor
(Function)
— function called for nodes that pass test
reverse
(boolean
, default: false
)
— traverse in reverse preorder (NRL) instead of preorder (NLR) (default
next? = visitor(node, ancestors)
Called when a node (matching test
, if given) is entered.
Visitors are free to change node
.
They can also transform the parent of node (the last of ancestors
).
Replacing node
itself is okay if SKIP
is returned.
When adding or removing previous siblings (or next siblings, in case of
reverse
) of node
, visitor
must return a new index
(number
)
to specify the sibling to move to after node
is traversed.
Adding or removing next siblings of node
(or previous siblings, in case of
reverse
) is fine without needing to return a new index
.
Replacing the children
of a node is fine, but replacing them on an ancestor
is not okay and still causes them to be visited.
Parameters
node
(Node
) — found nodeancestors
(Array<Node>
) — ancestors of node
Returns
The return value can have the following forms:
index
(number
) — like a tuple of [CONTINUE, index]
action
(*
) — like a tuple of [action]
tuple
([action, index?]
) — array with one or two values, the first an
action
, the second and index
.
👉 Note: yielding a tuple only makes sense if the action
is SKIP
.
Otherwise, if the action
is EXIT
, that action can be returned.
Or if the action
is CONTINUE
, index
can be returned.
action
An action can have the following values:
EXIT
(false
) — stop traversing immediatelyCONTINUE
(true
) — continue traversing as normalSKIP
('skip'
) — do not traverse this node’s children
index
Next index
(number
).
Defines that the sibling at index
should be moved to (after node
itself is
completely traversed).
Useful if mutating the tree, such as removing the node the visitor is currently
on, or any of its previous siblings (or next siblings, in case of reverse
).
Results less than 0
or greater than or equal to children.length
stop
traversing the parent
Types
This package is fully typed with TypeScript.
It exports the additional types Test
, Action
, Index
, ActionTuple
,
VisitorResult
, and Visitor
.
It also exports the types BuildVisitor<Tree extends Node = Node, Check extends Test = string>
to properly type visitors from a tree and a test, and
Visitor<Visited extends Node = Node, Ancestor extends Parent = Parent>
to
build an arbitrary visitor, from unist-util-visit-parents/complex-types.d.ts
.
Compatibility
Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
Our projects sometimes work with older versions, but this is not guaranteed.
Related
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.
License
MIT © Titus Wormer