Registry / serialization / unist-util-modify-children

unist-util-modify-children

library4.0.0jsnpmunverified

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.

serialization

npm install unist-util-modify-children

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-MODIFY-

unist-util-modify-children

serializationjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

modifyChildren

✓ import { modifyChildren } from 'unist-util-modify-children'

✗ const { modifyChildren } = require('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.

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' } ] } */

Debug

Known issues

gotchaThe 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.

affects: >=1.0.0

breakingVersion 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.

affects: >=4.0.0

breakingThe 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.

affects: >=3.0.0

breakingVersion 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`.

affects: >=4.0.0

breakingVersion 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.

affects: >=2.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/unist-util-modify-children/index.js from ... not supported.

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

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'.

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.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

@types/unistrequiredProvides TypeScript type definitions for Unist nodes, essential for type-safe usage and was updated as a breaking change in v4.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/syntax-tree/unist-util-modify-children ↗

packagehttps://www.npmjs.com/package/unist-util-modify-children ↗