LSP Text Document Implementation

Common errors

• TypeError: TextDocument.create is not a function

  cause Attempting to call `create` on a CommonJS `require` import where `TextDocument` might not be the default export or incorrectly destructured.
  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.

• Cannot read properties of undefined (reading 'getText')

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

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install vscode-languageserver-textdocument npm
• yarn add vscode-languageserver-textdocument yarn
• pnpm add vscode-languageserver-textdocument pnpm

Imports

• TextDocument
  wrong:

  const { TextDocument } = require('vscode-languageserver-textdocument');

  correct:

  import { TextDocument } from 'vscode-languageserver-textdocument';

  Primary class for managing document state. Use named imports. CommonJS `require` is generally discouraged in modern LSP server setups.
• TextDocument.create
  wrong:

  import * as TextDocumentModule from 'vscode-languageserver-textdocument';
  const doc = TextDocumentModule.create(uri, languageId, version, text);

  correct:

  import { TextDocument } from 'vscode-languageserver-textdocument';
  const doc = TextDocument.create(uri, languageId, version, text);

  Static factory method to create a new TextDocument instance. The class itself is exported, and static methods are accessed directly on the imported class.
• TextDocument.applyEdits
  wrong:

  import { TextDocument } from 'vscode-languageserver-textdocument';
  oldDoc.applyEdits(changes); // TextDocument instances are immutable

  correct:

  import { TextDocument } from 'vscode-languageserver-textdocument';
  const newDoc = TextDocument.applyEdits(oldDoc, changes);

  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.

Quickstart

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

import { TextDocument } from 'vscode-languageserver-textdocument';
import { Position, Range, TextEdit } from 'vscode-languageserver-types';

// 1. Create an initial document
const uri = 'file:///path/to/example.ts';
const languageId = 'typescript';
const version = 1;
const initialText = 'console.log("Hello");\nconst x = 10;';
let document = TextDocument.create(uri, languageId, version, initialText);

console.log(`Initial Document (v${document.version}):\n${document.getText()}`);
console.log(`Line Count: ${document.lineCount}`);

// 2. Simulate an edit: Change 'Hello' to 'World'
const changeRange: Range = {
  start: Position.create(0, 13),
  end: Position.create(0, 18)
};
const newText = 'World';

const edits: TextEdit[] = [
  TextEdit.replace(changeRange, newText)
];

// 3. Apply the edits to get a new document instance
const newVersion = document.version + 1;
const updatedDocument = TextDocument.applyEdits(document, edits);

// Important: The original document is unchanged
console.log(`\nOriginal Document (still v${document.version}):\n${document.getText()}`);

// The updated document reflects the changes
console.log(`\nUpdated Document (v${updatedDocument.version}):\n${updatedDocument.getText()}`);

// Example of getting position from offset and vice-versa
const offset = updatedDocument.offsetAt(Position.create(1, 6)); // 'x' in 'const x = 10;'
const position = updatedDocument.positionAt(offset);
console.log(`\nOffset of 'x': ${offset}, Position: { line: ${position.line}, character: ${position.character} }`);