unist-util-is
unist utility to check if nodes pass a test.
Contents
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()
is({children: []})
is(node)
is(node, 'strong')
is(node, 'emphasis')
is(node, node)
is(parent, {type: 'paragraph'})
is(parent, {type: 'strong'})
is(node, test)
is(node, test, 4, parent)
is(node, test, 5, parent)
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, typically Node
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 call test
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 call test
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
, see TestFunction
- 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
or undefined
)
— the node’s position in its parentparent
(Node
or undefined
)
— 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
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.
License
MIT © Titus Wormer