0
# Core Client
1

2
Core client classes and lifecycle management for establishing and maintaining language server connections.
3

4
## Capabilities
5

6
### BaseLanguageClient
7

8
Abstract base class providing core functionality for all language clients.
9

10
```typescript { .api }
11
/**
12
 * Abstract base class for all language clients providing core LSP functionality
13
 */
14
abstract class BaseLanguageClient {
15
  /** Client name identifier */
16
  readonly name: string;
17
  
18
  /** Current client state */
19
  readonly state: State;
20
  
21
  /** Initialization result from the language server */
22
  readonly initializeResult: InitializeResult | undefined;
23
  
24
  /** Client configuration options */
25
  readonly clientOptions: LanguageClientOptions;
26
  
27
  /** Middleware configuration for feature customization */
28
  readonly middleware: Middleware;
29
  
30
  /** Output channel for client messages */
31
  readonly outputChannel: OutputChannel;
32
  
33
  /** Output channel for trace messages */
34
  readonly traceOutputChannel: OutputChannel;
35
  
36
  /** Diagnostic collection for server diagnostics */
37
  readonly diagnostics: DiagnosticCollection | undefined;
38
  
39
  /** Protocol to code converter instance */
40
  readonly protocol2CodeConverter: Protocol2CodeConverter;
41
  
42
  /** Code to protocol converter instance */
43
  readonly code2ProtocolConverter: Code2ProtocolConverter;
44
  
45
  /** Event emitted when client state changes */
46
  readonly onDidChangeState: Event<StateChangeEvent>;
47
  
48
  /** Event emitted for telemetry data from server */
49
  readonly onTelemetry: Event<any>;
50
  
51
  /** Start the language client and establish connection to server */
52
  start(): Promise<void>;
53
  
54
  /** Stop the language client with optional timeout */
55
  stop(timeout?: number): Promise<void>;
56
  
57
  /** Dispose the client and cleanup resources */
58
  dispose(timeout?: number): Promise<void>;
59
  
60
  /** Send a request to the language server */
61
  sendRequest<R, PR, E>(type: ProtocolRequestType<PR, R, E, any>, params: PR, token?: CancellationToken): Promise<R>;
62
  sendRequest<R, E>(type: RequestType0<R, E>, token?: CancellationToken): Promise<R>;
63
  sendRequest<R, P, E>(type: RequestType<P, R, E>, params: P, token?: CancellationToken): Promise<R>;
64
  
65
  /** Send a notification to the language server */
66
  sendNotification<RO>(type: ProtocolNotificationType<RO, any>, params?: RO): Promise<void>;
67
  sendNotification<P>(type: NotificationType<P>, params?: P): Promise<void>;
68
  sendNotification(type: NotificationType0): Promise<void>;
69
  
70
  /** Register a request handler for server requests */
71
  onRequest<R, PR, E>(type: ProtocolRequestType<PR, R, E, any>, handler: RequestHandler<PR, R, E>): Disposable;
72
  onRequest<R, E>(type: RequestType0<R, E>, handler: RequestHandler0<R, E>): Disposable;
73
  onRequest<R, P, E>(type: RequestType<P, R, E>, handler: RequestHandler<P, R, E>): Disposable;
74
  onRequest(method: string, handler: GenericRequestHandler): Disposable;
75
  
76
  /** Register a notification handler for server notifications */
77
  onNotification<RO>(type: ProtocolNotificationType<RO, any>, handler: NotificationHandler<RO>): Disposable;
78
  onNotification<P>(type: NotificationType<P>, handler: NotificationHandler<P>): Disposable;
79
  onNotification(type: NotificationType0, handler: NotificationHandler0): Disposable;
80
  onNotification(method: string, handler: GenericNotificationHandler): Disposable;
81
  
82
  /** Send progress notification */
83
  sendProgress<P>(type: ProgressType<P>, token: ProgressToken, value: P): Promise<void>;
84
  
85
  /** Register progress handler */
86
  onProgress<P>(type: ProgressType<P>, token: ProgressToken, handler: NotificationHandler<P>): Disposable;
87
  
88
  /** Set trace level for debugging */
89
  setTrace(value: Trace): Promise<void>;
90
  
91
  /** Register a feature with the client */
92
  registerFeature(feature: StaticFeature | DynamicFeature<any>): void;
93
  
94
  /** Get a registered feature by request method */
95
  getFeature(request: string): DynamicFeature<any> | undefined;
96
  
97
  /** Create message transports for communication (implemented by subclasses) */
98
  protected abstract createMessageTransports(encoding: string): Promise<MessageTransports>;
99
  
100
  /** Handle connection errors */
101
  protected handleConnectionError(error: Error, message: Message | undefined, count: number | undefined): void;
102
  
103
  /** Handle connection closed */
104
  protected handleConnectionClosed(): void;
105
}
106
```
107

108
**Usage Examples:**
109

110
Basic client lifecycle:
111

