Registry / serialization / hast-util-is-element

hast-util-is-element

library3.0.0jsnpmunverified

This package, `hast-util-is-element`, is a fundamental utility within the HAST (Hypertext Abstract Syntax Tree) ecosystem, primarily designed to check if a given HAST node represents an HTML element. It offers flexible testing capabilities, allowing developers to verify not only if a node is an element but also if it matches specific tag names, an array of tag names, or even complex criteria through a predicate function. The library is currently stable at version 3.0.0, which introduced significant changes, including a migration to ESM-only distribution and a requirement for Node.js 16 or newer. Its release cadence is generally tied to updates within the broader syntax-tree ecosystem, including HAST type definition improvements and Node.js version alignment. A key differentiator is its specialized focus on HAST nodes, providing a more targeted and potentially performant alternative compared to the more generic `unist-util-is` for general Unist nodes. For advanced matching based on CSS selectors, `hast-util-select` offers more robust capabilities, positioning `hast-util-is-element` as a lightweight yet powerful tool for basic and custom element checks.

serialization web-framework

npm install hast-util-is-element

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-IS-ELEME

hast-util-is-element

serializationjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

isElement

✓ import { isElement } from 'hast-util-is-element'

✗ const isElement = require('hast-util-is-element').isElement

ESM-only since v2, explicitly requiring Node.js 16+ since v3. CommonJS `require` is not supported.

convertElement

✓ import { convertElement } from 'hast-util-is-element'

✗ const convertElement = require('hast-util-is-element').convertElement

Used to generate a pre-optimized check function for repeated use. ESM-only.

Check, Test, TestFunction

✓ import type { Check, Test, TestFunction } from 'hast-util-is-element'

These are TypeScript types for defining custom test functions and element checks. Since v3, avoid explicit type parameters and prefer these new type names.

Demonstrates how to use the `isElement` function to check different HAST nodes against various criteria, including tag names, arrays of tag names, and custom predicate functions.

import { isElement } from 'hast-util-is-element'; import { type Element, type Text } from 'hast'; // Assuming 'hast' types are installed // Example HAST nodes const textNode: Text = { type: 'text', value: 'foo' }; const anchorNode: Element = { type: 'element', tagName: 'a', properties: { href: '#' }, children: [] }; const divNode: Element = { type: 'element', tagName: 'div', properties: { id: 'main', class: ['container', 'flex'] }, children: [] }; const imgNode: Element = { type: 'element', tagName: 'img', properties: { src: 'image.png' }, children: [] }; console.log('Is textNode an element?', isElement(textNode)); // => false console.log('Is anchorNode an element?', isElement(anchorNode)); // => true console.log('Is anchorNode an "a" element?', isElement(anchorNode, 'a')); // => true console.log('Is imgNode an "img" element?', isElement(imgNode, 'img')); // => true console.log('Is anchorNode a "b" element?', isElement(anchorNode, 'b')); // => false console.log('Is divNode an "a" or "div" element?', isElement(divNode, ['a', 'div'])); // => true // More complex test using a predicate function console.log('Is divNode a div with class "container"?', isElement(divNode, (node) => node.tagName === 'div' && (node.properties?.class as string[])?.includes('container'))); // => true

Debug

Known issues

breakingVersion 3.0.0 and later are ESM-only. Importing via CommonJS `require()` is no longer supported and will lead to runtime errors.

fix

Migrate your project to use ES modules (`import`/`export`) or stick to an older version (<3.0.0) if CommonJS is strictly required.

affects: >=3.0.0

breakingVersion 3.0.0 and later require Node.js 16 or higher due to ESM-only distribution and other ecosystem updates.

fix

Ensure your Node.js environment is version 16 or newer. Upgrade Node.js if necessary.

affects: >=3.0.0

breakingThe package now uses the `exports` field in `package.json`. Direct deep imports (e.g., `hast-util-is-element/lib/some-internal-file`) are no longer supported and will break.

fix

Only use the public API as exported from the main package entry point (`import { ... } from 'hast-util-is-element'`).

affects: >=3.0.0

breakingType parameter changes in v3.0.0. Old types like `AssertAnything` and `AssertPredicate` have been replaced by `Check`, `Test`, and `TestFunction`. Explicit type parameters should generally be avoided.

fix

Update your TypeScript code to use the new type names: `Check`, `Test`, `TestFunction`. Remove explicit type parameters where they are no longer necessary.

affects: >=3.0.0

gotchaThe `isElement` function will throw an error if an incorrect `test`, `index`, or `parent` argument is provided. However, it will not throw an error if the `element` argument is not a valid HAST node or not an element type, instead returning `false`.

fix

Always ensure that `test`, `index`, and `parent` arguments conform to the expected types and structure to avoid runtime errors. Validate `element` type before calling if strict node type checking is needed.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ... not supported

Attempting to import `hast-util-is-element` using CommonJS `require()` syntax in a Node.js environment.

fix

Change `const { isElement } = require('hast-util-is-element');` to `import { isElement } from 'hast-util-is-element';` and ensure your project is configured for ESM.

TypeError: (0 , hast_util_is_element_1.isElement) is not a function

This typically indicates an incorrect import statement for an ESM module in a CommonJS context, or a bundling issue where the named export is not correctly resolved.

fix

Verify that you are using `import { isElement } from 'hast-util-is-element';` in an ESM context. If using a bundler, check its ESM/CommonJS compatibility settings.

Property 'AssertPredicate' does not exist on type 'typeof import("hast-util-is-element")'

Attempting to use old TypeScript types like `AssertPredicate` after upgrading to version 3.0.0.

fix

Update your TypeScript code to use the new type names introduced in v3: `Check`, `Test`, or `TestFunction`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/hast-util-is-element ↗

packagehttps://www.npmjs.com/package/hast-util-is-element ↗