Skip to content

Commit d68e907

Browse files
wooormwooorm
committed
Add improved docs
1 parent 230f8df commit d68e907

File tree

1 file changed

+120
-35
lines changed

1 file changed

+120
-35
lines changed

‎readme.md

Lines changed: 120 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -8,29 +8,100 @@
88
[![Backers][backers-badge]][collective]
99
[![Chat][chat-badge]][chat]
1010

11-
[**unist**][unist] utility with equivalents for `querySelector`,
12-
`querySelectorAll`, and `matches`.
13-
14-
Note that the DOM has references to their parent nodes, meaning that
15-
`document.body.matches(':last-child')` can be evaluated.
16-
This information is not stored in unist, so selectors like that don’t work.
17-
18-
[View the list of supported selectors »][support]
11+
[unist][] utility with equivalents for `querySelector`, `querySelectorAll`,
12+
and `matches`.
13+
14+
## Contents
15+
16+
* [What is this?](#what-is-this)
17+
* [When should I use this?](#when-should-i-use-this)
18+
* [Install](#install)
19+
* [Use](#use)
20+
* [API](#api)
21+
* [`matches(selector, node)`](#matchesselector-node)
22+
* [`select(selector, tree)`](#selectselector-tree)
23+
* [`selectAll(selector, tree)`](#selectallselector-tree)
24+
* [Support](#support)
25+
* [Types](#types)
26+
* [Compatibility](#compatibility)
27+
* [Related](#related)
28+
* [Contribute](#contribute)
29+
* [License](#license)
30+
31+
## What is this?
32+
33+
This package lets you find nodes in a tree, similar to how `querySelector`,
34+
`querySelectorAll`, and `matches` work with the DOM.
35+
36+
One notable difference between DOM and hast is that DOM nodes have references
37+
to their parents, meaning that `document.body.matches(':last-child')` can
38+
be evaluated to check whether the body is the last child of its parent.
39+
This information is not stored in hast, so selectors like that don’t work.
40+
41+
## When should I use this?
42+
43+
This utility works on any unist syntax tree and you can select all node types.
44+
If you are working with [hast][], and only want to select elements, use
45+
[`hast-util-select`][hast-util-select] instead.
46+
47+
This is a small utility that is quite useful, but is rather slow if you use it a
48+
lot.
49+
For each call, it has to walk the entire tree.
50+
In some cases, walking the tree once with [`unist-util-visit`][unist-util-visit]
51+
is smarter, such as when you want to change certain nodes.
52+
On the other hand, this is quite powerful and fast enough for many other cases.
1953

2054
## Install
2155

22-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
23-
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
24-
25-
[npm][]:
56+
This package is [ESM only][esm].
57+
In Node.js (version 14.14+, 16.0+), install with [npm][]:
2658

2759
```sh
2860
npm install unist-util-select
2961
```
3062

63+
In Deno with [`esm.sh`][esmsh]:
64+
65+
```js
66+
import {matches, select, selectAll} from "https://esm.sh/unist-util-select@4"
67+
```
68+
69+
In browsers with [`esm.sh`][esmsh]:
70+
71+
```html
72+
<script type="module">
73+
import {matches, select, selectAll} from "https://esm.sh/unist-util-select@4?bundle"
74+
</script>
75+
```
76+
77+
## Use
78+
79+
```js
80+
import {u} from 'unist-builder'
81+
import {matches, select, selectAll} from 'unist-util-select'
82+
83+
const tree = u('blockquote', [
84+
u('paragraph', [u('text', 'Alpha')]),
85+
u('paragraph', [u('text', 'Bravo')]),
86+
u('code', 'Charlie'),
87+
u('paragraph', [u('text', 'Delta')]),
88+
u('paragraph', [u('text', 'Echo')]),
89+
u('paragraph', [u('text', 'Foxtrot')]),
90+
u('paragraph', [u('text', 'Golf')])
91+
])
92+
93+
matches('blockquote, list', tree) // => true
94+
95+
console.log(select('code ~ :nth-child(even)', tree))
96+
// The paragraph with `Delta`
97+
98+
console.log(selectAll('code ~ :nth-child(even)', tree))
99+
// The paragraphs with `Delta` and `Foxtrot`
100+
```
101+
31102
## API
32103

33-
This package exports the following identifiers: `matches`, `select`, `selectAll`.
104+
This package exports the identifiers `matches`, `select`, and `selectAll`.
34105
There is no default export.
35106

36107
### `matches(selector, node)`
@@ -199,33 +270,35 @@ Yields:
199270

200271
###### Notes
201272

202-
* \* — Not supported in `matches`
273+
* \* — not supported in `matches`
274+
275+
## Types
276+
277+
This package is fully typed with [TypeScript][].
278+
It exports no additional types.
279+
280+
## Compatibility
281+
282+
Projects maintained by the unified collective are compatible with all maintained
283+
versions of Node.js.
284+
As of now, that is Node.js 14.14+ and 16.0+.
285+
Our projects sometimes work with older versions, but this is not guaranteed.
203286

204287
## Related
205288

206-
* [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
207-
— Create a new tree with all nodes that pass a test
208-
* [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
209-
— Create a new tree with all nodes mapped by a given function
210-
* [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap)
211-
— Create a new tree by mapping (to an array) with the given function
212289
* [`unist-util-is`](https://github.com/syntax-tree/unist-util-is)
213-
— Check if a node passes a test
214-
* [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove)
215-
— Remove nodes from trees
216-
* [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position)
217-
— Remove positional info from trees
290+
— check if a node passes a test
218291
* [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
219-
— Recursively walk over nodes
292+
— recursively walk over nodes
220293
* [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents)
221-
— Like `visit`, but with a stack of parents
294+
— like `visit`, but with a stack of parents
222295
* [`unist-builder`](https://github.com/syntax-tree/unist-builder)
223-
— Helper for creating trees
296+
— create unist trees
224297

225298
## Contribute
226299

227-
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
228-
started.
300+
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
301+
ways to get started.
229302
See [`support.md`][help] for ways to get help.
230303

231304
This project has a [code of conduct][coc].
@@ -266,18 +339,30 @@ abide by its terms.
266339

267340
[npm]: https://docs.npmjs.com/cli/install
268341

342+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
343+
344+
[esmsh]: https://esm.sh
345+
346+
[typescript]: https://www.typescriptlang.org
347+
269348
[license]: license
270349

271-
[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
350+
[health]: https://github.com/syntax-tree/.github
272351

273-
[help]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
352+
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
274353

275-
[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
354+
[help]: https://github.com/syntax-tree/.github/blob/main/support.md
276355

277-
[preorder]: https://github.com/syntax-tree/unist#preorder
356+
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
278357

279358
[unist]: https://github.com/syntax-tree/unist
280359

281360
[node]: https://github.com/syntax-tree/unist#node
282361

283-
[support]: #support
362+
[preorder]: https://github.com/syntax-tree/unist#preorder
363+
364+
[unist-util-visit]: https://github.com/syntax-tree/unist-util-visit
365+
366+
[hast]: https://github.com/syntax-tree/hast
367+
368+
[hast-util-select]: https://github.com/syntax-tree/hast-util-select

0 commit comments

Comments
 (0)