@lspeasy/server 4.0.1 → 4.0.3

package/dist/index.js

@@ -1,5 +1,56 @@
 /**
- * @lspeasy/server - Build LSP servers with simple, typed API
+ * LSP server package for hosting Language Server Protocol (LSP) servers.
+ *
+ * @remarks
+ * 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 {@link LSPServer}. Construct it with
+ * {@link 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
+ * - {@link RequestHandler} — async, throws {@link ResponseError} for
+ *   structured errors, checks `token.isCancellationRequested` for early exit.
+ * - {@link NotificationHandler} — fire-and-forget; unhandled rejections
+ *   surface via `server.onError()`.
+ *
+ * @packageDocumentation
  */
 // Main server class
 export { LSPServer } from './server.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oBAAoB;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAaxC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,+BAA+B;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AA0B1E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzF,uGAAuG;AACvG,gDAAgD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,oBAAoB;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAaxC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,+BAA+B;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AA0B1E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzF,uGAAuG;AACvG,gDAAgD"}

package/dist/lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAIR,IAAI;IACJ,OAAO;IACP,MAAM;IALjB,kBAAkB,GAAuB,EAAE,CAAC;IAEpD,YACmB,IAAY,EACZ,OAAe,EACf,MAAc,EAC/B;oBAHiB,IAAI;uBACJ,OAAO;sBACP,MAAM;IACtB,CAAC;IAEJ;;OAEG;IACH,oBAAoB,CAAC,YAAgC,EAAQ;QAC3D,IAAI,CAAC,kBAAkB,GAAG,YAAY,CAAC;IAAA,CACxC;IAED;;OAEG;IACH,eAAe,GAAuB;QACpC,OAAO,IAAI,CAAC,kBAAkB,CAAC;IAAA,CAChC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CACpB,MAAwB,EACxB,UAAqB,EACrB,GAAoB,EACO;QAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAqB;YAC/B,YAAY,EAAE,IAAI,CAAC,kBAAkB;YACrC,UAAU,EAAE;gBACV,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB;SACF,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACvC,OAAO,MAAM,CAAC;IAAA,CACf;IAED;;OAEG;IACH,iBAAiB,CAAC,MAAyB,EAAQ;QACjD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAAA,CAClD;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,UAAqB,EAAE,GAAoB,EAAiB;QAC/E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAAA,CAC9C;IAED;;OAEG;IACH,UAAU,GAAS;QACjB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAAA,CACjC;CACF"}
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAIR,IAAI;IACJ,OAAO;IACP,MAAM;IALjB,kBAAkB,GAAuB,EAAE,CAAC;IAEpD,YACmB,IAAY,EACZ,OAAe,EACf,MAAc;oBAFd,IAAI;uBACJ,OAAO;sBACP,MAAM;IACtB,CAAC;IAEJ;;OAEG;IACH,oBAAoB,CAAC,YAAgC;QACnD,IAAI,CAAC,kBAAkB,GAAG,YAAY,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CACpB,MAAwB,EACxB,UAAqB,EACrB,GAAoB;QAEpB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAqB;YAC/B,YAAY,EAAE,IAAI,CAAC,kBAAkB;YACrC,UAAU,EAAE;gBACV,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB;SACF,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACvC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,iBAAiB,CAAC,MAAyB;QACzC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,UAAqB,EAAE,GAAoB;QAC9D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/progress/partial-result-sender.d.ts

@@ -1,9 +1,38 @@
 import type { ProgressToken } from '@lspeasy/core';
 import type { BaseLSPServer } from '../server.js';
