{"id":13287,"library":"hast-util-heading-rank","title":"HAST Heading Rank Utility","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-heading-rank","tags":["javascript","unist","hast","hast-util","util","utility","html","heading","rank","typescript"],"install":[{"cmd":"npm install hast-util-heading-rank","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-heading-rank","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-heading-rank","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only since v2.0.0 and does not provide a default export. Use named imports.","wrong":"const headingRank = require('hast-util-heading-rank')","symbol":"headingRank","correct":"import { headingRank } from 'hast-util-heading-rank'"},{"note":"For Deno or browser environments, use `esm.sh` with the explicit version tag.","symbol":"headingRank","correct":"import { headingRank } from 'https://esm.sh/hast-util-heading-rank@3'"},{"note":"There is no default export; always use named imports with curly braces.","wrong":"import headingRank from 'hast-util-heading-rank'","symbol":"headingRank","correct":"import { headingRank } from 'hast-util-heading-rank'"}],"quickstart":{"code":"import { h } from 'hastscript';\nimport { headingRank } from 'hast-util-heading-rank';\nimport { toHtml } from 'hast-util-to-html';\n\n// Create some HAST nodes using hastscript for demonstration\nconst paragraphNode = h('p', 'This is a paragraph.');\nconst headingNode1 = h('h1', 'Main Title');\nconst headingNode3 = h('h3', 'Sub-Section');\nconst divNode = h('div', [h('h2', 'Nested Heading')]);\n\nconsole.log(`Node: ${toHtml(paragraphNode)}, Rank: ${headingRank(paragraphNode)}`);\nconsole.log(`Node: ${toHtml(headingNode1)}, Rank: ${headingRank(headingNode1)}`);\nconsole.log(`Node: ${toHtml(headingNode3)}, Rank: ${headingRank(headingNode3)}`);\n// A div containing a heading is not itself a heading\nconsole.log(`Node: ${toHtml(divNode)}, Rank: ${headingRank(divNode)}`); \n\n// Example of using a non-HAST node or invalid input (as of v3.0.0)\nconst textNode = { type: 'text', value: 'Some text' };\nconsole.log(`Node: ${JSON.stringify(textNode)}, Rank: ${headingRank(textNode)}`);\n\n// A valid h6 node\nconst headingNode6 = h('h6', 'Tiny Heading');\nconsole.log(`Node: ${toHtml(headingNode6)}, Rank: ${headingRank(headingNode6)}`);","lang":"typescript","description":"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."},"warnings":[{"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'`.","message":"The package became ESM-only in version 2.0.0. Attempting to use `require()` will result in a runtime error.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer. Use nvm or your package manager to update.","message":"Version 3.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always use the main entry point: `import { headingRank } from 'hast-util-heading-rank'`. Do not rely on internal file paths.","message":"Version 3.0.0 changes to use the `exports` field in `package.json`. Avoid using private or undocumented import paths.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure that the input passed to `headingRank` is always a valid HAST `Node`. Validate inputs if they might come from external sources.","message":"Support for non-node inputs has been removed in version 3.0.0. The `node` parameter must be a valid HAST `Node` object.","severity":"breaking","affected_versions":">=3.0.0"},{"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')`.","message":"As of version 3.0.0, `headingRank` now yields `undefined` instead of `null` when the input is not a heading node.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update `@types/hast` in your project to a compatible version (typically the latest major) to ensure correct type definitions and avoid TypeScript errors.","message":"Version 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`.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { headingRank } = require('hast-util-heading-rank')` to `import { headingRank } from 'hast-util-heading-rank'`.","cause":"Attempting to use CommonJS `require` with `hast-util-heading-rank`, which is an ESM-only package since v2.0.0.","error":"ReferenceError: require is not defined"},{"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`.","cause":"Passing a non-HAST `Node` object (e.g., plain object, string, number) to `headingRank` after v3.0.0 removed support for non-node inputs.","error":"TypeError: Parameter `node` must be a node"},{"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 */ }`.","cause":"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.","error":"Property 'rank' does not exist on type 'number | undefined'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}