Connection Management

/**
 * Creates a new connection based on the processes command line arguments
 */
function createConnection(): Connection;

/**
 * Creates a new connection with connection strategy or options
 * @param options Connection strategy or connection options to control additional settings
 */
function createConnection(options?: ConnectionStrategy | ConnectionOptions): Connection;

/**
 * Creates a new connection using the given streams
 * @param inputStream The stream to read messages from
 * @param outputStream The stream to write messages to
 * @param options Optional connection strategy or connection options
 */
function createConnection(
    inputStream: NodeJS.ReadableStream, 
    outputStream: NodeJS.WritableStream, 
    options?: ConnectionStrategy | ConnectionOptions
): Connection;

/**
 * Creates a new connection using message reader and writer
 * @param reader The message reader to read messages from
 * @param writer The message writer to write message to
 * @param options Optional connection strategy or connection options
 */
function createConnection(
    reader: MessageReader, 
    writer: MessageWriter, 
    options?: ConnectionStrategy | ConnectionOptions
): Connection;

/**
 * Creates a new connection with proposed features
 * @param factories The factories for implementing proposed API features
 * @param options Optional connection strategy or connection options
 */
function createConnection<PConsole = _, PTracer = _, PTelemetry = _, PClient = _, PWindow = _, PWorkspace = _, PLanguages = _, PNotebooks = _>(
    factories: Features<PConsole, PTracer, PTelemetry, PClient, PWindow, PWorkspace, PLanguages, PNotebooks>,
    options?: ConnectionStrategy | ConnectionOptions
): _Connection<PConsole, PTracer, PTelemetry, PClient, PWindow, PWorkspace, PLanguages, PNotebooks>;

import { createConnection, ProposedFeatures } from "vscode-languageserver";

// Auto-detect connection from command line arguments
const connection = createConnection();

// Connection with all proposed features
const proposedConnection = createConnection(ProposedFeatures.all);

// Connection with custom streams (Node.js)
import { createConnection } from "vscode-languageserver/node";
const streamConnection = createConnection(process.stdin, process.stdout);

// Connection with message reader/writer (browser)
import { createConnection } from "vscode-languageserver/browser";
const browserConnection = createConnection(reader, writer);

interface Connection extends _Connection {
    /** Remote console for logging and showing messages */
    console: RemoteConsole;
    /** Remote tracer for debugging and tracing */
    tracer: RemoteTracer;
    /** Telemetry interface for sending telemetry events */
    telemetry: Telemetry;
    /** Remote client interface for client-specific capabilities */
    client: RemoteClient;
    /** Remote window interface for window operations */
    window: RemoteWindow;
    /** Remote workspace interface for workspace operations */
    workspace: RemoteWorkspace;
    /** Languages interface for language-specific features */
    languages: Languages;
    /** Notebooks interface for notebook support */
    notebooks: Notebooks;
    
    /** Handle server initialization */
    onInitialize(handler: RequestHandler<InitializeParams, InitializeResult, InitializeError>): Disposable;
    /** Handle server initialized notification */
    onInitialized(handler: NotificationHandler<InitializedParams>): Disposable;
    /** Handle server shutdown request */
    onShutdown(handler: RequestHandler0<void, void>): Disposable;
    /** Handle server exit notification */
    onExit(handler: NotificationHandler0): Disposable;
    
    /** Send diagnostics to the client */
    sendDiagnostics(params: PublishDiagnosticsParams): void;
    /** Send progress notifications */
    sendProgress<T>(type: ProgressType<T>, token: string | number, value: T): void;
    
    /** Start listening for messages */
    listen(): void;
    /** Dispose the connection */
    dispose(): void;
}

interface ConnectionOptions {
    /** Maximum number of problems reported per file */
    maxNumberOfProblems?: number;
    /** Working directory for the server */
    workspaceRoot?: string;
}

interface ConnectionStrategy {
    /** Custom message reader */
    reader?: MessageReader;
    /** Custom message writer */
    writer?: MessageWriter;
}

