Nimble Pet Microbes

    hast-util-is-element
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.3 • Public • Published

    hast-util-is-element

    Build Coverage Downloads Size Sponsors Backers Chat

    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'}) // => 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
    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
    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
    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

    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

    Install

    npm i hast-util-is-element

    DownloadsWeekly Downloads

    707,204

    Version

    2.1.3

    License

    MIT

    Unpacked Size

    27.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • wooorm
    • kmck