{"id":16239,"library":"textlint-util-to-string","title":"Textlint Utility: AST Paragraph to String with SourceMap","description":"textlint-util-to-string is a utility library within the textlint ecosystem designed to convert Text Abstract Syntax Tree (TxtAST) 'Paragraph' nodes into plain text strings. Its primary distinguishing feature is the integrated SourceMap functionality, which allows developers to accurately map positions in the generated plain text back to their corresponding original positions within the AST. This is crucial for tools like textlint and textstat that require precise error reporting and manipulation based on the original source. The current stable version is 3.3.4, and the package demonstrates an active release cadence with frequent patch and minor updates addressing bug fixes and introducing new features, such as the `replacer` option for text transformation during string conversion. This library serves as a foundational component for building advanced text processing and linting tools.","status":"active","version":"3.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/textlint/textlint-util-to-string","tags":["javascript","typescript"],"install":[{"cmd":"npm install textlint-util-to-string","lang":"bash","label":"npm"},{"cmd":"yarn add textlint-util-to-string","lang":"bash","label":"yarn"},{"cmd":"pnpm add textlint-util-to-string","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the TypeScript type definitions for TxtAST nodes (e.g., TxtParagraphNode) which are consumed by this utility. While not a direct runtime dependency for the library itself to execute, it's essential for type-safe development and when creating mock AST nodes for testing or examples.","package":"@textlint/ast-node-types","optional":true}],"imports":[{"note":"Since version 3.0.0, StringSource is a named export. Older versions used a default export.","wrong":"import StringSource from 'textlint-util-to-string'","symbol":"StringSource","correct":"import { StringSource } from 'textlint-util-to-string'"}],"quickstart":{"code":"import { StringSource } from \"textlint-util-to-string\";\nimport { TxtParagraphNode, TxtCodeNode, TxtTextNode } from \"@textlint/ast-node-types\";\n\n// Simulate a textlint paragraph node with nested content\nconst paragraphNode: TxtParagraphNode = {\n  type: \"Paragraph\",\n  loc: {\n    start: { line: 1, column: 0 },\n    end: { line: 1, column: 27 },\n  },\n  range: [0, 27],\n  raw: \"This is a `code` example.\",\n  children: [\n    {\n      type: \"Str\",\n      value: \"This is a \",\n      loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 10 } },\n      range: [0, 10],\n      raw: \"This is a \",\n    } as TxtTextNode,\n    {\n      type: \"Code\",\n      value: \"code\",\n      loc: { start: { line: 1, column: 11 }, end: { line: 1, column: 15 } },\n      range: [11, 15],\n      raw: \"`code`\",\n    } as TxtCodeNode,\n    {\n      type: \"Str\",\n      value: \" example.\",\n      loc: { start: { line: 1, column: 17 }, end: { line: 1, column: 26 } },\n      range: [17, 26],\n      raw: \" example.\",\n    } as TxtTextNode,\n  ],\n};\n\n// 1. Basic conversion to plain text\nconst source = new StringSource(paragraphNode);\nconsole.log(\"Plain text:\", source.toString());\n// Expected output: \"Plain text: This is a code example.\"\n\n// 2. Conversion with a replacer function to mask specific node types\nconst maskedSource = new StringSource(paragraphNode, {\n  replacer: ({ node, maskValue }) => {\n    if (node.type === \"Code\") {\n      return maskValue(\"_\"); // Masks \"code\" to \"____\"\n    }\n    return undefined; // No change for other node types\n  },\n});\nconsole.log(\"Masked text:\", maskedSource.toString());\n// Expected output: \"Masked text: This is a ____ example.\"\n\n// 3. Demonstrate source map functionality (mapping back from generated string to original AST index)\nconst plainText = source.toString();\nconst codeStartIndexInPlainText = plainText.indexOf(\"code\"); // \"code\" starts at index 10 in \"This is a code example.\"\nif (codeStartIndexInPlainText !== -1) {\n    const originalIndex = source.originalIndexFromIndex(codeStartIndexInPlainText);\n    console.log(`'code' starts at plain text index ${codeStartIndexInPlainText}, original AST index: ${originalIndex}`);\n    // Expected: 'code' starts at plain text index 10, original AST index: 11\n}\n","lang":"typescript","description":"This quickstart demonstrates how to instantiate `StringSource` with a `TxtParagraphNode`, convert it to plain text, use the `replacer` option to mask specific node types, and retrieve original AST positions from the generated string using source map functionality."},"warnings":[{"fix":"Change your import statements from `import StringSource from 'textlint-util-to-string'` to `import { StringSource } from 'textlint-util-to-string'`.","message":"Version 3.0.0 introduced a breaking change by converting the primary export for `StringSource` from a default export to a named export. Code relying on the old import style will break.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Refer to the API documentation carefully for `position` (line, column) vs. `index` (offset) definitions and their respective 0-based/1-based indexing conventions. Use the specific `original*From*` methods matching your input and desired output.","message":"When working with position mapping, be mindful of the terminology: `position` refers to `{ line, column }` where `line` is 1-based and `column` is 0-based, while `index` refers to a 0-based offset number. Ensure you use the correct utility method (`originalIndexFromIndex`, `originalPositionFromPosition`, etc.) based on the input type.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update your import statement to `import { StringSource } from 'textlint-util-to-string'` for ESM or `const { StringSource } = require('textlint-util-to-string')` for CommonJS.","cause":"Attempting to import `StringSource` as a default export when it is now a named export (since v3.0.0). This often happens in CommonJS environments transpiled from ESM.","error":"TypeError: textlint_util_to_string_1.default is not a constructor"},{"fix":"Modify your import statement to `import { StringSource } from 'textlint-util-to-string'` to use the named export, and ensure your build tooling correctly handles ESM imports.","cause":"Attempting to use `StringSource` as a constructor directly from a default import (`import StringSource from '...'`) after the v3.0.0 breaking change.","error":"TypeError: StringSource is not a constructor"}],"ecosystem":"npm"}