hast-util-is-element

hast-util-is-element is a small, focused utility from the unified/syntax-tree ecosystem for verifying that a given node in a HAST (HTML Abstract Syntax Tree) is an Element, and optionally that it matches a specific test — a tag name string, an array of tag names, or a custom predicate function. It’s built for tools that walk or transform HTML syntax trees, such as rehype plugins, and need a fast, reliable way to filter or guard against non-element nodes (text, comments, doctypes) before acting on them.

The package exports two functions: isElement, which checks a single node inline, and convertElement, which compiles a test into a reusable, slightly faster check function for use across many nodes — handy when writing a plugin that inspects every node in a tree. Both are fully typed with TypeScript, including overloads that narrow the returned type when a string or predicate test is passed.

What You Get

• isElement() - a direct one-off check against a single node with an optional test
• convertElement() - compiles a test into a reusable, faster Check function for repeated use
• Flexible test matching - a test can be a tag name string, an array of tag names (matches any), or a custom TestFunction with full type narrowing
• Zero runtime dependencies - only a @types/hast type-only dependency, keeping it lightweight for tree-walking pipelines
• Full TypeScript typings - overloaded signatures narrow the return type based on the test passed in

Common Use Cases

• Filtering nodes in a rehype plugin - skip non-element nodes (text, comments) before applying transforms
• Guarding a tag-specific transform - check isElement(node, 'img') before rewriting image attributes
• Building a reusable node check - call convertElement(['h1','h2','h3']) once and reuse the returned function across a tree walk for performance
• Validating unknown input - confirm a value shaped like a hast node is actually an Element before accessing tagName or properties

Under The Hood

Architecture The package is a single-file module (lib/index.js, re-exported through index.js) built around one internal factory pattern: convertElement dispatches on the shape of its test argument to tagNameFactory, anyFactory, or castFactory, each producing a Check function that shares the same looksLikeAnElement/element guards used by isElement itself. There’s no state, no I/O, and no dependency graph to speak of — the only thing that could break every downstream consumer is a change to those shared guard functions, which both entry points route through.

Tech Stack It’s an ESM-only package ("type": "module") targeting Node.js 16+, with zero runtime dependencies beyond a type-only @types/hast import. Types are authored as JSDoc annotations and compiled to declarations with tsc --build, checked for completeness with type-coverage (configured to require 100% coverage) and verified against real call sites with tsd. Formatting and linting run through prettier and xo, with remark-preset-wooorm linting the README itself.

Code Quality Tests use Node’s built-in node:test runner with assert/strict, covering the empty-argument case, invalid test/index/parent inputs (which throw explicit errors rather than failing silently), and matching by string, array, and function tests. c8 --100 enforces full statement coverage as part of the test script, so the build itself fails under incomplete coverage. CI runs the suite across two Node versions and uploads results to Codecov, giving this small package a notably rigorous quality bar for its size.

API Design The public surface is deliberately tiny — just isElement and convertElement — but both use JSDoc-authored generic overloads so TypeScript narrows an unknown value down to Element, or even Element & {tagName: 'div'} for a string test, without the caller writing any casts. Every parameter is optional, argument order matches sibling hast-util-* packages for muscle-memory consistency, and thrown errors carry specific, actionable messages. The README documents every parameter, return value, and throw condition in full.