unified

Project: syntax-tree/unist-util-visit-parents

Package: unist-util-visit-parents@5.1.1

  1. unist utility to recursively walk over nodes, with ancestral information
  1. 83%
  3. MIT
  4. 82
  1. 264m
  1. util 130
  2. utility 126
  3. unist 116
  4. tree 42
  5. ast 35
  6. unist-util 25
  7. check 9
  8. walk 8
  9. visit 6
  10. parent 2
  11. parents 2

unist-util-visit-parents

Build Coverage Downloads Size Sponsors Backers Chat

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 16+), install with npm:

npm install unist-util-visit-parents

In Deno with esm.sh:

import {visitParents} from 'https://esm.sh/unist-util-visit-parents@6'

In browsers with esm.sh:

<script type="module">
  import {visitParents} from 'https://esm.sh/unist-util-visit-parents@6?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', function (node, ancestors) {
  console.log(node.type, ancestors.map(ancestor => ancestor.type))
})

Yields:

strong ['root', 'paragraph']

API

This package exports the identifiers CONTINUE, EXIT, SKIP, and visitParents. There is no default export.

visitParents(tree[, test], enter|visitors[, reverse])

Visit nodes, with ancestral information.

This algorithm performs depth-first tree traversal in preorder (NLR) or if reverse is given, in reverse preorder (NRL). An exit visitor is called in postorder (LRN) or if reverse is given, in reverse postorder (RLN).

You can choose which nodes are visited by passing a test. For complex tests, you should test yourself in a visitor, as it will be faster and will have improved type information.

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, walk it once, use unist-util-is to check if a node matches, and then perform different operations.

You can change the tree. Changes inside a node made when entering it are walked, changes made when exiting it are not. See Visitor and VisitorExit for more info.

Signatures
Parameters
Returns

Nothing (undefined).

CONTINUE

Continue traversing as normal (true).

EXIT

Stop traversing immediately (false).

SKIP

Do not traverse this node’s children ('skip'). Only works when entering a node.

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)?
]

BuildVisitor

Build a typed Visitor function from a tree and a test (TypeScript type).

It will infer which values are passed as node and which as parents.

Type parameters
Returns

Visitor.

BuildVisitors

Build typed Visitors from a tree and a test (TypeScript type).

It will infer which values are passed as node and which as parents.

Type parameters
Returns

Visitors.

Index

Move to the sibling at index next (after node itself is completely traversed) (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

Test

unist-util-is compatible test (TypeScript type).

Visitor

Handle a node (matching test, if given) before its children (TypeScript type).

Changes inside node are walked next. Replacing or removing it is easier in exit. When replacing or removing it here, return SKIP (as otherwise its old children are walked), or [SKIP, index] to continue with the node now at index. Changing next siblings (in walk order) is fine; changing previous siblings needs a new Index. Removing an ancestor or changing its previous siblings is not supported.

Parameters
Returns

What to do next (VisitorResult).

Passing a tuple back (ActionTuple) only makes sense as [SKIP, Index].

VisitorExit

Handle a node (matching test, if given) after its children (TypeScript type).

Changes inside node are not walked, which makes this a good place to change node based on its children, or to replace or remove it. When removing node or changing previous siblings (in walk order), return a new Index. Removing an ancestor or changing its previous siblings is not supported.

Parameters
Returns

What to do next (VisitorResultExit).

CONTINUE (true, nothing) continues as normal, EXIT (false) stops traversing, and Index continues at that sibling.

VisitorResult

Any value that can be returned from an enter visitor (TypeScript type).

Like VisitorResultExit but SKIP can be returned to not walk children of the node, and ActionTuple can be used to combine an action with an index.

Type
type VisitorResult =
  | Action
  | ActionTuple
  | Index
  | null
  | undefined
  | void

VisitorResultExit

Any value that can be returned from an exit visitor (TypeScript type).

Type
type VisitorResultExit = Index | boolean | null | undefined | void

Visitors

Handle nodes when entering and exiting them (TypeScript type). The enter visitor is optional while exit is required.

Pass an enter visitor directly to only handle nodes when entering them.

enter is called before children (if any) are walked and exit after that. exit is still called when enter returns SKIP. Both enter and exit are only called for nodes that match an optional test.

Fields

Types

This package is fully typed with TypeScript. It exports the additional types Action, ActionTuple, BuildVisitor, BuildVisitors, Index, Test, Visitor, VisitorExit, VisitorResult, VisitorResultExit, 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, unist-util-visit-parents@^6, compatible with Node.js 16.

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