Awesome
unist-util-is
unist utility to check if nodes pass a test.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Examples
- Types
- Compatibility
- Related
- Contribute
- License
What is this?
This package is a small utility that checks that a node is a certain node.
When should I use this?
Use this small utility if you find yourself repeating code for checking what nodes are.
A similar package, hast-util-is-element
, works on hast
elements.
For more advanced tests, unist-util-select
can be used
to match against CSS selectors.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install unist-util-is
In Deno with esm.sh
:
import {is} from 'https://esm.sh/unist-util-is@6'
In browsers with esm.sh
:
<script type="module">
import {is} from 'https://esm.sh/unist-util-is@6?bundle'
</script>
Use
import {is} from 'unist-util-is'
const node = {type: 'strong'}
const parent = {type: 'paragraph', children: [node]}
is() // => false
is({children: []}) // => false
is(node) // => true
is(node, 'strong') // => true
is(node, 'emphasis') // => false
is(node, node) // => true
is(parent, {type: 'paragraph'}) // => true
is(parent, {type: 'strong'}) // => false
is(node, test) // => false
is(node, test, 4, parent) // => false
is(node, test, 5, parent) // => true
function test(node, n) {
return n === 5
}
API
This package exports the identifiers convert
and
is
.
There is no default export.
is(node[, test[, index, parent[, context]]])
Check if node
is a Node
and whether it passes the given test.
Parameters
node
(unknown
, optional) — thing to check, typicallyNode
test
(Test
, optional) — a test for a specific elementindex
(number
, optional) — the node’s position in its parentparent
(Node
, optional) — the node’s parentcontext
(unknown
, optional) — context object (this
) to calltest
with
Returns
Whether node
is a Node
and passes a test (boolean
).
Throws
When an incorrect test
, index
, or parent
is given.
There is no error thrown when node
is not a node.
convert(test)
Generate a check from a test.
Useful if you’re going to test many nodes, for example when creating a utility where something else passes a compatible test.
The created function is a bit faster because it expects valid input only:
a node
, index
, and parent
.
Parameters
test
(Test
, optional) — a test for a specific node
Returns
A check (Check
).
Check
Check that an arbitrary value is a node (TypeScript type).
Parameters
this
(unknown
, optional) — context object (this
) to calltest
withnode
(unknown
) — anything (typically a node)index
(number
, optional) — the node’s position in its parentparent
(Node
, optional) — the node’s parent
Returns
Whether this is a node and passes a test (boolean
).
Test
Check for an arbitrary node (TypeScript type).
Type
type Test =
| Array<Record<string, unknown> | TestFunction | string>
| Record<string, unknown>
| TestFunction
| string
| null
| undefined
Checks that the given thing is a node, and then:
- when
string
, checks that the node has that tag name - when
function
, seeTestFunction
- when
object
, checks that all keys in test are in node, and that they have (strictly) equal values - when
Array
, checks if one of the subtests pass
TestFunction
Check if a node passes a test (TypeScript type).
Parameters
node
(Node
) — a nodeindex
(number
orundefined
) — the node’s position in its parentparent
(Node
orundefined
) — the node’s parent
Returns
Whether this node passes the test (boolean
, optional).
Examples
Example of convert
import {u} from 'unist-builder'
import {convert} from 'unist-util-is'
const test = convert('leaf')
const tree = u('tree', [
u('node', [u('leaf', '1')]),
u('leaf', '2'),
u('node', [u('leaf', '3'), u('leaf', '4')]),
u('leaf', '5')
])
const leafs = tree.children.filter(function (child, index) {
return test(child, index, tree)
})
console.log(leafs)
Yields:
[{type: 'leaf', value: '2'}, {type: 'leaf', value: '5'}]
Types
This package is fully typed with TypeScript.
It exports the additional types Check
,
Test
,
TestFunction
.
Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, unist-util-is@^6
,
compatible with Node.js 16.
Related
unist-util-find-after
— find a node after another nodeunist-util-find-before
— find a node before another nodeunist-util-find-all-after
— find all nodes after another nodeunist-util-find-all-before
— find all nodes before another nodeunist-util-find-all-between
— find all nodes between two nodesunist-util-filter
— create a new tree with nodes that pass a checkunist-util-remove
— remove nodes from tree
Contribute
See contributing.md
in syntax-tree/.github
for
ways to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.