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 2, the IDE implements a subset of version 3.15 of the LSP specification.

In addition to the base protocol, the following features are supported from the Language Server Protocol:

Window Features

Telemetry

Workspace

Text Synchronization

Diagnostics

Language Features

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
initializationOptions Custom options to send with the LSP initialize request (object) Added in Nova 2.
syntaxes Syntax names for which the client is valid (array)
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:

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.

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.