HAST Phrasing Content Utility

3.0.1 · active · verified Sun Apr 19

hast-util-phrasing is a niche utility within the unified (remark/rehype) ecosystem, specifically designed to determine if a given HAST (Hypertext Abstract Syntax Tree) node represents 'phrasing content' according to HTML specifications. This classification is crucial for advanced HTML manipulation and validation scenarios. The package is currently at version 3.0.1, indicating active maintenance and regular, albeit minor, updates since its major release. It adheres to the unified collective's release cadence, typically aligning major versions with Node.js LTS support lifecycles. Its key differentiator is its precise adherence to HTML phrasing content rules, making it invaluable for tools that need to strictly adhere to HTML parsing and serialization standards, particularly in content transformation pipelines.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module ... hast-util-phrasing.js not supported.
```
cause Attempting to use `require()` for this package, which is ESM-only since v2.0.0.

fix Use ESM import syntax: `import { phrasing } from 'hast-util-phrasing'`.
```
TypeError: Cannot read properties of undefined (reading 'type') at phrasing (hast-util-phrasing.js:...) or similar 'value is not a HAST Node' errors.
```
cause Passing `null`, `undefined`, or a non-object to `phrasing` after v3.0.0, which expects a valid HAST `Node`.

fix Ensure the input to `phrasing` is always a valid HAST node object. Add checks like `if (value && typeof value === 'object' && 'type' in value) { phrasing(value); }` if inputs are untrusted.

Warnings

breaking Version 3.0.0 removed support for non-nodes as input. The `phrasing` function now strictly expects a valid HAST `Node` object.
Fix: Ensure that the `value` argument passed to `phrasing` is always a valid HAST `Node`. Validate input before calling `phrasing` if external data is used.
breaking Version 3.0.0 updated `@types/hast` and other internal utilities. If you are using TypeScript, you might need to update your `@types/hast` dependency to match.
Fix: Update your `@types/hast` package to the latest compatible version (e.g., `npm install @types/hast@latest`).
breaking Version 3.0.0 changed the package to require Node.js 16 or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or newer. For projects that must support older Node.js, pin the package to `hast-util-phrasing@^2`.
breaking The package now uses `exports` in `package.json` since v3.0.0. This enforces strict import paths and removes access to private internal APIs. Direct imports to subpaths not explicitly exported will fail.
Fix: Always use the main entry point: `import { phrasing } from 'hast-util-phrasing'`. Do not rely on internal, non-exported paths.
breaking The package migrated to ESM (ES Module) only starting with version 2.0.0. CommonJS `require()` statements will no longer work.
Fix: Refactor your imports to use ES module syntax: `import { phrasing } from 'hast-util-phrasing'`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` files).

Install

npm install hast-util-phrasing npm
yarn add hast-util-phrasing yarn
pnpm add hast-util-phrasing pnpm

Imports

phrasing
wrong:
```
const phrasing = require('hast-util-phrasing')
```
correct:
```
import { phrasing } from 'hast-util-phrasing'
```
The package is ESM-only since v2.0.0. CommonJS 'require' is not supported.
phrasing
wrong:
```
import phrasing from 'https://esm.sh/hast-util-phrasing@3'
```
correct:
```
import { phrasing } from 'https://esm.sh/hast-util-phrasing@3'
```
When using Deno or browser ESM CDNs, ensure named import as there is no default export. Specify the major version for stability.

Quickstart

This quickstart demonstrates how to use the `phrasing` utility with various HAST node types to check if they qualify as phrasing content according to HTML specifications, illustrating different outcomes.

import { phrasing } from 'hast-util-phrasing';

// Example 1: A div element, which is typically flow content and not phrasing.
const divNode = {
  type: 'element',
  tagName: 'div',
  children: [{ type: 'text', value: 'Hello' }]
};
console.log('Is <div> phrasing content?', phrasing(divNode));
// Expected: false

// Example 2: A meta element with 'itemProp', which can be phrasing content.
const metaItemPropNode = {
  type: 'element',
  tagName: 'meta',
  properties: { itemProp: 'description' },
  children: []
};
console.log('Is <meta itemprop> phrasing content?', phrasing(metaItemPropNode));
// Expected: true

// Example 3: A meta element with 'charset', which is not phrasing content.
const metaCharsetNode = {
  type: 'element',
  tagName: 'meta',
  properties: { charSet: 'utf8' },
  children: []
};
console.log('Is <meta charset> phrasing content?', phrasing(metaCharsetNode));
// Expected: false

// Example 4: A text node, which is always phrasing content.
const textNode = { type: 'text', value: 'Some text' };
console.log('Is text node phrasing content?', phrasing(textNode));
// Expected: true

view raw JSON →