--- description: "LSP server package for hosting Language Server Protocol (LSP) servers. Use when: The client sets `partialResultToken` in the request params and you want to...." name: lspeasy-server --- # @lspeasy/server LSP server package for hosting Language Server Protocol (LSP) servers. 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. (12 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 - Author: Pradeep Mouli (https://github.com/pradeepmouli)