unist-util-visit-parents

unist-util-visit-parents is a tiny, dependency-light utility for traversing unist syntax trees — the abstract syntax tree format that underpins the unified ecosystem (remark for Markdown, rehype for HTML, and retext for natural language). Unlike a plain visitor, it hands your callback the complete stack of ancestors leading to each node, so you always know where you are in the tree.

It performs depth-first, preorder (or reverse preorder) traversal, supports unist-util-is-compatible tests to target specific node types, and lets visitors mutate the tree or control traversal via CONTINUE, SKIP, and EXIT signals. It is fully typed and ships as ESM.

What You Get

• A single visitParents(tree, test?, visitor, reverse?) function that traverses a unist tree depth-first
• The full ancestor stack for every visited node, so plugins can reason about surrounding context
• Traversal control via the CONTINUE, SKIP, and EXIT return values, plus index-based re-entry for mutation
• unist-util-is-compatible tests to filter which nodes the visitor is called for
• Complete TypeScript types that infer node and ancestor types from your tree and test

Common Use Cases

• Writing remark or rehype plugins that need to know a node’s parent chain
• Transforming or removing nodes in a Markdown/HTML AST while keeping traversal correct
• Collecting nodes that match a test together with contextual ancestor information
• Building higher-level tree utilities on top of a reliable traversal primitive

Under The Hood

Architecture - The package is deliberately minimal: index.js re-exports CONTINUE, EXIT, SKIP, and visitParents from lib/index.js, where a single iterative traversal maintains an explicit stack of ancestors as it descends into each node’s children. Return values from the visitor are normalized into an [action, index] tuple that determines whether traversal continues, skips children, exits entirely, or resumes at a specific sibling index — the mechanism that makes in-place tree mutation safe. Tech Stack - Pure ESM JavaScript (type: module, sideEffects: false) with types authored as JSDoc and emitted to index.d.ts. Its only runtime dependencies are unist-util-is (for test matching) and @types/unist. Tooling uses xo, prettier, remark-cli, and c8 for coverage. Code Quality - The repo pairs a compact implementation with an extensive test.js suite and a dedicated index.test-d.ts for type-level assertions, targeting full coverage. Naming follows unist conventions and the code is heavily documented inline. API Design - The public surface is a single well-named function plus three intuitive constants, mirroring the sibling unist-util-visit. Types infer the concrete node and ancestor shapes from the tree and test arguments, giving strong editor support with almost no boilerplate to get started.