1 | # unist-util-remove
|
2 |
|
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]
|
10 |
|
11 | [unist][] utility to remove all nodes that pass a test from the tree.
|
12 |
|
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 | * [`remove(tree[, options], test)`](#removetree-options-test)
|
21 | * [`Options`](#options)
|
22 | * [Types](#types)
|
23 | * [Compatibility](#compatibility)
|
24 | * [Related](#related)
|
25 | * [Contribute](#contribute)
|
26 | * [License](#license)
|
27 |
|
28 | ## What is this?
|
29 |
|
30 | This is a small utility that helps you clean a tree by removing some stuff.
|
31 |
|
32 | ## When should I use this?
|
33 |
|
34 | You can use this utility to remove things from a tree.
|
35 | This utility is very similar to [`unist-util-filter`][unist-util-filter], which
|
36 | creates a new tree.
|
37 | Modifying a tree like this utility `unist-util-remove` does is much faster on
|
38 | larger documents though.
|
39 |
|
40 | You can also walk the tree with [`unist-util-visit`][unist-util-visit] to remove
|
41 | nodes.
|
42 | To create trees, use [`unist-builder`][unist-builder].
|
43 |
|
44 | ## Install
|
45 |
|
46 | This package is [ESM only][esm].
|
47 | In Node.js (version 14.14+ and 16.0+), install with [npm][]:
|
48 |
|
49 | ```sh
|
50 | npm install unist-util-remove
|
51 | ```
|
52 |
|
53 | In Deno with [`esm.sh`][esmsh]:
|
54 |
|
55 | ```js
|
56 | import {remove} from 'https://esm.sh/unist-util-remove@3'
|
57 | ```
|
58 |
|
59 | In browsers with [`esm.sh`][esmsh]:
|
60 |
|
61 | ```html
|
62 | <script type="module">
|
63 | import {remove} from 'https://esm.sh/unist-util-remove@3?bundle'
|
64 | </script>
|
65 | ```
|
66 |
|
67 | ## Use
|
68 |
|
69 | ```js
|
70 | import {u} from 'unist-builder'
|
71 | import {remove} from 'unist-util-remove'
|
72 |
|
73 | const tree = u('root', [
|
74 | u('leaf', '1'),
|
75 | u('parent', [
|
76 | u('leaf', '2'),
|
77 | u('parent', [u('leaf', '3'), u('other', '4')]),
|
78 | u('parent', [u('leaf', '5')])
|
79 | ]),
|
80 | u('leaf', '6')
|
81 | ])
|
82 |
|
83 | // Remove all nodes of type `leaf`.
|
84 | remove(tree, 'leaf')
|
85 |
|
86 | console.dir(tree, {depth: null})
|
87 | ```
|
88 |
|
89 | Yields:
|
90 |
|
91 | ```js
|
92 | {
|
93 | type: 'root',
|
94 | children: [
|
95 | {
|
96 | type: 'parent',
|
97 | children: [{type: 'parent', children: [{type: 'other', value: '4'}]}]
|
98 | }
|
99 | ]
|
100 | }
|
101 | ```
|
102 |
|
103 | > 👉 **Note**: the parent of leaf `5` is also removed, `options.cascade` can
|
104 | > change that.
|
105 |
|
106 | ## API
|
107 |
|
108 | This package exports the identifier [`remove`][api-remove].
|
109 | There is no default export.
|
110 |
|
111 | ### `remove(tree[, options], test)`
|
112 |
|
113 | Change the given `tree` by removing all nodes that pass `test`.
|
114 |
|
115 | The tree is walked in *[preorder][]* (NLR), visiting the node itself, then its
|
116 | head, etc.
|
117 |
|
118 | ###### Parameters
|
119 |
|
120 | * `tree` ([`Node`][node])
|
121 | — tree to change
|
122 | * `options` ([`Options`][api-options], optional)
|
123 | — configuration
|
124 | * `test` ([`Test`][test], optional)
|
125 | — `unist-util-is` compatible test
|
126 |
|
127 | ###### Returns
|
128 |
|
129 | A changed given `tree`, without nodes that pass `test`.
|
130 |
|
131 | `null` is returned if `tree` itself didn’t pass the test or is cascaded away.
|
132 |
|
133 | ### `Options`
|
134 |
|
135 | Configuration (TypeScript type).
|
136 |
|
137 | ###### Fields
|
138 |
|
139 | * `cascade` (`boolean`, default: `true`)
|
140 | — whether to drop parent nodes if they had children, but all their children
|
141 | were filtered out
|
142 |
|
143 | ## Types
|
144 |
|
145 | This package is fully typed with [TypeScript][].
|
146 | It exports the additional type [`Options`][api-options].
|
147 |
|
148 | ## Compatibility
|
149 |
|
150 | Projects maintained by the unified collective are compatible with all maintained
|
151 | versions of Node.js.
|
152 | As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
|
153 | Our projects sometimes work with older versions, but this is not guaranteed.
|
154 |
|
155 | ## Related
|
156 |
|
157 | * [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
|
158 | — create a new tree with all nodes that pass the given function
|
159 | * [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap)
|
160 | — create a new tree by expanding a node into many
|
161 | * [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
|
162 | — create a new tree by mapping nodes
|
163 | * [`unist-util-select`](https://github.com/syntax-tree/unist-util-select)
|
164 | — select nodes with CSS-like selectors
|
165 | * [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
|
166 | — walk the tree
|
167 | * [`unist-builder`](https://github.com/syntax-tree/unist-builder)
|
168 | — create trees
|
169 |
|
170 | ## Contribute
|
171 |
|
172 | See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
|
173 | ways to get started.
|
174 | See [`support.md`][support] for ways to get help.
|
175 |
|
176 | This project has a [Code of Conduct][coc].
|
177 | By interacting with this repository, organisation, or community you agree to
|
178 | abide by its terms.
|
179 |
|
180 | ## License
|
181 |
|
182 | [MIT][license] © Eugene Sharygin
|
183 |
|
184 |
|
185 |
|
186 | [build-badge]: https://github.com/syntax-tree/unist-util-filter/workflows/main/badge.svg
|
187 |
|
188 | [build]: https://github.com/syntax-tree/unist-util-filter/actions
|
189 |
|
190 | [coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-filter.svg
|
191 |
|
192 | [coverage]: https://codecov.io/github/syntax-tree/unist-util-filter
|
193 |
|
194 | [downloads-badge]: https://img.shields.io/npm/dm/unist-util-filter.svg
|
195 |
|
196 | [downloads]: https://www.npmjs.com/package/unist-util-filter
|
197 |
|
198 | [size-badge]: https://img.shields.io/bundlephobia/minzip/unist-util-filter.svg
|
199 |
|
200 | [size]: https://bundlephobia.com/result?p=unist-util-filter
|
201 |
|
202 | [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
|
203 |
|
204 | [backers-badge]: https://opencollective.com/unified/backers/badge.svg
|
205 |
|
206 | [collective]: https://opencollective.com/unified
|
207 |
|
208 | [chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
|
209 |
|
210 | [chat]: https://github.com/syntax-tree/unist/discussions
|
211 |
|
212 | [npm]: https://docs.npmjs.com/cli/install
|
213 |
|
214 | [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
|
215 |
|
216 | [esmsh]: https://esm.sh
|
217 |
|
218 | [typescript]: https://www.typescriptlang.org
|
219 |
|
220 | [license]: license
|
221 |
|
222 | [health]: https://github.com/syntax-tree/.github
|
223 |
|
224 | [contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
|
225 |
|
226 | [support]: https://github.com/syntax-tree/.github/blob/main/support.md
|
227 |
|
228 | [coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
|
229 |
|
230 | [unist]: https://github.com/syntax-tree/unist
|
231 |
|
232 | [node]: https://github.com/syntax-tree/unist#node
|
233 |
|
234 | [preorder]: https://github.com/syntax-tree/unist#preorder
|
235 |
|
236 | [test]: https://github.com/syntax-tree/unist-util-is#test
|
237 |
|
238 | [unist-util-filter]: https://github.com/syntax-tree/unist-util-filter
|
239 |
|
240 | [unist-util-visit]: https://github.com/syntax-tree/unist-util-visit
|
241 |
|
242 | [unist-builder]: https://github.com/syntax-tree/unist-builder
|
243 |
|
244 | [api-remove]: #removetree-options-test
|
245 |
|
246 | [api-options]: #options
|