Big update!Introducing GitHub Bot Commands. Learn more
Socket
Log inBook a demo

unist-util-visit-parents

Package Overview
Dependencies
2
Maintainers
2
Versions
20
Issues
File Explorer

Advanced tools

unist-util-visit-parents

unist utility to recursively walk over nodes, with ancestral information

    5.1.1latest

Version published
Maintainers
2
Weekly downloads
8,726,671
decreased by-13.72%

Weekly downloads

Changelog

Source

5.1.1

  • 348f2f6 Fix TypeScript node16 and ESM by @alecmev in https://github.com/syntax-tree/unist-util-visit-parents/pull/12
  • c4fdbdb Add improved docs

Full Changelog: https://github.com/syntax-tree/unist-util-visit-parents/compare/5.1.0...5.1.1

Readme

Source

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 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/[email protected]"

In browsers with esm.sh:

<script type="module"> import {visitParents} from "https://esm.sh/[email protected]?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 tests, 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 traverse
  • test (Test, optional) — unist-util-is-compatible test
  • visitor (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 node
  • ancestors (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 immediately
  • CONTINUE (true) — continue traversing as normal
  • SKIP ('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.

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

Keywords

FAQs

What is unist-util-visit-parents?

unist utility to recursively walk over nodes, with ancestral information

Is unist-util-visit-parents popular?

The npm package unist-util-visit-parents receives a total of 8,321,158 weekly downloads. As such, unist-util-visit-parents popularity was classified as popular.

Is unist-util-visit-parents well maintained?

We found that unist-util-visit-parents 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.

Last updated on 21 Aug 2022

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket
Socket

Product

Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc