Sync language TS definitions with Flow (#2107)

* Sync language TS definitions with Flow

* [] => never[], as empty tuple is invalid in TS@2

tstypes/language/ast.d.ts

@@ -1,5 +1,5 @@
 import { Source } from './source';
-import { TokenKindEnum } from './lexer';
+import { TokenKindEnum } from './tokenKind';
 
 /**
  * Contains a range of UTF-8 character offsets and token references that

tstypes/language/blockString.d.ts

@@ -5,3 +5,17 @@
  * This implements the GraphQL spec's BlockStringValue() static algorithm.
  */
 export function dedentBlockStringValue(rawString: string): string;
+
+// @internal
+export function getBlockStringIndentation(lines: ReadonlyArray<string>): number;
+
+/**
+ * Print a block string in the indented block form by adding a leading and
+ * trailing blank line. However, if a block string starts with whitespace and is
+ * a single-line, adding a leading blank line would strip that whitespace.
+ */
+export function printBlockString(
+  value: string,
+  indentation?: string,
+  preferMultipleLines?: boolean,
+): string;

tstypes/language/index.d.ts

@@ -1,16 +1,16 @@
+export { Source } from './source';
 export { getLocation, SourceLocation } from './location';
 export { Kind, KindEnum } from './kinds';
-export { createLexer, TokenKind, Lexer, TokenKindEnum } from './lexer';
+export { TokenKind, TokenKindEnum } from './tokenKind';
+export { createLexer, Lexer } from './lexer';
 export { parse, parseValue, parseType, ParseOptions } from './parser';
 export { print } from './printer';
-export { Source } from './source';
 export {
   visit,
   visitInParallel,
   visitWithTypeInfo,
   getVisitFn,
   BREAK,
-  // type
   ASTVisitor,
   Visitor,
   VisitFn,

tstypes/language/lexer.d.ts

@@ -1,6 +1,6 @@
+import { syntaxError } from '../error';
 import { Token } from './ast';
 import { Source } from './source';
-import { syntaxError } from '../error';
 
 /**
  * Given a Source object, this returns a Lexer for that source.
@@ -55,43 +55,6 @@ export interface Lexer<TOptions> {
 }
 
 /**
- * An exported enum describing the different kinds of tokens that the
- * lexer emits.
- */
-export const TokenKind: _TokenKind;
-
-// @internal
-type _TokenKind = {
-  SOF: '<SOF>';
-  EOF: '<EOF>';
-  BANG: '!';
-  DOLLAR: '$';
-  AMP: '&';
-  PAREN_L: '(';
-  PAREN_R: ')';
-  SPREAD: '...';
-  COLON: ':';
-  EQUALS: '=';
-  AT: '@';
-  BRACKET_L: '[';
-  BRACKET_R: ']';
-  BRACE_L: '{';
-  PIPE: '|';
-  BRACE_R: '}';
-  NAME: 'Name';
-  INT: 'Int';
-  FLOAT: 'Float';
-  STRING: 'String';
-  BLOCK_STRING: 'BlockString';
-  COMMENT: 'Comment';
-};
-
-/**
- * The enum type representing the token kinds values.
- */
-export type TokenKindEnum = _TokenKind[keyof _TokenKind];
-
-/**
- * A helper function to describe a token as a string for debugging
+ * @internal
  */
-export function getTokenDesc(token: Token): string;
+export function isPunctuatorToken(token: Token): boolean;

tstypes/language/parser.d.ts

@@ -1,6 +1,6 @@
-import { NamedTypeNode, TypeNode, ValueNode, DocumentNode } from './ast';
 import { Source } from './source';
 import { Lexer } from './lexer';
+import { NamedTypeNode, TypeNode, ValueNode, DocumentNode } from './ast';
 
 /**
  * Configuration options to control parser behavior
@@ -50,17 +50,6 @@ export interface ParseOptions {
    * future.
    */
   experimentalFragmentVariables?: boolean;
-
-  /**
-   * EXPERIMENTAL:
-   *
-   * If enabled, the parser understands directives on variable definitions:
-   *
-   * query Foo($var: String = "abc" @variable_definition_directive) {
-   *   ...
-   * }
-   */
-  experimentalVariableDefinitionDirectives?: boolean;
 }
 
 /**
@@ -98,18 +87,3 @@ export function parseType(
   source: string | Source,
   options?: ParseOptions,
 ): TypeNode;
-
-export function parseConstValue<TOptions>(lexer: Lexer<TOptions>): ValueNode;
-
-/**
- * Type :
- *   - NamedType
- *   - ListType
- *   - NonNullType
- */
-export function parseTypeReference<TOptions>(lexer: Lexer<TOptions>): TypeNode;
-
-/**
- * NamedType : Name
- */
-export function parseNamedType<TOptions>(lexer: Lexer<TOptions>): NamedTypeNode;

tstypes/language/printLocation.d.ts

@@ -0,0 +1,16 @@
+import { Location } from '../language/ast';
+import { Source } from '../language/source';
+import { SourceLocation } from '../language/location';
+
+/**
+ * Render a helpful description of the location in the GraphQL Source document.
+ */
+export function printLocation(location: Location): string;
+
+/**
+ * Render a helpful description of the location in the GraphQL Source document.
+ */
+export function printSourceLocation(
+  source: Source,
+  sourceLocation: SourceLocation,
+): string;

tstypes/language/tokenKind.d.ts

@@ -0,0 +1,35 @@
+/**
+ * An exported enum describing the different kinds of tokens that the
+ * lexer emits.
+ */
+export const TokenKind: _TokenKind;
+
+type _TokenKind = {
+  SOF: '<SOF>';
+  EOF: '<EOF>';
+  BANG: '!';
+  DOLLAR: '$';
+  AMP: '&';
+  PAREN_L: '(';
+  PAREN_R: ')';
+  SPREAD: '...';
+  COLON: ':';
+  EQUALS: '=';
+  AT: '@';
+  BRACKET_L: '[';
+  BRACKET_R: ']';
+  BRACE_L: '{';
+  PIPE: '|';
+  BRACE_R: '}';
+  NAME: 'Name';
+  INT: 'Int';
+  FLOAT: 'Float';
+  STRING: 'String';
+  BLOCK_STRING: 'BlockString';
+  COMMENT: 'Comment';
+};
+
+/**
+ * The enum type representing the token kinds values.
+ */
+export type TokenKindEnum = _TokenKind[keyof _TokenKind];

tstypes/language/visitor.d.ts

@@ -1,6 +1,15 @@
 import Maybe from '../tsutils/Maybe';
-import { ASTNode, ASTKindToNode } from './ast';
 import { TypeInfo } from '../utilities/TypeInfo';
+import { ASTNode, ASTKindToNode } from './ast';
+
+/**
+ * A visitor is provided to visit, it contains the collection of
+ * relevant functions to be called during the visitor's traversal.
+ */
+export type ASTVisitor = Visitor<ASTKindToNode>;
+export type Visitor<KindToNode, Nodes = KindToNode[keyof KindToNode]> =
+  | EnterLeaveVisitor<KindToNode, Nodes>
+  | ShapeMapVisitor<KindToNode, Nodes>;
 
 interface EnterLeave<T> {
   readonly enter?: T;
@@ -17,27 +26,23 @@ type ShapeMapVisitor<KindToNode, Nodes> = {
     | EnterLeave<VisitFn<Nodes, KindToNode[K]>>;
 };
 
-export type ASTVisitor = Visitor<ASTKindToNode>;
-export type Visitor<KindToNode, Nodes = KindToNode[keyof KindToNode]> =
-  | EnterLeaveVisitor<KindToNode, Nodes>
-  | ShapeMapVisitor<KindToNode, Nodes>;
-
 /**
  * A visitor is comprised of visit functions, which are called on each node
  * during the visitor's traversal.
  */
 export type VisitFn<TAnyNode, TVisitedNode = TAnyNode> = (
-  // The current node being visiting.
+  /** The current node being visiting.*/
   node: TVisitedNode,
-  // The index or key to this node from the parent node or Array.
+  /** The index or key to this node from the parent node or Array. */
   key: string | number | undefined,
-  // The parent immediately above this node, which may be an Array.
+  /** The parent immediately above this node, which may be an Array. */
   parent: TAnyNode | ReadonlyArray<TAnyNode> | undefined,
-  // The key path to get to this node from the root node.
+  /** The key path to get to this node from the root node. */
   path: ReadonlyArray<string | number>,
-  // All nodes and Arrays visited before reaching parent of this node.
-  // These correspond to array indices in `path`.
-  // Note: ancestors includes arrays which contain the parent of visited node.
+  /** All nodes and Arrays visited before reaching parent of this node.
+   * These correspond to array indices in `path`.
+   * Note: ancestors includes arrays which contain the parent of visited node.
+   */
   ancestors: ReadonlyArray<TAnyNode | ReadonlyArray<TAnyNode>>,
 ) => any;
 
@@ -46,9 +51,96 @@ export type VisitFn<TAnyNode, TVisitedNode = TAnyNode> = (
  */
 export type VisitorKeyMap<T> = { [P in keyof T]: ReadonlyArray<keyof T[P]> };
 
-export const QueryDocumentKeys: { [key: string]: string[] };
+// TODO: Should be `[]`, but that requires TypeScript@3
+type EmptyTuple = never[];
+
+export const QueryDocumentKeys: {
+  Name: EmptyTuple;
+
+  Document: ['definitions'];
+  // Prettier forces trailing commas, but TS pre 3.2 doesn't allow them.
+  // prettier-ignore
+  OperationDefinition: [
+    'name',
+    'variableDefinitions',
+    'directives',
+    'selectionSet'
+  ];
+  VariableDefinition: ['variable', 'type', 'defaultValue', 'directives'];
+  Variable: ['name'];
+  SelectionSet: ['selections'];
+  Field: ['alias', 'name', 'arguments', 'directives', 'selectionSet'];
+  Argument: ['name', 'value'];
+
+  FragmentSpread: ['name', 'directives'];
+  InlineFragment: ['typeCondition', 'directives', 'selectionSet'];
+  // prettier-ignore
+  FragmentDefinition: [
+    'name',
+    // Note: fragment variable definitions are experimental and may be changed
+    // or removed in the future.
+    'variableDefinitions',
+    'typeCondition',
+    'directives',
+    'selectionSet'
+  ];
+
+  IntValue: EmptyTuple;
+  FloatValue: EmptyTuple;
+  StringValue: EmptyTuple;
+  BooleanValue: EmptyTuple;
+  NullValue: EmptyTuple;
+  EnumValue: EmptyTuple;
+  ListValue: ['values'];
+  ObjectValue: ['fields'];
+  ObjectField: ['name', 'value'];
+
+  Directive: ['name', 'arguments'];
+
+  NamedType: ['name'];
+  ListType: ['type'];
+  NonNullType: ['type'];
+
+  SchemaDefinition: ['directives', 'operationTypes'];
+  OperationTypeDefinition: ['type'];
+
+  ScalarTypeDefinition: ['description', 'name', 'directives'];
+  // prettier-ignore
+  ObjectTypeDefinition: [
+    'description',
+    'name',
+    'interfaces',
+    'directives',
+    'fields'
+  ];
+  FieldDefinition: ['description', 'name', 'arguments', 'type', 'directives'];
+  // prettier-ignore
+  InputValueDefinition: [
+    'description',
+    'name',
+    'type',
+    'defaultValue',
+    'directives'
+  ];
+  InterfaceTypeDefinition: ['description', 'name', 'directives', 'fields'];
+  UnionTypeDefinition: ['description', 'name', 'directives', 'types'];
+  EnumTypeDefinition: ['description', 'name', 'directives', 'values'];
+  EnumValueDefinition: ['description', 'name', 'directives'];
+  InputObjectTypeDefinition: ['description', 'name', 'directives', 'fields'];
+
+  DirectiveDefinition: ['description', 'name', 'arguments', 'locations'];
+
+  SchemaExtension: ['directives', 'operationTypes'];
+
+  ScalarTypeExtension: ['name', 'directives'];
+  ObjectTypeExtension: ['name', 'interfaces', 'directives', 'fields'];
+  InterfaceTypeExtension: ['name', 'directives', 'fields'];
+  UnionTypeExtension: ['name', 'directives', 'types'];
+  EnumTypeExtension: ['name', 'directives', 'values'];
+  InputObjectTypeExtension: ['name', 'directives', 'fields'];
+};
 
-export const BREAK: any;
+export const BREAK: {};
 
 /**
  * visit() will walk through an AST using a depth first traversal, calling
@@ -149,7 +241,7 @@ export function visit(
  * If a prior visitor edits a node, no following visitors will see that node.
  */
 export function visitInParallel(
-  visitors: Array<Visitor<ASTKindToNode>>,
+  visitors: ReadonlyArray<Visitor<ASTKindToNode>>,
 ): Visitor<ASTKindToNode>;
 
 /**