node_modules/hast-util-is-element/readme.md

hast-util-is-element

hast utility to check if a node is a (certain) element.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • isElement(node[, test[, index, parent[, context]]])
  • convertElement(test)
  • AssertAnything
  • AssertPredicate
  • Test
  • TestFunctionAnything
  • PredicateTest
  • TestFunctionPredicate
• Types
• Compatibility
• Security
• Related
• Contribute
• License

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'}) // => false
isElement({type: 'element', tagName: 'a'}) // => true
isElement({type: 'element', tagName: 'a'}, 'a') // => true
isElement({type: 'element', tagName: 'a'}, ['a', 'area']) // => true

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 element
• index (number, optional) — the node’s position in its parent
• parent (Node, optional) — the node’s parent
• context (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

• test (Test or PredicateTest, optional) — a check for a specific element

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 parent
• parent (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

• T (Element) — element type

Parameters

• node (unknown) — anything (typically a node)
• index (number, optional) — the node’s position in its parent
• parent (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 element
• index (number, optional) — the element’s position in its parent
• parent (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

• T (Element) — element type

Parameters

• element (Element) — an element
• index (number, optional) — the element’s position in its parent
• parent (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

• hast-util-has-property — check if a node has a property
• hast-util-is-body-ok-link — check if a node is “Body OK” link element
• hast-util-is-conditional-comment — check if a node is a conditional comment
• hast-util-is-css-link — check if a node is a CSS link element
• hast-util-is-css-style — check if a node is a CSS style element
• hast-util-embedded — check if a node is an embedded element
• hast-util-heading — check if a node is a heading element
• hast-util-interactive — check if a node is interactive
• hast-util-is-javascript — check if a node is a JavaScript script element
• hast-util-labelable — check whether a node is labelable
• hast-util-phrasing — check if a node is phrasing content
• hast-util-script-supporting — check if a node is a script-supporting element
• hast-util-sectioning — check if a node is a sectioning element
• hast-util-transparent — check if a node is a transparent element
• hast-util-whitespace — check if a node is inter-element whitespace

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