update graphql/utilities/* -> v0.13.2.

https://github.com/graphql/graphql-js/tree/v0.13.2/src/utilities

types/graphql/utilities/TypeInfo.d.ts

@@ -22,22 +22,26 @@ export class TypeInfo {
         // NOTE: this experimental optional second parameter is only needed in order
         // to support non-spec-compliant codebases. You should never need to use it.
         // It may disappear in the future.
-        getFieldDefFn?: getFieldDef
+        getFieldDefFn?: getFieldDef,
+        // Initial type may be provided in rare cases to facilitate traversals
+        // beginning somewhere other than documents.
+        initialType?: GraphQLType
     );
 
-    getType(): GraphQLOutputType;
-    getParentType(): GraphQLCompositeType;
-    getInputType(): GraphQLInputType;
-    getFieldDef(): GraphQLField<any, any>;
-    getDirective(): GraphQLDirective;
-    getArgument(): GraphQLArgument;
-    getEnumValue(): GraphQLEnumValue;
+    getType(): GraphQLOutputType | void;
+    getParentType(): GraphQLCompositeType | void;
+    getInputType(): GraphQLInputType | void;
+    getParentInputType(): GraphQLInputType | void;
+    getFieldDef(): GraphQLField<any, any> | void;
+    getDirective(): GraphQLDirective | void;
+    getArgument(): GraphQLArgument | void;
+    getEnumValue(): GraphQLEnumValue | void;
     enter(node: ASTNode): any;
     leave(node: ASTNode): any;
 }
 
-export type getFieldDef = (
+type getFieldDef = (
     schema: GraphQLSchema,
     parentType: GraphQLType,
     fieldNode: FieldNode
-) => GraphQLField<any, any>;
+) => GraphQLField<any, any> | void;

types/graphql/utilities/assertValidName.d.ts

@@ -1,2 +1,12 @@
-// Helper to assert that provided names are valid.
-export function assertValidName(name: string): void;
+import { GraphQLError } from "../error/GraphQLError";
+import { ASTNode } from "../language/ast";
+
+/**
+ * Upholds the spec rules about naming.
+ */
+export function assertValidName(name: string): string;
+
+/**
+ * Returns an Error if a name is invalid.
+ */
+export function isValidNameError(name: string, node?: ASTNode | undefined): GraphQLError | undefined;

types/graphql/utilities/astFromValue.d.ts

@@ -1,16 +1,4 @@
-import {
-    ValueNode,
-    /*
-    TODO:
-    IntValueNode,
-    FloatValueNode,
-    StringValueNode,
-    BooleanValueNode,
-    EnumValueNode,
-    ListValueNode,
-    ObjectValueNode,
-    */
-} from "../language/ast";
+import { ValueNode } from "../language/ast";
 import { GraphQLInputType } from "../type/definition";
 
 /**
@@ -27,7 +15,7 @@ import { GraphQLInputType } from "../type/definition";
  * | String        | String / Enum Value  |
  * | Number        | Int / Float          |
  * | Mixed         | Enum Value           |
+ * | null          | NullValue            |
  *
  */
-// TODO: this should set overloads according to above the table
-export function astFromValue(value: any, type: GraphQLInputType): ValueNode; // Warning: there is a code in bottom: throw new TypeError
+export function astFromValue(value: any, type: GraphQLInputType): ValueNode | void;

types/graphql/utilities/buildASTSchema.d.ts

@@ -1,6 +1,18 @@
-import { DocumentNode, Location, StringValueNode } from "../language/ast";
+import {
+    DocumentNode,
+    Location,
+    StringValueNode,
+    TypeDefinitionNode,
+    NamedTypeNode,
+    DirectiveDefinitionNode,
+    FieldDefinitionNode,
+} from "../language/ast";
+import { GraphQLNamedType, GraphQLFieldConfig } from "../type/definition";
+import { GraphQLDirective } from "../type/directives";
 import { Source } from "../language/source";
 import { GraphQLSchema, GraphQLSchemaValidationOptions } from "../type/schema";
+import { ParseOptions } from "../language/parser";
+import blockStringValue from "../language/blockStringValue";
 
 interface BuildSchemaOptions extends GraphQLSchemaValidationOptions {
     /**
@@ -22,8 +34,29 @@ interface BuildSchemaOptions extends GraphQLSchemaValidationOptions {
  *
  * Given that AST it constructs a GraphQLSchema. The resulting schema
  * has no resolve methods, so execution will use default resolvers.
+ *
+ * Accepts options as a second argument:
+ *
+ *    - commentDescriptions:
+ *        Provide true to use preceding comments as the description.
+ *
  */
-export function buildASTSchema(ast: DocumentNode): GraphQLSchema;
+export function buildASTSchema(ast: DocumentNode, options?: BuildSchemaOptions): GraphQLSchema;
+
+type TypeDefinitionsMap = { [key: string]: TypeDefinitionNode };
+type TypeResolver = (typeRef: NamedTypeNode) => GraphQLNamedType;
+
+export class ASTDefinitionBuilder {
+    constructor(typeDefinitionsMap: TypeDefinitionsMap, options: BuildSchemaOptions | void, resolveType: TypeResolver);
+
+    buildTypes(nodes: ReadonlyArray<NamedTypeNode | TypeDefinitionNode>): Array<GraphQLNamedType>;
+
+    buildType(node: NamedTypeNode | TypeDefinitionNode): GraphQLNamedType;
+
+    buildDirective(directiveNode: DirectiveDefinitionNode): GraphQLDirective;
+
+    buildField(field: FieldDefinitionNode): GraphQLFieldConfig<any, any>;
+}
 
 /**
  * Given an ast node, returns its string description.
@@ -35,12 +68,12 @@ export function buildASTSchema(ast: DocumentNode): GraphQLSchema;
  *
  */
 export function getDescription(
-    node: { description?: StringValueNode; loc?: Location },
-    options: BuildSchemaOptions
-): string;
+    node: { readonly description?: StringValueNode; readonly loc?: Location },
+    options: BuildSchemaOptions | void
+): string | undefined;
 
 /**
  * A helper function to build a GraphQLSchema directly from a source
  * document.
  */
-export function buildSchema(source: string | Source): GraphQLSchema;
+export function buildSchema(source: string | Source, options?: BuildSchemaOptions & ParseOptions): GraphQLSchema;

types/graphql/utilities/buildClientSchema.d.ts

@@ -11,5 +11,8 @@ interface Options extends GraphQLSchemaValidationOptions {}
  * tools, but cannot be used to execute a query, as introspection does not
  * represent the "resolver", "parse" or "serialize" functions or any other
  * server-internal mechanisms.
+ *
+ * This function expects a complete introspection result. Don't forget to check
+ * the "errors" field of a server response before calling this function.
  */
 export function buildClientSchema(introspection: IntrospectionQuery, options?: Options): GraphQLSchema;

types/graphql/utilities/coerceValue.d.ts

@@ -0,0 +1,22 @@
+import { GraphQLError } from "../error";
+import { ASTNode } from "../language/ast";
+import { GraphQLInputType } from "../type/definition";
+
+interface CoercedValue {
+    readonly errors: ReadonlyArray<GraphQLError> | undefined;
+    readonly value: any;
+}
+
+interface Path {
+    readonly prev: Path | undefined;
+    readonly key: string | number;
+}
+
+/**
+ * Coerces a JavaScript value given a GraphQL Type.
+ *
+ * Returns either a value which is valid for the provided type or a list of
+ * encountered coercion errors.
+ *
+ */
+export function coerceValue(value: any, type: GraphQLInputType, blameNode?: ASTNode, path?: Path): CoercedValue;

types/graphql/utilities/concatAST.d.ts

@@ -5,4 +5,4 @@ import { DocumentNode } from "../language/ast";
  * concatenate the ASTs together into batched AST, useful for validating many
  * GraphQL source files which together represent one conceptual application.
  */
-export function concatAST(asts: DocumentNode[]): DocumentNode;
+export function concatAST(asts: ReadonlyArray<DocumentNode>): DocumentNode;

types/graphql/utilities/extendSchema.d.ts

@@ -1,5 +1,17 @@
 import { DocumentNode } from "../language/ast";
 import { GraphQLSchema } from "../type/schema";
+import { GraphQLSchemaValidationOptions } from "../type/schema";
+
+interface Options extends GraphQLSchemaValidationOptions {
+    /**
+     * Descriptions are defined as preceding string literals, however an older
+     * experimental version of the SDL supported preceding comments as
+     * descriptions. Set to true to enable this deprecated behavior.
+     *
+     * Default: false
+     */
+    commentDescriptions?: boolean;
+}
 
 /**
  * Produces a new schema given an existing schema and a document which may
@@ -12,5 +24,11 @@ import { GraphQLSchema } from "../type/schema";
  *
  * This algorithm copies the provided schema, applying extensions while
  * producing the copy. The original schema remains unaltered.
+ *
+ * Accepts options as a third argument:
+ *
+ *    - commentDescriptions:
+ *        Provide true to use preceding comments as the description.
+ *
  */
-export function extendSchema(schema: GraphQLSchema, documentAST: DocumentNode): GraphQLSchema;
+export function extendSchema(schema: GraphQLSchema, documentAST: DocumentNode, options?: Options): GraphQLSchema;

types/graphql/utilities/findBreakingChanges.d.ts

