Registry / serialization / unist-util-select

unist-util-select

library5.1.0jsnpmunverified

unist-util-select is a utility designed to query and match nodes within a unist (Universal Syntax Tree) abstract syntax tree using CSS-like selectors. The package is currently at stable version 5.1.0 and maintains an active release cadence, with multiple minor and major updates in the past year, reflecting ongoing development and adherence to modern JavaScript standards. Key differentiators include its ability to work with any unist syntax tree and select all node types, providing equivalents to DOM's `querySelector`, `querySelectorAll`, and `matches`. However, it's important to note that unlike the DOM, unist nodes do not inherently store parent references, meaning certain parent-sensitive selectors (e.g., `:first-child`) will not function as they do in a browser environment. For performance-critical scenarios involving numerous modifications, alternatives like `unist-util-visit` might be more efficient, as `unist-util-select` walks the entire tree on each call. For `hast` (HTML AST) specific element selections, `hast-util-select` is recommended.

serialization data

npm install unist-util-select

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-SELECT

unist-util-select

serializationjavascriptv5.1.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.

matches

✓ import { matches } from 'unist-util-select'

✗ import matches from 'unist-util-select'

The package only provides named exports. Since v4.0.0, it is ESM-only, so CommonJS `require()` is not supported.

select

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

✗ const { select } = require('unist-util-select')

unist-util-select is ESM-only since v4.0.0. The `require()` syntax will result in a runtime error.

selectAll

✓ import { selectAll } from 'unist-util-select'

✗ import * as selectAll from 'unist-util-select'

Use specific named imports for `selectAll` as there is no default export and wildcard imports are typically not desired for a single function.

Demonstrates how to use `matches`, `select`, and `selectAll` to query a unist tree with CSS-like selectors, including handling different selector types and multiple results.

import { u } from 'unist-builder'; import { matches, select, selectAll } from 'unist-util-select'; const tree = u('blockquote', [ u('paragraph', [u('text', 'Alpha')]), u('paragraph', [u('text', 'Bravo')]), u('code', 'Charlie'), u('paragraph', [u('text', 'Delta')]), u('paragraph', [u('text', 'Echo')]), u('paragraph', [u('text', 'Foxtrot')]), u('paragraph', [u('text', 'Golf')]) ]); console.log('Matches blockquote or list:', matches('blockquote, list', tree)); const selectedNode = select('code ~ :nth-child(even)', tree); console.log('Selected single node (Delta):', selectedNode ? selectedNode.children[0].value : 'None'); const allSelectedNodes = selectAll('code ~ :nth-child(even)', tree); console.log('Selected all nodes (Delta, Foxtrot):', allSelectedNodes.map(node => node.children[0].value));

Debug

Known issues

breakingVersion 5.0.0 changed the minimum Node.js requirement to 16. Ensure your environment meets this minimum before upgrading.

fix

Upgrade Node.js to version 16 or higher, or pin to `unist-util-select@^4`.

affects: >=5.0.0

breakingSince version 4.0.0, the package is ESM-only and uses the `exports` map. CommonJS `require()` statements will no longer work and will lead to runtime errors.

fix

Migrate all imports to use ES module syntax (e.g., `import { select } from 'unist-util-select'`).

affects: >=4.0.0

breakingIn version 5.0.0, the `select` and `selectAll` functions now yield `undefined` instead of `null` when no matching node is found.

fix

Update existing code to expect and handle `undefined` instead of `null` for no match.

affects: >=5.0.0

gotchaParent-sensitive CSS selectors (e.g., `:first-child`, `:last-child`, `>`) are not supported. unist nodes do not store references to their parents, making these selectors impossible to evaluate directly.

fix

Refactor logic to manually traverse parent/child relationships using `unist-util-visit` or `unist-util-parents` for context, or use simpler, node-specific selectors.

affects: >=3.0.0

gotchaFrequent use of `select` or `selectAll` on large unist trees can be inefficient as each call involves walking the entire tree. For scenarios requiring many changes or bulk operations, `unist-util-visit` might offer better performance.

fix

Consider optimizing operations that repeatedly query the tree. For complex modifications, use `unist-util-visit` to traverse once and make changes, or cache selection results if appropriate.

affects: >=3.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax for `unist-util-select` in an environment where it's treated as an ES module.

fix

Change your import statements to use ES module syntax: `import { select } from 'unist-util-select';`

TypeError: matches is not a function

This error typically occurs if `matches` (or `select`/`selectAll`) is imported incorrectly, such as attempting a default import or incorrectly destructuring named exports from a CommonJS `require()` call.

fix

Ensure you are using named ES module imports: `import { matches } from 'unist-util-select';`

Error: Unknown pseudo-class :first-child

This error indicates an attempt to use a parent-sensitive CSS pseudo-class (like `:first-child`, `:last-child`, `:nth-child` without context) which is not supported by `unist-util-select` due to the lack of parent references in unist nodes.

fix

Revise your selector to avoid parent-sensitive pseudo-classes. If parent context is strictly needed, you may need to pre-process your tree (e.g., with `unist-util-parents`) or perform manual checks during traversal.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

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

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