Generate typescript types from schema

[bollwyvl]

We're quickly iterating on the spec and server schema. We need a reasonable way to build typescript types for the frontend as we learn more about integrating more servers and shifting concerns back and forth between the server and client.

Tool options

• https://www.npmjs.com/package/dtsgenerator (6k weekly downloads, 3 new deps)
  • i've used this before, but it's been ages
• https://www.npmjs.com/package/json-schema-to-typescript (42k weekly downloads, 18 new deps)
  • seems a bit better documented

I'll kick the tires on both of them and see what we get. There's also nothing wrong with making choices in the schema itself to get better types out.

References

• Add server status endpoint #81
• Language Server Spec v1 #90
• 💭 streamline server starting, binder, architectural musings #22

I'll do a bit of research

[bollwyvl]

dtsgenerator didn't like it, but js2ts rendered:

/* tslint:disable */
/**
 * This file was automatically generated by json-schema-to-typescript.
 * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
 * and run json-schema-to-typescript to regenerate this file.
 */

/**
 * describes the current state of (potentially) running language servers
 */
export type JupyterLspServerStatusResponse =
  | ServersResponse
  | LanguageServerSpecsMap;
/**
 * the count of currently-connected WebSocket handlers
 */
export type HandlerCount = number;
/**
 * the arguments to start the language server normally
 */
export type LaunchArguments = string[];
/**
 * the arguments to start the language server with more verbose output
 */
export type DebugArguments = string[];
/**
 * name shown in the UI
 */
export type DisplayName = string;
/**
 * This interface was referenced by `EnvironmentVariables`'s JSON-Schema definition
 * via the `patternProperty` "[^ ]+".
 */
export type AnEnvironmentVariableMayContainPythonStringTemplateEvaluatedAgainstTheExistingEnvironmentEG$HOME = string;
/**
 * the install commands or description for installing the language server
 *
 * This interface was referenced by `Installation`'s JSON-Schema definition
 * via the `patternProperty` ".+".
 *
 * This interface was referenced by `Installation1`'s JSON-Schema definition
 * via the `patternProperty` ".+".
 */
export type InstallHelp = string;
/**
 * known extensions that can contribute to the Language Server's features
 */
export type Extensions = LanguageServerExtension[];
/**
 * languages supported by this Language Server
 */
export type LanguageList = [string, ...(string)[]];
/**
 * list of MIME types supported by the language server
 */
export type MIMETypes = [string, ...(string)[]];
/**
 * which version of the spec this implements
 */
export type SpecSchemaVersion = 1;
/**
 * a description of a language server that could be started
 *
 * This interface was referenced by `LanguageServerSpecsMap`'s JSON-Schema definition
 * via the `patternProperty` ".*".
 */
export type LanguageServerSpec = ServerSpecProperties & {
  [k: string]: any;
};

export interface ServersResponse {
  /**
   * a list of servers that are, could be, or were running
   */
  sessions: LanguageServerSession[];
  version: SpecSchemaVersion;
  [k: string]: any;
}
/**
 * a language server session
 */
export interface LanguageServerSession {
  handler_count: HandlerCount;
  /**
   * date-time of last seen message from a WebSocket handler
   */
  last_handler_message_at: string | null;
  /**
   * date-time of last seen message from the language server
   */
  last_server_message_at: string | null;
  spec: ServerSpecProperties;
  /**
   * a string describing the current state of the server
   */
  status: 'not_started' | 'starting' | 'started' | 'stopping' | 'stopped';
}
/**
 * all properties that might be required to start and/or describe a Language Server
 */
export interface ServerSpecProperties {
  argv?: LaunchArguments;
  config_schema?: ClientConfigurationSchema;
  debug_argv?: DebugArguments;
  display_name?: DisplayName;
  env?: EnvironmentVariables;
  extend?: Extensions;
  install?: Installation1;
  languages?: LanguageList;
  mime_types?: MIMETypes;
  urls?: URLs;
  version?: SpecSchemaVersion;
  [k: string]: any;
}
/**
 * a JSON schema to configure the Language Server behavior from the client
 */
export interface ClientConfigurationSchema {
  [k: string]: any;
}
/**
 * additional environment variables to set when starting the language server
 */
export interface EnvironmentVariables {
  [k: string]: AnEnvironmentVariableMayContainPythonStringTemplateEvaluatedAgainstTheExistingEnvironmentEG$HOME;
}
/**
 * an extension which can extend the functionality of the language server and client
 */
export interface LanguageServerExtension {
  config_schema?: ClientConfigurationSchema1;
  display_name?: string;
  install?: Installation;
  [k: string]: any;
}
/**
 * a JSON schema to configure the Language Server or extension behavior from the client
 */
export interface ClientConfigurationSchema1 {
  [k: string]: any;
}
/**
 * a list of installation approaches keyed by package manager, e.g. pip, npm, yarn, apt
 */
export interface Installation {
  [k: string]: InstallHelp;
}
/**
 * a list of installation approaches keyed by package manager, e.g. pip, npm, yarn, apt
 */
export interface Installation1 {
  [k: string]: InstallHelp;
}
/**
 * a collection of urls keyed by type, e.g. home, issues
 */
export interface URLs {
  [k: string]: string;
}
/**
 * a set of language servers keyed by their implementation name
 */
export interface LanguageServerSpecsMap {
  [k: string]: LanguageServerSpec;
}

[bollwyvl]

I don't like the Installation1, but otherwise looks pretty good. There are more types in here than would be coming back from the server (we elide AnEnvironmentVariableMayContainPythonStringTemplateEvaluatedAgainstTheExistingEnvironmentEG (whoops). The actual index.ts would just probably just re-export ServersResponse, and we'd want to tighten that up (it should demand languages now, and key if we opt for implementation-named endpoints).

[bollwyvl]

Closed by #110