Skip to content

Commit 332b6e0

Browse files
committedJan 24, 2023
Add improved docs
1 parent 83df9b3 commit 332b6e0

File tree

1 file changed

+131
-16
lines changed

1 file changed

+131
-16
lines changed
 

‎readme.md

+131-16
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,16 @@
1818
* [Use](#use)
1919
* [API](#api)
2020
* [`visit(tree[, test], visitor[, reverse])`](#visittree-test-visitor-reverse)
21+
* [`CONTINUE`](#continue)
22+
* [`EXIT`](#exit)
23+
* [`SKIP`](#skip)
24+
* [`Action`](#action)
25+
* [`ActionTuple`](#actiontuple)
26+
* [`BuildVisitor`](#buildvisitor)
27+
* [`Index`](#index)
28+
* [`Test`](#test)
29+
* [`Visitor`](#visitor)
30+
* [`VisitorResult`](#visitorresult)
2131
* [Types](#types)
2232
* [Compatibility](#compatibility)
2333
* [Related](#related)
@@ -38,7 +48,7 @@ of parents.
3848
## Install
3949

4050
This package is [ESM only][esm].
41-
In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:
51+
In Node.js (version 14.14+ and 16.0+), install with [npm][]:
4252

4353
```sh
4454
npm install unist-util-visit
@@ -47,14 +57,14 @@ npm install unist-util-visit
4757
In Deno with [`esm.sh`][esmsh]:
4858

4959
```js
50-
import {visit} from "https://esm.sh/unist-util-visit@4"
60+
import {visit} from 'https://esm.sh/unist-util-visit@4'
5161
```
5262

5363
In browsers with [`esm.sh`][esmsh]:
5464

5565
```html
5666
<script type="module">
57-
import {visit} from "https://esm.sh/unist-util-visit@4?bundle"
67+
import {visit} from 'https://esm.sh/unist-util-visit@4?bundle'
5868
</script>
5969
```
6070

@@ -86,29 +96,102 @@ Yields:
8696

8797
## API
8898

89-
This package exports the identifiers `visit`, `CONTINUE`, `SKIP`, and `EXIT`.
99+
This package exports the identifiers [`CONTINUE`][api-continue],
100+
[`EXIT`][api-exit], [`SKIP`][api-skip], and [`visit`][api-visit].
90101
There is no default export.
91102

92103
### `visit(tree[, test], visitor[, reverse])`
93104

94105
This function works exactly the same as [`unist-util-visit-parents`][vp],
95-
but `visitor` has a different signature.
106+
but [`Visitor`][api-visitor] has a different signature.
96107

97-
#### `next? = visitor(node, index, parent)`
108+
### `CONTINUE`
98109

99-
Instead of being passed an array of ancestors, `visitor` is called with the
100-
`node`’s [`index`][index] and its [`parent`][parent].
110+
Continue traversing as normal (`true`).
101111

102-
Please see [`unist-util-visit-parents`][vp].
112+
### `EXIT`
113+
114+
Stop traversing immediately (`false`).
115+
116+
### `SKIP`
117+
118+
Do not traverse this node’s children (`'skip'`).
119+
120+
### `Action`
121+
122+
Union of the action types (TypeScript type).
123+
See [`Action` in `unist-util-visit-parents`][vp-action].
124+
125+
### `ActionTuple`
126+
127+
List with an action and an index (TypeScript type).
128+
See [`ActionTuple` in `unist-util-visit-parents`][vp-actiontuple].
129+
130+
### `BuildVisitor`
131+
132+
Build a typed `Visitor` function from a tree and a test (TypeScript type).
133+
See [`BuildVisitor` in `unist-util-visit-parents`][vp-buildvisitor].
134+
135+
### `Index`
136+
137+
Move to the sibling at `index` next (TypeScript type).
138+
See [`Index` in `unist-util-visit-parents`][vp-index].
139+
140+
### `Test`
141+
142+
[`unist-util-is`][unist-util-is] compatible test (TypeScript type).
143+
144+
### `Visitor`
145+
146+
Handle a node (matching `test`, if given) (TypeScript type).
147+
148+
Visitors are free to transform `node`.
149+
They can also transform `parent`.
150+
151+
Replacing `node` itself, if `SKIP` is not returned, still causes its
152+
descendants to be walked (which is a bug).
153+
154+
When adding or removing previous siblings of `node` (or next siblings, in
155+
case of reverse), the `Visitor` should return a new `Index` to specify the
156+
sibling to traverse after `node` is traversed.
157+
Adding or removing next siblings of `node` (or previous siblings, in case
158+
of reverse) is handled as expected without needing to return a new `Index`.
159+
160+
Removing the children property of `parent` still results in them being
161+
traversed.
162+
163+
###### Parameters
164+
165+
* `node` ([`Node`][node])
166+
— found node
167+
* `index` (`number` or `null`)
168+
— index of `node` in `parent`
169+
* `parent` ([`Node`][node] or `null`)
170+
— parent of `node`
171+
172+
###### Returns
173+
174+
What to do next.
175+
176+
An `Index` is treated as a tuple of `[CONTINUE, Index]`.
177+
An `Action` is treated as a tuple of `[Action]`.
178+
179+
Passing a tuple back only makes sense if the `Action` is `SKIP`.
180+
When the `Action` is `EXIT`, that action can be returned.
181+
When the `Action` is `CONTINUE`, `Index` can be returned.
182+
183+
### `VisitorResult`
184+
185+
Any value that can be returned from a visitor (TypeScript type).
186+
See [`VisitorResult` in `unist-util-visit-parents`][vp-visitorresult].
103187

104188
## Types
105189

106190
This package is fully typed with [TypeScript][].
107-
It exports the additional types `Test`, `VisitorResult`, and `Visitor`.
108-
109-
It also exports the types `BuildVisitor<Tree extends Node = Node, Check extends
110-
Test = string>` to properly type visitors from a tree and a test, from
111-
`unist-util-visit-parents/complex-types.d.ts`.
191+
It exports the additional types [`Action`][api-action],
192+
[`ActionTuple`][api-actiontuple], [`BuildVisitor`][api-buildvisitor],
193+
[`Index`][api-index], [`Test`][api-test], [`Visitor`][api-visitor], and
194+
[`VisitorResult`][api-visitorresult].
112195

113196
## Compatibility
114197

@@ -196,8 +279,40 @@ abide by its terms.
196279

197280
[unist]: https://github.com/syntax-tree/unist
198281

282+
[node]: https://github.com/syntax-tree/unist#nodes
283+
284+
[unist-util-is]: https://github.com/syntax-tree/unist-util-is
285+
199286
[vp]: https://github.com/syntax-tree/unist-util-visit-parents
200287

201-
[index]: https://github.com/syntax-tree/unist#index
288+
[vp-action]: https://github.com/syntax-tree/unist-util-visit-parents#action
289+
290+
[vp-actiontuple]: https://github.com/syntax-tree/unist-util-visit-parents#actiontuple
291+
292+
[vp-buildvisitor]: https://github.com/syntax-tree/unist-util-visit-parents#buildvisitor
293+
294+
[vp-index]: https://github.com/syntax-tree/unist-util-visit-parents#index
295+
296+
[vp-visitorresult]: https://github.com/syntax-tree/unist-util-visit-parents#visitorresult
297+
298+
[api-visit]: #visittree-test-visitor-reverse
299+
300+
[api-continue]: #continue
301+
302+
[api-exit]: #exit
303+
304+
[api-skip]: #skip
305+
306+
[api-action]: #action
307+
308+
[api-actiontuple]: #actiontuple
309+
310+
[api-buildvisitor]: #buildvisitor
311+
312+
[api-index]: #index
313+
314+
[api-test]: #test
315+
316+
[api-visitor]: #visitor
202317

203-
[parent]: https://github.com/syntax-tree/unist#parent-1
318+
[api-visitorresult]: #visitorresult

0 commit comments

Comments
 (0)
Please sign in to comment.