Documents and edits

LspDocument

session.openDocument(item) sends didOpen and returns the LspDocument that owns the document's text and version from then on. item has a uri, a languageId, the text and an optional version, 1 by default. A URI can be open once per session; session.getDocument(uri) returns it. Wait for document.ready before you count on the server having it.

updateText(text) sends the one range that differs from the text the document holds, and nothing when it is the same. applyChanges(changes) sends didChange entries in order, each in the text the entry before it left. Both raise the version by one. A server that negotiated full sync gets the whole new text instead of the ranges.

save() sends didSave when the server asked for it, with the text when it asked for that too. It writes no file: call it after the app saved. close() cancels what is pending, sends didClose and clears the document's diagnostics; calling it again does nothing.

Opening, changes, requests, saving and closing go out in the order they were made.

Requests

LspDocument has a method per feature, each with the position or range it needs and optional DocumentRequestOptions:

Feature	Methods
Completion	completion, resolveCompletion
Information	hover, signatureHelp
Navigation	definition, declaration, typeDefinition, implementation
Uses	references, documentHighlights
Symbols and structure	documentSymbols, foldingRanges, selectionRanges, codeLenses, resolveCodeLens
Rename	prepareRename, rename
Actions	codeActions, resolveCodeAction
Formatting	formatting, rangeFormatting
Colors and hints	semanticTokens, semanticTokensDelta, semanticTokensRange, inlayHints, resolveInlayHint
Diagnostics	diagnostics, the pull model

request(method, params, options?) sends any other method of a document, with the same guards.

A method the server does not support rejects with MethodNotFound before anything is sent. A new request of a method cancels the one before it, unless cancelPrevious is false. A change or a close cancels all of them. An answer that arrives after the text changed rejects with StaleResultError, also when the server ignored the cancel. A completion item, code action, lens or hint resolves only for the version it came from. signal and timeoutMs in the options cancel a request from outside.

Edit helpers

The protocol has two shapes of edit, and mixing them up gives wrong text:

Shape	Ranges are in	Helper
ContentChange, as in didChange	The text the change before it left	applyContentChanges(text, changes)
TextEdit, as in formatting or rename	The text before all of them, at once	applyTextEdits(text, edits)

import { applyContentChanges, applyTextEdits, minimalChange } from '@adecore/lsp';

const after = applyTextEdits('red blue red', [
    { range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } }, newText: 'green' },
    { range: { start: { line: 0, character: 9 }, end: { line: 0, character: 12 } }, newText: 'green' }
]);
// 'green blue green'

applyContentChanges('red blue red', [minimalChange('red blue red', after)]) === after; // true

applyTextEdits rejects edits that overlap; several insertions at one position keep their order. minimalChange(before, after) is the one ContentChange between two texts, never splitting a surrogate pair or a \r\n. offsetAt, positionAt and endPosition convert between offsets and positions and throw on a position outside the text instead of clamping.

Workspace edits

planWorkspaceEdit(edit, snapshots) works out a WorkspaceEdit in memory without applying it. snapshots maps each URI to a DocumentSnapshot, its text and version (or null). The result is a PlannedDocumentEdit per document: uri, version, the text before and the planned text. A file the edit creates has no snapshot, since it is not there; it is planned from an empty text with created: true, and the app makes it with exclusive creation, so a file that appeared in the meantime is not written over. It throws an LspError for a document without a snapshot, a version that does not match, edits that overlap, a create of a file that has a snapshot (unless its options say overwrite or ignoreIfExists), and any rename or delete. The app applies the plan, after its own permission checks.

applyWorkspaceEdit of the editor views goes further: it edits open editors, stages drafts and moves files, but checks no versions.

Files and URIs

pathToFileUri(path) makes a file: URI of a POSIX or Windows path, escaping each segment. fileUriToPath(uri) goes back, or returns null for another scheme. Neither checks that a path is inside the project.

session.watchedFiles() returns the file watchers the server registered. watchesFile(watchers, root, path, type) says whether a change of a path concerns them, with type 1 created, 2 changed or 3 deleted; send those with session.didChangeWatchedFiles(changes). A path in node_modules, vendor or .git only matches a pattern that names that folder. Watching the disk is the app's work. globMatch(path, pattern) is the protocol's glob on its own.

For a file that moves, session.willRenameFiles(files) asks the server for the edits that come with the move, such as changed imports, and didRenameFiles(files) tells it afterwards. Each RenamedFile has oldUri, newUri and whether it is a directory. Only the files the server's filters take are sent; fileOperationFilters(operation) and renamesTaken(filters, files) are that filter. Moving the file is the app's.