Unist Utility for Direct Child Traversal

3.0.0 · active · verified Sun Apr 19

unist-util-visit-children is a focused utility within the unified ecosystem designed to create a reusable function for iterating over only the direct children of a given unist (Universal Syntax Tree) node. The current stable version is 3.0.0. Releases are tied to major Node.js version support, with new major versions often dropping support for unmaintained Node.js versions. While it provides a specific function for direct child visitation, the package's own documentation recommends using `unist-util-visit` for most general tree traversal needs due to its broader capabilities. It's distinct in its narrow scope, avoiding recursive traversal and providing a lightweight, dedicated mechanism for immediate child processing.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` an ESM-only package.

fix Change `const { visitChildren } = require('unist-util-visit-children')` to `import { visitChildren } from 'unist-util-visit-children'` and ensure your environment supports ESM.
```
SyntaxError: Unexpected token 'export' in <path>/node_modules/unist-util-visit-children/index.js
```
cause Your Node.js version is too old to handle ES Modules directly, or your bundler isn't configured for ESM.

fix Upgrade Node.js to version 16 or newer. If using a bundler, ensure it's configured to process ES Modules from `node_modules`.
```
TypeError: (0, _unist_util_visit_children.visitChildren) is not a function
```
cause Incorrect import of the named export `visitChildren`, or the module was loaded improperly.

fix Ensure you are using named imports: `import { visitChildren } from 'unist-util-visit-children'`. Do not try to destructure a default export, as there is none.

Warnings

breaking Version 3.0.0 changed to use `export` maps, which requires modern Node.js module resolution. It also updated `@types/unist` and requires Node.js 16 or higher.
Fix: Ensure your project is running Node.js 16+ and update your `@types/unist` dependency if you are using TypeScript. Update your import paths if using bundlers that do not automatically resolve `export` maps.
breaking Version 2.0.0 converted the package to be ESM-only. CommonJS `require()` is no longer supported.
Fix: Migrate your codebase to use ES Modules (ESM) syntax (`import ... from '...'`) and ensure your Node.js environment or bundler is configured for ESM.
gotcha The package itself advises against its general use, stating, 'Probably never! Use `unist-util-visit`.' This utility is specifically for *direct* children, whereas `unist-util-visit` provides full recursive tree traversal.
Fix: For most tree traversal scenarios, consider using `unist-util-visit` (or `unist-util-visit-parents` for parent access) for a more robust and widely applicable solution, unless your use case strictly requires only visiting direct children without recursion.

Install

npm install unist-util-visit-children npm
yarn add unist-util-visit-children yarn
pnpm add unist-util-visit-children pnpm

Imports

visitChildren
wrong:
```
const visitChildren = require('unist-util-visit-children')
```
correct:
```
import { visitChildren } from 'unist-util-visit-children'
```
This package is ESM-only since v2.0.0 and requires Node.js 16+ since v3.0.0. CommonJS `require` will fail.
Visitor
```
import type { Visitor } from 'unist-util-visit-children'
```
TypeScript type for the visitor callback function.
Visit
```
import type { Visit } from 'unist-util-visit-children'
```
TypeScript type for the function returned by `visitChildren`.

Quickstart

Demonstrates how to import and use `visitChildren` to iterate over the direct children of a unist tree node, logging each child's type.

import u from 'unist-builder';
import { visitChildren } from 'unist-util-visit-children';

const visitorFunction = function (node) {
  console.log(`Visiting direct child: ${node.type}`);
  if (node.value) {
    console.log(`  Value: ${node.value}`);
  }
};

const visit = visitChildren(visitorFunction);

const tree = u('root', [
  u('leaf', 'leaf 1'),
  u('parent-node', [
    u('child-leaf', 'child 2'),
    u('child-leaf', 'child 3')
  ]),
  u('leaf', 'leaf 4'),
  u('void-node')
]);

console.log('--- Traversing direct children of the root node ---');
visit(tree);

view raw JSON →