LanguageClient
A LanguageClient is an interface for adding a language server compatible with the Language Server Protocol specification. Creating an instance of a LanguageClient object sets up configuration for the server, at which point communication with the server is handed-off to the application.
The LanguageClient class is not subclassable.
Supported Language Server Features
As of Nova 10, in addition to the base protocol, the IDE implements the following features of the LSP specification:
Window Features
Telemetry
Workspace
Text Synchronization
Diagnostics
Language Features
Debug Logging
To better help with development of a language server extension, Nova supports debugging logging of messages to the Extension Console.
In Nova 9, debug logging was enabled by default if the extension was loaded for development. This was changed in Nova 10 to require enabling it explicitly for better performance during development, as many language servers are very chatty.
To enable debugging logging, set the debug option in the clientOptions to true when creating a LanguageClient instance
Class Methods
constructor(identifier, name, serverOptions, clientOptions)
Creates a LanguageClient object for communication with a language server.
The identifier parameter should be a simple, unique string that can be used to identify the server (such as "typescript"). It will not be displayed to the user.
The name parameter is the name of the server that can potentially be shown to the user, to indicate that the server has been enabled and is in use.
The serverOptions object defines configuration settings for launching and communicating with the server executable:
| Value | Description | Note |
|---|---|---|
| args | Additional arguments to pass (array) | |
| env | Additional environment variables to set (object) | |
| path | The path to the server executable | Absolute, or relative to the extension’s bundle) |
| type | The type of transport to use (“stdio”, “socket”, “pipe”) | Defaults to “stdio” if not value is specified |
The clientOptions object defines configuration settings for how the editor invokes the language client:
| Value | Description | Note |
|---|---|---|
| debug | Enable debug logging to the Extension Console | Added in Nova 10. |
| initializationOptions | Custom options to send with the LSP initialize request (object) | Added in Nova 2. |
| syntaxes | Syntaxes for which the client is valid (array, see “Syntaxes” below) |
var serverOptions = {
path: path
};
var clientOptions = {
syntaxes: ['typescript']
};
var client = new LanguageClient('typescript', 'TypeScript Language Server', serverOptions, clientOptions);
client.start();
Supported Language Server Transport Types
The LanguageClient interface and extension APIs support three methods of standard communication with language server subprocesses:
stdio: Connects to the subprocess’s standard I/O channels (this is the default)socket: Connects to a specified socket port accessible on the local machinepipe: Connects to a specified Unix Domain Socket via a path or file descriptor
Standard I/O
When the stdio transport type is specified, the subprocess receives no additional launch arguments. This is the default behavior for language clients.
Sockets
When the socket transport type is specified, the subprocess will receive a launch argument --socket whose value is a port on which the client will attempt to connect on the TCP/IP nameserver. The server is responsible for opening a communication channel to listen for connections on this port.
Unix Domain Sockets (Pipe)
When the pipe transport type is specified, the subprocess will receive a launch argument --pipe whose value is a filename on disk on which the client will attempt to open a domain socket channel. The server is responsible for opening a communication channel and listening for messages from the client.
Syntaxes
To specify which documents in a workspace are relevant to a language server, the syntaxes client option should be used. The value for this key is an array.
Syntaxes may be specified by name, which will make any documents using those syntaxes available to the language server:
clientOptions: {
syntaxes: ['javascript', 'typescript', 'tsx']
}
Starting with Nova 10, the syntaxes array may contain objects which specify additional options:
clientOptions: {
syntaxes: [
'javascript',
'typescript',
{'syntax': 'tsx', 'languageId': 'typescript-react'}
]
}
The available options for a syntax object are:
| Value | Description |
|---|---|
| syntax | The syntax name |
| languageId | The Language Server Protocol language ID. If not present, the syntax name is used. |
Properties
identifier
The identifier of the language client specified when it was created.
This property is readonly.
name
The visible name of the language client specified when it was created.
This property is readonly.
running
A boolean indicating whether the client’s language server is currently running. This value will be false before .start() is invoked, and after the language server is stopped.
This property is readonly.
Methods
onDidStop(callback, [thisValue])
Adds an event listener that invokes the provided callback when the language server stops. The callback will receive as an argument an Error object if the language server stopped unexpectedly. Otherwise, this argument will be undefined.
The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.
This method returns a Disposable that can be used to unregister the listener.
Added in Nova 2.
onNotification(method, callback)
Registers a notification handler with the language client. If the language service sends a notification with the provided method name to the host it will be forwarded to the provided callback. The callback will receive the parameters objects as an argument.
If another handler was previously registered for the provided method name it will be replaced.
Note: This should only be used for methods that are not part of the core Language Server Protocol specification. Attempting to register handlers for core methods will not invoke the provided callback.
onRequest(method, callback)
Registers a request handler with the language client. If the language service sends a request with the provided method name to the host it will be forwarded to the provided callback. The callback will receive the parameters objects as an argument, and the return value will be returned to the language service as the response. If the return value is a Promise, it will be returned once the promise resolves or rejects.
If another handler was previously registered for the provided method name it will be replaced.
Note: This should only be used for methods that are not part of the core Language Server Protocol specification. Attempting to register handlers for core methods will not invoke the provided callback.
sendRequest(method, [params])
Sends a request with the provided method name to the language service, and returns a Promise object that resolves when the reply or an error is received by the host. The resolved value will be the parameters returned in the response.
sendNotification(method, [params])
Sends a notification with the provided method name to the language service.
start()
Attempts to asynchronously start the language server. If the server was already running, or is in the process of stopping, this method does nothing. If the server is unable to start, such as if the executable was not found at the specified path or module, then an error will be sent via the onDidStop event listener.
Changed in Nova 2: This method may be invoked safely after the language server stops to attempt to restart it. In previous versions, this would raise an Error.
stop()
Attempts to asynchronously stop the language server. If the server was not running, this method does nothing.