Language Server Protocol

Completion items can support snippets by setting insertTextFormat to InsertTextFormat.Snippet. Snippets use a specific syntax to control cursors and text insertion:

• Tab stops: Use $1, $2 for cursor locations. $0 is the final position.
• Placeholders: Use ${1:foo} to provide a default value that is selected for easy editing. Supports nesting: ${1:another ${2:placeholder}}.
• Choice: Use ${1|one,two,three|} to provide a dropdown of options.
• Variables: Use $name or ${name:default}. Supported variables include:
  • TM_SELECTED_TEXT: Currently selected text.
  • TM_CURRENT_LINE: Contents of the current line.
  • TM_CURRENT_WORD: Word under cursor.
  • TM_LINE_INDEX: 0-indexed line number.
  • TM_LINE_NUMBER: 1-indexed line number.
  • TM_FILENAME: Filename.
  • TM_FILENAME_BASE: Filename without extension.
  • TM_DIRECTORY: Directory of the document.
  • TM_FILEPATH: Full file path.
• Variable Transforms: Modify variables using regex. Example: ${TM_FILENAME/(.*)\..+$/$1/} extracts the filename without the extension.

${TM_FILENAME/(.*)\..+$/$1/}
  |           |         | |
  |           |         | |-> no options
  |           |         | |
  |           |         |-> references the contents of the first
  |           |             capture group
  |           |           |
  |           |           |-> regex to capture everything before
  |           |           |   the final `.suffix`
  |           |           |
  |-> resolves to the filename

Since version 3.15.0, servers can stream partial results to the client using the $/progress notification.

1. Client Signaling: The client must include a partialResultToken in the request parameters to accept partial results.
2. Server Reporting: The server sends $/progress notifications where the value payload matches the final result type (e.g., SymbolInformation[]).
3. Final Response: When the server is finished, the final response to the original request must have an empty result value to avoid confusion between a final result and a partial result.

Error Handling: If the request is cancelled (RequestCancelled), the client may use the partial results but should note they are incomplete. For all other errors, partial results should be discarded.

{
  "textDocument": { "uri": "file:///folder/file.ts" },
  "position": { "line": 9, "character": 5 },
  "workDoneToken": "1d546990-40a3-4b77-b134-46622995f6ae",
  "partialResultToken": "5f6f349e-4f81-4a3b-afff-ee04bff96804"
}

The protocol is designed for textual documents. Positions are expressed using zero-based line and character offsets based on a UTF-16 string representation.

Important details:

• UTF-16 Offsets: A character like 𐐀 occupies two code units, so the character offset increments by 2.
• End-of-Line (EOL): The protocol supports \n, \r\n, and \r. Positions are agnostic to the specific EOL sequence used.
• Positioning: A Position represents the gap between characters (like an insertion cursor). Special values like -1 are not supported.

export const EOL: string[] = ['\n', '\r\n', '\r'];

interface Position {
	/**
	 * Line position in a document (zero-based).
	 */
	line: number;

	/**
	 * Character offset on a line in a document (zero-based). Assuming that the line is
	 * represented as a string, the `character` value represents the gap between the
	 * `character` and `character + 1`.
	 *
	 * If the character value is greater than the line length it defaults back to the
	 * line length.
	 */
	character: number;
}

When a client performs a WorkspaceEdit, it specifies which resource operations it supports and how it handles failures.

ResourceOperationKind defines the types of file/folder manipulations supported:

• create: Creating new files and folders.
• rename: Renaming existing files and folders.
• delete: Deleting existing files and folders.

FailureHandlingKind defines the strategy used if applying a workspace edit fails:

• abort: The operation is aborted; changes made before the failure remain.
• transactional: All operations succeed or none are applied.
• textOnlyTransactional: Textual changes are transactional, but resource changes (create/rename/delete) use the abort strategy.
• undo: The client attempts to undo already executed operations (no guarantee of success).

export type ResourceOperationKind = 'create' | 'rename' | 'delete';

export type FailureHandlingKind = 'abort' | 'transactional' | 'undo' | 'textOnlyTransactional';

When implementing notebook support, you must choose between two synchronization modes:

• cellContent mode: Only the text content of individual cells is synchronized using standard textDocument/did* notifications. The server does not receive the notebook structure or the relationship between cells. This is easier to implement as it reuses existing text document logic.
• notebook mode: The entire notebook document, its cell structure, and cell text content are synchronized together. Cell text is NOT synchronized via standard textDocument/did* notifications; instead, it uses special notebookDocument/did* notifications. This ensures that cell structure and content arrive in a single, consistent atomic update, allowing the server to reason about the whole notebook (e.g., for cross-cell variable references).

To request a specific mode, the server defines notebookDocumentSync in its capabilities.