Unist Utility to Modify Children

4.0.0 · maintenance · verified Sun Apr 19

unist-util-modify-children is a utility within the unist (Universal Syntax Tree) ecosystem designed to create a reusable function for directly modifying the children of a parent node in an AST. The current stable version is 4.0.0, which notably moved to ESM-only and requires Node.js 16+. Releases generally follow semantic versioning, with major versions introducing breaking changes like environment requirements or module system shifts. A key differentiator and strong recommendation from its maintainers is that most users should probably use `unist-util-visit` instead, as `unist-util-modify-children` is intended for very specific, advanced scenarios where direct, in-place manipulation of child arrays is explicitly required and other traversal utilities are insufficient.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/unist-util-modify-children/index.js from ... not supported.
```
cause Attempting to import `unist-util-modify-children` using CommonJS `require()` syntax in a Node.js environment.

fix Change `const { modifyChildren } = require('unist-util-modify-children')` to `import { modifyChildren } from 'unist-util-modify-children'`. Ensure your project's `package.json` has `"type": "module"` or uses `.mjs` file extensions for ESM files.
```
TypeError: modifyChildren is not a function
```
cause This typically occurs when trying to call `modifyChildren` after an incorrect import (e.g., attempting a default import or a malformed named import) or if `require` was used and failed silently.

fix Verify the import statement is `import { modifyChildren } from 'unist-util-modify-children'` and that your environment supports ESM. Also ensure the package is correctly installed.
```
SyntaxError: Named export 'Modifier' not found. The requested module 'unist-util-modify-children' does not provide an export named 'Modifier'.
```
cause Attempting to import a TypeScript type as a value export, or incorrectly importing a type in an environment that doesn't support `import type`.

fix For TypeScript types, ensure you use `import type { Modifier } from 'unist-util-modify-children'` to explicitly import it as a type, especially in modern TypeScript environments. If using an older TypeScript version or Babel, ensure correct transpilation settings.

Warnings

gotcha The maintainers strongly recommend using `unist-util-visit` for most tree traversal and modification tasks. `unist-util-modify-children` is primarily for very specific cases requiring direct child array manipulation.
Fix: Consider `import { visit } from 'unist-util-visit'` for general tree operations.
breaking Version 4.0.0 changed to require Node.js 16 or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or newer. Use an older package version (e.g., `unist-util-modify-children@3`) if you must support older Node.js.
breaking The package transitioned to ESM-only starting from version 3.0.0. CommonJS `require()` statements will no longer work.
Fix: Update your import statements to use ES modules syntax (e.g., `import { modifyChildren } from 'unist-util-modify-children'`). Ensure your project is configured for ESM.
breaking Version 4.0.0 updated its internal `@types/unist` dependency. If your project or its dependencies rely on specific `unist` types, you may need to update your own `@types/unist` version to avoid type conflicts.
Fix: Update your project's `@types/unist` dependency to the latest compatible version or match the version used by `unist-util-modify-children`.
breaking Version 2.0.0 introduced TypeScript types. If you or your dependents were using TypeScript and relying on implicit typings or custom declarations, this change could potentially break your build due to new type strictness or conflicting declarations.
Fix: Review your TypeScript configuration and code to ensure compatibility with the official types. Update your `tsconfig.json` if necessary.

Install

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

Imports

modifyChildren
wrong:
```
const { modifyChildren } = require('unist-util-modify-children')
```
correct:
```
import { modifyChildren } from 'unist-util-modify-children'
```
The package is ESM-only since v3.0.0 and requires Node.js 16+ since v4.0.0, making CommonJS `require` calls invalid.
Modifier
```
import type { Modifier } from 'unist-util-modify-children'
```
TypeScript type for the callback function passed to `modifyChildren`. Use `import type` for type-only imports to avoid bundling issues.
Modify
```
import type { Modify } from 'unist-util-modify-children'
```
TypeScript type for the function returned by `modifyChildren`. Use `import type` for type-only imports.

Quickstart

This quickstart demonstrates how to initialize `unist-util-modify-children` with a custom modifier function and apply it to a Unist tree to replace a specific type of parent node with a new structure.

import u from 'unist-builder';
import { modifyChildren } from 'unist-util-modify-children';

// Create a sample Unist tree
const tree = u('root', [
  u('leaf', '1'),
  u('parent', [u('leaf', '2')]),
  u('leaf', '3')
]);

// Define a modifier function that replaces a 'parent' node with a 'subtree' node
const modify = modifyChildren(function (node, index, parent) {
  if (node.type === 'parent') {
    // Replace the 'parent' node with a new 'subtree' node containing its children
    parent.children.splice(index, 1, { type: 'subtree', children: node.children });
    // Return the new index to continue iteration from after the splice
    return index + 1;
  }
});

// Apply the modification to the tree
modify(tree);

// Output the modified tree structure
console.dir(tree, { depth: undefined });

/*
Yields:
{
  type: 'root',
  children: [
    { type: 'leaf', value: '1' },
    { type: 'subtree', children: [{ type: 'leaf', value: '2' }] },
    { type: 'leaf', value: '3' }
  ]
}
*/

view raw JSON →