@typerighter/rpc-client 0.24.0 → 0.25.0

package/src/core/client.ts

@@ -0,0 +1,260 @@
+/**
+ * JSON-RPC 2.0 client with Content-Length framing
+ * Simplified from vscode-jsonrpc (MIT, Microsoft Corporation)
+ * Ref: https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/connection.ts#L506-L591
+ */
+
+import { createConnection } from 'node:net';
+import type { Readable, Writable } from 'node:stream';
+import type { Message, RequestMessage, NotificationMessage, ResponseMessage } from './types.js';
+import { Message as MessageGuards, ErrorCodes, ResponseError } from './types.js';
+
+type PendingRequest = {
+  resolve: (value: unknown) => void;
+  reject: (error: ResponseError) => void;
+};
+
+// A Disposable interface to undo a previous side-effectful step
+interface Disposable {
+  dispose (): void;
+}
+
+const HEADER_SEPARATOR = Buffer.from('\r\n\r\n', 'ascii');
+const HEADER_SEPARATOR_LENGTH = 4; // \r\n\r\n
+
+/**
+ * Simplified MessageConnection interface
+ * https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/connection.ts#L506-L591
+ */
+export interface MessageConnection extends Disposable {
+  /** Send a JSON-RPC request and wait for the response */
+  sendRequest<R> (method: string, params?: any[] | object): Promise<R>;
+  /** Send a one-way JSON-RPC notification (no response expected) */
+  sendNotification (method: string, params?: any[] | object): void;
+  /** Register a handler for server-sent notifications, returns an unsubscribe handle */
+  onNotification (method: string, handler: (params: any) => void): Disposable;
+  /** Register a listener for connection close, returns an unsubscribe handle */
+  onClose (listener: () => void): Disposable;
+  /** Reject all pending requests and stop listening */
+  dispose (): void;
+}
+
+export class JsonRpcClient implements MessageConnection {
+  // Transport
+  private reader: Readable;
+  private writer: Writable;
+
+  // Request/response matching
+  private sequenceNumber = 1;
+  private responsePromises = new Map<number, PendingRequest>();
+  private notificationHandlers = new Map<string, (params: unknown) => void>();
+
+  // Inbound buffer, raw chunks to avoid corrupting multi-byte UTF-8
+  private chunks: Buffer[] = [];
+  private chunksLength = 0;
+  private contentLength = -1; // -1 = waiting for header
+
+  // Lifecycle
+  private disposed = false;
+  private closeHandlers: Array<() => void> = [];
+
+  constructor (reader: Readable, writer: Writable) {
+    this.reader = reader;
+    this.writer = writer;
+
+    this.reader.on('data', (chunk: Buffer) => this.onData(chunk));
+    this.reader.on('end', () => this.handleStreamClose());
+    this.reader.on('close', () => this.handleStreamClose());
+  }
+
+  static connectTcp (host: string, port: number): Promise<JsonRpcClient> {
+    return new Promise((resolve, reject) => {
+      const socket = createConnection({ host, port }, () => {
+        resolve(new JsonRpcClient(socket, socket));
+      });
+      socket.on('error', reject);
+    });
+  }
+
+  static connectStdio (stdin: Readable, stdout: Writable): JsonRpcClient {
+    return new JsonRpcClient(stdin, stdout);
+  }
+
+  // https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/connection.ts#L1563-L1590
+  dispose (): void {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    this.rejectAllPending('Connection disposed');
+  }
+
+  // https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/connection.ts#L565
+  onClose (listener: () => void): Disposable {
+    this.closeHandlers.push(listener);
+    return {
+      dispose: () => {
+        const index = this.closeHandlers.indexOf(listener);
+        if (index >= 0) this.closeHandlers.splice(index, 1);
+      },
+    };
+  }
+
+  // https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/connection.ts#L537
+  sendRequest<R> (method: string, params?: any[] | object): Promise<R> {
+    const id = this.sequenceNumber++;
+    const message: RequestMessage = { jsonrpc: '2.0', id, method, params };
+
+    return new Promise<R>((resolve, reject) => {
+      this.responsePromises.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      this.writeMessage(message);
+    });
+  }
+
+  // https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/connection.ts#L549
+  sendNotification (method: string, params?: any[] | object): void {
+    const message: NotificationMessage = { jsonrpc: '2.0', method, params };
+    this.writeMessage(message);
+  }
+
+  // https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/connection.ts#L557
+  onNotification (method: string, handler: (params: any) => void): Disposable {
+    this.notificationHandlers.set(method, handler);
+    return {
+      dispose: () => this.notificationHandlers.delete(method),
+    };
+  }
+
+  // Accumulate chunk and parse as many complete messages as possible
+  // A single chunk can contain multiple messages
+  // Ref: vscode-jsonrpc ReadableStreamMessageReader.nextMessage
+  private onData (chunk: Buffer): void {
+    this.chunks.push(chunk);
+    this.chunksLength += chunk.length;
+
+    while (true) {
+      if (this.contentLength < 0) {
+        const buffer = this.compact();
+        const separatorIndex = buffer.indexOf(HEADER_SEPARATOR);
+
+        if (separatorIndex < 0) return;
+
+        const header = buffer.subarray(0, separatorIndex).toString('ascii');
+        const match = header.match(/Content-Length:\s*(\d+)/i);
+
+        if (!match) {
+          this.consume(separatorIndex + HEADER_SEPARATOR_LENGTH);
+          continue;
+        }
+
+        this.contentLength = Number(match[1]);
+        this.consume(separatorIndex + HEADER_SEPARATOR_LENGTH);
+      }
+
+      if (this.chunksLength < this.contentLength) return;
+
+      const buffer = this.compact();
+      const body = buffer.subarray(0, this.contentLength).toString('utf-8');
+
+      this.consume(this.contentLength);
+      this.contentLength = -1;
+
+      try {
+        const message = JSON.parse(body);
+
+        if (MessageGuards.isResponse(message)) {
+          this.handleResponse(message);
+        } else if (MessageGuards.isNotification(message)) {
+          this.handleNotification(message);
+        }
+      } catch (error) {
+        console.error('[jsonrpc] Failed to parse message:', error);
+      }
+    }
+  }
+
+  // Ref: vscode-jsonrpc connection.ts
+
+  private handleResponse (response: ResponseMessage): void {
+    if (typeof response.id !== 'number') return;
+
+    const pending = this.responsePromises.get(response.id);
+
+    if (!pending) return;
+    this.responsePromises.delete(response.id);
+
+    if (response.error) {
+      pending.reject(new ResponseError(response.error.code, response.error.message, response.error.data));
+    } else if (response.result !== undefined) {
+      pending.resolve(response.result);
+    }
+  }
+
+  private handleNotification (notification: NotificationMessage): void {
+    const handler = this.notificationHandlers.get(notification.method);
+
+    if (!handler) return;
+
+    try {
+      handler(notification.params);
+    } catch (error) {
+      console.error(`[jsonrpc] Notification handler for '${notification.method}' threw:`, error);
+    }
+  }
+
+  // Cleanup
+
+  private rejectAllPending (reason: string): void {
+    for (const [, pending] of this.responsePromises) {
+      pending.reject(new ResponseError(ErrorCodes.PendingResponseRejected, reason));
+    }
+    this.responsePromises.clear();
+  }
+
+  // Fires once on stream end/close
+  private handleStreamClose (): void {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    this.rejectAllPending('Server disconnected');
+
+    for (const handler of this.closeHandlers) {
+      handler();
+    }
+  }
+
+  /* Helpers */
+
+  // Single buffer write to prevent interleaving under concurrent requests
+  private writeMessage (message: Message): void {
+    const body = Buffer.from(JSON.stringify(message), 'utf-8');
+    const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii');
+
+    this.writer.write(Buffer.concat([header, body]));
+  }
+
+  // Concat all chunks into 1 buffer
+  private compact (): Buffer {
+    if (this.chunks.length === 1) return this.chunks[0];
+
+    const buffer = Buffer.concat(this.chunks);
+
+    this.chunks = [buffer];
+    this.chunksLength = buffer.length;
+
+    return buffer;
+  }
+
+  // Consume n bytes from buffer
+  private consume (bytes: number): void {
+    const buffer = this.compact();
+    const remaining = buffer.subarray(bytes);
+
+    if (remaining.length > 0) {
+      this.chunks = [remaining];
+      this.chunksLength = remaining.length;
+    } else {
+      this.chunks = [];
+      this.chunksLength = 0;
+    }
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,10 @@
+export { JsonRpcClient, type MessageConnection } from './client.js';
+export {
+  type RequestMessage,
+  type ResponseMessage,
+  type NotificationMessage,
+  type ResponseErrorLiteral,
+  Message,
+  ErrorCodes,
+  ResponseError,
+} from './types.js';

package/src/core/types.ts

@@ -0,0 +1,104 @@
+/**
+ * JSON-RPC 2.0 message types and error codes
+ * Copied from vscode-jsonrpc (MIT, Microsoft Corporation)
+ * Ref: https://github.com/microsoft/vscode-languageserver-node/tree/main/jsonrpc/src/common/messages
+ */
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L11
+export interface Message {
+  jsonrpc: string;
+}
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L18
+export interface RequestMessage extends Message {
+  id: number | string | null;
+  method: string;
+  params?: any[] | object;
+}
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L150-L165
+export interface ResponseMessage extends Message {
+  id: number | string | null;
+  result?: string | number | boolean | object | any[] | null;
+  error?: ResponseErrorLiteral<any>;
+}
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L283-L292
+export interface NotificationMessage extends Message {
+  method: string;
+  params?: any[] | object;
+}
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L105-L122
+export interface ResponseErrorLiteral<D = void> {
+  code: number;
+  message: string;
+  data?: D;
+}
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L298-L323
+export namespace Message {
+  export function isRequest (message: Message | undefined): message is RequestMessage {
+    const candidate = message as RequestMessage;
+    return candidate !== undefined && typeof candidate.method === 'string'
+      && (typeof candidate.id === 'string' || typeof candidate.id === 'number');
+  }
+
+  export function isNotification (message: Message | undefined): message is NotificationMessage {
+    const candidate = message as NotificationMessage;
+    return candidate !== undefined && typeof candidate.method === 'string'
+      && (candidate as any).id === undefined;
+  }
+
+  export function isResponse (message: Message | undefined): message is ResponseMessage {
+    const candidate = message as ResponseMessage;
+    return candidate !== undefined
+      && (candidate.result !== undefined || !!candidate.error)
+      && (typeof candidate.id === 'string' || typeof candidate.id === 'number' || candidate.id === null);
+  }
+}
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L32-L83
+export namespace ErrorCodes {
+  export const ParseError: -32700 = -32700;
+  export const InvalidRequest: -32600 = -32600;
+  export const MethodNotFound: -32601 = -32601;
+  export const InvalidParams: -32602 = -32602;
+  export const InternalError: -32603 = -32603;
+
+  // JSON-RPC reserved error range (-32099 to -32000)
+  export const jsonrpcReservedErrorRangeStart: -32099 = -32099;
+  export const MessageWriteError: -32099 = -32099;
+  export const MessageReadError: -32098 = -32098;
+  export const PendingResponseRejected: -32097 = -32097;
+  export const ConnectionInactive: -32096 = -32096;
+  export const ServerNotInitialized: -32002 = -32002;
+  export const UnknownErrorCode: -32001 = -32001;
+  export const jsonrpcReservedErrorRangeEnd: -32000 = -32000;
+}
+
+// https://github.com/microsoft/vscode-languageserver-node/blob/5010cdf9822e1038a30ee7eb6ee5d7aaa79acc4a/jsonrpc/src/common/messages.ts#L128-L148
+export class ResponseError<D = void> extends Error {
+  readonly code: number;
+  readonly data: D | undefined;
+
+  constructor (code: number, message: string, data?: D) {
+    super(message);
+    this.code = typeof code === 'number' ? code : ErrorCodes.UnknownErrorCode;
+    this.data = data;
+    Object.setPrototypeOf(this, ResponseError.prototype);
+  }
+
+  toJson (): ResponseErrorLiteral<D> {
+    const result: ResponseErrorLiteral<D> = {
+      code: this.code,
+      message: this.message,
+    };
+
+    if (this.data !== undefined) {
+      result.data = this.data;
+    }
+
+    return result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,252 @@
+/**
+ * Typedown RPC client
+ *
+ * Thin wrapper over JsonRpcClient that provides typed methods
+ * matching the Rust RPC server's contract (rpc/contract.rs)
+ *
+ * The server (typedown-rpc binary) sends notifications for FS changes;
+ * register handlers via onContentChanged/onSchemaChanged/onConfigChanged
+ */
+
+import type { Readable, Writable } from 'node:stream';
+import { JsonRpcClient } from './core/index.js';
+
+export { JsonRpcClient, Message, ResponseError, ErrorCodes } from './core/index.js';
+export type { RequestMessage, ResponseMessage, NotificationMessage, ResponseErrorLiteral } from './core/index.js';
+
+/* Types contract
+ * WARNING: must match the Rust contract in rpc/contract.rs */
+
+export interface TdDiagnosticItem {
+  filepath: string;
+  line: number;
+  column: number;
+  severity: string;
+  code: string;
+  message: string;
+}
+
+export interface TdContentNotification {
+  content: string;
+}
+
+export interface TdFileMetadata {
+  mtime: number;
+  ctime: number;
+}
+
+export interface TdHeading {
+  level: number;
+  title: string;
+  slug: string;
+}
+
+export interface TdSidebarItem {
+  filepath: string;
+  schema?: string;
+  schemaLabel?: string;
+  label?: string;
+  icon?: TdIcon;
+  metadata: TdFileMetadata;
+}
+
+export interface TdContentSummary {
+  filepath: string;
+  schema?: string;
+  schemaLabel?: string;
+  label?: string;
+  icon?: TdIcon;
+  header: Record<string, any>;
+  excerpt?: string;
+  metadata: TdFileMetadata;
+}
+
+export interface TdNavItem {
+  title: string;
+  link: string;
+  icon?: string;
+}
+
+export interface TdIcon {
+  name: string;
+}
+
+export interface TdDiagnosticReport {
+  diagnostics: TdDiagnosticItem[];
+  fileCount: number;
+  errorCount: number;
+  warningCount: number;
+}
+
+export interface TdFormatResult {
+  content: string;
+  changed: boolean;
+}
+
+export interface TdSchemaNotification {
+  schema: string;
+}
+
+export interface TdSchemaInfo {
+  schema: string;
+  label: string;
+  properties: Record<string, any>;
+}
+
+export interface TdSiteConfig {
+  version: string;
+  basePath: string;
+  rootDir: string;
+  siteTitle: string;
+  siteDescription: string;
+  repo: string | undefined;
+  author: string | undefined;
+  license: string | undefined;
+  publicDir: string;
+  nav: TdNavItem[];
+}
+
+export interface TdBuiltResource {
+  schema?: string;
+  schemaLabel?: string;
+  label?: string;
+  icon?: TdIcon;
+  header: Record<string, any>;
+  content: string;
+  headings: TdHeading[];
+  title?: string;
+  metadata: TdFileMetadata;
+}
+
+// Server-reserved JSON-RPC error code for cancelled queries (-32000 to -32099)
+export const RPC_CANCELLED_CODE = -32002;
+
+/* Method names
+ * WARNING: must match Rust contract constants in rpc/contract.rs */
+
+const METHOD_REQUEST_FILE = 'typedown_build.request_file';
+const METHOD_REQUEST_FILES = 'typedown_build.request_files';
+const METHOD_LIST_VAULT = 'typedown_build.list_vault';
+const METHOD_LIST_FILES_GROUPED_BY_SCHEMA = 'typedown_build.list_files_grouped_by_schema';
+const METHOD_LIST_SIDEBAR = 'typedown_build.list_sidebar';
+const METHOD_LIST_SCHEMAS = 'typedown_build.list_schemas';
+const METHOD_GET_SCHEMA = 'typedown_build.get_schema';
+const METHOD_GET_VERSION = 'typedown_build.get_version';
+const METHOD_GET_CONFIG = 'typedown_build.get_config';
+const METHOD_CHECK_VAULT = 'typedown_build.check_vault';
+const METHOD_FORMAT_FILE = 'typedown_build.format_file';
+
+const NOTIF_CONTENT_CHANGED = 'typedown_build.content_changed';
+const NOTIF_CONTENT_CREATED = 'typedown_build.content_created';
+const NOTIF_CONTENT_DELETED = 'typedown_build.content_deleted';
+const NOTIF_SCHEMA_CHANGED = 'typedown_build.schema_changed';
+const NOTIF_SCHEMA_CREATED = 'typedown_build.schema_created';
+const NOTIF_SCHEMA_DELETED = 'typedown_build.schema_deleted';
+const NOTIF_CONFIG_CHANGED = 'typedown_build.config_changed';
+
+/**
+ * Typed RPC client for the Typedown build server
+ *
+ * Wraps a generic JsonRpcClient with typed request methods
+ * and notification handlers matching the Rust RPC contract
+ */
+export class RpcClient {
+  private rpc: JsonRpcClient;
+
+  private constructor (rpc: JsonRpcClient) {
+    this.rpc = rpc;
+  }
+
+  static async connectTcp (host: string, port: number): Promise<RpcClient> {
+    const rpc = await JsonRpcClient.connectTcp(host, port);
+    return new RpcClient(rpc);
+  }
+
+  static connectStdio (stdin: Readable, stdout: Writable): RpcClient {
+    return new RpcClient(JsonRpcClient.connectStdio(stdin, stdout));
+  }
+
+  dispose (): void {
+    this.rpc.dispose();
+  }
+
+  onClose (callback: () => void): { dispose: () => void } {
+    return this.rpc.onClose(callback);
+  }
+
+  /* Request methods */
+
+  requestFile (path: string): Promise<TdBuiltResource> {
+    return this.rpc.sendRequest(METHOD_REQUEST_FILE, { filePath: path });
+  }
+
+  requestFiles (paths: string[]): Promise<TdBuiltResource[]> {
+    return this.rpc.sendRequest(METHOD_REQUEST_FILES, { filePaths: paths });
+  }
+
+  listVault (): Promise<string[]> {
+    return this.rpc.sendRequest(METHOD_LIST_VAULT, {});
+  }
+
+  listFilesGroupedBySchema (): Promise<Record<string, TdContentSummary[]>> {
+    return this.rpc.sendRequest(METHOD_LIST_FILES_GROUPED_BY_SCHEMA, {});
+  }
+
+  listSidebar (): Promise<TdSidebarItem[]> {
+    return this.rpc.sendRequest(METHOD_LIST_SIDEBAR, {});
+  }
+
+  listSchemas (): Promise<string[]> {
+    return this.rpc.sendRequest(METHOD_LIST_SCHEMAS, {});
+  }
+
+  getSchema (schema: string): Promise<TdSchemaInfo> {
+    return this.rpc.sendRequest(METHOD_GET_SCHEMA, { schema });
+  }
+
+  getVersion (): Promise<string> {
+    return this.rpc.sendRequest(METHOD_GET_VERSION, {});
+  }
+
+  getConfig (): Promise<TdSiteConfig> {
+    return this.rpc.sendRequest(METHOD_GET_CONFIG, {});
+  }
+
+  checkVault (): Promise<TdDiagnosticReport> {
+    return this.rpc.sendRequest(METHOD_CHECK_VAULT, {});
+  }
+
+  formatFile (path: string): Promise<TdFormatResult> {
+    return this.rpc.sendRequest(METHOD_FORMAT_FILE, { filePath: path });
+  }
+
+  /* Notification handlers, server pushes these when FS changes are detected */
+
+  onContentChanged (callback: (notification: TdContentNotification) => void): void {
+    this.rpc.onNotification(NOTIF_CONTENT_CHANGED, callback);
+  }
+
+  onContentCreated (callback: (notification: TdContentNotification) => void): void {
+    this.rpc.onNotification(NOTIF_CONTENT_CREATED, callback);
+  }
+
+  onContentDeleted (callback: (notification: TdContentNotification) => void): void {
+    this.rpc.onNotification(NOTIF_CONTENT_DELETED, callback);
+  }
+
+  onSchemaChanged (callback: (notification: TdSchemaNotification) => void): void {
+    this.rpc.onNotification(NOTIF_SCHEMA_CHANGED, callback);
+  }
+
+  onSchemaCreated (callback: (notification: TdSchemaNotification) => void): void {
+    this.rpc.onNotification(NOTIF_SCHEMA_CREATED, callback);
+  }
+
+  onSchemaDeleted (callback: (notification: TdSchemaNotification) => void): void {
+    this.rpc.onNotification(NOTIF_SCHEMA_DELETED, callback);
+  }
+
+  onConfigChanged (callback: (config: TdSiteConfig) => void): void {
+    this.rpc.onNotification(NOTIF_CONFIG_CHANGED, callback);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}