{"id":11405,"library":"nlcst-to-string","title":"NLCST to String Converter","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/nlcst-to-string","tags":["javascript","unist","nlcst","nlcst-util","util","utility","string","serialize","stringify","typescript"],"install":[{"cmd":"npm install nlcst-to-string","lang":"bash","label":"npm"},{"cmd":"yarn add nlcst-to-string","lang":"bash","label":"yarn"},{"cmd":"pnpm add nlcst-to-string","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only since v3, so CommonJS `require` will fail. Use ES module `import`.","wrong":"const toString = require('nlcst-to-string')","symbol":"toString","correct":"import { toString } from 'nlcst-to-string'"},{"note":"For browser usage via CDN, use `esm.sh` with the `?bundle` flag for better compatibility and tree-shaking.","wrong":"import { toString } from 'nlcst-to-string'","symbol":"toString (browser)","correct":"import { toString } from 'https://esm.sh/nlcst-to-string@4?bundle'"},{"note":"This package exports no additional types; NLCST node types should be imported from the `nlcst` package.","wrong":"import { Node, toString } from 'nlcst-to-string'","symbol":"Type definitions","correct":"import type { Node } from 'nlcst'\nimport { toString } from 'nlcst-to-string'"}],"quickstart":{"code":"import { toString } from 'nlcst-to-string';\nimport type { Parent, Text } from 'nlcst';\n\nconst exampleNode: Parent = {\n  type: 'SentenceNode',\n  children: [\n    { type: 'WordNode', children: [{ type: 'TextNode', value: 'Hello' }] },\n    { type: 'PunctuationNode', value: ',' },\n    { type: 'SpaceNode', value: ' ' },\n    { type: 'WordNode', children: [{ type: 'TextNode', value: 'world' }] },\n    { type: 'PunctuationNode', value: '!' }\n  ]\n};\n\nconst complexWordNode: Parent = {\n  type: 'WordNode',\n  children: [\n    { type: 'TextNode', value: 'AT' },\n    { type: 'SymbolNode', value: '&' },\n    { type: 'TextNode', value: 'T' }\n  ]\n};\n\nconsole.log(toString(exampleNode));\nconsole.log(toString(complexWordNode));\n// Expected output:\n// Hello, world!\n// AT&T","lang":"typescript","description":"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."},"warnings":[{"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+).","message":"Version 4.0.0 changed to require Node.js 16 or higher. Projects running on older Node.js versions will encounter compatibility issues.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Remove the `separator` option from your `toString` calls. The utility now solely focuses on extracting concatenated text content.","message":"Version 4.0.0 removed the `separator` option. Although noted as likely unused, any code relying on this option will break.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Version 3.0.0 converted the package to be ESM-only. CommonJS `require()` statements will no longer work, leading to module loading errors.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The package uses the `exports` field in `package.json` (since v4.0.0). Direct access to internal paths or non-exported files may break.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const toString = require('nlcst-to-string')` to `import { toString } from 'nlcst-to-string'`.","cause":"Attempting to use `require()` to import `nlcst-to-string` which is an ESM-only package since v3.0.0.","error":"ERR_REQUIRE_ESM"},{"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`.","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.","error":"TypeError: toString is not a function"},{"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.","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`).","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}