0
# Connection Management
1

2
Core connection establishment and communication infrastructure for Language Server Protocol implementations. The connection handles all communication between the language client and server.
3

4
## Capabilities
5

6
### Create Connection
7

8
Creates a new LSP connection with various configuration options. The connection can be created automatically from command line arguments, with specific streams, or with custom message readers/writers.
9

10
```typescript { .api }
11
/**
12
 * Creates a new connection based on the processes command line arguments
13
 */
14
function createConnection(): Connection;
15

16
/**
17
 * Creates a new connection with connection strategy or options
18
 * @param options Connection strategy or connection options to control additional settings
19
 */
20
function createConnection(options?: ConnectionStrategy | ConnectionOptions): Connection;
21

22
/**
23
 * Creates a new connection using the given streams
24
 * @param inputStream The stream to read messages from
25
 * @param outputStream The stream to write messages to
26
 * @param options Optional connection strategy or connection options
27
 */
28
function createConnection(
29
    inputStream: NodeJS.ReadableStream, 
30
    outputStream: NodeJS.WritableStream, 
31
    options?: ConnectionStrategy | ConnectionOptions
32
): Connection;
33

34
/**
35
 * Creates a new connection using message reader and writer
36
 * @param reader The message reader to read messages from
37
 * @param writer The message writer to write message to
38
 * @param options Optional connection strategy or connection options
39
 */
40
function createConnection(
41
    reader: MessageReader, 
42
    writer: MessageWriter, 
43
    options?: ConnectionStrategy | ConnectionOptions
44
): Connection;
45

46
/**
47
 * Creates a new connection with proposed features
48
 * @param factories The factories for implementing proposed API features
49
 * @param options Optional connection strategy or connection options
50
 */
51
function createConnection<PConsole = _, PTracer = _, PTelemetry = _, PClient = _, PWindow = _, PWorkspace = _, PLanguages = _, PNotebooks = _>(
52
    factories: Features<PConsole, PTracer, PTelemetry, PClient, PWindow, PWorkspace, PLanguages, PNotebooks>,
53
    options?: ConnectionStrategy | ConnectionOptions
54
): _Connection<PConsole, PTracer, PTelemetry, PClient, PWindow, PWorkspace, PLanguages, PNotebooks>;
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { createConnection, ProposedFeatures } from "vscode-languageserver";
61

62
// Auto-detect connection from command line arguments
63
const connection = createConnection();
64

65
// Connection with all proposed features
66
const proposedConnection = createConnection(ProposedFeatures.all);
67

68
// Connection with custom streams (Node.js)
69
import { createConnection } from "vscode-languageserver/node";
70
const streamConnection = createConnection(process.stdin, process.stdout);
71

72
// Connection with message reader/writer (browser)
73
import { createConnection } from "vscode-languageserver/browser";
74
const browserConnection = createConnection(reader, writer);
75
```
76

77
### Connection Interface
78

79
The main connection interface providing access to all LSP functionality and communication channels.
80

81
```typescript { .api }
82
interface Connection extends _Connection {
83
    /** Remote console for logging and showing messages */
84
    console: RemoteConsole;
85
    /** Remote tracer for debugging and tracing */
86
    tracer: RemoteTracer;
87
    /** Telemetry interface for sending telemetry events */
88
    telemetry: Telemetry;
89
    /** Remote client interface for client-specific capabilities */
90
    client: RemoteClient;
91
    /** Remote window interface for window operations */
92
    window: RemoteWindow;
93
    /** Remote workspace interface for workspace operations */
94
    workspace: RemoteWorkspace;
95
    /** Languages interface for language-specific features */
96
    languages: Languages;
97
    /** Notebooks interface for notebook support */
98
    notebooks: Notebooks;
99
    
100
    /** Handle server initialization */
101
    onInitialize(handler: RequestHandler<InitializeParams, InitializeResult, InitializeError>): Disposable;
102
    /** Handle server initialized notification */
103
    onInitialized(handler: NotificationHandler<InitializedParams>): Disposable;
104
    /** Handle server shutdown request */
105
    onShutdown(handler: RequestHandler0<void, void>): Disposable;
106
    /** Handle server exit notification */
107
    onExit(handler: NotificationHandler0): Disposable;
108
    
109
    /** Send diagnostics to the client */
110
    sendDiagnostics(params: PublishDiagnosticsParams): void;
111
    /** Send progress notifications */
112
    sendProgress<T>(type: ProgressType<T>, token: string | number, value: T): void;
113
    
114
    /** Start listening for messages */
115
    listen(): void;
116
    /** Dispose the connection */
117
    dispose(): void;
118
}
119
```
120

121
### Connection Options
122

123
Configuration options for customizing connection behavior.
124

125
```typescript { .api }
126
interface ConnectionOptions {
127
    /** Maximum number of problems reported per file */
128
    maxNumberOfProblems?: number;
129
    /** Working directory for the server */
130
    workspaceRoot?: string;
131
}
132

133
interface ConnectionStrategy {
134
    /** Custom message reader */
135
    reader?: MessageReader;
136
    /** Custom message writer */
137
    writer?: MessageWriter;
138
}
139
```
140

