0
# VSCode Language Server
1

2
The VSCode Language Server is a comprehensive implementation of the Language Server Protocol (LSP) for Node.js and browser environments. It provides server-side infrastructure for building language servers that power intelligent code features in Visual Studio Code and other editors supporting LSP.
3

4
## Package Information
5

6
- **Package Name**: vscode-languageserver
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vscode-languageserver`
10

11
## Core Imports
12

13
```typescript
14
import { createConnection, TextDocuments, ProposedFeatures } from "vscode-languageserver";
15
import { TextDocument } from "vscode-languageserver-textdocument";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { createConnection, TextDocuments, ProposedFeatures } = require("vscode-languageserver");
22
```
23

24
Node.js specific imports:
25

26
```typescript
27
import { createConnection } from "vscode-languageserver/node";
28
```
29

30
Browser specific imports:
31

32
```typescript
33
import { createConnection } from "vscode-languageserver/browser";
34
```
35

36
## Basic Usage
37

38
```typescript
39
import { createConnection, TextDocuments, ProposedFeatures } from "vscode-languageserver";
40
import { TextDocument } from "vscode-languageserver-textdocument";
41

42
// Create a connection for the server
43
const connection = createConnection(ProposedFeatures.all);
44

45
// Create a simple text document manager
46
const documents = new TextDocuments(TextDocument);
47

48
// Listen for document changes
49
documents.onDidChangeContent(change => {
50
    // Validate the document when its content has changed
51
    validateTextDocument(change.document);
52
});
53

54
// Listen for when a text document is opened
55
documents.onDidOpen(event => {
56
    validateTextDocument(event.document);
57
});
58

59
// Provide hover information
60
connection.onHover(params => {
61
    return {
62
        contents: "Hover information here"
63
    };
64
});
65

66
// Start listening for messages
67
documents.listen(connection);
68
connection.listen();
69
```
70

71
## Architecture
72

73
The VSCode Language Server is built around several key components:
74

75
- **Connection Management**: Creates and manages the communication channel between client and server
76
- **Document Lifecycle**: Tracks and synchronizes text documents between client and server
77
- **Feature Handlers**: Implements LSP request/notification handlers for language features
78
- **Type System**: Full TypeScript integration with comprehensive LSP protocol types
79
- **Cross-Platform Support**: Works in both Node.js and browser environments
80
- **Feature Composition**: Extensible architecture supporting both standard and proposed LSP features
81

82
## Capabilities
83

84
### Connection Management
85

86
Core connection establishment and communication infrastructure for Language Server Protocol implementations. Essential for all language servers.
87

88
```typescript { .api }
89
function createConnection(): Connection;
90
function createConnection(options?: ConnectionStrategy | ConnectionOptions): Connection;
91
function createConnection(
92
    inputStream: NodeJS.ReadableStream, 
93
    outputStream: NodeJS.WritableStream, 
94
    options?: ConnectionStrategy | ConnectionOptions
95
): Connection;
96
function createConnection(
97
    reader: MessageReader, 
98
    writer: MessageWriter, 
99
    options?: ConnectionStrategy | ConnectionOptions
100
): Connection;
101
```
102

103
[Connection Management](./connection.md)
104

105
### Document Management
106

107
Text document lifecycle management and synchronization between client and server. Handles document open, change, save, and close events.
108

109
```typescript { .api }
110
class TextDocuments<T extends { uri: DocumentUri }> {
111
    constructor(configuration: TextDocumentsConfiguration<T>);
112
    onDidOpen: Event<TextDocumentChangeEvent<T>>;
113
    onDidClose: Event<TextDocumentChangeEvent<T>>;
114
    onDidChangeContent: Event<TextDocumentChangeEvent<T>>;
115
    onDidSave: Event<TextDocumentChangeEvent<T>>;
116
    onWillSave: Event<TextDocumentWillSaveEvent<T>>;
117
    get(uri: DocumentUri): T | undefined;
118
    all(): T[];
119
    keys(): DocumentUri[];
120
    listen(connection: TextDocumentConnection): void;
121
}
122

123
interface TextDocumentsConfiguration<T extends { uri: DocumentUri }> {
124
    create(uri: DocumentUri, languageId: string, version: number, content: string): T;
125
    update(document: T, changes: TextDocumentContentChangeEvent[], version: number): T;
126
}
127
```
128

129
[Document Management](./documents.md)
130

131
### Language Features
132

133
Complete Language Server Protocol feature implementations including completion, hover, diagnostics, and all standard LSP capabilities.
134

135
```typescript { .api }
136
interface Connection {
137
    onCompletion(handler: CompletionHandler): Disposable;
138
    onHover(handler: HoverHandler): Disposable;
139
    onDefinition(handler: DefinitionHandler): Disposable;
140
    onReferences(handler: ReferencesHandler): Disposable;
141
    onDocumentSymbol(handler: DocumentSymbolHandler): Disposable;
142
    // ... all other LSP handlers
143
}
144

