NLCST to String Converter

4.0.0 · active · verified Sun Apr 19

nlcst-to-string is a utility designed to serialize NLCST (Natural Language Concrete Syntax Tree) nodes into their plain-text string representation. It is part of the unified ecosystem, focusing specifically on text content extraction from linguistic ASTs. The current stable version is 4.0.0. Releases follow the unified collective's compatibility policy, typically dropping support for unmaintained Node.js versions with new major releases (e.g., v4 requires Node.js 16+). Key differentiators include its tight integration with the NLCST specification, its minimal API (a single `toString` function), and its robust handling of various NLCST node types by prioritizing plain-text fields or recursively serializing children. This package is an ESM-only module since version 3.0.0 and ships with full TypeScript type definitions.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import `nlcst-to-string` which is an ESM-only package since v3.0.0.

fix Change `const toString = require('nlcst-to-string')` to `import { toString } from 'nlcst-to-string'`.
```
TypeError: toString is not a function
```
cause This can occur if an incorrect import path is used, or if a build process incorrectly bundles the ESM module, or if an older version of Node.js (prior to 12.17.0 for full ESM support) is used with a CommonJS context.

fix Verify that `import { toString } from 'nlcst-to-string'` is correctly configured for an ESM environment and that Node.js 16+ is used for `nlcst-to-string@4`.
```
SyntaxError: Cannot use import statement outside a module
```
cause You are trying to use ES module `import` syntax in a CommonJS context (e.g., a `.js` file without `"type": "module"` in `package.json`).

fix Ensure your file is treated as an ES module by either renaming it to `.mjs` or adding `"type": "module"` to your project's `package.json`. Alternatively, for older Node.js versions or CJS-only environments, you might need to use an older version of `nlcst-to-string` (pre-v3) or a dynamic `import()` call.

Warnings

breaking Version 4.0.0 changed to require Node.js 16 or higher. Projects running on older Node.js versions will encounter compatibility issues.
Fix: Upgrade your Node.js environment to version 16 or newer. If unable to upgrade, consider staying on `nlcst-to-string@3` (which requires Node.js 12+).
breaking Version 4.0.0 removed the `separator` option. Although noted as likely unused, any code relying on this option will break.
Fix: Remove the `separator` option from your `toString` calls. The utility now solely focuses on extracting concatenated text content.
breaking Version 3.0.0 converted the package to be ESM-only. CommonJS `require()` statements will no longer work, leading to module loading errors.
Fix: Refactor your imports to use ES module syntax (e.g., `import { toString } from 'nlcst-to-string'`). Ensure your project is configured for ESM, potentially by setting `"type": "module"` in `package.json` or using `.mjs` extensions.
gotcha The package uses the `exports` field in `package.json` (since v4.0.0). Direct access to internal paths or non-exported files may break.
Fix: Always use the public API as documented (`import { toString } from 'nlcst-to-string'`). Avoid using private APIs or deep imports into the package's internal structure.

Install

npm install nlcst-to-string npm
yarn add nlcst-to-string yarn
pnpm add nlcst-to-string pnpm

Imports

toString
wrong:
```
const toString = require('nlcst-to-string')
```
correct:
```
import { toString } from 'nlcst-to-string'
```
The package is ESM-only since v3, so CommonJS `require` will fail. Use ES module `import`.
toString (browser)
wrong:
```
import { toString } from 'nlcst-to-string'
```
correct:
```
import { toString } from 'https://esm.sh/nlcst-to-string@4?bundle'
```
For browser usage via CDN, use `esm.sh` with the `?bundle` flag for better compatibility and tree-shaking.
Type definitions
wrong:
```
import { Node, toString } from 'nlcst-to-string'
```
correct:
```
import type { Node } from 'nlcst'
import { toString } from 'nlcst-to-string'
```
This package exports no additional types; NLCST node types should be imported from the `nlcst` package.

Quickstart

This quickstart demonstrates how to import and use the `toString` function to convert an NLCST node or a list of nodes into a plain-text string, showing its handling of different node types.

import { toString } from 'nlcst-to-string';
import type { Parent, Text } from 'nlcst';

const exampleNode: Parent = {
  type: 'SentenceNode',
  children: [
    { type: 'WordNode', children: [{ type: 'TextNode', value: 'Hello' }] },
    { type: 'PunctuationNode', value: ',' },
    { type: 'SpaceNode', value: ' ' },
    { type: 'WordNode', children: [{ type: 'TextNode', value: 'world' }] },
    { type: 'PunctuationNode', value: '!' }
  ]
};

const complexWordNode: Parent = {
  type: 'WordNode',
  children: [
    { type: 'TextNode', value: 'AT' },
    { type: 'SymbolNode', value: '&' },
    { type: 'TextNode', value: 'T' }
  ]
};

console.log(toString(exampleNode));
console.log(toString(complexWordNode));
// Expected output:
// Hello, world!
// AT&T

view raw JSON →