namespace ProposedFeatures {
    /** All proposed features combined */
    const all: Features<_, _, _, _, _, _, InlineCompletionFeatureShape, _>;
    
    /** Connection type with proposed features */
    type Connection = _Connection<_, _, _, _, _, _, InlineCompletionFeatureShape, _>;
}

interface _Connection<PConsole = _, PTracer = _, PTelemetry = _, PClient = _, PWindow = _, PWorkspace = _, PLanguages = _, PNotebooks = _> {
    console: PConsole;
    tracer: PTracer;
    telemetry: PTelemetry;
    client: PClient;
    window: PWindow;
    workspace: PWorkspace;
    languages: PLanguages;
    notebooks: PNotebooks;
    
    onRequest<R, PR, E, RO>(
        type: ProtocolRequestType0<R, PR, E, RO>,
        handler: RequestHandler0<R, E>
    ): Disposable;
    
    onRequest<P, R, PR, E, RO>(
        type: ProtocolRequestType<P, R, PR, E, RO>,
        handler: RequestHandler<P, R, E>
    ): Disposable;
    
    onNotification<RO>(
        type: ProtocolNotificationType0<RO>,
        handler: NotificationHandler0
    ): Disposable;
    
    onNotification<P, RO>(
        type: ProtocolNotificationType<P, RO>,
        handler: NotificationHandler<P>
    ): Disposable;
    
    sendRequest<R, PR, E, RO>(
        type: ProtocolRequestType0<R, PR, E, RO>,
        token?: CancellationToken
    ): Promise<R>;
    
    sendRequest<P, R, PR, E, RO>(
        type: ProtocolRequestType<P, R, PR, E, RO>,
        params: P,
        token?: CancellationToken
    ): Promise<R>;
    
    sendNotification<RO>(type: ProtocolNotificationType0<RO>): Promise<void>;
    sendNotification<P, RO>(type: ProtocolNotificationType<P, RO>, params: P): Promise<void>;
    
    listen(): void;
    dispose(): void;
}

namespace Files {
    /** Convert URI to file path */
    function uriToFilePath(uri: string): string | undefined;
    /** Resolve global Node.js module path */
    function resolveGlobalNodePath(path: string): string | undefined;
    /** Resolve global Yarn module path */
    function resolveGlobalYarnPath(path: string): string | undefined;
    /** Resolve module with optional node path and working directory */
    function resolve(
        moduleName: string,
        nodePath?: string,
        cwd?: string,
        tracer?: (message: string, verbose?: string) => void
    ): Promise<string>;
    /** Resolve module path with workspace context */
    function resolveModulePath(
        workspaceRoot: string,
        moduleName: string,
        nodePath?: string,
        tracer?: (message: string, verbose?: string) => void
    ): Promise<string>;
}

/**
 * Creates a new connection for browser environments
 * @param reader The message reader to read messages from
 * @param writer The message writer to write message to
 * @param options Optional connection strategy or connection options
 */
function createConnection(
    reader: MessageReader, 
    writer: MessageWriter, 
    options?: ConnectionStrategy | ConnectionOptions
): Connection;

type RequestHandler<P, R, E> = (params: P, token: CancellationToken, workDoneProgress: WorkDoneProgressReporter, partialResultProgress: ResultProgressReporter<Partial<R>>) => HandlerResult<R, E>;

type RequestHandler0<R, E> = (token: CancellationToken, workDoneProgress: WorkDoneProgressReporter, partialResultProgress: ResultProgressReporter<Partial<R>>) => HandlerResult<R, E>;

type NotificationHandler<P> = (params: P) => void;

type NotificationHandler0 = () => void;

type HandlerResult<R, E> = R | ResponseError<E> | Promise<R> | Promise<ResponseError<E>>;

interface Disposable {
    dispose(): void;
}

interface CancellationToken {
    readonly isCancellationRequested: boolean;
    readonly onCancellationRequested: Event<any>;
}