Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
unist-util-remove
Advanced tools
unist-util-remove - npm Package Compare versions
Comparing version 3.1.0 to 3.1.1
@@ -1,65 +0,3 @@ | ||
| export const remove: (<Tree extends import('unist').Node<import('unist').Data>>( | ||
| node: Tree, | ||
| options: RemoveOptions, | ||
| test: | ||
| | string | ||
| | import('unist-util-is').Props | ||
| | TestFunction< | ||
| import('unist-util-visit-parents/complex-types').InclusiveDescendant< | ||
| Tree, | ||
| void | ||
| > | ||
| > | ||
| | ( | ||
| | string | ||
| | import('unist-util-is').Props | ||
| | TestFunction< | ||
| import('unist-util-visit-parents/complex-types').InclusiveDescendant< | ||
| Tree, | ||
| void | ||
| > | ||
| > | ||
| )[] | ||
| ) => Tree | null) & | ||
| (<Tree_1 extends import('unist').Node<import('unist').Data>>( | ||
| node: Tree_1, | ||
| test: | ||
| | string | ||
| | import('unist-util-is').Props | ||
| | TestFunction< | ||
| import('unist-util-visit-parents/complex-types').InclusiveDescendant< | ||
| Tree_1, | ||
| void | ||
| > | ||
| > | ||
| | ( | ||
| | string | ||
| | import('unist-util-is').Props | ||
| | TestFunction< | ||
| import('unist-util-visit-parents/complex-types').InclusiveDescendant< | ||
| Tree_1, | ||
| void | ||
| > | ||
| > | ||
| )[] | ||
| ) => Tree_1 | null) | ||
| export type Node = import('unist').Node | ||
| export type Parent = import('unist').Parent | ||
| export type Type = import('unist-util-is').Type | ||
| export type Props = import('unist-util-is').Props | ||
| /** | ||
| * Check if a node passes a test | ||
| */ | ||
| export type TestFunction< | ||
| Tree extends import('unist').Node<import('unist').Data> | ||
| > = ( | ||
| node: Tree, | ||
| index?: number | null | undefined, | ||
| parent?: Parent | null | undefined | ||
| ) => boolean | void | ||
| export type RemoveOptions = { | ||
| /** | ||
| * Whether to drop parent nodes if they had children, but all their children were filtered out test | ||
| */ | ||
| cascade?: boolean | undefined | ||
| } | ||
| export {remove} from './lib/index.js' | ||
| export type Options = import('./lib/index.js').Options | ||
| export type RemoveOptions = Options |
95
index.js
| /** | ||
| * @typedef {import('unist').Node} Node | ||
| * @typedef {import('unist').Parent} Parent | ||
| * | ||
| * @typedef {import('unist-util-is').Type} Type | ||
| * @typedef {import('unist-util-is').Props} Props | ||
| * @typedef {import('./lib/index.js').Options} Options | ||
| */ | ||
| // To do: next major: remove. | ||
| /** | ||
| * Check if a node passes a test | ||
| * | ||
| * @template {Node} Tree Node type that is checked. | ||
| * @callback TestFunction | ||
| * @param {Tree} node | ||
| * @param {number|null|undefined} [index] | ||
| * @param {Parent|null|undefined} [parent] | ||
| * @returns {boolean|void} | ||
| * @typedef {Options} RemoveOptions | ||
| */ | ||
| /** | ||
| * @typedef {Object} RemoveOptions | ||
| * @property {boolean} [cascade] Whether to drop parent nodes if they had children, but all their children were filtered out test | ||
| */ | ||
| import {convert} from 'unist-util-is' | ||
| /** @type {Array.<Node>} */ | ||
| const empty = [] | ||
| export const remove = | ||
| /** | ||
| * @type {( | ||
| * (<Tree extends Node>(node: Tree, options: RemoveOptions, test: Type|Props|TestFunction<import('unist-util-visit-parents/complex-types').InclusiveDescendant<Tree>>|Array<Type|Props|TestFunction<import('unist-util-visit-parents/complex-types').InclusiveDescendant<Tree>>>) => Tree|null) & | ||
| * (<Tree extends Node>(node: Tree, test: Type|Props|TestFunction<import('unist-util-visit-parents/complex-types').InclusiveDescendant<Tree>>|Array<Type|Props|TestFunction<import('unist-util-visit-parents/complex-types').InclusiveDescendant<Tree>>>) => Tree|null) | ||
| * )} | ||
| */ | ||
| ( | ||
| /** | ||
| * Mutate the given tree by removing all nodes that pass `test`. | ||
| * The tree is walked in preorder (NLR), visiting the node itself, then its head, etc. | ||
| * | ||
| * @param {Node} tree Tree to filter | ||
| * @param {RemoveOptions} options Whether to drop parent nodes if they had children, but all their children were filtered out. Default is `{cascade: true}` | ||
| * @param {Type|Props|TestFunction<Node>|Array<Type|Props|TestFunction<Node>>} test is-compatible test (such as a type) | ||
| * @returns {Node|null} | ||
| */ | ||
| function (tree, options, test) { | ||
| const is = convert(test || options) | ||
| const cascade = | ||
| options.cascade === undefined || options.cascade === null | ||
| ? true | ||
| : options.cascade | ||
| return preorder(tree) | ||
| /** | ||
| * Check and remove nodes recursively in preorder. | ||
| * For each composite node, modify its children array in-place. | ||
| * | ||
| * @param {Node} node | ||
| * @param {number|undefined} [index] | ||
| * @param {Parent|undefined} [parent] | ||
| * @returns {Node|null} | ||
| */ | ||
| function preorder(node, index, parent) { | ||
| /** @type {Array.<Node>} */ | ||
| // @ts-expect-error looks like a parent. | ||
| const children = node.children || empty | ||
| let childIndex = -1 | ||
| let position = 0 | ||
| if (is(node, index, parent)) { | ||
| return null | ||
| } | ||
| if (children.length > 0) { | ||
| // Move all living children to the beginning of the children array. | ||
| while (++childIndex < children.length) { | ||
| // @ts-expect-error looks like a parent. | ||
| if (preorder(children[childIndex], childIndex, node)) { | ||
| children[position++] = children[childIndex] | ||
| } | ||
| } | ||
| // Cascade delete. | ||
| if (cascade && !position) { | ||
| return null | ||
| } | ||
| // Drop other nodes. | ||
| children.length = position | ||
| } | ||
| return node | ||
| } | ||
| } | ||
| ) | ||
| export {remove} from './lib/index.js' |
| { | ||
| "name": "unist-util-remove", | ||
| "version": "3.1.0", | ||
| "version": "3.1.1", | ||
| "description": "unist utility to remove nodes from a tree", | ||
@@ -37,2 +37,3 @@ "license": "MIT", | ||
| "files": [ | ||
| "lib/", | ||
| "index.d.ts", | ||
@@ -47,21 +48,18 @@ "index.js" | ||
| "devDependencies": { | ||
| "@types/tape": "^4.0.0", | ||
| "@types/node": "^18.0.0", | ||
| "c8": "^7.0.0", | ||
| "prettier": "^2.0.0", | ||
| "remark-cli": "^9.0.0", | ||
| "remark-preset-wooorm": "^8.0.0", | ||
| "rimraf": "^3.0.0", | ||
| "tape": "^5.0.0", | ||
| "remark-cli": "^11.0.0", | ||
| "remark-preset-wooorm": "^9.0.0", | ||
| "type-coverage": "^2.0.0", | ||
| "typescript": "^4.0.0", | ||
| "unist-builder": "^3.0.0", | ||
| "xo": "^0.42.0" | ||
| "xo": "^0.53.0" | ||
| }, | ||
| "scripts": { | ||
| "prepack": "npm run build && npm run format", | ||
| "build": "rimraf \"*.d.ts\" && tsc && type-coverage", | ||
| "build": "tsc --build --clean && tsc --build && type-coverage", | ||
| "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix", | ||
| "test-api": "node test.js", | ||
| "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js", | ||
| "test-types": "dtslint types", | ||
| "test-api": "node --conditions development test.js", | ||
| "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api", | ||
| "test": "npm run build && npm run format && npm run test-coverage" | ||
@@ -68,0 +66,0 @@ }, |
161
readme.md
@@ -11,12 +11,40 @@ # unist-util-remove | ||
| [**unist**][unist] utility to modify the given tree by removing all nodes that | ||
| pass the given test. | ||
| [unist][] utility to remove all nodes that pass a test from the tree. | ||
| ## Contents | ||
| * [What is this?](#what-is-this) | ||
| * [When should I use this?](#when-should-i-use-this) | ||
| * [Install](#install) | ||
| * [Use](#use) | ||
| * [API](#api) | ||
| * [`remove(tree[, options], test)`](#removetree-options-test) | ||
| * [`Options`](#options) | ||
| * [Types](#types) | ||
| * [Compatibility](#compatibility) | ||
| * [Related](#related) | ||
| * [Contribute](#contribute) | ||
| * [License](#license) | ||
| ## What is this? | ||
| This is a small utility that helps you clean a tree by removing some stuff. | ||
| ## When should I use this? | ||
| You can use this utility to remove things from a tree. | ||
| This utility is very similar to [`unist-util-filter`][unist-util-filter], which | ||
| creates a new tree. | ||
| Modifying a tree like this utility `unist-util-remove` does is much faster on | ||
| larger documents though. | ||
| You can also walk the tree with [`unist-util-visit`][unist-util-visit] to remove | ||
| nodes. | ||
| To create trees, use [`unist-builder`][unist-builder]. | ||
| ## 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. | ||
| This package is [ESM only][esm]. | ||
| In Node.js (version 14.14+ and 16.0+), install with [npm][]: | ||
| [npm][]: | ||
| ```sh | ||
@@ -26,2 +54,16 @@ npm install unist-util-remove | ||
| In Deno with [`esm.sh`][esmsh]: | ||
| ```js | ||
| import {remove} from 'https://esm.sh/unist-util-remove@3' | ||
| ``` | ||
| In browsers with [`esm.sh`][esmsh]: | ||
| ```html | ||
| <script type="module"> | ||
| import {remove} from 'https://esm.sh/unist-util-remove@3?bundle' | ||
| </script> | ||
| ``` | ||
| ## Use | ||
@@ -35,6 +77,6 @@ | ||
| u('leaf', '1'), | ||
| u('node', [ | ||
| u('parent', [ | ||
| u('leaf', '2'), | ||
| u('node', [u('leaf', '3'), u('other', '4')]), | ||
| u('node', [u('leaf', '5')]) | ||
| u('parent', [u('leaf', '3'), u('other', '4')]), | ||
| u('parent', [u('leaf', '5')]) | ||
| ]), | ||
@@ -50,3 +92,3 @@ u('leaf', '6') | ||
| Yields: (note the parent of `5` is also removed, due to `options.cascade`) | ||
| Yields: | ||
@@ -58,4 +100,4 @@ ```js | ||
| { | ||
| type: 'node', | ||
| children: [{type: 'node', children: [{type: 'other', value: '4'}]}] | ||
| type: 'parent', | ||
| children: [{type: 'parent', children: [{type: 'other', value: '4'}]}] | ||
| } | ||
@@ -66,5 +108,8 @@ ] | ||
| > 👉 **Note**: the parent of leaf `5` is also removed, `options.cascade` can | ||
| > change that. | ||
| ## API | ||
| This package exports the following identifiers: `remove`. | ||
| This package exports the identifier [`remove`][api-remove]. | ||
| There is no default export. | ||
@@ -74,39 +119,63 @@ | ||
| Mutate the given [tree][] by removing all nodes that pass `test`. | ||
| The tree is walked in [preorder][] (NLR), visiting the node itself, then its | ||
| [head][], etc. | ||
| Change the given `tree` by removing all nodes that pass `test`. | ||
| The tree is walked in *[preorder][]* (NLR), visiting the node itself, then its | ||
| head, etc. | ||
| ###### Parameters | ||
| * `tree` ([`Node?`][node]) | ||
| — [Tree][] to filter | ||
| * `options.cascade` (`boolean`, default: `true`) | ||
| — Whether to drop parent nodes if they had children, but all their children | ||
| were filtered out | ||
| * `test` ([`Test`][is]) — [`is`][is]-compatible test (such as a [type][]) | ||
| * `tree` ([`Node`][node]) | ||
| — tree to change | ||
| * `options` ([`Options`][api-options], optional) | ||
| — configuration | ||
| * `test` ([`Test`][test], optional) | ||
| — `unist-util-is` compatible test | ||
| ###### Returns | ||
| [`Node?`][node] — The given `tree` with nodes for which `test` passed removed. | ||
| `null` is returned if `tree` itself didn’t pass the test, or is cascaded away. | ||
| A changed given `tree`, without nodes that pass `test`. | ||
| `null` is returned if `tree` itself didn’t pass the test or is cascaded away. | ||
| ### `Options` | ||
| Configuration (TypeScript type). | ||
| ###### Fields | ||
| * `cascade` (`boolean`, default: `true`) | ||
| — whether to drop parent nodes if they had children, but all their children | ||
| were filtered out | ||
| ## Types | ||
| This package is fully typed with [TypeScript][]. | ||
| It exports the additional type [`Options`][api-options]. | ||
| ## Compatibility | ||
| Projects maintained by the unified collective are compatible with all maintained | ||
| versions of Node.js. | ||
| As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.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 the given function | ||
| — create a new tree with all nodes that pass the given function | ||
| * [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap) | ||
| — Create a new tree by expanding a node into many | ||
| — create a new tree by expanding a node into many | ||
| * [`unist-util-map`](https://github.com/syntax-tree/unist-util-map) | ||
| — Create a new tree by mapping nodes | ||
| — create a new tree by mapping nodes | ||
| * [`unist-util-select`](https://github.com/syntax-tree/unist-util-select) | ||
| — Select nodes with CSS-like selectors | ||
| — select nodes with CSS-like selectors | ||
| * [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit) | ||
| — Recursively walk over nodes | ||
| — walk the tree | ||
| * [`unist-builder`](https://github.com/syntax-tree/unist-builder) | ||
| — Creating trees | ||
| — create 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`][support] for ways to get help. | ||
@@ -152,4 +221,18 @@ | ||
| [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c | ||
| [esmsh]: https://esm.sh | ||
| [typescript]: https://www.typescriptlang.org | ||
| [license]: license | ||
| [health]: https://github.com/syntax-tree/.github | ||
| [contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md | ||
| [support]: https://github.com/syntax-tree/.github/blob/main/support.md | ||
| [coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md | ||
| [unist]: https://github.com/syntax-tree/unist | ||
@@ -159,16 +242,14 @@ | ||
| [tree]: https://github.com/syntax-tree/unist#tree | ||
| [preorder]: https://github.com/syntax-tree/unist#preorder | ||
| [head]: https://github.com/syntax-tree/unist#head | ||
| [test]: https://github.com/syntax-tree/unist-util-is#test | ||
| [type]: https://github.com/syntax-tree/unist#type | ||
| [unist-util-filter]: https://github.com/syntax-tree/unist-util-filter | ||
| [is]: https://github.com/syntax-tree/unist-util-is | ||
| [unist-util-visit]: https://github.com/syntax-tree/unist-util-visit | ||
| [contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md | ||
| [unist-builder]: https://github.com/syntax-tree/unist-builder | ||
| [support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md | ||
| [api-remove]: #removetree-options-test | ||
| [coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md | ||
| [api-options]: #options |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by6.78%
13867
- Dev dependency count
- decreased by-18.18%
9
- Number of package files
- increased by40%
7
- Number of lines in readme file
- increased by48.8%
247
Worsened metrics
- Lines of code
- decreased by-5.96%
142
- Number of medium supply chain risk alerts
- increased byInfinity%
1
No dependency changes