Enable synchronous API connections to existing servers

Allow the synchronous JavaScript API to attach to standalone and LSP-hosted API sessions without spawning another compiler process. Use FIFO pairs on Unix and named pipes on Windows, with cancellable setup and cleanup.

Author: jakebailey

packages/typescript/src/api/async/api.ts

@@ -422,7 +422,8 @@ export class API<FromLSP extends boolean = false> implements FormatDiagnosticsHo
 
     /**
      * Create an API instance from an existing LSP connection's API session.
-     * Use this when connecting to an API pipe provided by an LSP server via custom/initializeAPISession.
+     * Use this with the pipe returned by custom/initializeAPISession. The
+     * requested session transport must match the async or sync API variant.
      */
     static async fromLSPConnection(options: LSPConnectionOptions): Promise<API<true>> {
         const api = new API<true>(options);

packages/typescript/src/api/options.ts

@@ -8,7 +8,12 @@ import { fileURLToPath } from "node:url";
 import type { FileSystemCallbacks } from "./fs.ts";
 
 export interface ClientSocketOptions {
-    /** Path to the Unix domain socket or Windows named pipe for API communication */
+    /**
+     * Path returned by custom/initializeAPISession.
+     *
+     * The async API connects to a Unix domain socket or Windows named pipe.
+     * The sync API connects to a FIFO pair on Unix or a named pipe on Windows.
+     */
     pipe: string;
     /** Maximum encoded byte size of each batch response page. Defaults to 300 million bytes. Individual responses can be larger than this size, but this controls where batch pages are cutoff. */
     maxResponseBytesPerPage?: number | undefined;

packages/typescript/src/api/sync/api.ts

@@ -476,7 +476,8 @@ export class API<FromLSP extends boolean = false> implements FormatDiagnosticsHo
 
     /**
      * Create an API instance from an existing LSP connection's API session.
-     * Use this when connecting to an API pipe provided by an LSP server via custom/initializeAPISession.
+     * Use this with the pipe returned by custom/initializeAPISession. The
+     * requested session transport must match the async or sync API variant.
      */
     static get fromLSPConnection(): {
         (options: LSPConnectionOptions): API<true>;

packages/typescript/src/api/sync/client.ts

@@ -1,6 +1,8 @@
+import type { FileSystemCallbacks } from "../fs.ts";
 import {
     configureFileSystemCallbacks,
     encodeFileSystemCallbackResult,
+    type FileSystemCallbackConfiguration,
 } from "../fsCallbacks.ts";
 import {
     type ClientOptions,
@@ -35,30 +37,40 @@ export class Client {
     private maxResponseBytesPerPage: number | undefined;
 
     constructor(options: ClientOptions) {
-        if (!isSpawnOptions(options)) {
-            throw new Error("Socket connections are not yet supported in the sync client");
-        }
+        let fsConfiguration: FileSystemCallbackConfiguration | undefined;
+        let channel: SyncRpcChannel;
+        let fs: FileSystemCallbacks | undefined;
+        let collectTiming = false;
 
-        const args = getAPIProcessArgs(options, false);
         this.maxResponseBytesPerPage = options.maxResponseBytesPerPage;
+        if (isSpawnOptions(options)) {
+            const args = getAPIProcessArgs(options, false);
 
-        const fsConfiguration = configureFileSystemCallbacks(options.fs);
-        if (fsConfiguration.arguments.length > 0) {
-            args.push(`--callbacks=${fsConfiguration.arguments.join(",")}`);
-        }
+            fsConfiguration = configureFileSystemCallbacks(options.fs);
+            if (fsConfiguration.arguments.length > 0) {
+                args.push(`--callbacks=${fsConfiguration.arguments.join(",")}`);
+            }
 
-        const collectTiming = options.collectTiming ?? false;
+            collectTiming = options.collectTiming ?? false;
+            fs = options.fs;
+            channel = new SyncRpcChannel({
+                exe: resolveExePath(options),
+                args,
+            }, collectTiming);
+        }
+        else {
+            channel = new SyncRpcChannel({ pipe: options.pipe }, collectTiming);
+        }
         if (collectTiming) {
             this.timing = new TimingCollector();
         }
 
-        const channel = new SyncRpcChannel(resolveExePath(options), args, collectTiming);
         this.channel = channel;
 
-        if (options.fs) {
+        if (fs && fsConfiguration) {
             for (const name of fsConfiguration.callbackNames) {
                 if (name === "writeFile") {
-                    const callback = options.fs.writeFile;
+                    const callback = fs.writeFile;
                     if (typeof callback !== "function") throw new Error("Invalid writeFile callback configuration");
 
                     channel.registerCallback(name, (_, arg) => {
@@ -69,7 +81,7 @@ export class Client {
                     continue;
                 }
 
-                const callback = options.fs[name];
+                const callback = fs[name];
                 if (typeof callback !== "function") throw new Error(`Invalid ${name} callback configuration`);
                 channel.registerCallback(name, (_, arg) => {
                     return JSON.stringify(encodeFileSystemCallbackResult(name, callback(JSON.parse(arg))));