unist-util-select

What is unist-util-select?

The unist-util-select package is a utility for selecting nodes in a Unist syntax tree using CSS-like selectors. It allows for querying and manipulating nodes in a tree structure, making it easier to work with abstract syntax trees (ASTs) in JavaScript.

What are unist-util-select's main functionalities?

Select a single node

This feature allows you to select a single node from the tree that matches the given selector. In this example, it selects the first 'paragraph' node in the tree.

const select = require('unist-util-select').select;
const tree = { type: 'root', children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Hello, world!' }] }] };
const node = select('paragraph', tree);
console.log(node);

Select multiple nodes

This feature allows you to select all nodes from the tree that match the given selector. In this example, it selects all 'paragraph' nodes in the tree.

const selectAll = require('unist-util-select').selectAll;
const tree = { type: 'root', children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Hello, world!' }] }, { type: 'paragraph', children: [{ type: 'text', value: 'Another paragraph.' }] }] };
const nodes = selectAll('paragraph', tree);
console.log(nodes);

Select nodes with specific attributes

This feature allows you to select nodes that have specific attributes. In this example, it selects all nodes with a 'data-id' attribute equal to 'intro'.

const selectAll = require('unist-util-select').selectAll;
const tree = { type: 'root', children: [{ type: 'paragraph', data: { id: 'intro' }, children: [{ type: 'text', value: 'Introduction' }] }, { type: 'paragraph', data: { id: 'main' }, children: [{ type: 'text', value: 'Main content' }] }] };
const nodes = selectAll('[data-id="intro"]', tree);
console.log(nodes);

Other packages similar to unist-util-select

unist-util-visit

unist-util-visit is a utility for recursively visiting nodes in a Unist syntax tree. It allows for more complex traversal and manipulation of nodes compared to unist-util-select, but does not use CSS-like selectors.

hast-util-select

hast-util-select is similar to unist-util-select but is specifically designed for working with HAST (Hypertext Abstract Syntax Tree) nodes. It provides CSS-like selectors for querying HAST nodes.

unist-builder

unist-builder is a utility for creating Unist syntax trees. While it does not provide querying capabilities like unist-util-select, it is useful for constructing trees programmatically.

README

unist-util-select

Select Unist nodes with CSS-like selectors.

Example

example.md:

Get all TODO items from this list:

1. Step 1.
2. TODO Step 2.
3. Step 3.
  1. TODO Step 3.1.
  2. Step 3.2.
  3. TODO Step 3.3.

remark takes this Markdown as an input and returns unist syntax tree. After that, we use unist-util-select to extract the required parts:

var select = require('unist-util-select');

var markdown = fs.readFileSync('example.md', 'utf8');
var ast = remark.parse(markdown);

select(ast, 'list text[value*=TODO]')
//=> [ { type: 'text', value: 'TODO Step 2.' },
//     { type: 'text', value: 'TODO Step 3.1.' },
//     { type: 'text', value: 'TODO Step 3.3.' } ]

That's it!

Features

All the relevant parts of Selectors Level 3:

• Type selectors: paragraph
• Descendant selectors: paragraph text
• Child selectors: paragraph > text
• Sibling selectors: paragraph ~ text
• Adjacent sibling selectors: paragraph + text
• Group selectors: paragraph, text
• Universal selector: *
• Attribute selectors: text[value*="substr"]
  • Existence: [value]
  • Equality: [value="foo"]
  • Begins with: [value^="prefix"]
  • Containment: [value*="substr"]
  • Ends with: [value$="suffix"]
• Structural pseudo-classes: paragraph:first-of-type
  • :root
  • :nth-child(2n+1)
  • :nth-last-child(2n+1)
  • :nth-of-type(2n+1)
  • :nth-last-of-type(2n+1)
  • :first-child
  • :last-child
  • :first-of-type
  • :last-of-type
  • :only-child
  • :only-of-type
  • :empty
• Negation pseudo-class: *:not(paragraph)

API

select(ast, selector)

Curried form: select(ast)(selector)

Applies selector to ast, returns array of matching nodes.

select.one(ast, selector)

Curried form: select.one(ast)(selector)

Returns a single node matching selector.

Throws an error if node is not found or not unique.

Install

npm install unist-util-select

License

MIT