141
### Proposed Features
142

143
Access to experimental LSP features not yet part of the official specification.
144

145
```typescript { .api }
146
namespace ProposedFeatures {
147
    /** All proposed features combined */
148
    const all: Features<_, _, _, _, _, _, InlineCompletionFeatureShape, _>;
149
    
150
    /** Connection type with proposed features */
151
    type Connection = _Connection<_, _, _, _, _, _, InlineCompletionFeatureShape, _>;
152
}
153
```
154

155
### Generic Connection Interface
156

157
The generic connection interface with configurable feature types.
158

159
```typescript { .api }
160
interface _Connection<PConsole = _, PTracer = _, PTelemetry = _, PClient = _, PWindow = _, PWorkspace = _, PLanguages = _, PNotebooks = _> {
161
    console: PConsole;
162
    tracer: PTracer;
163
    telemetry: PTelemetry;
164
    client: PClient;
165
    window: PWindow;
166
    workspace: PWorkspace;
167
    languages: PLanguages;
168
    notebooks: PNotebooks;
169
    
170
    onRequest<R, PR, E, RO>(
171
        type: ProtocolRequestType0<R, PR, E, RO>,
172
        handler: RequestHandler0<R, E>
173
    ): Disposable;
174
    
175
    onRequest<P, R, PR, E, RO>(
176
        type: ProtocolRequestType<P, R, PR, E, RO>,
177
        handler: RequestHandler<P, R, E>
178
    ): Disposable;
179
    
180
    onNotification<RO>(
181
        type: ProtocolNotificationType0<RO>,
182
        handler: NotificationHandler0
183
    ): Disposable;
184
    
185
    onNotification<P, RO>(
186
        type: ProtocolNotificationType<P, RO>,
187
        handler: NotificationHandler<P>
188
    ): Disposable;
189
    
190
    sendRequest<R, PR, E, RO>(
191
        type: ProtocolRequestType0<R, PR, E, RO>,
192
        token?: CancellationToken
193
    ): Promise<R>;
194
    
195
    sendRequest<P, R, PR, E, RO>(
196
        type: ProtocolRequestType<P, R, PR, E, RO>,
197
        params: P,
198
        token?: CancellationToken
199
    ): Promise<R>;
200
    
201
    sendNotification<RO>(type: ProtocolNotificationType0<RO>): Promise<void>;
202
    sendNotification<P, RO>(type: ProtocolNotificationType<P, RO>, params: P): Promise<void>;
203
    
204
    listen(): void;
205
    dispose(): void;
206
}
207
```
208

209
## Platform-Specific Features
210

211
### Node.js Specific
212

213
Additional file system utilities available when using the Node.js entry point.
214

215
```typescript { .api }
216
namespace Files {
217
    /** Convert URI to file path */
218
    function uriToFilePath(uri: string): string | undefined;
219
    /** Resolve global Node.js module path */
220
    function resolveGlobalNodePath(path: string): string | undefined;
221
    /** Resolve global Yarn module path */
222
    function resolveGlobalYarnPath(path: string): string | undefined;
223
    /** Resolve module with optional node path and working directory */
224
    function resolve(
225
        moduleName: string,
226
        nodePath?: string,
227
        cwd?: string,
228
        tracer?: (message: string, verbose?: string) => void
229
    ): Promise<string>;
230
    /** Resolve module path with workspace context */
231
    function resolveModulePath(
232
        workspaceRoot: string,
233
        moduleName: string,
234
        nodePath?: string,
235
        tracer?: (message: string, verbose?: string) => void
236
    ): Promise<string>;
237
}
238
```
239

240
### Browser Specific
241

242
Browser connections require explicit message reader and writer instances.
243

244
```typescript { .api }
245
/**
246
 * Creates a new connection for browser environments
247
 * @param reader The message reader to read messages from
248
 * @param writer The message writer to write message to
249
 * @param options Optional connection strategy or connection options
250
 */
251
function createConnection(
252
    reader: MessageReader, 
253
    writer: MessageWriter, 
254
    options?: ConnectionStrategy | ConnectionOptions
255
): Connection;
256
```
257

258
## Core Types
259

260
```typescript { .api }
261
type RequestHandler<P, R, E> = (params: P, token: CancellationToken, workDoneProgress: WorkDoneProgressReporter, partialResultProgress: ResultProgressReporter<Partial<R>>) => HandlerResult<R, E>;
262

263
type RequestHandler0<R, E> = (token: CancellationToken, workDoneProgress: WorkDoneProgressReporter, partialResultProgress: ResultProgressReporter<Partial<R>>) => HandlerResult<R, E>;
264

265
type NotificationHandler<P> = (params: P) => void;
266

267
type NotificationHandler0 = () => void;
268

269
type HandlerResult<R, E> = R | ResponseError<E> | Promise<R> | Promise<ResponseError<E>>;
270

271
interface Disposable {
272
    dispose(): void;
273
}
274

275
interface CancellationToken {
276
    readonly isCancellationRequested: boolean;
277
    readonly onCancellationRequested: Event<any>;
278
}
279
```