{"id":12391,"library":"vscode-languageserver-textdocument","title":"LSP Text Document Implementation","description":"The `vscode-languageserver-textdocument` package provides a lightweight and immutable in-memory representation of a text document, specifically designed for use within Node.js-based Language Server Protocol (LSP) servers. It abstracts away the complexities of file system interactions, offering a consistent model for document content, versioning, and change tracking. This is a foundational utility within the larger `vscode-languageserver-node` monorepo, which is actively maintained by Microsoft. While the monorepo sees frequent `next` releases (e.g., `10.0.0-next.x` for server components), `vscode-languageserver-textdocument` itself is currently stable at version `1.0.12`, indicating a mature and less frequently changing API for its core document management functions. It is written in TypeScript and ships with comprehensive type definitions, making it well-suited for TypeScript-first development environments. Its primary differentiator is its focus on being a simple, efficient, and reliable document model optimized for LSP server operations like diagnostics, completions, and refactoring.","status":"active","version":"1.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/vscode-languageserver-node","tags":["javascript","typescript"],"install":[{"cmd":"npm install vscode-languageserver-textdocument","lang":"bash","label":"npm"},{"cmd":"yarn add vscode-languageserver-textdocument","lang":"bash","label":"yarn"},{"cmd":"pnpm add vscode-languageserver-textdocument","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary class for managing document state. Use named imports. CommonJS `require` is generally discouraged in modern LSP server setups.","wrong":"const { TextDocument } = require('vscode-languageserver-textdocument');","symbol":"TextDocument","correct":"import { TextDocument } from 'vscode-languageserver-textdocument';"},{"note":"Static factory method to create a new TextDocument instance. The class itself is exported, and static methods are accessed directly on the imported class.","wrong":"import * as TextDocumentModule from 'vscode-languageserver-textdocument';\nconst doc = TextDocumentModule.create(uri, languageId, version, text);","symbol":"TextDocument.create","correct":"import { TextDocument } from 'vscode-languageserver-textdocument';\nconst doc = TextDocument.create(uri, languageId, version, text);"},{"note":"Static method to apply an array of `TextEdit`s to an existing document, returning a *new* `TextDocument` instance with the changes applied. Original documents are immutable.","wrong":"import { TextDocument } from 'vscode-languageserver-textdocument';\noldDoc.applyEdits(changes); // TextDocument instances are immutable","symbol":"TextDocument.applyEdits","correct":"import { TextDocument } from 'vscode-languageserver-textdocument';\nconst newDoc = TextDocument.applyEdits(oldDoc, changes);"}],"quickstart":{"code":"import { TextDocument } from 'vscode-languageserver-textdocument';\nimport { Position, Range, TextEdit } from 'vscode-languageserver-types';\n\n// 1. Create an initial document\nconst uri = 'file:///path/to/example.ts';\nconst languageId = 'typescript';\nconst version = 1;\nconst initialText = 'console.log(\"Hello\");\\nconst x = 10;';\nlet document = TextDocument.create(uri, languageId, version, initialText);\n\nconsole.log(`Initial Document (v${document.version}):\\n${document.getText()}`);\nconsole.log(`Line Count: ${document.lineCount}`);\n\n// 2. Simulate an edit: Change 'Hello' to 'World'\nconst changeRange: Range = {\n  start: Position.create(0, 13),\n  end: Position.create(0, 18)\n};\nconst newText = 'World';\n\nconst edits: TextEdit[] = [\n  TextEdit.replace(changeRange, newText)\n];\n\n// 3. Apply the edits to get a new document instance\nconst newVersion = document.version + 1;\nconst updatedDocument = TextDocument.applyEdits(document, edits);\n\n// Important: The original document is unchanged\nconsole.log(`\\nOriginal Document (still v${document.version}):\\n${document.getText()}`);\n\n// The updated document reflects the changes\nconsole.log(`\\nUpdated Document (v${updatedDocument.version}):\\n${updatedDocument.getText()}`);\n\n// Example of getting position from offset and vice-versa\nconst offset = updatedDocument.offsetAt(Position.create(1, 6)); // 'x' in 'const x = 10;'\nconst position = updatedDocument.positionAt(offset);\nconsole.log(`\\nOffset of 'x': ${offset}, Position: { line: ${position.line}, character: ${position.character} }`);\n\n","lang":"typescript","description":"Demonstrates creating a `TextDocument`, applying simulated text edits to generate a new document version, and retrieving document content and position/offset information. Note that `vscode-languageserver-types` is a peer dependency for `Position`, `Range`, `TextEdit`."},"warnings":[{"fix":"Ensure your Node.js runtime is updated to a version that fully supports ES2020 (Node.js 14+ recommended) or configure your build pipeline to transpile down to an older ECMAScript target if necessary.","message":"Version 1.0.3 and later target ES2020. This might introduce breaking changes for environments not supporting ES2020 features, potentially requiring updated Node.js versions or additional transpilation steps in your build process.","severity":"breaking","affected_versions":">=1.0.3"},{"fix":"Always capture the return value of methods that modify document content (e.g., `let newDoc = TextDocument.applyEdits(oldDoc, edits);`) and update your internal state to reference the new document.","message":"TextDocument instances are immutable. Methods like `TextDocument.applyEdits` do not modify the original document but return a *new* `TextDocument` instance with the changes applied. Failing to reassign or use the new instance will lead to working with stale document content.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When using multiple packages from the `vscode-languageserver-node` family, ensure they are compatible versions. Prefer stable releases unless actively testing new features, and consult the monorepo's changelog for specific compatibility notes, especially when using 'next' channel packages.","message":"This package is part of the `vscode-languageserver-node` monorepo. While `vscode-languageserver-textdocument` is relatively stable, the broader monorepo often publishes `next` versions for its server and client packages. Be mindful of version compatibility when integrating with other `@vscode/languageserver-*` packages, as their `next` releases might introduce changes that could affect broader server logic, even if not directly breaking `textdocument`'s API.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using ESM named imports: `import { TextDocument } from 'vscode-languageserver-textdocument';` if your environment supports it. If strictly in CJS, try `const TextDocument = require('vscode-languageserver-textdocument').TextDocument;` or `const { TextDocument } = require('vscode-languageserver-textdocument');` if the package provides CJS interop.","cause":"Attempting to call `create` on a CommonJS `require` import where `TextDocument` might not be the default export or incorrectly destructured.","error":"TypeError: TextDocument.create is not a function"},{"fix":"Verify that `TextDocument.create` successfully returned a document instance and that your logic correctly handles the lifecycle of document objects, ensuring they are always valid when accessed. Check for missing input parameters to `create` or incorrect logic flow.","cause":"This typically occurs when a `TextDocument` variable is `undefined` or `null` because document creation failed, or it was not properly initialized before attempting to access its methods.","error":"Cannot read properties of undefined (reading 'getText')"}],"ecosystem":"npm"}