{"id":12286,"library":"unist-util-filter","title":"Unist Utility to Filter Nodes","description":"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.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-filter","tags":["javascript","unist","unist-util","util","utility","ast","tree","node","clone","typescript"],"install":[{"cmd":"npm install unist-util-filter","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-filter","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-filter","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"unist-util-filter is ESM-only since v3. For CommonJS projects, consider using dynamic import or pinning to v2.","wrong":"const filter = require('unist-util-filter')","symbol":"filter","correct":"import { filter } from 'unist-util-filter'"},{"note":"'Options' is a TypeScript type and should be imported using 'import type' for type-only imports.","wrong":"import { Options } from 'unist-util-filter'","symbol":"Options","correct":"import type { Options } from 'unist-util-filter'"},{"note":"For Deno or browser environments, use the esm.sh CDN for direct imports. Append '?bundle' for browser-bundled versions.","symbol":"filter (Deno/Browser)","correct":"import { filter } from 'https://esm.sh/unist-util-filter@5'"}],"quickstart":{"code":"import {u} from 'unist-builder'\nimport {filter} from 'unist-util-filter'\n\nconst tree = u('root', [\n  u('leaf', '1'),\n  u('parent', [u('leaf', '2'), u('parent', [u('leaf', '3')])]),\n  u('leaf', '4')\n])\n\nconst newTree = filter(tree, node => node.type !== 'leaf' || Number(node.value) % 2 === 0)\n\nconsole.dir(newTree, {depth: null})\n\n/*\nYields:\n{\n  type: 'root',\n  children: [\n    {type: 'parent', children: [{type: 'leaf', value: '2'}]},\n    {type: 'leaf', value: '4'}\n  ]\n}\n*/","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer, or pin your dependency to `unist-util-filter@^4`.","message":"Version 5.0.0 and later require Node.js 16 or higher.","severity":"breaking","affected_versions":">=5.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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your code to expect and handle `undefined` as a possible return value when the entire tree is filtered out.","message":"The `filter` function now yields `undefined` instead of `null` if the root `tree` itself does not pass the test or is entirely cascaded away.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your TypeScript code to use the `Options` type where `FilterOptions` was previously used.","message":"The legacy TypeScript type `FilterOptions` was removed in favor of `Options`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Review and update TypeScript definitions related to the return type of `filter` to align with the type of the `tree` input.","message":"TypeScript types in v4.0.0 changed to base what is returned on the input `tree` type, potentially affecting strict type checking.","severity":"breaking","affected_versions":">=4.0.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your project to use ES modules (`import`) or switch to a dynamic import statement (`import('unist-util-filter')`) if remaining in CommonJS.","cause":"Attempting to import `unist-util-filter` (an ESM package) using CommonJS `require()` syntax.","error":"Error: require() of ES module /path/to/node_modules/unist-util-filter/index.js from /your/project/file.js not supported."},{"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.","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.","error":"TypeError: filter is not a function"},{"fix":"Replace all instances of `FilterOptions` with `Options` in your TypeScript code, ensuring you use `import type { Options } from 'unist-util-filter'`.","cause":"TypeScript error indicating that the `FilterOptions` type has been removed from the public API since v5.0.0.","error":"Property 'FilterOptions' does not exist on type 'typeof import(\"unist-util-filter\")'."}],"ecosystem":"npm"}