Unist Utility to Filter Nodes

5.0.1 · active · verified Sun Apr 19

unist-util-filter is a utility for the Unist ecosystem that creates a new, immutable tree containing only the nodes that pass a provided test function. Unlike `unist-util-remove`, which modifies the original tree in place, `unist-util-filter` ensures immutability, making it suitable for functional programming paradigms or scenarios where the original tree must be preserved. The current stable version is 5.0.1. Major releases are not on a fixed cadence but often coincide with updates to Node.js LTS lines and significant changes in TypeScript definitions or module resolution. It integrates seamlessly with `unist-util-is` for defining complex testing conditions and offers a `cascade` option to control whether parent nodes should be removed if all their children are filtered out, with `true` as the default. This utility provides a clean, predictable way to prune ASTs without side effects.

Common errors

```
Error: require() of ES module /path/to/node_modules/unist-util-filter/index.js from /your/project/file.js not supported.
```
cause Attempting to import `unist-util-filter` (an ESM package) using CommonJS `require()` syntax.

fix Update your project to use ES modules (`import`) or switch to a dynamic import statement (`import('unist-util-filter')`) if remaining in CommonJS.
```
TypeError: filter is not a function
```
cause The `filter` symbol was not correctly imported, or the return value of `filter` was `undefined` (meaning the root node was filtered) and subsequently treated as a function.

fix Ensure you are using `import { filter } from 'unist-util-filter'` and verify that the result of the `filter` call is not `undefined` before attempting to access properties or methods on it.
```
Property 'FilterOptions' does not exist on type 'typeof import("unist-util-filter")'.
```
cause TypeScript error indicating that the `FilterOptions` type has been removed from the public API since v5.0.0.

fix Replace all instances of `FilterOptions` with `Options` in your TypeScript code, ensuring you use `import type { Options } from 'unist-util-filter'`.

Warnings

breaking Version 5.0.0 and later require Node.js 16 or higher.
Fix: Upgrade your Node.js environment to version 16 or newer, or pin your dependency to `unist-util-filter@^4`.
breaking The package transitioned to an ESM-only distribution model starting from v3.0.0, and further solidified with an 'exports' map in v5.0.0.
Fix: Migrate your project to use ECMAScript Modules (ESM) or consider using dynamic `import()` for CommonJS contexts. Alternatively, use `unist-util-filter@^2` for full CommonJS compatibility.
breaking The `filter` function now yields `undefined` instead of `null` if the root `tree` itself does not pass the test or is entirely cascaded away.
Fix: Update your code to expect and handle `undefined` as a possible return value when the entire tree is filtered out.
breaking The legacy TypeScript type `FilterOptions` was removed in favor of `Options`.
Fix: Update your TypeScript code to use the `Options` type where `FilterOptions` was previously used.
breaking TypeScript types in v4.0.0 changed to base what is returned on the input `tree` type, potentially affecting strict type checking.
Fix: Review and update TypeScript definitions related to the return type of `filter` to align with the type of the `tree` input.
gotcha The `cascade` option defaults to `true`, meaning parent nodes are removed if all their children are filtered out. This might lead to unexpected removals if you intend to keep parent nodes even when their children are gone.
Fix: If you need to preserve parent nodes when their children are filtered, explicitly set `{ cascade: false }` in the options object: `filter(tree, { cascade: false }, test)`.

Install

npm install unist-util-filter npm
yarn add unist-util-filter yarn
pnpm add unist-util-filter pnpm

Imports

filter
wrong:
```
const filter = require('unist-util-filter')
```
correct:
```
import { filter } from 'unist-util-filter'
```
unist-util-filter is ESM-only since v3. For CommonJS projects, consider using dynamic import or pinning to v2.
Options
wrong:
```
import { Options } from 'unist-util-filter'
```
correct:
```
import type { Options } from 'unist-util-filter'
```
'Options' is a TypeScript type and should be imported using 'import type' for type-only imports.
filter (Deno/Browser)
```
import { filter } from 'https://esm.sh/unist-util-filter@5'
```
For Deno or browser environments, use the esm.sh CDN for direct imports. Append '?bundle' for browser-bundled versions.

Quickstart

This example demonstrates filtering a Unist tree to retain only parent nodes and leaf nodes with even values, showing the immutable nature of the operation.

import {u} from 'unist-builder'
import {filter} from 'unist-util-filter'

const tree = u('root', [
  u('leaf', '1'),
  u('parent', [u('leaf', '2'), u('parent', [u('leaf', '3')])]),
  u('leaf', '4')
])

const newTree = filter(tree, node => node.type !== 'leaf' || Number(node.value) % 2 === 0)

console.dir(newTree, {depth: null})

/*
Yields:
{
  type: 'root',
  children: [
    {type: 'parent', children: [{type: 'leaf', value: '2'}]},
    {type: 'leaf', value: '4'}
  ]
}
*/

view raw JSON →