| description | Documentation site for lspeasy Use when: The client sets `partialResultToken` in the request params and you want to.... |
| name | lspeasy-server |
@lspeasy/server
Documentation site for lspeasy
Use @lspeasy/server when you need to build the provider side of the
Language Server Protocol — a daemon that editors and language-client tooling
connect to in order to get diagnostics, completions, hover, go-to-definition,
and other language intelligence features.
The primary entry point is LSPServer. Construct it with
ServerOptions, call registerCapabilities(caps) to declare what
the server supports, register handlers with onRequest / onNotification,
then call listen(transport) to accept the first client connection.
Transport Decision Tree
Stdio (StdioTransport from @lspeasy/core/node)
— Use when: the client spawns your server as a child process (the canonical
VS Code extension pattern). No network, no port management. Failure mode:
ConsoleLogger writes to stdout and corrupts the LSP stream — always use
NullLogger or a file-based logger with stdio.
WebSocket (WebSocketTransport from @lspeasy/core)
— Use when: multiple clients connect over a network, or the server must be
browser-accessible. Each accepted WebSocket connection needs its own
LSPServer instance. Failure mode: one client crash should not affect
others — wrap each wss.on('connection') callback in try/catch and
create a fresh LSPServer per socket.
TCP (TcpTransport from @lspeasy/core/node)
— Use when: building a persistent local daemon (e.g. a formatting server
shared across editor sessions). Failure mode: client disconnect fires
close() on the server instance — use mode: 'server' and create a new
LSPServer on each reconnect.
DedicatedWorkerTransport (DedicatedWorkerTransport from @lspeasy/core)
— Use when: running the server logic in a Web Worker for in-process browser
isolation. Zero serialization overhead. Failure mode: worker crash is
silent from the server side — monitor the worker's onerror in the host.
Typed capability namespaces
After registerCapabilities({ hoverProvider: true }), TypeScript exposes
server.textDocument.onHover(handler) — methods that are absent unless the
corresponding capability is declared. This prevents accidentally registering
handlers for capabilities the server never advertised.
Handler conventions
- RequestHandler — async, throws ResponseError for
structured errors, checks
token.isCancellationRequested for early exit.
- NotificationHandler — fire-and-forget; unhandled rejections
surface via
server.onError().
When to Use
Use this skill when:
- The client sets
partialResultToken in the request params and you want to stream intermediate results (e.g. symbols found so far) rather than waiting for the complete set. → use PartialResultSender
- A request handler needs to reject with a machine-readable error code that the client can act on (e.g. respond with
MethodNotFound when a capability was not declared, or InvalidParams when schema validation fails). → use ResponseError
Do NOT use when:
- You want to log a server-side error without sending an error to the client — throw a plain
Error and handle it via server.onError() instead.
API surface: 4 classes, 27 types, 1 enums, 2 constants
NEVER
- NEVER register the same method in both the request and notification handler registries — the dispatcher uses separate lookup tables and the method will only match one path, silently ignoring the other.
- NEVER call
dispatch before calling setClientCapabilities if your handler reads context.clientCapabilities — the value will be undefined until the initialize request is processed.
- NEVER call
send after the handler has already returned a response — the $/progress notification will arrive after the client has closed the partial-result channel, and the client will silently discard or error on it.
- NEVER send partial results without a
partialResultToken — the client has no way to correlate the $/progress notification to the pending request.
- NEVER throw
ResponseError with a code outside the defined ranges without documenting it. Undocumented codes are opaque to clients and tools.
- NEVER use
ConsoleLogger in a stdio LSP server (StdioTransport) — the LSP base protocol uses stdout as the message channel. Any console.log / console.info / console.debug output will corrupt the stdio stream. Use NullLogger or a file-based logger instead, and send diagnostic messages via window/logMessage notifications.
Configuration
ServerOptions — Configuration for an LSPServer instance. (10 options — see references/config.md)
Quick Reference
Key classes: MessageDispatcher (Routes incoming JSON-RPC requests and notifications to their registered handlers), PartialResultSender (Emits typed $/progress partial-result batches from server-side request handlers), ResponseError (An Error subclass that maps to a JSON-RPC 2), ConsoleLogger (Logger implementation that writes to the process console with level filtering)
34 exports total — see references/ for full API.
References
Load these on demand — do NOT read all at once:
- When using a class → read
references/classes.md for properties, methods, and inheritance
- When defining typed variables or function parameters → read
references/types.md
- When using exported constants → read
references/variables.md
- When configuring options → read
references/config.md for all settings and defaults
Links
