hast-util-is-element
hast utility to check if a node is a (certain) element.
Contents
What is this?
This package is a small utility that checks that a node is a certain element.
When should I use this?
Use this small utility if you find yourself repeating code for checking what
elements nodes are.
A similar package, unist-util-is
, works on any unist node.
For more advanced tests, hast-util-select
can be used
to match against CSS selectors.
Install
This package is ESM only.
In Node.js (version 14.14+ and 16.0+), install with npm:
npm install hast-util-is-element
In Deno with esm.sh
:
import {isElement} from 'https://esm.sh/hast-util-is-element@2'
In browsers with esm.sh
:
<script type="module">
import {isElement} from 'https://esm.sh/hast-util-is-element@2?bundle'
</script>
Use
import {isElement} from 'hast-util-is-element'
isElement({type: 'text', value: 'foo'})
isElement({type: 'element', tagName: 'a'})
isElement({type: 'element', tagName: 'a'}, 'a')
isElement({type: 'element', tagName: 'a'}, ['a', 'area'])
API
This package exports the identifiers isElement
and
convertElement
.
There is no default export.
isElement(node[, test[, index, parent[, context]]])
Check if node
is an Element
and whether it passes the given test.
Parameters
node
(unknown
)
— thing to check, typically Node
test
(Test
or PredicateTest
, optional)
— a check for a specific elementindex
(number
, optional)
— the node’s position in its parentparent
(Node
, optional)
— the node’s parentcontext
(any
, optional)
— context object (this
) to call test
with
Returns
Whether node
is an Element
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 or not an element.
convertElement(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
Returns
An assertion (AssertAnything
or
AssertPredicate
).
AssertAnything
Check that an arbitrary value is an element, unaware of TypeScript inferral
(TypeScript type).
Parameters
node
(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 an element and passes a test (boolean
).
AssertPredicate
Check that an arbitrary value is a specific element, aware of TypeScript
(TypeScript type).
Type parameters
Parameters
node
(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 an element and passes a test (node is T
).
Test
Check for an arbitrary element, unaware of TypeScript inferral (TypeScript
type).
Type
type Test = null | undefined | string | TestFunctionAnything | Array<string | TestFunctionAnything>
Checks that the given thing is an element, and then:
- when
string
, checks that the element has that tag name - when
function
, see TestFunctionAnything
- when
Array
, checks if one of the subtests pass
TestFunctionAnything
Check if an element passes a test, unaware of TypeScript inferral (TypeScript
type).
Parameters
element
(Element
)
— an elementindex
(number
, optional)
— the element’s position in its parentparent
(Node
, optional)
— the element’s parent
Returns
Whether this element passes the test (boolean
).
PredicateTest
Check for an element that can be inferred by TypeScript (TypeScript type).
Type
type PredicateTest<T extends Element> =
| T['tagName']
| TestFunctionPredicate<T>
| Array<T['tagName'] | TestFunctionPredicate<T>>
See TestFunctionPredicate
.
TestFunctionPredicate
Check if an element passes a certain node test (TypeScript type).
Type parameters
Parameters
element
(Element
)
— an elementindex
(number
, optional)
— the element’s position in its parentparent
(Node
, optional)
— the element’s parent
Returns
Whether this element passes the test (element is T
).
Types
This package is fully typed with TypeScript.
It exports the additional types AssertAnything
,
AssertPredicate
, Test
,
TestFunctionAnything
,
TestFunctionPredicate
, and
PredicateTest
.
Compatibility
Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.
Security
hast-util-is-element
does not change the syntax tree so there are no openings
for cross-site scripting (XSS) attacks.
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