Registry / serialization / hast-util-to-nlcst

hast-util-to-nlcst

library4.0.0jsnpmunverified

hast-util-to-nlcst is a utility package within the unified/syntax-tree ecosystem designed to transform a HAST (HTML Abstract Syntax Tree) into an NLCST (Natural Language Concrete Syntax Tree). This transformation extracts the natural language content from an HTML structure, making it suitable for natural language processing tasks such as linting, sentiment analysis, or spell checking with tools like retext. The package is currently stable at version 4.0.0 and follows a semver release cadence, with major versions often introducing breaking changes related to environment support (e.g., Node.js versions, ESM-only) or parser API updates. A key differentiator is its focused role in bridging HTML content to natural language processing within the unist AST family, though it currently lacks a mechanism to apply changes back from NLCST to HAST. It is often used in conjunction with parsers like `parse-english` and wrappers like `rehype-retext`.

serialization ai-ml data

npm install hast-util-to-nlcst

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-TO-NLCST

hast-util-to-nlcst

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

toNlcst

✓ import { toNlcst } from 'hast-util-to-nlcst'

✗ const toNlcst = require('hast-util-to-nlcst')

This package is ESM-only since v2.0.0 and requires Node.js 16+ since v4.0.0. CommonJS `require` statements will fail.

ParserConstructor

✓ import type { ParserConstructor } from 'hast-util-to-nlcst'

Use `import type` for type-only imports to prevent bundling issues and ensure correct type inference.

ParserInstance

✓ import type { ParserInstance } from 'hast-util-to-nlcst'

Use `import type` for type-only imports.

This example demonstrates how to parse an HTML string into a HAST tree, then convert that HAST tree into an NLCST tree using `hast-util-to-nlcst` with `ParseEnglish`. It then uses `unist-util-inspect` to log the resulting natural language tree structure, showing how text content from HTML elements is represented.

import { fromHtml } from 'hast-util-from-html'; import { toNlcst } from 'hast-util-to-nlcst'; import { ParseEnglish } from 'parse-english'; import { readSync } from 'to-vfile'; import { inspect } from 'unist-util-inspect'; import * as fs from 'fs'; import * as path from 'path'; // Create a dummy HTML file for the example const exampleHtmlContent = ` <article> Implicit. <h1>Explicit: <strong>foo</strong>s-ball</h1> <pre><code class="language-foo">bar()</code></pre> </article> `; const exampleHtmlPath = path.join(process.cwd(), 'example.html'); fs.writeFileSync(exampleHtmlPath, exampleHtmlContent); // Read the virtual file const file = readSync(exampleHtmlPath); // Parse HTML string to HAST const tree = fromHtml(file); // Transform HAST to NLCST using ParseEnglish const nlcstTree = toNlcst(tree, file, ParseEnglish); // Log the inspected NLCST tree (positional info removed for brevity) console.log(inspect(nlcstTree)); // Clean up the dummy file fs.unlinkSync(exampleHtmlPath);

Debug

Known issues

breakingVersion 4.0.0 introduces a requirement for Node.js version 16 or higher. Running on older Node.js environments will lead to runtime errors or module resolution failures.

fix

Upgrade your Node.js environment to version 16 or newer.

affects: >=4.0.0

breakingVersion 4.0.0 changed to use the `exports` field in `package.json`, which affects module resolution behavior, especially in some bundlers or older Node.js versions. This may require adjustments to build configurations.

fix

Ensure your build tools and Node.js version fully support the `exports` field. If experiencing issues, verify your `tsconfig.json` (for TypeScript) or bundler configuration is up-to-date.

affects: >=4.0.0

breakingVersion 3.0.0 introduced breaking changes related to the NLCST parsers. The `Parser` argument passed to `toNlcst` must be updated to the latest compatible version (e.g., `parse-latin`, `parse-english`, `parse-dutch`).

fix

Update the NLCST parser packages you are using (e.g., `npm install parse-english@latest`) and ensure your code passes their latest constructor function.

affects: >=3.0.0

breakingVersion 2.0.0 switched the package to be ESM-only (ECMAScript Modules). CommonJS `require()` statements are no longer supported and will result in module loading errors.

fix

Refactor your code to use ES module `import` statements. Ensure your project is configured for ESM, potentially by adding `"type": "module"` to your `package.json` or using `.mjs` file extensions.

affects: >=2.0.0

gotchaThe `toNlcst` function requires the input HAST `tree` to have positional information (line, column, offset data) for accurate NLCST conversion. The `VFile` passed must also correspond directly to the `tree`.

fix

When creating your HAST tree, ensure that the parser used (e.g., `hast-util-from-html`, `rehype-parse`) is configured to retain positional information. For example, `fromHtml` automatically handles this when given a `VFile`.

affects: *

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to use `require()` to import `hast-util-to-nlcst`, which is an ESM-only package.

fix

Change `const { toNlcst } = require('hast-util-to-nlcst')` to `import { toNlcst } from 'hast-util-to-nlcst'`. Ensure your project runs in an ESM context (e.g., `type: "module"` in `package.json` or `.mjs` file extension).

SyntaxError: Cannot use import statement outside a module

You are trying to use an `import` statement in a Node.js environment that is not configured for ES modules, or an older Node.js version.

fix

Ensure your Node.js version is 16+ (required by v4.0.0), and add `"type": "module"` to your `package.json` file. Alternatively, rename your file to use the `.mjs` extension.

TypeError: Parser is not a constructor

The NLCST parser passed to `toNlcst` is either an outdated version or incorrectly imported/instantiated, especially after the v3.0.0 breaking change.

fix

Update your NLCST parser package (e.g., `npm install parse-english@latest`). Ensure you are passing the constructor function itself (e.g., `ParseEnglish`) and not an instance or an incorrect export.

TypeError: Cannot read properties of undefined (reading 'position') or incorrect NLCST output with missing text.

The input HAST `tree` lacks positional information, which `hast-util-to-nlcst` relies on for accurate conversion.

fix

Ensure the utility or parser you use to create the HAST tree preserves positional data. For instance, when using `hast-util-from-html`, ensure you pass a `VFile` object created from actual content, which typically retains this info.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

parse-englishoptionalThis utility requires an NLCST parser (e.g., `parse-english`, `parse-latin`, `parse-dutch`) to be provided as a parameter to its `toNlcst` function. While not a direct `peerDependency` in package.json, it's a functional requirement for practical use.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/hast-util-to-nlcst ↗

packagehttps://www.npmjs.com/package/hast-util-to-nlcst ↗