112
```typescript
113
import { LanguageClient } from "vscode-languageclient/node";
114

115
const client = new LanguageClient(
116
  'my-language-client',
117
  'My Language Client', 
118
  serverOptions,
119
  clientOptions
120
);
121

122
// Start the client
123
await client.start();
124
console.log(`Client state: ${client.state}`); // State.Running
125

126
// Send a custom request
127
const result = await client.sendRequest('custom/method', { param: 'value' });
128

129
// Stop the client
130
await client.stop();
131
```
132

133
Request/notification handling:
134

135
```typescript
136
// Handle server requests
137
client.onRequest('workspace/configuration', (params) => {
138
  return [{ setting: 'value' }];
139
});
140

141
// Handle server notifications
142
client.onNotification('window/logMessage', (params) => {
143
  console.log(`Server: ${params.message}`);
144
});
145

146
// Send custom notification
147
await client.sendNotification('custom/notification', { data: 'value' });
148
```
149

150
### LanguageClient (Node.js)
151

152
Node.js implementation of the language client supporting various transport mechanisms.
153

154
```typescript { .api }
155
/**
156
 * Node.js implementation of LanguageClient supporting stdio, IPC, pipe, and socket transports
157
 */
158
class LanguageClient extends BaseLanguageClient {
159
  /** Whether the client is running in debug mode */
160
  readonly isInDebugMode: boolean;
161
  
162
  /**
163
   * Create a language client for Node.js environment
164
   * @param name - Client name (also used as ID)
165
   * @param serverOptions - Server configuration options
166
   * @param clientOptions - Client configuration options  
167
   * @param forceDebug - Force debug mode regardless of environment
168
   */
169
  constructor(name: string, serverOptions: ServerOptions, clientOptions: LanguageClientOptions, forceDebug?: boolean);
170
  
171
  /**
172
   * Create a language client with explicit ID and name
173
   * @param id - Client identifier
174
   * @param name - Display name for the client
175
   * @param serverOptions - Server configuration options
176
   * @param clientOptions - Client configuration options
177
   * @param forceDebug - Force debug mode regardless of environment
178
   */
179
  constructor(id: string, name: string, serverOptions: ServerOptions, clientOptions: LanguageClientOptions, forceDebug?: boolean);
180
  
181
  /** Create message transports based on server options */
182
  protected createMessageTransports(encoding: string): Promise<MessageTransports>;
183
}
184
```
185

186
### LanguageClient (Browser)
187

188
Browser implementation of the language client using Web Workers for communication.
189

190
```typescript { .api }
191
/**
192
 * Browser implementation of LanguageClient using Web Worker communication
193
 */
194
class LanguageClient extends BaseLanguageClient {
195
  /** The Web Worker running the language server */
196
  private readonly worker: Worker;
197
  
198
  /**
199
   * Create a language client for browser environment
200
   * @param id - Client identifier
201
   * @param name - Display name for the client
202
   * @param clientOptions - Client configuration options
203
   * @param worker - Web Worker instance running the language server
204
   */
205
  constructor(id: string, name: string, clientOptions: LanguageClientOptions, worker: Worker);
206
  
207
  /** Create message transports using browser message readers/writers */
208
  protected createMessageTransports(encoding: string): Promise<MessageTransports>;
209
}
210
```
211

212
**Usage Examples:**
213

214
Node.js client with stdio transport:
215

216
```typescript
217
import { LanguageClient, ServerOptions, TransportKind } from "vscode-languageclient/node";
218

219
const serverOptions: ServerOptions = {
220
  run: { command: 'language-server', transport: TransportKind.stdio },
221
  debug: { command: 'language-server', args: ['--debug'], transport: TransportKind.stdio }
222
};
223

224
const client = new LanguageClient(
225
  'example-client',
226
  'Example Language Client',
227
  serverOptions,
228
  clientOptions
229
);
230
```
231

232
Browser client with Web Worker:
233

234
```typescript
235
import { LanguageClient } from "vscode-languageclient/browser";
236

237
const worker = new Worker('./language-server-worker.js');
238
const client = new LanguageClient(
239
  'example-browser-client',
240
  'Example Browser Client',
241
  clientOptions,
242
  worker
243
);
244
```
245

246
## Types
247

248
### State Management
249

250
```typescript { .api }
251
enum State {
252
  /** Client is stopped */
253
  Stopped = 1,
254
  /** Client is starting up */
255
  Starting = 3,
256
  /** Client is running and connected */
257
  Running = 2
258
}
259

260
interface StateChangeEvent {
261
  /** Previous client state */
262
  oldState: State;
263
  /** New client state */
264
  newState: State;
265
}
266
```
267

268
### Message Transports
269

270
```typescript { .api }
271
interface MessageTransports {
272
  /** Message reader for receiving from server */
273
  reader: MessageReader;
274
  /** Message writer for sending to server */  
275
  writer: MessageWriter;
276
  /** Whether the transport is detached from the client lifecycle */
277
  detached?: boolean;
278
}
279
```