Registry / web-framework / hast-util-heading-rank

hast-util-heading-rank

library3.0.0jsnpmunverified

hast-util-heading-rank is a specialized utility within the unified ecosystem, designed to determine the rank (or level) of HTML heading elements (h1-h6) within a HAST (Hypertext Abstract Syntax Tree) node. The current stable version is 3.0.0. As part of the unified collective, it maintains a consistent release cadence, with major versions often dropping support for unmaintained Node.js versions and introducing breaking changes, particularly concerning module systems and type definitions. Its primary differentiator is its focused role in parsing and analyzing HAST structures, providing a clean, immutable API to query heading levels without altering the tree. This contrasts with related utilities like `hast-util-shift-heading`, which is designed to modify heading ranks, or `hast-util-heading`, which merely checks if a node is a heading.

web-framework serialization

npm install hast-util-heading-rank

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-HEADING-

hast-util-heading-rank

web-frameworkjavascriptv3.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.

headingRank

✓ import { headingRank } from 'hast-util-heading-rank'

✗ const headingRank = require('hast-util-heading-rank')

This package is ESM-only since v2.0.0 and does not provide a default export. Use named imports.

headingRank

✓ import { headingRank } from 'https://esm.sh/hast-util-heading-rank@3'

For Deno or browser environments, use `esm.sh` with the explicit version tag.

headingRank

✓ import { headingRank } from 'hast-util-heading-rank'

✗ import headingRank from 'hast-util-heading-rank'

There is no default export; always use named imports with curly braces.

Demonstrates how to use `headingRank` to determine the numerical rank of various HAST heading nodes, including non-heading elements and plain text, showing that it returns `undefined` for non-headings.

import { h } from 'hastscript'; import { headingRank } from 'hast-util-heading-rank'; import { toHtml } from 'hast-util-to-html'; // Create some HAST nodes using hastscript for demonstration const paragraphNode = h('p', 'This is a paragraph.'); const headingNode1 = h('h1', 'Main Title'); const headingNode3 = h('h3', 'Sub-Section'); const divNode = h('div', [h('h2', 'Nested Heading')]); console.log(`Node: ${toHtml(paragraphNode)}, Rank: ${headingRank(paragraphNode)}`); console.log(`Node: ${toHtml(headingNode1)}, Rank: ${headingRank(headingNode1)}`); console.log(`Node: ${toHtml(headingNode3)}, Rank: ${headingRank(headingNode3)}`); // A div containing a heading is not itself a heading console.log(`Node: ${toHtml(divNode)}, Rank: ${headingRank(divNode)}`); // Example of using a non-HAST node or invalid input (as of v3.0.0) const textNode = { type: 'text', value: 'Some text' }; console.log(`Node: ${JSON.stringify(textNode)}, Rank: ${headingRank(textNode)}`); // A valid h6 node const headingNode6 = h('h6', 'Tiny Heading'); console.log(`Node: ${toHtml(headingNode6)}, Rank: ${headingRank(headingNode6)}`);

Debug

Known issues

breakingThe package became ESM-only in version 2.0.0. Attempting to use `require()` will result in a runtime error.

fix

Migrate your codebase to use ES module `import` syntax. For example, change `const { headingRank } = require('hast-util-heading-rank')` to `import { headingRank } from 'hast-util-heading-rank'`.

affects: >=2.0.0

breakingVersion 3.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.

fix

Upgrade your Node.js environment to version 16 or newer. Use nvm or your package manager to update.

affects: >=3.0.0

breakingVersion 3.0.0 changes to use the `exports` field in `package.json`. Avoid using private or undocumented import paths.

fix

Always use the main entry point: `import { headingRank } from 'hast-util-heading-rank'`. Do not rely on internal file paths.

affects: >=3.0.0

breakingSupport for non-node inputs has been removed in version 3.0.0. The `node` parameter must be a valid HAST `Node` object.

fix

Ensure that the input passed to `headingRank` is always a valid HAST `Node`. Validate inputs if they might come from external sources.

affects: >=3.0.0

breakingAs of version 3.0.0, `headingRank` now yields `undefined` instead of `null` when the input is not a heading node.

fix

Update your code to expect and handle `undefined` instead of `null` for non-heading results. For example, `if (result === undefined)` or `if (typeof result === 'undefined')`.

affects: >=3.0.0

breakingVersion 3.0.0 updates its dependency on `@types/hast`. This might lead to type conflicts if your project uses an older, incompatible version of `@types/hast`.

fix

Update `@types/hast` in your project to a compatible version (typically the latest major) to ensure correct type definitions and avoid TypeScript errors.

affects: >=3.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use CommonJS `require` with `hast-util-heading-rank`, which is an ESM-only package since v2.0.0.

fix

Change `const { headingRank } = require('hast-util-heading-rank')` to `import { headingRank } from 'hast-util-heading-rank'`.

TypeError: Parameter `node` must be a node

Passing a non-HAST `Node` object (e.g., plain object, string, number) to `headingRank` after v3.0.0 removed support for non-node inputs.

fix

Ensure that the `node` argument is always a valid HAST `Node` object. You might need to validate or transform your input before passing it to `headingRank`.

Property 'rank' does not exist on type 'number | undefined'.

TypeScript error occurring when trying to access properties (like `node.rank`) on the result of `headingRank` without checking if it's `undefined`, expecting `null` from older versions.

fix

Add a type guard to check if the result is `undefined` before trying to use it. For example: `const rank = headingRank(node); if (typeof rank !== 'undefined') { /* use rank */ }`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/hast-util-heading-rank ↗

packagehttps://www.npmjs.com/package/hast-util-heading-rank ↗