@@ -8,27 +8,44 @@ import {
     GraphQLUnionType,
     GraphQLNamedType,
 } from "../type/definition";
+import { GraphQLDirective } from "../type/directives";
 import { GraphQLSchema } from "../type/schema";
+import { DirectiveLocationEnum } from "../language/directiveLocation";
 
-export const BreakingChangeType: {
+export type BreakingChangeType = {
     FIELD_CHANGED_KIND: "FIELD_CHANGED_KIND";
     FIELD_REMOVED: "FIELD_REMOVED";
     TYPE_CHANGED_KIND: "TYPE_CHANGED_KIND";
     TYPE_REMOVED: "TYPE_REMOVED";
     TYPE_REMOVED_FROM_UNION: "TYPE_REMOVED_FROM_UNION";
     VALUE_REMOVED_FROM_ENUM: "VALUE_REMOVED_FROM_ENUM";
+    ARG_REMOVED: "ARG_REMOVED";
+    ARG_CHANGED_KIND: "ARG_CHANGED_KIND";
+    NON_NULL_ARG_ADDED: "NON_NULL_ARG_ADDED";
+    NON_NULL_INPUT_FIELD_ADDED: "NON_NULL_INPUT_FIELD_ADDED";
+    INTERFACE_REMOVED_FROM_OBJECT: "INTERFACE_REMOVED_FROM_OBJECT";
+    DIRECTIVE_REMOVED: "DIRECTIVE_REMOVED";
+    DIRECTIVE_ARG_REMOVED: "DIRECTIVE_ARG_REMOVED";
+    DIRECTIVE_LOCATION_REMOVED: "DIRECTIVE_LOCATION_REMOVED";
+    NON_NULL_DIRECTIVE_ARG_ADDED: "NON_NULL_DIRECTIVE_ARG_ADDED";
 };
 
-export type BreakingChangeKey =
-    | "FIELD_CHANGED_KIND"
-    | "FIELD_REMOVED"
-    | "TYPE_CHANGED_KIND"
-    | "TYPE_REMOVED"
-    | "TYPE_REMOVED_FROM_UNION"
-    | "VALUE_REMOVED_FROM_ENUM";
+export type DangerousChangeType = {
+    ARG_DEFAULT_VALUE_CHANGE: "ARG_DEFAULT_VALUE_CHANGE";
+    VALUE_ADDED_TO_ENUM: "VALUE_ADDED_TO_ENUM";
+    INTERFACE_ADDED_TO_OBJECT: "INTERFACE_ADDED_TO_OBJECT";
+    TYPE_ADDED_TO_UNION: "TYPE_ADDED_TO_UNION";
+    NULLABLE_INPUT_FIELD_ADDED: "NULLABLE_INPUT_FIELD_ADDED";
+    NULLABLE_ARG_ADDED: "NULLABLE_ARG_ADDED";
+};
 
 export interface BreakingChange {
-    type: BreakingChangeKey;
+    type: keyof BreakingChangeType;
+    description: string;
+}
+
+export interface DangerousChange {
+    type: keyof DangerousChangeType;
     description: string;
 }
 
@@ -36,35 +53,102 @@ export interface BreakingChange {
  * Given two schemas, returns an Array containing descriptions of all the types
  * of breaking changes covered by the other functions down below.
  */
-export function findBreakingChanges(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): BreakingChange[];
+export function findBreakingChanges(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<BreakingChange>;
+
+/**
+ * Given two schemas, returns an Array containing descriptions of all the types
+ * of potentially dangerous changes covered by the other functions down below.
+ */
+export function findDangerousChanges(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<DangerousChange>;
 
 /**
  * Given two schemas, returns an Array containing descriptions of any breaking
  * changes in the newSchema related to removing an entire type.
  */
-export function findRemovedTypes(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): BreakingChange[];
+export function findRemovedTypes(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<BreakingChange>;
 
 /**
  * Given two schemas, returns an Array containing descriptions of any breaking
  * changes in the newSchema related to changing the type of a type.
  */
-export function findTypesThatChangedKind(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): BreakingChange[];
+export function findTypesThatChangedKind(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<BreakingChange>;
 
 /**
- * Given two schemas, returns an Array containing descriptions of any breaking
- * changes in the newSchema related to the fields on a type. This includes if
- * a field has been removed from a type or if a field has changed type.
+ * Given two schemas, returns an Array containing descriptions of any
+ * breaking or dangerous changes in the newSchema related to arguments
+ * (such as removal or change of type of an argument, or a change in an
+ * argument's default value).
  */
-export function findFieldsThatChangedType(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): BreakingChange[];
+export function findArgChanges(
+    oldSchema: GraphQLSchema,
+    newSchema: GraphQLSchema
+): {
+    breakingChanges: Array<BreakingChange>;
+    dangerousChanges: Array<DangerousChange>;
+};
+
+export function findFieldsThatChangedTypeOnObjectOrInterfaceTypes(
+    oldSchema: GraphQLSchema,
+    newSchema: GraphQLSchema
+): Array<BreakingChange>;
+
+export function findFieldsThatChangedTypeOnInputObjectTypes(
+    oldSchema: GraphQLSchema,
+    newSchema: GraphQLSchema
+): {
+    breakingChanges: Array<BreakingChange>;
+    dangerousChanges: Array<DangerousChange>;
+};
 
 /**
  * Given two schemas, returns an Array containing descriptions of any breaking
  * changes in the newSchema related to removing types from a union type.
  */
-export function findTypesRemovedFromUnions(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): BreakingChange[];
+export function findTypesRemovedFromUnions(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<BreakingChange>;
+
+/**
+ * Given two schemas, returns an Array containing descriptions of any dangerous
+ * changes in the newSchema related to adding types to a union type.
+ */
+export function findTypesAddedToUnions(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<DangerousChange>;
 
 /**
  * Given two schemas, returns an Array containing descriptions of any breaking
  * changes in the newSchema related to removing values from an enum type.
  */
-export function findValuesRemovedFromEnums(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): BreakingChange[];
+export function findValuesRemovedFromEnums(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<BreakingChange>;
+
+/**
+ * Given two schemas, returns an Array containing descriptions of any dangerous
+ * changes in the newSchema related to adding values to an enum type.
+ */
+export function findValuesAddedToEnums(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<DangerousChange>;
+
+export function findInterfacesRemovedFromObjectTypes(
+    oldSchema: GraphQLSchema,
+    newSchema: GraphQLSchema
+): Array<BreakingChange>;
+
+export function findInterfacesAddedToObjectTypes(
+    oldSchema: GraphQLSchema,
+    newSchema: GraphQLSchema
+): Array<DangerousChange>;
+
+export function findRemovedDirectives(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<BreakingChange>;
+
+export function findRemovedDirectiveArgs(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): Array<BreakingChange>;
+
+export function findAddedNonNullDirectiveArgs(
+    oldSchema: GraphQLSchema,
+    newSchema: GraphQLSchema
+): Array<BreakingChange>;
+
+export function findRemovedLocationsForDirective(
+    oldDirective: GraphQLDirective,
+    newDirective: GraphQLDirective
+): Array<DirectiveLocationEnum>;
+
+export function findRemovedDirectiveLocations(
+    oldSchema: GraphQLSchema,
+    newSchema: GraphQLSchema
+): Array<BreakingChange>;

types/graphql/utilities/getOperationAST.d.ts

@@ -5,4 +5,7 @@ import { DocumentNode, OperationDefinitionNode } from "../language/ast";
  * name. If a name is not provided, an operation is only returned if only one is
  * provided in the document.
  */
-export function getOperationAST(documentAST: DocumentNode, operationName?: string): OperationDefinitionNode;
+export function getOperationAST(
+    documentAST: DocumentNode,
+    operationName: string | void
+): OperationDefinitionNode | void;

types/graphql/utilities/index.d.ts

@@ -1,9 +1,17 @@
 // The GraphQL query recommended for a full schema introspection.
-export { introspectionQuery } from "./introspectionQuery";
 export {
+    getIntrospectionQuery,
+    // Deprecated, use getIntrospectionQuery()
+    introspectionQuery,
+} from "./introspectionQuery";
+
+export {
+    IntrospectionOptions,
     IntrospectionQuery,
     IntrospectionSchema,
     IntrospectionType,
+    IntrospectionInputType,
+    IntrospectionOutputType,
     IntrospectionScalarType,
     IntrospectionObjectType,
     IntrospectionInterfaceType,
@@ -11,6 +19,8 @@ export {
     IntrospectionEnumType,
     IntrospectionInputObjectType,
     IntrospectionTypeRef,
+    IntrospectionInputTypeRef,
+    IntrospectionOutputTypeRef,
     IntrospectionNamedTypeRef,
     IntrospectionListTypeRef,
     IntrospectionNonNullTypeRef,
@@ -23,24 +33,33 @@ export {
 // Gets the target Operation from a Document
 export { getOperationAST } from "./getOperationAST";
 
+// Convert a GraphQLSchema to an IntrospectionQuery
+export { introspectionFromSchema } from "./introspectionFromSchema";
+
 // Build a GraphQLSchema from an introspection result.
 export { buildClientSchema } from "./buildClientSchema";
 
 // Build a GraphQLSchema from GraphQL Schema language.
-export { buildASTSchema, buildSchema, getDescription } from "./buildASTSchema";
+export { buildASTSchema, buildSchema, getDescription, BuildSchemaOptions } from "./buildASTSchema";
 
 // Extends an existing GraphQLSchema from a parsed GraphQL Schema language AST.
 export { extendSchema } from "./extendSchema";
 
+// Sort a GraphQLSchema.
+export { lexicographicSortSchema } from "./lexicographicSortSchema";
+
 // Print a GraphQLSchema to GraphQL Schema language.
 export { printSchema, printType, printIntrospectionSchema } from "./schemaPrinter";
 
 // Create a GraphQLType from a GraphQL language AST.
 export { typeFromAST } from "./typeFromAST";
 
-// Create a JavaScript value from a GraphQL language AST.
+// Create a JavaScript value from a GraphQL language AST with a type.
 export { valueFromAST } from "./valueFromAST";
 
+// Create a JavaScript value from a GraphQL language AST without a type.
+export { valueFromASTUntyped } from "./valueFromASTUntyped";
+
 // Create a GraphQL language AST from a JavaScript value.
 export { astFromValue } from "./astFromValue";
 
@@ -48,7 +67,10 @@ export { astFromValue } from "./astFromValue";
 // the GraphQL type system.
 export { TypeInfo } from "./TypeInfo";
 
-// Determine if JavaScript values adhere to a GraphQL type.
+// Coerces a JavaScript value to a GraphQL type, or produces errors.
+export { coerceValue } from "./coerceValue";
+
+// @deprecated use coerceValue
 export { isValidJSValue } from "./isValidJSValue";
 
 // Determine if AST values adhere to a GraphQL type.
@@ -64,11 +86,17 @@ export { separateOperations } from "./separateOperations";
 export { isEqualType, isTypeSubTypeOf, doTypesOverlap } from "./typeComparators";
 
 // Asserts that a string is a valid GraphQL name
-export { assertValidName } from "./assertValidName";
+export { assertValidName, isValidNameError } from "./assertValidName";
 
 // Compares two GraphQLSchemas and detects breaking changes.
-export { findBreakingChanges } from "./findBreakingChanges";
-export { BreakingChange } from "./findBreakingChanges";
+export {
+    BreakingChangeType,
+    DangerousChangeType,
+    findBreakingChanges,
+    findDangerousChanges,
+    BreakingChange,
+    DangerousChange,
+} from "./findBreakingChanges";
 
 // Report all deprecated usage within a GraphQL document.
 export { findDeprecatedUsages } from "./findDeprecatedUsages";

types/graphql/utilities/introspectionFromSchema.d.ts

@@ -0,0 +1,13 @@
+import { GraphQLSchema } from "../type/schema";
+import { IntrospectionQuery, IntrospectionOptions } from "./introspectionQuery";
+
+/**
+ * Build an IntrospectionQuery from a GraphQLSchema
+ *
+ * IntrospectionQuery is useful for utilities that care about type and field
+ * relationships, but do not need to traverse through those relationships.
+ *
+ * This is the inverse of buildClientSchema. The primary use case is outside
+ * of the server context, for instance when doing schema comparisons.
+ */
+export function introspectionFromSchema(schema: GraphQLSchema, options: IntrospectionOptions): IntrospectionQuery;

types/graphql/utilities/introspectionQuery.d.ts

@@ -1,110 +1,25 @@
-import { DirectiveLocationEnum } from "../type/directives";
+import { DirectiveLocationEnum } from "../language/directiveLocation";
 
-/*
-query IntrospectionQuery {
-    __schema {
-    queryType { name }
-    mutationType { name }
-    subscriptionType { name }
-    types {
-        ...FullType
-    }
-    directives {
-        name
-        description
-        locations
-        args {
-        ...InputValue
-        }
-    }
-    }
+export interface IntrospectionOptions {
+    // Whether to include descriptions in the introspection result.
+    // Default: true
+    descriptions: boolean;
 }
 
-fragment FullType on __Type {
-    kind
-    name
-    description
-    fields(includeDeprecated: true) {
-    name
-    description
-    args {
-        ...InputValue
-    }
-    type {
-        ...TypeRef
-    }
-    isDeprecated
-    deprecationReason
-    }
-    inputFields {
-    ...InputValue
-    }
-    interfaces {
-    ...TypeRef
-    }
-    enumValues(includeDeprecated: true) {
-    name
-    description
-    isDeprecated
-    deprecationReason
-    }
-    possibleTypes {
-    ...TypeRef
-    }
-}
+export function getIntrospectionQuery(options?: IntrospectionOptions): string;
 
-fragment InputValue on __InputValue {
-    name
-    description
-    type { ...TypeRef }
-    defaultValue
-}
-
-fragment TypeRef on __Type {
-    kind
-    name
-    ofType {
-    kind
-    name
-    ofType {
-        kind
-        name
-        ofType {
-        kind
-        name
-        ofType {
-            kind
-            name
-            ofType {
-            kind
-            name
-            ofType {
-                kind
-                name
-                ofType {
-                kind
-                name
-                }
-            }
-            }
-        }
-        }
-    }
-    }
-}
-*/
 export const introspectionQuery: string;
 
 export interface IntrospectionQuery {
-    __schema: IntrospectionSchema;
+    readonly __schema: IntrospectionSchema;
 }
 
 export interface IntrospectionSchema {
-    queryType: IntrospectionNamedTypeRef;
-    mutationType?: IntrospectionNamedTypeRef;
-    subscriptionType?: IntrospectionNamedTypeRef;
-    types: IntrospectionType[];
-    directives: IntrospectionDirective[];
+    readonly queryType: IntrospectionNamedTypeRef<IntrospectionObjectType>;
+    readonly mutationType: IntrospectionNamedTypeRef<IntrospectionObjectType> | void;
+    readonly subscriptionType: IntrospectionNamedTypeRef<IntrospectionObjectType> | void;
+    readonly types: ReadonlyArray<IntrospectionType>;
+    readonly directives: ReadonlyArray<IntrospectionDirective>;
 }
 
 export type IntrospectionType =
@@ -115,92 +30,114 @@ export type IntrospectionType =
     | IntrospectionEnumType
     | IntrospectionInputObjectType;
 
+export type IntrospectionOutputType =
+    | IntrospectionScalarType
+    | IntrospectionObjectType
+    | IntrospectionInterfaceType
+    | IntrospectionUnionType
+    | IntrospectionEnumType;
+
+export type IntrospectionInputType = IntrospectionScalarType | IntrospectionEnumType | IntrospectionInputObjectType;
+
 export interface IntrospectionScalarType {
-    kind: "SCALAR";
-    name: string;
-    description?: string;
+    readonly kind: "SCALAR";
+    readonly name: string;
+    readonly description?: string | void;
 }
 
 export interface IntrospectionObjectType {
-    kind: "OBJECT";
-    name: string;
-    description?: string;
-    fields: IntrospectionField[];
-    interfaces: IntrospectionNamedTypeRef[];
+    readonly kind: "OBJECT";
+    readonly name: string;
+    readonly description?: string | void;
+    readonly fields: ReadonlyArray<IntrospectionField>;
+    readonly interfaces: ReadonlyArray<IntrospectionNamedTypeRef<IntrospectionInterfaceType>>;
 }
 
 export interface IntrospectionInterfaceType {
-    kind: "INTERFACE";
-    name: string;
-    description?: string;
-    fields: IntrospectionField[];
-    possibleTypes: IntrospectionNamedTypeRef[];
+    readonly kind: "INTERFACE";
+    readonly name: string;
+    readonly description?: string | void;
+    readonly fields: ReadonlyArray<IntrospectionField>;
+    readonly possibleTypes: ReadonlyArray<IntrospectionNamedTypeRef<IntrospectionObjectType>>;
 }
 
 export interface IntrospectionUnionType {
-    kind: "UNION";
-    name: string;
-    description?: string;
-    possibleTypes: IntrospectionNamedTypeRef[];
+    readonly kind: "UNION";
+    readonly name: string;
+    readonly description?: string | void;
+    readonly possibleTypes: ReadonlyArray<IntrospectionNamedTypeRef<IntrospectionObjectType>>;
 }
 
 export interface IntrospectionEnumType {
-    kind: "ENUM";
-    name: string;
-    description?: string;
-    enumValues: IntrospectionEnumValue[];
+    readonly kind: "ENUM";
+    readonly name: string;
+    readonly description?: string | void;
+    readonly enumValues: ReadonlyArray<IntrospectionEnumValue>;
 }
 
 export interface IntrospectionInputObjectType {
-    kind: "INPUT_OBJECT";
-    name: string;
-    description?: string;
-    inputFields: IntrospectionInputValue[];
+    readonly kind: "INPUT_OBJECT";
+    readonly name: string;
+    readonly description?: string | void;
+    readonly inputFields: ReadonlyArray<IntrospectionInputValue>;
 }
 
-export type IntrospectionTypeRef = IntrospectionNamedTypeRef | IntrospectionListTypeRef | IntrospectionNonNullTypeRef;
-
-export interface IntrospectionNamedTypeRef {
-    kind: string;
-    name: string;
+export interface IntrospectionListTypeRef<T extends IntrospectionTypeRef = IntrospectionTypeRef> {
+    readonly kind: "LIST";
+    readonly ofType: T;
 }
 
-export interface IntrospectionListTypeRef {
-    kind: "LIST";
-    ofType?: IntrospectionTypeRef;
+export interface IntrospectionNonNullTypeRef<T extends IntrospectionTypeRef = IntrospectionTypeRef> {
+    readonly kind: "NON_NULL";
+    readonly ofType: T;
 }
 
-export interface IntrospectionNonNullTypeRef {
-    kind: "NON_NULL";
-    ofType?: IntrospectionTypeRef;
+export type IntrospectionTypeRef =
+    | IntrospectionNamedTypeRef<IntrospectionType>
+    | IntrospectionListTypeRef<any>
+    | IntrospectionNonNullTypeRef<IntrospectionNamedTypeRef<IntrospectionType> | IntrospectionListTypeRef<any>>;
+
+export type IntrospectionOutputTypeRef =
+    | IntrospectionNamedTypeRef<IntrospectionOutputType>
+    | IntrospectionListTypeRef<any>
+    | IntrospectionNonNullTypeRef<IntrospectionNamedTypeRef<IntrospectionOutputType> | IntrospectionListTypeRef<any>>;
+
+export type IntrospectionInputTypeRef =
+    | IntrospectionNamedTypeRef<IntrospectionInputType>
+    | IntrospectionListTypeRef<any>
+    | IntrospectionNonNullTypeRef<IntrospectionNamedTypeRef<IntrospectionInputType> | IntrospectionListTypeRef<any>>;
+
+export interface IntrospectionNamedTypeRef<T extends IntrospectionType = IntrospectionType> {
+    readonly kind: T["kind"];
+    readonly name: string;
 }
 
 export interface IntrospectionField {
-    name: string;
-    description?: string;
-    args: IntrospectionInputValue[];
-    type: IntrospectionTypeRef;
-    isDeprecated: boolean;
-    deprecationReason?: string;
+    readonly name: string;
+    readonly description?: string | void;
+    readonly args: ReadonlyArray<IntrospectionInputValue>;
+    readonly type: IntrospectionOutputTypeRef;
+    readonly isDeprecated: boolean;
+    readonly deprecationReason?: string | void;
 }
 
 export interface IntrospectionInputValue {
-    name: string;
-    description?: string;
-    type: IntrospectionTypeRef;
-    defaultValue?: string;
+    readonly name: string;
+    readonly description?: string | void;
+    readonly type: IntrospectionInputTypeRef;
+    readonly defaultValue?: string | void;
 }
 
 export interface IntrospectionEnumValue {
-    name: string;
-    description?: string;
-    isDeprecated: boolean;
-    deprecationReason?: string;
+    readonly name: string;
+    readonly description?: string | void;
+    readonly isDeprecated: boolean;
+    readonly deprecationReason?: string | void;
 }
 
 export interface IntrospectionDirective {
-    name: string;
-    description?: string;
-    locations: DirectiveLocationEnum[];
-    args: IntrospectionInputValue[];
+    readonly name: string;
+    readonly description?: string | void;
+    readonly locations: ReadonlyArray<DirectiveLocationEnum>;
+    readonly args: ReadonlyArray<IntrospectionInputValue>;
 }

types/graphql/utilities/isValidJSValue.d.ts

@@ -1,8 +1,6 @@
 import { GraphQLInputType } from "../type/definition";
 
 /**
- * Given a JavaScript value and a GraphQL type, determine if the value will be
- * accepted for that type. This is primarily useful for validating the
- * runtime values of query variables.
+ * Deprecated. Use coerceValue() directly for richer information.
  */
 export function isValidJSValue(value: any, type: GraphQLInputType): string[];

types/graphql/utilities/isValidLiteralValue.d.ts

@@ -1,11 +1,10 @@
+import { GraphQLError } from "../error/GraphQLError";
 import { ValueNode } from "../language/ast";
 import { GraphQLInputType } from "../type/definition";
 
 /**
- * Utility for validators which determines if a value literal AST is valid given
- * an input type.
+ * Utility which determines if a value literal node is valid for an input type.
  *
- * Note that this only validates literal values, variables are assumed to
- * provide values of the correct type.
+ * Deprecated. Rely on validation for documents containing literal values.
  */
-export function isValidLiteralValue(type: GraphQLInputType, valueNode: ValueNode): string[];
+export function isValidLiteralValue(type: GraphQLInputType, valueNode: ValueNode): ReadonlyArray<GraphQLError>;

types/graphql/utilities/lexicographicSortSchema.d.ts

@@ -0,0 +1,6 @@
+import { GraphQLSchema } from "../type/schema";
+
+/**
+ * Sort GraphQLSchema.
+ */
+export function lexicographicSortSchema(schema: GraphQLSchema): GraphQLSchema;

types/graphql/utilities/schemaPrinter.d.ts

@@ -1,12 +1,19 @@
 import { GraphQLSchema } from "../type/schema";
-import { GraphQLType } from "../type/definition";
+import { GraphQLType, GraphQLNamedType } from "../type/definition";
 
-export interface PrinterOptions {
+export interface Options {
     commentDescriptions?: boolean;
 }
 
-export function printSchema(schema: GraphQLSchema, options?: PrinterOptions): string;
+/**
+ * Accepts options as a second argument:
+ *
+ *    - commentDescriptions:
+ *        Provide true to use preceding comments as the description.
+ *
+ */
+export function printSchema(schema: GraphQLSchema, options?: Options): string;
 
-export function printIntrospectionSchema(schema: GraphQLSchema, options?: PrinterOptions): string;
+export function printIntrospectionSchema(schema: GraphQLSchema, options?: Options): string;
 
-export function printType(type: GraphQLType, options?: PrinterOptions): string;
+export function printType(type: GraphQLNamedType, options?: Options): string;

types/graphql/utilities/separateOperations.d.ts

@@ -1,3 +1,9 @@
 import { DocumentNode, OperationDefinitionNode } from "../language/ast";
 
-export function separateOperations(documentAST: DocumentNode): { [operationName: string]: DocumentNode };
+/**
+ * separateOperations accepts a single AST document which may contain many
+ * operations and fragments and returns a collection of AST documents each of
+ * which contains a single operation as well the fragment definitions it
+ * refers to.
+ */
+export function separateOperations(documentAST: DocumentNode): { [key: string]: DocumentNode };

types/graphql/utilities/typeFromAST.d.ts

@@ -1,5 +1,16 @@
-import { TypeNode } from "../language/ast";
-import { GraphQLType, GraphQLNullableType } from "../type/definition";
+import { TypeNode, NamedTypeNode, ListTypeNode, NonNullTypeNode } from "../language/ast";
+import { GraphQLType, GraphQLNullableType, GraphQLNamedType, GraphQLList, GraphQLNonNull } from "../type/definition";
 import { GraphQLSchema } from "../type/schema";
 
-export function typeFromAST(schema: GraphQLSchema, typeNode: TypeNode): GraphQLType;
+/**
+ * Given a Schema and an AST node describing a type, return a GraphQLType
+ * definition which applies to that type. For example, if provided the parsed
+ * AST node for `[User]`, a GraphQLList instance will be returned, containing
+ * the type called "User" found in the schema. If a type called "User" is not
+ * found in the schema, then undefined will be returned.
+ */
+export function typeFromAST(schema: GraphQLSchema, typeNode: NamedTypeNode): GraphQLNamedType | undefined;
+
+export function typeFromAST(schema: GraphQLSchema, typeNode: ListTypeNode): GraphQLList<any> | undefined;
+
+export function typeFromAST(schema: GraphQLSchema, typeNode: NonNullTypeNode): GraphQLNonNull<any> | undefined;

types/graphql/utilities/valueFromAST.d.ts

@@ -1,10 +1,28 @@
 import { GraphQLInputType } from "../type/definition";
 import { ValueNode, VariableNode, ListValueNode, ObjectValueNode } from "../language/ast";
 
+/**
+ * Produces a JavaScript value given a GraphQL Value AST.
+ *
+ * A GraphQL type must be provided, which will be used to interpret different
+ * GraphQL Value literals.
+ *
+ * Returns `undefined` when the value could not be validly coerced according to
+ * the provided type.
+ *
+ * | GraphQL Value        | JSON Value    |
+ * | -------------------- | ------------- |
+ * | Input Object         | Object        |
+ * | List                 | Array         |
+ * | Boolean              | Boolean       |
+ * | String               | String        |
+ * | Int / Float          | Number        |
+ * | Enum Value           | Mixed         |
+ * | NullValue            | null          |
+ *
+ */
 export function valueFromAST(
-    valueNode: ValueNode,
+    valueNode: ValueNode | void,
     type: GraphQLInputType,
-    variables?: {
-        [key: string]: any;
-    }
+    variables?: { [key: string]: any } | void
 ): any;

types/graphql/utilities/valueFromASTUntyped.d.ts

@@ -0,0 +1,19 @@
+import { ValueNode } from "../language/ast";
+
+/**
+ * Produces a JavaScript value given a GraphQL Value AST.
+ *
+ * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value
+ * will reflect the provided GraphQL value AST.
+ *
+ * | GraphQL Value        | JavaScript Value |
+ * | -------------------- | ---------------- |
+ * | Input Object         | Object           |
+ * | List                 | Array            |
+ * | Boolean              | Boolean          |
+ * | String / Enum        | String           |
+ * | Int / Float          | Number           |
+ * | Null                 | null             |
+ *
+ */
+export function valueFromASTUntyped(valueNode: ValueNode, variables?: { [key: string]: any } | void): any;