pro_lsp

Unified LSP 3.18 Dart bindings and a typed server/client framework. pro_lsp is lightweight, transport-agnostic, and strictly type-safe — build Language Servers and Language Clients in Dart without hand-writing JSON-RPC plumbing.

import 'package:pro_lsp/pro_lsp.dart';

void main() async {
  final server = LspServer();

  server.general.onInitialize((params, context) async {
    return const InitializeResult(
      capabilities: ServerCapabilities(hoverProvider: .bool(true)),
      serverInfo: ServerInfo(name: 'my-dart-lsp', version: '1.0.0'),
    );
  });

  server.textDocument.onHover((params, context) async {
    return Hover(
      contents: HoverContents.markupContent(
        MarkupContent(kind: .markdown, value: '`${params.textDocument.uri}`'),
      ),
    );
  });

  // Blocks until the client exits. `shutdown`/`exit` are handled for you.
  await server.listen();
}

Never write to stdout from a stdio server. On stdio, stdout is the protocol channel — a stray print() corrupts the JSON-RPC stream. Log to stderr or a file, and set server.onError. See Building a server → Logging.

Why pro_lsp

• Complete LSP 3.18 surface, generated from the official Microsoft meta-model: Freezed structures (copyWith, value equality, JSON), extension type unions, and open/closed enums.
• Typed, symmetric API — incoming messages are handlers (server.textDocument.onHover(...)); outgoing messages are senders (server.client.window.showMessage(...)). The client mirrors the server.
• Lifecycle handled for you — an enforced state machine (uninitialized → initialized → shuttingDown → exited) with sensible shutdown/exit defaults.
• Cancellation both ways via CancellationToken, plus timeout on outgoing requests.
• Typed errors — everything surfaces as LspException; you never touch the transport's RpcException.
• Pluggable & extensible — modular LspFeatures, middleware, and a built-in service container (DI).
• Transport-agnostic framing over stdio, TCP, or any byte stream via LspByteStreamChannel.

Install

dart pub add pro_lsp

Requires Dart SDK ^3.10 — the generated API uses recent language features, including dot-shorthands for enums and union factories (.bool(true), .markdown). Where the target type is known, you can drop the type name and start with ..

Documentation

The full guide lives in doc/. Start there for concepts, end-to-end walkthroughs, and a per-method tutorial covering every LSP request and notification with "what / when / example".

Guides

• Getting started — install, first server, first client
• Core concepts — handlers, senders, context, lifecycle
• Building a server — capabilities, talking back, lifecycle, logging
• Building a client — handshake, calling the server, receiving messages
• Working with models — Freezed structures, unions, enums
• Error handling — LspException, error codes
• Cancellation — incoming and outgoing
• Testing — in-memory client↔server
• Transports — stdio, sockets, custom framing
• Advanced — features, dependency injection, middleware

Method reference (catalog)

• Lifecycle & protocol — initialize, shutdown, progress, trace
• Document sync — didOpen / didChange / didClose / save
• Language features — hover, definition, completion, …
• Call & type hierarchy
• Workspace — symbols, commands, files, configuration, refresh
• Window — messages, progress, show document
• Notebooks

License

MIT — see LICENSE for details.