lspeasy / core/src

core/src

Core types, transports, and utilities shared by all lspeasy packages.

Remarks

@lspeasy/core is the shared foundation for the lspeasy SDK. It contains everything needed to build custom LSP integrations, and re-exports the most-used pieces from @lspeasy/client and @lspeasy/server.

Key areas

JSON-RPC 2.0 — Message types (RequestMessage, NotificationMessage, ResponseMessage) and framing (parseMessage, serializeMessage). Zod schemas for validating them live in @lspeasy/core/schemas.

Transports — The Transport interface is exported here; the implementations are not. Browser transports (WebSocketTransport, DedicatedWorkerTransport, SharedWorkerTransport) are in @lspeasy/core/transport; Node.js transports (StdioTransport, TcpTransport, IpcTransport, SocketTransport) are in @lspeasy/core/node, so browser bundles never pull node: builtins.

This barrel deliberately contains no runtime zod. See barrel-purity.test.ts and the design note in docs/superpowers/specs/2026-09-02-zod-off-the-runtime-path-design.md.

Transport Selection Guide

Need	Transport	Critical Gotcha
Spawn server as child process	StdioTransport	ConsoleLogger corrupts stdout — use NullLogger
Browser or remote server	WebSocketTransport	Call send() only after isConnected() is true
Persistent local daemon	TcpTransport	Create a new server instance per client reconnect
In-process browser isolation	DedicatedWorkerTransport	Monitor worker.onerror; crashes are silent
Shared worker, multiple tabs	SharedWorkerTransport	One worker handles all port connections

Middleware — The Middleware pipeline runs on every client-to-server and server-to-client message. Use createScopedMiddleware to limit a middleware to specific methods, and createTypedMiddleware for full param/result type inference.

LSP protocol — LSPRequest and LSPNotification namespaces expose every standard LSP method with its params and result types. LSPRequestMethod / LSPNotificationMethod are the union types for string-literal method names.

Utilities — CancellationTokenSource for request cancellation, DisposableStore for lifecycle management, ResponseError for structured JSON-RPC errors, DocumentVersionTracker for document sync.

Document

Name	Description
DocumentVersionTracker	Tracks monotonically increasing version numbers for open text documents.
createFullDidChangeParams	Builds DidChangeTextDocumentParams for a full-document text replacement.
createIncrementalDidChangeParams	Builds DidChangeTextDocumentParams for an incremental (range-based) document change notification.

Errors

Name	Description
ResponseError	An Error subclass that maps to a JSON-RPC 2.0 error response.
JSONRPCErrorCode	Numeric error codes defined by JSON-RPC 2.0 and the LSP specification.

JSON-RPC

Name	Description
BaseMessage	Base JSON-RPC 2.0 message discriminant.
ErrorResponseMessage	JSON-RPC 2.0 error response to a prior request.
NotificationMessage	JSON-RPC 2.0 Notification message — no response is expected or sent.
RequestMessage	JSON-RPC 2.0 Request message — expects a response from the peer.
ResponseErrorInterface	JSON-RPC 2.0 error object embedded in an error response.
SuccessResponseMessage	JSON-RPC 2.0 success response to a prior request.
Message	Union of all JSON-RPC 2.0 message types sent over a transport.
ResponseMessage	JSON-RPC 2.0 Response message — either a success result or an error.
isErrorResponse	Returns true when response carries an error (error case).
isNotificationMessage	Returns true when message is a JSON-RPC notification (has method, no id).
isRequestMessage	Returns true when message is a JSON-RPC request (has id + method).
isResponseMessage	Returns true when message is a JSON-RPC response (has id, no method).
isSuccessResponse	Returns true when response carries a result (success case).
parseMessage	Parses a single framed JSON-RPC 2.0 message from a raw byte buffer.
serializeMessage	Serializes a JSON-RPC 2.0 message into a framed byte buffer with Content-Length and Content-Type headers.

Lifecycle

Name	Description
CancellationTokenSource	Controller that creates and manages a CancellationToken.
DisposableStore	Collects multiple Disposable instances and releases them together.
CancellationToken	Read-only handle for observing cancellation state.
Disposable	Represents a resource that can be explicitly released.

Logging

Name	Description
LogLevel	Numeric severity levels for filtering log output.
ConsoleLogger	Logger implementation that writes to the process console with level filtering.
NullLogger	No-op logger that silently discards all messages.
Logger	Structured logging interface used throughout lspeasy.

Middleware

Name	Description
MethodFilter	Filter predicate used by ScopedMiddleware to select which messages a middleware should intercept.
MiddlewareContext	Execution context passed to every middleware function in the pipeline.
MiddlewareResult	The return value from a middleware function.
ScopedMiddleware	A Middleware paired with a MethodFilter so it only runs for matching messages.
TypedMiddlewareContext	Typed middleware context narrowed to a specific LSP method. Use with createTypedMiddleware for full type inference.
LSPMethod	Union of all LSP request and notification method strings.
Middleware	A function that intercepts JSON-RPC messages flowing through LSPServer or LSPClient.
MiddlewareDirection	Direction of a JSON-RPC message in the middleware pipeline.
MiddlewareMessage	The JSON-RPC message exposed to middleware, with id made read-only to prevent accidental mutation that would break response correlation.
MiddlewareMessageType	Kind of JSON-RPC message flowing through middleware.
MiddlewareNext	Calls the next middleware (or final handler) in the pipeline.
TypedMiddleware	A middleware function narrowed to a specific LSP method with full type inference for params and result.
TypedParams	Infers the params type for a given LSP method.
TypedResult	Infers the result type for a given LSP method (void for notifications).
composeMiddleware	Combines multiple middleware functions into a single middleware that runs them left-to-right, each delegating to the next via next().
createScopedMiddleware	Wraps a middleware with a filter so it only runs for matching LSP messages.
createTypedMiddleware	Creates a typed, method-scoped middleware with full TypeScript inference for the message params and result.
executeMiddlewarePipeline	Runs the registered middleware chain for a single JSON-RPC message, then calls finalHandler if no middleware short-circuits.

Other

CancellationTokenNone

Renames and re-exports CancellationToken

Transport

Interface	Description
Transport	Pluggable communication layer for JSON-RPC message exchange.
WebSocketTransportOptions	Options for configuring a WebSocketTransport.

Utilities

Name	Description
CLIENT_METHODS	Pre-built method sets indexed by client capability. Used by ClientCapabilityGuard in @lspeasy/client and @lspeasy/server.
SERVER_METHODS	Pre-built method sets indexed by server capability. Used by CapabilityGuard in @lspeasy/client and @lspeasy/server.
buildMethodSets	Builds the full set of LSP methods and the subset that are always allowed (not gated by a capability) for a given capability key.