Registry / serialization / unist-util-remove

unist-util-remove

library4.0.0jsnpmunverified

unist-util-remove is a utility package within the unified ecosystem designed to modify unist (Universal Syntax Tree) structures by removing nodes that pass a given test. Unlike `unist-util-filter`, this utility mutates the tree in-place, which can offer significant performance benefits on large documents. The current stable version is 4.0.0, which notably introduced a requirement for Node.js 16+, transitioned to being an ESM-only package, and altered the return type of the `remove` function from the modified tree to `undefined`. The package maintains compatibility with actively maintained Node.js versions and receives updates for bug fixes, performance improvements, and minor enhancements. Major version releases typically align with Node.js LTS updates or significant architectural shifts within the unified ecosystem, such as the move to ESM.

serialization

npm install unist-util-remove

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-REMOVE

unist-util-remove

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.

remove

✓ import { remove } from 'unist-util-remove'

✗ const remove = require('unist-util-remove')

Since v3.0.0, unist-util-remove is an ESM-only package. CommonJS require() will fail.

remove

✓ import { remove } from 'unist-util-remove'

✗ import remove from 'unist-util-remove'

The package provides a named export for `remove`, not a default export.

Options

✓ import type { Options } from 'unist-util-remove'

TypeScript type for configuration options.

Demonstrates importing `remove` and using it to mutate a unist tree by removing nodes matching a type, including an example of the `cascade` option.

import { u } from 'unist-builder'; import { remove } from 'unist-util-remove'; // Create a sample unist tree const tree = u('root', [ u('leaf', '1'), u('parent', [ u('leaf', '2'), u('parent', [u('leaf', '3'), u('other', '4')]), u('parent', [u('leaf', '5')]) ]), u('leaf', '6'), u('emptyParent', []) ]); console.log('Original Tree:'); console.dir(tree, { depth: undefined }); // Remove all nodes of type `leaf`. // Note: `remove` mutates the tree in-place and returns undefined since v4.0.0. remove(tree, 'leaf'); console.log('\nTree after removing all `leaf` nodes:'); console.dir(tree, { depth: undefined }); // Example with `cascade: false` to keep parents if only children were removed const anotherTree = u('root', [ u('parent', [ u('removableChild', 'a'), u('keepableChild', 'b') ]) ]); console.log('\nOriginal Tree for cascade example:'); console.dir(anotherTree, { depth: undefined }); remove(anotherTree, { cascade: false }, 'removableChild'); console.log('\nTree after removing `removableChild` with cascade: false:'); console.dir(anotherTree, { depth: undefined });

Debug

Known issues

breakingunist-util-remove v4.0.0 and later require Node.js 16 or newer. Older Node.js versions are no longer supported.

fix

Upgrade your Node.js environment to version 16 or higher, or pin to an older major version of unist-util-remove (e.g., `unist-util-remove@^3`).

affects: >=4.0.0

breakingAs of v3.0.0, unist-util-remove is an ECMAScript Module (ESM) only package. Attempting to `require()` it in a CommonJS context will result in an error.

fix

Migrate your project to ESM by setting `"type": "module"` in your `package.json` or by using dynamic `import()` for this package. Use `import { remove } from 'unist-util-remove'`.

affects: >=3.0.0

breakingThe `remove` function no longer returns the modified tree. It now returns `undefined`. The tree is always mutated in-place.

fix

Remove any code that expects `remove` to return the tree. The `tree` object passed to `remove` is modified directly. If you need to test if the root `tree` itself should be removed, do so explicitly with `unist-util-is` before calling `remove` on its children.

affects: >=4.0.0

breakingThe `RemoveOptions` TypeScript type was removed in v4.0.0.

fix

If you were explicitly using `RemoveOptions`, update your type annotations. The `Options` type is now the correct reference for configuration.

affects: >=4.0.0

breakingThe `unist-util-is` dependency was updated in v2.0.0, which could be a breaking change for TypeScript users if `unist-util-is` itself was used indirectly in a way that exposed its internal types.

fix

Ensure your project's types are updated and compatible with `unist-util-is@^4`. If you use `unist-util-is` directly, update it to the latest version.

affects: >=2.0.0

gotchaThe `cascade` option (default `true`) will remove parent nodes if all their children are removed. If you wish to keep parent nodes even if they become childless, set `cascade` to `false` in the options.

fix

Pass `{ cascade: false }` as the second argument to `remove` if you want to prevent parents from being removed when their children are filtered out.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to import an ESM-only package using CommonJS `require()`.

fix

Change your import statement to `import { remove } from 'unist-util-remove'` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

TypeError: (0 , unist_util_remove_1.remove) is not a function

Incorrect CommonJS require usage, or trying to destructure a non-existent default export.

fix

Ensure you are using the correct named import syntax for ESM: `import { remove } from 'unist-util-remove'`.

TypeError: Cannot read properties of undefined (reading 'children') at remove

Passing `null` or `undefined` as the `tree` argument to `remove`.

fix

Always ensure the first argument passed to `remove` is a valid unist `Node` object, or handle `null`/`undefined` cases before calling the function.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

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

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