lspeasy / core/src / WebSocketTransport

Class: WebSocketTransport

Defined in: packages/core/src/transport/websocket.ts:240

WebSocket-based transport for LSP communication.

Remarks

Operates in two modes, determined by the constructor options:

• Client mode (url provided) — opens a new WebSocket connection to the given URL. Optionally supports automatic reconnection with exponential back-off.
• Server mode (socket provided) — wraps an already-accepted WebSocket instance (e.g. from an http.Server upgrade event).

Works in browsers (native WebSocket), Node.js ≥ 22.4 (native globalThis.WebSocket), and earlier Node.js versions with the optional ws peer dependency installed.

Throws

When neither url nor socket is provided. Fix: supply exactly one — url for client mode, socket for server mode.

Throws

When both url and socket are provided. Fix: mutually exclusive — pick one mode per instance.

Throws

(from send()) When the socket is not yet open (still in CONNECTING state). Fix: wait for the transport's first message or use isConnected() before calling send(); in client mode the socket connects asynchronously after construction.

Use When

You are building a browser-based LSP client, a WebSocket-backed language server, or any LSP integration that must run over HTTP/HTTPS infrastructure.

Avoid When

You are building a CLI language server — StdioTransport (from @lspeasy/core/node) is the conventional choice and avoids the overhead of a network stack. For same-process workers prefer DedicatedWorkerTransport or SharedWorkerTransport.

Never

NEVER set enableReconnect: true in server mode (socket provided) — the option is silently ignored (reconnect has no URL to reconnect to), but the intent is misleading and suggests lifecycle management will be handled when it is not.

NEVER send messages before isConnected() returns true. In client mode the socket is in CONNECTING state immediately after construction; send() will throw until the open event fires.

Examples

// Client mode — connect to a running WebSocket LSP server
import { LSPClient } from '@lspeasy/server';
import { WebSocketTransport } from '@lspeasy/core';

const transport = new WebSocketTransport({ url: 'ws://localhost:2087' });
const client = new LSPClient();
await client.connect(transport);

// Server mode — wrap an accepted WebSocket (e.g. inside a ws upgrade handler)
import { LSPServer } from '@lspeasy/server';
import { WebSocketTransport } from '@lspeasy/core';
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 2087 });
wss.on('connection', (socket) => {
  const transport = new WebSocketTransport({ socket });
  const server = new LSPServer();
  void server.listen(transport);
});

Implements

• Transport

Constructors

Constructor

new WebSocketTransport(options): WebSocketTransport;

Defined in: packages/core/src/transport/websocket.ts:259

Parameters

Parameter	Type
options	WebSocketTransportOptions

Returns

WebSocketTransport

Methods

close()

close(): Promise<void>;

Defined in: packages/core/src/transport/websocket.ts:494

Close the WebSocket connection

Returns

Promise<void>

Implementation of

Transport.close

---

getReconnectAttempts()

getReconnectAttempts(): number;

Defined in: packages/core/src/transport/websocket.ts:536

Get the current reconnection attempt count.

Returns

number

The number of reconnection attempts made since the last successful connection.

---

isConnected()

isConnected(): boolean;

Defined in: packages/core/src/transport/websocket.ts:527

Check if the transport is currently connected

Returns

boolean

Implementation of

Transport.isConnected

---

isReconnectEnabled()

isReconnectEnabled(): boolean;

Defined in: packages/core/src/transport/websocket.ts:543

Check if reconnection is enabled

Returns

boolean

---

onClose()

onClose(handler): Disposable;

Defined in: packages/core/src/transport/websocket.ts:481

Register a handler for transport closure.

Parameters

Parameter	Type	Description
handler	() => void	Callback invoked when the WebSocket closes (clean or error).

Returns

Disposable

A Disposable — call dispose() to unregister the handler.

Implementation of

Transport.onClose

---

onError()

onError(handler): Disposable;

Defined in: packages/core/src/transport/websocket.ts:465

Register a handler for transport errors.

Parameters

Parameter	Type	Description
handler	(error) => void	Callback invoked whenever a WebSocket error occurs.

Returns

Disposable

A Disposable — call dispose() to unregister the handler.

Implementation of

Transport.onError

---

onMessage()

onMessage(handler): Disposable;

Defined in: packages/core/src/transport/websocket.ts:449

Register a handler for incoming messages.

Parameters

Parameter	Type	Description
handler	(message) => void	Callback invoked with each parsed Message received over the socket.

Returns

Disposable

A Disposable — call dispose() to unregister the handler.

Implementation of

Transport.onMessage

---

send()

send(message): Promise<void>;

Defined in: packages/core/src/transport/websocket.ts:414

Send a message through the WebSocket

Parameters

Parameter	Type
message	Message

Returns

Promise<void>

Implementation of

Transport.send