diff --git a/readme.md b/readme.md index bb4c7d3..1e09ce8 100644 --- a/readme.md +++ b/readme.md @@ -8,29 +8,100 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -[**unist**][unist] utility with equivalents for `querySelector`, -`querySelectorAll`, and `matches`. - -Note that the DOM has references to their parent nodes, meaning that -`document.body.matches(':last-child')` can be evaluated. -This information is not stored in unist, so selectors like that don’t work. - -[View the list of supported selectors »][support] +[unist][] utility with equivalents for `querySelector`, `querySelectorAll`, +and `matches`. + +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`matches(selector, node)`](#matchesselector-node) + * [`select(selector, tree)`](#selectselector-tree) + * [`selectAll(selector, tree)`](#selectallselector-tree) +* [Support](#support) +* [Types](#types) +* [Compatibility](#compatibility) +* [Related](#related) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package lets you find nodes in a tree, similar to how `querySelector`, +`querySelectorAll`, and `matches` work with the DOM. + +One notable difference between DOM and hast is that DOM nodes have references +to their parents, meaning that `document.body.matches(':last-child')` can +be evaluated to check whether the body is the last child of its parent. +This information is not stored in hast, so selectors like that don’t work. + +## When should I use this? + +This utility works on any unist syntax tree and you can select all node types. +If you are working with [hast][], and only want to select elements, use +[`hast-util-select`][hast-util-select] instead. + +This is a small utility that is quite useful, but is rather slow if you use it a +lot. +For each call, it has to walk the entire tree. +In some cases, walking the tree once with [`unist-util-visit`][unist-util-visit] +is smarter, such as when you want to change certain nodes. +On the other hand, this is quite powerful and fast enough for many other cases. ## Install -This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): -Node 12+ is needed to use it and it must be `import`ed instead of `require`d. - -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 14.14+, 16.0+), install with [npm][]: ```sh npm install unist-util-select ``` +In Deno with [`esm.sh`][esmsh]: + +```js +import {matches, select, selectAll} from "https://esm.sh/unist-util-select@4" +``` + +In browsers with [`esm.sh`][esmsh]: + +```html + +``` + +## Use + +```js +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')]) +]) + +matches('blockquote, list', tree) // => true + +console.log(select('code ~ :nth-child(even)', tree)) +// The paragraph with `Delta` + +console.log(selectAll('code ~ :nth-child(even)', tree)) +// The paragraphs with `Delta` and `Foxtrot` +``` + ## API -This package exports the following identifiers: `matches`, `select`, `selectAll`. +This package exports the identifiers `matches`, `select`, and `selectAll`. There is no default export. ### `matches(selector, node)` @@ -199,33 +270,35 @@ Yields: ###### Notes -* \* — Not supported in `matches` +* \* — not supported in `matches` + +## Types + +This package is fully typed with [TypeScript][]. +It exports no additional types. + +## Compatibility + +Projects maintained by the unified collective are compatible with all maintained +versions of Node.js. +As of now, that is Node.js 14.14+ and 16.0+. +Our projects sometimes work with older versions, but this is not guaranteed. ## Related -* [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter) - — Create a new tree with all nodes that pass a test -* [`unist-util-map`](https://github.com/syntax-tree/unist-util-map) - — Create a new tree with all nodes mapped by a given function -* [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap) - — Create a new tree by mapping (to an array) with the given function * [`unist-util-is`](https://github.com/syntax-tree/unist-util-is) - — Check if a node passes a test -* [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove) - — Remove nodes from trees -* [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position) - — Remove positional info from trees + — check if a node passes a test * [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit) - — Recursively walk over nodes + — recursively walk over nodes * [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents) - — Like `visit`, but with a stack of parents + — like `visit`, but with a stack of parents * [`unist-builder`](https://github.com/syntax-tree/unist-builder) - — Helper for creating trees + — create unist trees ## Contribute -See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get -started. +See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for +ways to get started. See [`support.md`][help] for ways to get help. This project has a [code of conduct][coc]. @@ -266,18 +339,30 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install +[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c + +[esmsh]: https://esm.sh + +[typescript]: https://www.typescriptlang.org + [license]: license -[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md +[health]: https://github.com/syntax-tree/.github -[help]: https://github.com/syntax-tree/.github/blob/HEAD/support.md +[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md -[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md +[help]: https://github.com/syntax-tree/.github/blob/main/support.md -[preorder]: https://github.com/syntax-tree/unist#preorder +[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md [unist]: https://github.com/syntax-tree/unist [node]: https://github.com/syntax-tree/unist#node -[support]: #support +[preorder]: https://github.com/syntax-tree/unist#preorder + +[unist-util-visit]: https://github.com/syntax-tree/unist-util-visit + +[hast]: https://github.com/syntax-tree/hast + +[hast-util-select]: https://github.com/syntax-tree/hast-util-select