Unist Node Selector Utility

Common errors

• ReferenceError: require is not defined in ES module scope

  cause 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

  cause 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

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

Warnings

• breaking Version 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`.
• breaking Since 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'`).
• breaking In 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.
• gotcha Parent-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.
• gotcha Frequent 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.

Install

• npm install unist-util-select npm
• yarn add unist-util-select yarn
• pnpm add unist-util-select pnpm

Imports

• matches
  wrong:

  import matches from 'unist-util-select'

  correct:

  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
  wrong:

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

  correct:

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

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

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

  correct:

  import { 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.

Quickstart

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));