HAST Utility to Parse CSS Selectors

Common errors

• ERR_REQUIRE_ESM

  cause 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

  cause 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.

  cause 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).

Warnings

• breaking Version 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.
• breaking Version 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.
• breaking Version 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'`.
• breaking Version 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.
• gotcha Using 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.

Install

• npm install hast-util-parse-selector npm
• yarn add hast-util-parse-selector yarn
• pnpm add hast-util-parse-selector pnpm

Imports

• parseSelector
  wrong:

  const { parseSelector } = require('hast-util-parse-selector')

  correct:

  import { parseSelector } from '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.

Quickstart

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: [] }