Skip to content

Commit 5b1e08d

Browse files
wooormwooorm
committed
Refactor docs
1 parent 964950a commit 5b1e08d

File tree

3 files changed

+244
-36
lines changed

3 files changed

+244
-36
lines changed

‎README.md

Lines changed: 219 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,92 @@
1-
# unist-util-find [![Travis](https://img.shields.io/travis/blahah/unist-util-find.svg)](https://travis-ci.org/blahah/unist-util-find)
1+
# unist-util-find
22

3-
[Unist](https://github.com/wooorm/unist) node finder utility. Useful for working with [remark](https://github.com/wooorm/remark), [rehype](https://github.com/wooorm/rehype) and [retext](https://github.com/wooorm/retext).
3+
[![Build][build-badge]][build]
4+
[![Coverage][coverage-badge]][coverage]
5+
[![Downloads][downloads-badge]][downloads]
6+
[![Size][size-badge]][size]
7+
[![Sponsors][sponsors-badge]][collective]
8+
[![Backers][backers-badge]][collective]
9+
[![Chat][chat-badge]][chat]
410

5-
## Installation
11+
[unist][] utility to find a node.
612

13+
## Contents
14+
15+
* [What is this?](#what-is-this)
16+
* [When should I use this?](#when-should-i-use-this)
17+
* [Install](#install)
18+
* [Use](#use)
19+
* [API](#api)
20+
* [`find(tree, condition)`](#findtree-condition)
21+
* [`TestFn`](#testfn)
22+
* [`TestObj`](#testobj)
23+
* [`TestStr`](#teststr)
24+
* [Types](#types)
25+
* [Compatibility](#compatibility)
26+
* [Security](#security)
27+
* [Related](#related)
28+
* [Contribute](#contribute)
29+
* [License](#license)
30+
31+
## What is this?
32+
33+
This package is a utility that takes any [unist][] (whether mdast, hast, etc)
34+
node and returns the first node that matches a given condition.
35+
36+
## When should I use this?
37+
38+
This utility is the simplest way to find a single node in a tree.
39+
40+
For much more powerful tree walking, see [`unist-util-visit`][visit].
41+
42+
## Install
43+
44+
This package is [ESM only][esm].
45+
In Node.js (version 16+), install with [npm][]:
46+
47+
```sh
48+
npm install unist-util-find
749
```
8-
npm install --save unist-util-find
50+
51+
In Deno with [`esm.sh`][esmsh]:
52+
53+
```js
54+
import {find} from 'https://esm.sh/unist-util-find@1'
955
```
1056

11-
## Usage
57+
In browsers with [`esm.sh`][esmsh]:
1258

13-
### Example
59+
```html
60+
<script type="module">
61+
import {find} from 'https://esm.sh/unist-util-find@1?bundle'
62+
</script>
63+
```
64+
65+
## Use
1466

1567
```js
1668
import {fromMarkdown} from 'mdast-util-from-markdown'
17-
import {find} from './index.js'
69+
import {find} from 'unist-util-find'
1870

1971
const tree = fromMarkdown('Some _emphasis_, **strongness**, and `code`.')
2072

21-
// String condition
73+
// String condition:
2274
console.log(find(tree, 'value'))
2375

24-
// Object condition
76+
// Object condition:
2577
console.log(find(tree, {value: 'emphasis'}))
2678

27-
// Function condition
79+
// Function condition:
2880
console.log(
2981
find(tree, function (node) {
3082
return node.type === 'inlineCode'
3183
})
3284
)
3385
```
3486

35-
Result:
87+
Yields:
3688

37-
```
89+
```js
3890
// string condition: 'value'
3991
{
4092
type: 'text',
@@ -66,18 +118,164 @@ Result:
66118
}
67119
```
68120

69-
### API
121+
## API
122+
123+
This package exports the identifier [`find`][api-find].
124+
There is no default export.
125+
126+
### `find(tree, condition)`
127+
128+
Find a node in `tree` matching `condition`.
129+
130+
###### Parameters
131+
132+
* `tree` ([`Node`][node])
133+
— tree to search in
134+
* `condition` ([`TestFn`][api-test-fn], [`TestObj`][api-test-obj], or
135+
[`TestStr`][api-test-str])
136+
— condition used to test each node
137+
138+
###### Returns
139+
140+
The first node ([`Node`][node]) that matches condition, or `undefined` if no
141+
node matches
142+
143+
### `TestFn`
144+
145+
Find the first node for which function returns `true` when passed node as
146+
argument (TypeScript type).
147+
148+
###### Parameters
149+
150+
* `node` ([`Node`][node])
151+
— node to check
152+
153+
###### Returns
154+
155+
Whether `node` matches your condition (`boolean`).
156+
157+
### `TestObj`
158+
159+
Find the first node that has matching values for all properties of object
160+
(TypeScript type).
161+
162+
###### Type
163+
164+
```ts
165+
type TestObj = Record<string, unknown>;
166+
```
167+
168+
### `TestStr`
169+
170+
Find the first node with a truthy property matching `string` (TypeScript type).
171+
172+
###### Type
173+
174+
```ts
175+
type TestStr = string;
176+
```
177+
178+
## Types
179+
180+
This package is fully typed with [TypeScript][].
181+
It exports the additional types [`TestFn`][api-test-fn],
182+
[`TestObj`][api-test-obj], and [`TestStr`][api-test-str].
183+
184+
## Compatibility
185+
186+
Projects maintained by the unified collective are compatible with maintained
187+
versions of Node.js.
188+
189+
When we cut a new major release, we drop support for unmaintained versions of
190+
Node.
191+
This means we try to keep the current release line,
192+
`unist-util-find@^1`, compatible with Node.js 12.
70193

71-
#### `find(node, condition)`
194+
## Security
72195

73-
Return the first node that matches `condition`, or `undefined` if no node matches.
196+
This project is safe.
74197

75-
- `node` ([`Node`](https://github.com/wooorm/unist#node)) - Node to search
76-
- `condition` (`string`, `object` or `function`) - Condition used to test each node. Behaviour depends on the type of the condition:
77-
- `string` finds first node with a truthy property matching `string`
78-
- `object` finds first node that has matching values for all properties of `object`
79-
- `function` finds first node for which `function` returns true when passed `node` as argument
198+
## Related
199+
200+
* [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated)
201+
— check if a node is generated
202+
* [`unist-util-position`](https://github.com/syntax-tree/unist-util-position)
203+
— get positional info of nodes
204+
* [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position)
205+
— remove positional info from trees
206+
* [`unist-util-source`](https://github.com/syntax-tree/unist-util-source)
207+
— get the source of a value (node or position) in a file
208+
209+
## Contribute
210+
211+
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
212+
started.
213+
See [`support.md`][support] for ways to get help.
214+
215+
This project has a [code of conduct][coc].
216+
By interacting with this repository, organization, or community you agree to
217+
abide by its terms.
80218

81219
## License
82220

83-
MIT
221+
[MIT][license] © [Titus Wormer][author]
222+
223+
<!-- Definition -->
224+
225+
[build-badge]: https://github.com/syntax-tree/unist-util-find/workflows/main/badge.svg
226+
227+
[build]: https://github.com/syntax-tree/unist-util-find/actions
228+
229+
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-find.svg
230+
231+
[coverage]: https://codecov.io/github/syntax-tree/unist-util-find
232+
233+
[downloads-badge]: https://img.shields.io/npm/dm/unist-util-find.svg
234+
235+
[downloads]: https://www.npmjs.com/package/unist-util-find
236+
237+
[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-find
238+
239+
[size]: https://bundlejs.com/?q=unist-util-find
240+
241+
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
242+
243+
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
244+
245+
[collective]: https://opencollective.com/unified
246+
247+
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
248+
249+
[chat]: https://github.com/syntax-tree/unist/discussions
250+
251+
[npm]: https://docs.npmjs.com/cli/install
252+
253+
[license]: license
254+
255+
[author]: https://wooorm.com
256+
257+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
258+
259+
[esmsh]: https://esm.sh
260+
261+
[typescript]: https://www.typescriptlang.org
262+
263+
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
264+
265+
[support]: https://github.com/syntax-tree/.github/blob/main/support.md
266+
267+
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
268+
269+
[unist]: https://github.com/syntax-tree/unist
270+
271+
[visit]: https://github.com/syntax-tree/unist-util-visit
272+
273+
[node]: https://github.com/syntax-tree/unist#node
274+
275+
[api-find]: #findtree-condition
276+
277+
[api-test-fn]: #testfn
278+
279+
[api-test-obj]: #testobj
280+
281+
[api-test-str]: #teststr

‎index.js

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,34 @@
11
/**
2-
* @author Richard Smith-Unna
3-
* @copyright 2016 Richard Smith-Unnar
4-
* @license MIT
5-
* @module unist:find
6-
* @fileoverview Unist node finder
7-
*
82
* @typedef {import('unist').Node} Node
3+
*/
4+
5+
/**
6+
* @callback TestFn
7+
* Find the first node for which function returns `true` when passed node as
8+
* argument.
9+
* @param {Node} node
10+
* Node to check.
11+
* @returns {boolean}
12+
* Whether `node` matches your condition.
13+
*
14+
* @typedef {Record<string, unknown>} TestObj
15+
* Find the first node that has matching values for all properties of object.
916
*
1017
* @typedef {string} TestStr
11-
* Finds first node with a truthy property matching string.
12-
* @typedef {Object.<string, unknown>} TestObj
13-
* Finds first node that has matching values for all properties of object.
14-
* @typedef {<V extends Node>(node: V) => boolean} TestFn
15-
* Finds first node for which function returns true when passed node as argument.
18+
* Find the first node with a truthy property matching `string`.
1619
*/
1720

1821
import {visit} from 'unist-util-visit'
1922
import iteratee from 'lodash.iteratee'
2023

2124
/**
22-
* Unist node finder utility.
25+
* Find a node in `tree` matching `condition`.
2326
*
2427
* @template {Node} V
2528
* Node to search for.
2629
* @param {Node} tree
2730
* Tree to search in.
28-
* @param {TestStr | TestObj | TestFn} condition
31+
* @param {TestFn | TestObj | TestStr} condition
2932
* Condition used to test each node, which matches `V`.
3033
* @returns {V | undefined}
3134
* The first node that matches condition, or `undefined` if no node matches.

‎package.json

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,12 @@
4444
"devDependencies": {
4545
"@types/lodash.iteratee": "^4.0.0",
4646
"@types/tape": "^5.0.0",
47-
"@types/unist": "^2.0.6",
47+
"@types/unist": "^2.0.0",
4848
"c8": "^8.0.0",
4949
"mdast-util-from-markdown": "^1.0.0",
5050
"prettier": "^2.0.0",
51+
"remark-cli": "^11.0.0",
52+
"remark-preset-wooorm": "^9.0.0",
5153
"tape": "^5.0.0",
5254
"type-coverage": "^2.0.0",
5355
"typescript": "^5.0.0",
@@ -56,7 +58,7 @@
5658
"scripts": {
5759
"prepack": "npm run build && npm run format",
5860
"build": "tsc --build --clean && tsc --build && type-coverage",
59-
"format": "prettier . -w --loglevel warn && xo --fix",
61+
"format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
6062
"test-api": "node --conditions development test.js",
6163
"test-coverage": "c8 --100 --reporter lcov npm run test-api",
6264
"test": "npm run build && npm run format && npm run test-coverage"
@@ -69,6 +71,11 @@
6971
"trailingComma": "none",
7072
"useTabs": false
7173
},
74+
"remarkConfig": {
75+
"plugins": [
76+
"remark-preset-wooorm"
77+
]
78+
},
7279
"typeCoverage": {
7380
"atLeast": 100,
7481
"detail": true,

0 commit comments

Comments
 (0)