Registry / web-framework / hast-util-parse-selector

hast-util-parse-selector

JSON →
library4.0.0jsnpmunverified

`hast-util-parse-selector` is a focused utility within the `unified` ecosystem designed to create HAST (Hypertext Abstract Syntax Tree) element nodes from simple CSS selector strings. Currently at stable version 4.0.0, this package follows semantic versioning, with major releases typically aligning with dropping support for unmaintained Node.js versions. It processes basic selectors that can include a tag name, multiple class names, and a single ID, transforming them into a `hast` element object with corresponding `tagName` and `properties` (including `id` and `className` arrays). While powerful for its specific use case, it explicitly states its niche nature, recommending more comprehensive alternatives like `hastscript` or `hast-util-from-selector` for handling complex CSS selectors. Its primary differentiator is its simplicity and directness in parsing straightforward selectors into HAST nodes, making it suitable for scenarios where a full-blown selector engine is overkill.

npm install hast-util-parse-selector
INSTALL
IMPORT
SIG · HAST-UTIL-PARSE-SE
H
hast-util-parse-selector
web-frameworkjavascriptv4.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

parseSelector
import { parseSelector } from 'hast-util-parse-selector'
const { parseSelector } = require('hast-util-parse-selector')
This package is ESM-only since v3.0.0. Use `import` statements; `require()` is not supported.
parseSelector
import { parseSelector } from 'https://esm.sh/hast-util-parse-selector@4'
For Deno environments, use the `esm.sh` CDN import path. Ensure the version matches your requirement.
parseSelector
<script type="module"> import { parseSelector } from 'https://esm.sh/hast-util-parse-selector@4?bundle' </script>
For browser environments, use the `esm.sh` CDN with the `?bundle` query parameter for broader compatibility.

Demonstrates how to create `hast` element nodes using various simple CSS selectors and `defaultTagName` options, including class names, IDs, and custom tag fallbacks.

import { parseSelector } from 'hast-util-parse-selector'; import type { Element } from 'hast'; // Import for type definition // Create a HAST element from a complex class/id selector const complexSelectorElement: Element = parseSelector('.quux#bar.baz.qux'); console.log('Complex Selector Result:', complexSelectorElement); // Expected: { type: 'element', tagName: 'div', properties: { id: 'bar', className: [ 'quux', 'baz', 'qux' ] }, children: [] } // Create a HAST element with a specific tag name and ID const spanElement: Element = parseSelector('span#foo'); console.log('Span with ID Result:', spanElement); // Expected: { type: 'element', tagName: 'span', properties: { id: 'foo' }, children: [] } // Create an element with a default tag name when no selector is provided const defaultElement: Element = parseSelector(undefined, 'p'); console.log('Default Tag Name Result:', defaultElement); // Expected: { type: 'element', tagName: 'p', properties: {}, children: [] } // Using an empty string selector also results in the default tag name const emptySelectorElement: Element = parseSelector(''); console.log('Empty Selector Result:', emptySelectorElement); // Expected: { type: 'element', tagName: 'div', properties: {}, children: [] } // Example with a different default tag name const customDefaultElement: Element = parseSelector('.my-class', 'section'); console.log('Custom Default Tag Name Result:', customDefaultElement); // Expected: { type: 'element', tagName: 'section', properties: { className: [ 'my-class' ] }, children: [] }
Debug
Known issues
breakingVersion 4.0.0 raises the minimum required Node.js version to 16. Older Node.js versions are no longer supported.
fix
Upgrade your Node.js environment to version 16 or higher. Alternatively, use `hast-util-parse-selector@^3` if you must remain on an older Node.js version.
affects: >=4.0.0
breakingVersion 4.0.0 removed support for TypeScript 4.1. Ensure your project is using a compatible TypeScript version.
fix
Update your TypeScript dependency to a newer, supported version (e.g., TS 4.2+). The package is fully typed and expects a modern TypeScript environment.
affects: >=4.0.0
breakingVersion 4.0.0 changed to use `exports` in `package.json` for module resolution. Direct imports of internal or private module paths are no longer supported and will break.
fix
Always import directly from the package name (`'hast-util-parse-selector'`). Avoid referencing internal paths like `'hast-util-parse-selector/lib/some-module.js'`.
affects: >=4.0.0
breakingVersion 3.0.0 converted the package to be ESM-only. CommonJS `require()` statements are no longer supported.
fix
Migrate your project to use ES Modules (`import ... from '...'`) or ensure your build system correctly transpiles ESM for CommonJS environments. Avoid `require()` for this package.
affects: >=3.0.0
gotchaUsing unsanitized user input in the `selector` or `defaultTagName` parameters can lead to a Cross-Site Scripting (XSS) vulnerability. If a `tagName` resolves to `script`, it will inject a script element into the HAST tree.
fix
Never pass unsanitized user input directly to `parseSelector`. If user input is necessary, thoroughly sanitize it using a library like `hast-util-sanitize` before processing.
affects: >=2.2.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to use `require()` to import `hast-util-parse-selector`, which is an ESM-only package.
fix
Change `const { parseSelector } = require('hast-util-parse-selector');` to `import { parseSelector } from 'hast-util-parse-selector';`. Ensure your project's `package.json` has `"type": "module"` or that files are `.mjs`.
TypeError: parseSelector is not a function
This usually indicates an incorrect import or module resolution issue, especially when mixing CommonJS and ESM, or when an invalid import path is used.
fix
Verify your import statement is `import { parseSelector } from 'hast-util-parse-selector';` and that your environment supports ESM. If using a bundler, ensure it's configured for ESM.
TS2307: Cannot find module 'hast-util-parse-selector' or its corresponding type declarations.
Your TypeScript compiler cannot locate the package's type definitions, possibly due to an outdated TypeScript version, incorrect `moduleResolution` in `tsconfig.json`, or an issue with the `@types/hast` dependency if type inference relies on it.
fix
Ensure your `tsconfig.json` includes `"moduleResolution": "bundler"` (for modern bundlers) or `"node"` and `"allowSyntheticDefaultImports": true`. Also, update your `typescript` and potentially `@types/hast` dependencies to match the package's requirements (TS 4.2+ for v4.0.0).
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
hast-util-parse-selector — npm install hast-util-parse-selector · libregistry