145
type CompletionHandler = RequestHandler<CompletionParams, CompletionItem[] | CompletionList | null, CompletionItem>;
146
type HoverHandler = RequestHandler<HoverParams, Hover | null, void>;
147
type DefinitionHandler = RequestHandler<DefinitionParams, Definition | DefinitionLink[] | null, void>;
148
```
149

150
[Language Features](./language-features.md)
151

152
### Extended Features
153

154
Advanced Language Server Protocol features including semantic tokens, call hierarchy, type hierarchy, and diagnostics.
155

156
```typescript { .api }
157
interface Languages {
158
    semanticTokens: {
159
        on(handler: SemanticTokensHandler): Disposable;
160
        onDelta(handler: SemanticTokensDeltaHandler): Disposable;
161
        onRange(handler: SemanticTokensRangeHandler): Disposable;
162
        refresh(): void;
163
    };
164
    callHierarchy: {
165
        onPrepare(handler: CallHierarchyPrepareHandler): Disposable;
166
        onIncomingCalls(handler: CallHierarchyIncomingCallsHandler): Disposable;
167
        onOutgoingCalls(handler: CallHierarchyOutgoingCallsHandler): Disposable;
168
    };
169
    typeHierarchy: {
170
        onPrepare(handler: TypeHierarchyPrepareHandler): Disposable;
171
        onSupertypes(handler: TypeHierarchySupertypesHandler): Disposable;
172
        onSubtypes(handler: TypeHierarchySubtypesHandler): Disposable;
173
    };
174
}
175
```
176

177
[Extended Features](./extended-features.md)
178

179
### Notebook Support
180

181
Notebook document synchronization and management for Jupyter notebooks and other notebook formats. Supports both notebook-level and cell-level text document management.
182

183
```typescript { .api }
184
class NotebookDocuments<T extends { uri: DocumentUri }> {
185
    constructor(configurationOrTextDocuments: TextDocumentsConfiguration<T> | TextDocuments<T>);
186
    onDidOpen: Event<NotebookDocument>;
187
    onDidChange: Event<NotebookDocumentChangeEvent>;
188
    onDidSave: Event<NotebookDocument>;
189
    onDidClose: Event<NotebookDocument>;
190
    getCellTextDocument(cellUri: DocumentUri): T | undefined;
191
    getNotebookDocument(notebookUri: DocumentUri): NotebookDocument | undefined;
192
    getNotebookCell(cellUri: DocumentUri): NotebookCell | undefined;
193
}
194
```
195

196
[Notebook Support](./notebooks.md)
197

198
### Utility Classes
199

200
Helper classes for common language server tasks including semantic token building, error tracking, and progress reporting.
201

202
```typescript { .api }
203
class SemanticTokensBuilder {
204
    constructor();
205
    push(line: number, char: number, length: number, tokenType: number, tokenModifiers?: number): void;
206
    build(): SemanticTokens;
207
    buildEdits(): SemanticTokensEdits;
208
}
209

210
class ErrorMessageTracker {
211
    constructor();
212
    add(message: string): void;
213
    sendErrors(connection: { window: RemoteWindow }): void;
214
}
215
```
216

217
[Utility Classes](./utilities.md)
218

219
## Core Types
220

221
```typescript { .api }
222
interface Connection extends _Connection {
223
    console: RemoteConsole;
224
    tracer: RemoteTracer;
225
    telemetry: Telemetry;
226
    client: RemoteClient;
227
    window: RemoteWindow;
228
    workspace: RemoteWorkspace;
229
    languages: Languages;
230
    notebooks: Notebooks;
231
    
232
    onInitialize(handler: RequestHandler<InitializeParams, InitializeResult, InitializeError>): Disposable;
233
    onInitialized(handler: NotificationHandler<InitializedParams>): Disposable;
234
    onShutdown(handler: RequestHandler0<void, void>): Disposable;
235
    onExit(handler: NotificationHandler0): Disposable;
236
    
237
    sendDiagnostics(params: PublishDiagnosticsParams): void;
238
    sendProgress<T>(type: ProgressType<T>, token: string | number, value: T): void;
239
    
240
    listen(): void;
241
    dispose(): void;
242
}
243

244
interface TextDocumentChangeEvent<T> {
245
    document: T;
246
}
247

248
interface TextDocumentWillSaveEvent<T> {
249
    document: T;
250
    reason: TextDocumentSaveReason;
251
}
252

253
type DocumentUri = string;
254

255
interface Disposable {
256
    dispose(): void;
257
}
258

259
type Event<T> = (listener: (e: T) => any, thisArg?: any) => Disposable;
260
```