-/** Helper for emitting typed `$/progress` partial result batches from server handlers. */
+/**
+ * Emits typed `$/progress` partial-result batches from server-side request handlers.
+ *
+ * @remarks
+ * Use `PartialResultSender` inside a `RequestHandler` when the client has
+ * supplied a `partialResultToken` (e.g. for `textDocument/references` or
+ * `workspace/symbol`). Call `send(token, value)` to stream result batches
+ * before returning the final response.
+ *
+ * @useWhen
+ * 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.
+ *
+ * @never
+ * 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.
+ *
+ * @category Server
+ */
 export declare class PartialResultSender {
     private readonly server;
     constructor(server: BaseLSPServer);
+    /**
+     * Send a batch of partial results to the client.
+     *
+     * @param token - The `partialResultToken` from the originating request params.
+     * @param value - The partial result batch to stream to the client via `$/progress`.
+     */
     send<T>(token: ProgressToken, value: T): Promise<void>;
 }
 //# sourceMappingURL=partial-result-sender.d.ts.map

package/dist/progress/partial-result-sender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"partial-result-sender.d.ts","sourceRoot":"","sources":["../../src/progress/partial-result-sender.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,0FAA0F;AAC1F,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,aAAa,EAAI;IAEhD,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3D;CACF"}
+{"version":3,"file":"partial-result-sender.d.ts","sourceRoot":"","sources":["../../src/progress/partial-result-sender.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,aAAa,EAAI;IAEtD;;;;;OAKG;IACG,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3D;CACF"}

package/dist/progress/partial-result-sender.js

@@ -1,9 +1,38 @@
-/** Helper for emitting typed `$/progress` partial result batches from server handlers. */
+/**
+ * Emits typed `$/progress` partial-result batches from server-side request handlers.
+ *
+ * @remarks
+ * Use `PartialResultSender` inside a `RequestHandler` when the client has
+ * supplied a `partialResultToken` (e.g. for `textDocument/references` or
+ * `workspace/symbol`). Call `send(token, value)` to stream result batches
+ * before returning the final response.
+ *
+ * @useWhen
+ * 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.
+ *
+ * @never
+ * 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.
+ *
+ * @category Server
+ */
 export class PartialResultSender {
     server;
     constructor(server) {
         this.server = server;
     }
+    /**
+     * Send a batch of partial results to the client.
+     *
+     * @param token - The `partialResultToken` from the originating request params.
+     * @param value - The partial result batch to stream to the client via `$/progress`.
+     */
     async send(token, value) {
         const payload = {
             token,

package/dist/progress/partial-result-sender.js.map

@@ -1 +1 @@
-{"version":3,"file":"partial-result-sender.js","sourceRoot":"","sources":["../../src/progress/partial-result-sender.ts"],"names":[],"mappings":"AAGA,0FAA0F;AAC1F,MAAM,OAAO,mBAAmB;IACD,MAAM;IAAnC,YAA6B,MAAqB,EAAE;sBAAvB,MAAM;IAAkB,CAAC;IAEtD,KAAK,CAAC,IAAI,CAAI,KAAoB,EAAE,KAAQ,EAAiB;QAC3D,MAAM,OAAO,GAAG;YACd,KAAK;YACL,KAAK;SAC4C,CAAC;QAEpD,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,GAAG,OAAO;SACX,CAAC,CAAC;IAAA,CACJ;CACF"}
+{"version":3,"file":"partial-result-sender.js","sourceRoot":"","sources":["../../src/progress/partial-result-sender.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,mBAAmB;IACD,MAAM;IAAnC,YAA6B,MAAqB;sBAArB,MAAM;IAAkB,CAAC;IAEtD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAI,KAAoB,EAAE,KAAQ;QAC1C,MAAM,OAAO,GAAG;YACd,KAAK;YACL,KAAK;SAC4C,CAAC;QAEpD,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/progress.js.map

@@ -1 +1 @@
-{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,eAAe,CAAC;AA6BvB;;GAEG;AACH,MAAM,oBAAoB;IAEd,KAAK;IACL,MAAM;IAFhB,YACU,KAAoB,EACpB,MAAsB,EAC9B;qBAFQ,KAAK;sBACL,MAAM;IACb,CAAC;IAEJ,KAAK,CAAC,KAAK,CACT,KAAa,EACb,WAAqB,EACrB,OAAgB,EAChB,UAAmB,EACJ;QACf,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAC3E,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK;SACN,CAAC,CAAC;IAAA,CACJ;IAED,KAAK,CAAC,MAAM,CAAC,OAAgB,EAAE,UAAmB,EAAiB;QACjE,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACxD,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK;SACN,CAAC,CAAC;IAAA,CACJ;IAED,KAAK,CAAC,GAAG,CAAC,OAAgB,EAAiB;QACzC,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK;SACN,CAAC,CAAC;IAAA,CACJ;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAoB,EACpB,MAAsB,EACJ;IAClB,OAAO,IAAI,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAAA,CAChD;AAED;;GAEG;AACH,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,eAAe,CAAC;AA6BvB;;GAEG;AACH,MAAM,oBAAoB;IAEd,KAAK;IACL,MAAM;IAFhB,YACU,KAAoB,EACpB,MAAsB;qBADtB,KAAK;sBACL,MAAM;IACb,CAAC;IAEJ,KAAK,CAAC,KAAK,CACT,KAAa,EACb,WAAqB,EACrB,OAAgB,EAChB,UAAmB;QAEnB,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAC3E,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAgB,EAAE,UAAmB;QAChD,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACxD,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,OAAgB;QACxB,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE;YAC/C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAoB,EACpB,MAAsB;IAEtB,OAAO,IAAI,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/server.d.ts

@@ -5,18 +5,75 @@ import type { Transport, Disposable, ServerCapabilities, ClientCapabilities, LSP
 import type { ServerOptions, RequestHandler, NotificationHandler, NotebookDocumentHandlerNamespace } from './types.js';
 import { ServerState } from './types.js';
 /**
- * LSP Server class with dynamic capability-aware typing
+ * Full-featured LSP server with automatic lifecycle management, typed handlers,
+ * capability-aware namespaces, and pluggable middleware.
  *
- * This class dynamically provides handler registration and send methods based on capabilities.
- * Methods are type-safe and conditionally available based on the Capabilities type parameter.
+ * @remarks
+ * `LSPServer` manages the complete LSP lifecycle (`initialize` / `initialized`
+ * / `shutdown` / `exit`) automatically. Register your handlers with
+ * `onRequest` / `onNotification`, declare capabilities with
+ * `registerCapabilities`, then start the server with `listen(transport)`.
  *
- * @template Capabilities - Server capabilities (defaults to ServerCapabilities)
+ * ### Capability-aware namespaces
+ *
+ * After calling `registerCapabilities(caps)`, the server exposes typed
+ * namespaces — e.g. `server.textDocument.onHover(handler)` — that are only
+ * present when the corresponding capability is declared. TypeScript enforces
+ * this at compile time so you cannot accidentally register a handler for a
+ * capability you never advertised.
+ *
+ * ### Transport selection
+ *
+ * - **Browser / universal**: `WebSocketTransport` (from `@lspeasy/core`)
+ * - **Node.js**: `StdioTransport`, `TcpTransport`, `IpcTransport` (from `@lspeasy/core/node`)
+ * - **Web Workers**: `DedicatedWorkerTransport`, `SharedWorkerTransport` (from `@lspeasy/core`)
+ *
+ * @useWhen
+ * You are building an LSP language server that editors and language-client
+ * tooling will connect to. `LSPServer` is the primary entry point for all
+ * server implementations.
+ *
+ * @avoidWhen
+ * You need a bare JSON-RPC layer without LSP semantics — use the transport
+ * and framing utilities directly instead.
+ *
+ * @never
+ * NEVER call `server.shutdown()` or `server.close()` from inside a request
+ * or notification handler — doing so attempts to close the transport while it
+ * is actively dispatching, causing a deadlock.
+ *
+ * NEVER mutate `ServerCapabilities` after `initialized` has been received.
+ * The client cached the `InitializeResult` at handshake time; runtime changes
+ * are invisible to it.
+ *
+ * NEVER share one `LSPServer` instance across multiple transports or
+ * connections. Each connection requires its own server instance to maintain
+ * independent protocol state (lifecycle phase, pending request IDs, etc.).
+ *
+ * NEVER send a server-to-client notification before the `initialize` response
+ * has been dispatched. Use the `initialized` notification handler as the
+ * earliest safe point for server-initiated messages.
  *
  * @example
- * // Create a server with specific capabilities
- * type MyCaps = { hoverProvider: true; completionProvider: { triggerCharacters: ['.'] } };
- * const server = new LSPServer<MyCaps>();
- * server.registerCapabilities({ hoverProvider: true, completionProvider: { triggerCharacters: ['.'] } });
+ * ```ts
+ * import { LSPServer } from '@lspeasy/server';
+ * // Node.js: import { StdioTransport } from '@lspeasy/core/node';
+ * // Browser: import { WebSocketTransport } from '@lspeasy/core';
+ *
+ * const server = new LSPServer({ name: 'my-lsp', version: '1.0.0' })
+ *   .registerCapabilities({ hoverProvider: true });
+ *
+ * server.textDocument.onHover(async (params, token) => {
+ *   if (token.isCancellationRequested) return null;
+ *   return { contents: { kind: 'plaintext', value: 'Hello from my-lsp' } };
+ * });
+ *
+ * const transport = new StdioTransport();
+ * await server.listen(transport);
+ * ```
+ *
+ * @template Capabilities - Shape of the server capabilities, defaults to `ServerCapabilities`.
+ * @category Server
  */
 export declare class BaseLSPServer<Capabilities extends Partial<ServerCapabilities> = ServerCapabilities> {
     private readonly logger;
@@ -104,19 +161,56 @@ export declare class BaseLSPServer<Capabilities extends Partial<ServerCapabiliti
      */
     expect<C extends Partial<ClientCapabilities>>(): this & Server<C, Capabilities>;
     /**
-     * Send a server-to-client request.
+     * Send a server-to-client request and await the client's response.
+     *
+     * @param method - The LSP request method name (server-to-client direction).
+     * @param params - Optional request parameters.
+     * @returns A promise resolving to the client's result.
+     * @throws {Error} When not listening (transport not attached). Fix: only call `sendRequest` from inside a handler or after the `listening` event fires.
+     * @throws {Error} When the client returns a JSON-RPC error response. Fix: catch and inspect `error.code`; `window/showMessageRequest` rejections are user-initiated (user dismissed), not bugs.
+     * @throws {Error} When the request times out (if `requestTimeout` is configured). Fix: increase `ServerOptions.requestTimeout` for slow UI interactions like `window/showMessageRequest`.
+     *
+     * @category Server
      */
     sendRequest<Method extends LSPRequestMethod<'serverToClient'>>(method: Method, params?: ParamsForRequest<Method>): Promise<ResultForRequest<Method>>;
     /**
-     * Send a server-to-client notification.
+     * Send a server-to-client notification (fire-and-forget).
+     *
+     * @param method - The LSP notification method name (server-to-client direction).
+     * @param params - Optional notification parameters.
+     * @throws {Error} When not listening. Fix: only send notifications after `listen()` resolves and before `shutdown()` is called; guard with `isListening()`.
+     * @throws {Error} When the transport's underlying `send()` fails (e.g. broken socket). Fix: subscribe to `server.onError()` to catch transport-level write failures.
+     *
+     * @category Server
      */
     sendNotification<Method extends LSPNotificationMethod<'serverToClient'>>(method: Method, params?: ParamsForNotification<Method>): Promise<void>;
     /**
-     * Start listening on a transport
+     * Attaches the server to a transport and begins processing messages.
+     *
+     * @remarks
+     * After `listen()` returns the server is ready to receive the `initialize`
+     * request from the client. The LSP handshake proceeds automatically.
+     *
+     * @param transport - The transport to listen on.
+     * @throws {Error} When already listening. Fix: call `close()` then create a fresh `LSPServer` instance — do not reuse a single instance across connections.
+     *
+     * @category Lifecycle
      */
     listen(transport: Transport): Promise<void>;
     /**
-     * Graceful shutdown
+     * Initiates graceful shutdown, waits for in-flight handlers, then closes
+     * the transport.
+     *
+     * @remarks
+     * Waits up to `timeout` ms for pending handlers to complete, then
+     * cancels any remaining in-flight requests before closing. Use this method
+     * to shut down in response to an OS signal or editor session end.
+     *
+     * @param timeout - Maximum milliseconds to wait for in-flight handlers before
+     *   force-cancelling them.
+     * @defaultValue 5000
+     *
+     * @category Lifecycle
      */
     shutdown(timeout?: number): Promise<void>;
     /**
@@ -165,6 +259,68 @@ export declare class BaseLSPServer<Capabilities extends Partial<ServerCapabiliti
      */
     private handleResponse;
 }
+/**
+ * Full-featured LSP server with automatic lifecycle management, typed handlers,
+ * capability-aware namespaces, and pluggable middleware.
+ *
+ * @remarks
+ * `LSPServer` manages the complete LSP lifecycle (`initialize` / `initialized`
+ * / `shutdown` / `exit`) automatically. Register handlers with `onRequest` /
+ * `onNotification`, declare capabilities with `registerCapabilities`, then
+ * start with `listen(transport)`.
+ *
+ * ### Capability-aware namespaces
+ * After `registerCapabilities({ hoverProvider: true })`, TypeScript exposes
+ * `server.textDocument.onHover(handler)` — methods absent unless the
+ * corresponding capability is declared.
+ *
+ * @useWhen
+ * You are building an LSP language server that editors and language-client
+ * tooling will connect to.
+ *
+ * @avoidWhen
+ * You need a bare JSON-RPC layer without LSP semantics — use the transport
+ * and framing utilities from `@lspeasy/core` directly.
+ *
+ * @never
+ * NEVER call `server.shutdown()` or `server.close()` from inside a request
+ * or notification handler — doing so attempts to close the transport while it
+ * is actively dispatching, causing a deadlock.
+ *
+ * NEVER mutate `ServerCapabilities` after `initialized` has been received.
+ * The client cached the `InitializeResult` at handshake time; runtime changes
+ * are invisible to it.
+ *
+ * NEVER share one `LSPServer` instance across multiple transports or connections.
+ * Each connection requires its own server instance to maintain independent state.
+ *
+ * @example
+ * ```ts
+ * import { LSPServer } from '@lspeasy/server';
+ * import { StdioTransport } from '@lspeasy/core/node';
+ *
+ * const server = new LSPServer({ name: 'my-lsp', version: '1.0.0' })
+ *   .registerCapabilities({ hoverProvider: true });
+ *
+ * server.textDocument.onHover(async (params, token) => {
+ *   if (token.isCancellationRequested) return null;
+ *   return { contents: { kind: 'plaintext', value: 'Hello from my-lsp' } };
+ * });
+ *
+ * await server.listen(new StdioTransport());
+ * ```
+ *
+ * @template ServerCaps - Shape of the server capabilities.
+ * @category Server
+ */
 export type LSPServer<ServerCaps extends Partial<ServerCapabilities> = ServerCapabilities> = BaseLSPServer<ServerCaps> & Server<ClientCapabilities, ServerCaps>;
+/**
+ * Constructs an {@link LSPServer} instance.
+ *
+ * @param options - Optional {@link ServerOptions} to configure the server.
+ * @returns A new `LSPServer` instance.
+ *
+ * @category Server
+ */
 export declare const LSPServer: new <ServerCaps extends Partial<ServerCapabilities> = ServerCapabilities>(options?: ServerOptions<ServerCaps>) => LSPServer<ServerCaps>;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -11,18 +11,75 @@ import { validateParams } from './validation.js';
 import { CapabilityGuard, ClientCapabilityGuard } from './capability-guard.js';
 import { initializeServerHandlerMethods, initializeServerSendMethods } from './capability-proxy.js';
 /**
- * LSP Server class with dynamic capability-aware typing
+ * Full-featured LSP server with automatic lifecycle management, typed handlers,
+ * capability-aware namespaces, and pluggable middleware.
  *
- * This class dynamically provides handler registration and send methods based on capabilities.
- * Methods are type-safe and conditionally available based on the Capabilities type parameter.
+ * @remarks
+ * `LSPServer` manages the complete LSP lifecycle (`initialize` / `initialized`
+ * / `shutdown` / `exit`) automatically. Register your handlers with
+ * `onRequest` / `onNotification`, declare capabilities with
+ * `registerCapabilities`, then start the server with `listen(transport)`.
  *
- * @template Capabilities - Server capabilities (defaults to ServerCapabilities)
+ * ### Capability-aware namespaces
+ *
+ * After calling `registerCapabilities(caps)`, the server exposes typed
+ * namespaces — e.g. `server.textDocument.onHover(handler)` — that are only
+ * present when the corresponding capability is declared. TypeScript enforces
+ * this at compile time so you cannot accidentally register a handler for a
+ * capability you never advertised.
+ *
+ * ### Transport selection
+ *
+ * - **Browser / universal**: `WebSocketTransport` (from `@lspeasy/core`)
+ * - **Node.js**: `StdioTransport`, `TcpTransport`, `IpcTransport` (from `@lspeasy/core/node`)
+ * - **Web Workers**: `DedicatedWorkerTransport`, `SharedWorkerTransport` (from `@lspeasy/core`)
+ *
+ * @useWhen
+ * You are building an LSP language server that editors and language-client
+ * tooling will connect to. `LSPServer` is the primary entry point for all
+ * server implementations.
+ *
+ * @avoidWhen
+ * You need a bare JSON-RPC layer without LSP semantics — use the transport
+ * and framing utilities directly instead.
+ *
+ * @never
+ * NEVER call `server.shutdown()` or `server.close()` from inside a request
+ * or notification handler — doing so attempts to close the transport while it
+ * is actively dispatching, causing a deadlock.
+ *
+ * NEVER mutate `ServerCapabilities` after `initialized` has been received.
+ * The client cached the `InitializeResult` at handshake time; runtime changes
+ * are invisible to it.
+ *
+ * NEVER share one `LSPServer` instance across multiple transports or
+ * connections. Each connection requires its own server instance to maintain
+ * independent protocol state (lifecycle phase, pending request IDs, etc.).
+ *
+ * NEVER send a server-to-client notification before the `initialize` response
+ * has been dispatched. Use the `initialized` notification handler as the
+ * earliest safe point for server-initiated messages.
  *
  * @example
- * // Create a server with specific capabilities
- * type MyCaps = { hoverProvider: true; completionProvider: { triggerCharacters: ['.'] } };
- * const server = new LSPServer<MyCaps>();
- * server.registerCapabilities({ hoverProvider: true, completionProvider: { triggerCharacters: ['.'] } });
+ * ```ts
+ * import { LSPServer } from '@lspeasy/server';
+ * // Node.js: import { StdioTransport } from '@lspeasy/core/node';
+ * // Browser: import { WebSocketTransport } from '@lspeasy/core';
+ *
+ * const server = new LSPServer({ name: 'my-lsp', version: '1.0.0' })
+ *   .registerCapabilities({ hoverProvider: true });
+ *
+ * server.textDocument.onHover(async (params, token) => {
+ *   if (token.isCancellationRequested) return null;
+ *   return { contents: { kind: 'plaintext', value: 'Hello from my-lsp' } };
+ * });
+ *
+ * const transport = new StdioTransport();
+ * await server.listen(transport);
+ * ```
+ *
+ * @template Capabilities - Shape of the server capabilities, defaults to `ServerCapabilities`.
+ * @category Server
  */
 export class BaseLSPServer {
     logger;
@@ -165,7 +222,16 @@ export class BaseLSPServer {
         return this;
     }
     /**
-     * Send a server-to-client request.
+     * Send a server-to-client request and await the client's response.
+     *
+     * @param method - The LSP request method name (server-to-client direction).
+     * @param params - Optional request parameters.
+     * @returns A promise resolving to the client's result.
+     * @throws {Error} When not listening (transport not attached). Fix: only call `sendRequest` from inside a handler or after the `listening` event fires.
+     * @throws {Error} When the client returns a JSON-RPC error response. Fix: catch and inspect `error.code`; `window/showMessageRequest` rejections are user-initiated (user dismissed), not bugs.
+     * @throws {Error} When the request times out (if `requestTimeout` is configured). Fix: increase `ServerOptions.requestTimeout` for slow UI interactions like `window/showMessageRequest`.
+     *
+     * @category Server
      */
     async sendRequest(method, params) {
         if (!this.transport) {
@@ -199,7 +265,14 @@ export class BaseLSPServer {
         return promise;
     }
     /**
-     * Send a server-to-client notification.
+     * Send a server-to-client notification (fire-and-forget).
+     *
+     * @param method - The LSP notification method name (server-to-client direction).
+     * @param params - Optional notification parameters.
+     * @throws {Error} When not listening. Fix: only send notifications after `listen()` resolves and before `shutdown()` is called; guard with `isListening()`.
+     * @throws {Error} When the transport's underlying `send()` fails (e.g. broken socket). Fix: subscribe to `server.onError()` to catch transport-level write failures.
+     *
+     * @category Server
      */
     async sendNotification(method, params) {
         if (!this.transport) {
@@ -224,7 +297,16 @@ export class BaseLSPServer {
         });
     }
     /**
-     * Start listening on a transport
+     * Attaches the server to a transport and begins processing messages.
+     *
+     * @remarks
+     * After `listen()` returns the server is ready to receive the `initialize`
+     * request from the client. The LSP handshake proceeds automatically.
+     *
+     * @param transport - The transport to listen on.
+     * @throws {Error} When already listening. Fix: call `close()` then create a fresh `LSPServer` instance — do not reuse a single instance across connections.
+     *
+     * @category Lifecycle
      */
     async listen(transport) {
         if (this.transport) {
@@ -248,7 +330,19 @@ export class BaseLSPServer {
         this.events.emit('listening');
     }
     /**
-     * Graceful shutdown
+     * Initiates graceful shutdown, waits for in-flight handlers, then closes
+     * the transport.
+     *
+     * @remarks
+     * Waits up to `timeout` ms for pending handlers to complete, then
+     * cancels any remaining in-flight requests before closing. Use this method
+     * to shut down in response to an OS signal or editor session end.
+     *
+     * @param timeout - Maximum milliseconds to wait for in-flight handlers before
+     *   force-cancelling them.
+     * @defaultValue 5000
+     *
+     * @category Lifecycle
      */
     async shutdown(timeout = 5000) {
         if (this.state === ServerState.Shutdown) {
@@ -521,6 +615,14 @@ export class BaseLSPServer {
         this.pendingRequests.reject(String(id), new Error('Invalid response message'));
     }
 }
+/**
+ * Constructs an {@link LSPServer} instance.
+ *
+ * @param options - Optional {@link ServerOptions} to configure the server.
+ * @returns A new `LSPServer` instance.
+ *
+ * @category Server
+ */
 // Generic constructor that preserves type parameters
 export const LSPServer = BaseLSPServer;
 //# sourceMappingURL=server.js.map