graphql 14.5.0 → 14.5.4

package/error/GraphQLError.d.ts

@@ -1,8 +1,8 @@
 import Maybe from '../tsutils/Maybe';
-import { getLocation } from '../language';
+
 import { ASTNode } from '../language/ast';
 import { Source } from '../language/source';
-import { SourceLocation } from '../language/location';
+import { SourceLocation, getLocation } from '../language/location';
 
 /**
  * A GraphQLError describes an Error found during the parse, validate, or
@@ -11,6 +11,16 @@ import { SourceLocation } from '../language/location';
  * GraphQL document and/or execution result that correspond to the Error.
  */
 export class GraphQLError extends Error {
+  constructor(
+    message: string,
+    nodes?: ReadonlyArray<ASTNode> | ASTNode | undefined,
+    source?: Maybe<Source>,
+    positions?: Maybe<ReadonlyArray<number>>,
+    path?: Maybe<ReadonlyArray<string | number>>,
+    originalError?: Maybe<Error>,
+    extensions?: Maybe<{ [key: string]: any }>,
+  );
+
   /**
    * A message describing the Error for debugging purposes.
    *
@@ -47,6 +57,9 @@ export class GraphQLError extends Error {
 
   /**
    * The source GraphQL document corresponding to this error.
+   *
+   * Note that if this Error represents more than one node, the source may not
+   * represent nodes after the first node.
    */
   readonly source: Source | undefined;
 
@@ -65,14 +78,10 @@ export class GraphQLError extends Error {
    * Extension fields to add to the formatted error.
    */
   readonly extensions: { [key: string]: any } | undefined;
-
-  constructor(
-    message: string,
-    nodes?: ReadonlyArray<ASTNode> | ASTNode | undefined,
-    source?: Maybe<Source>,
-    positions?: Maybe<ReadonlyArray<number>>,
-    path?: Maybe<ReadonlyArray<string | number>>,
-    originalError?: Maybe<Error>,
-    extensions?: Maybe<{ [key: string]: any }>,
-  );
 }
+
+/**
+ * Prints a GraphQLError to a string, representing useful location information
+ * about the error's position in the source.
+ */
+export function printError(error: GraphQLError): string;

package/error/formatError.d.ts

@@ -1,5 +1,5 @@
-import { GraphQLError } from './GraphQLError';
 import { SourceLocation } from '../language/location';
+import { GraphQLError } from './GraphQLError';
 
 /**
  * Given a GraphQLError, format it according to the rules described by the

package/error/formatError.js

@@ -30,3 +30,6 @@ function formatError(error) {
     path: path
   };
 }
+/**
+ * @see https://github.com/graphql/graphql-spec/blob/master/spec/Section%207%20--%20Response.md#errors
+ */

package/error/formatError.js.flow

@@ -22,9 +22,31 @@ export function formatError(error: GraphQLError): GraphQLFormattedError {
     : { message, locations, path };
 }
 
+/**
+ * @see https://github.com/graphql/graphql-spec/blob/master/spec/Section%207%20--%20Response.md#errors
+ */
 export type GraphQLFormattedError = {|
+  /**
+   * A short, human-readable summary of the problem that **SHOULD NOT** change
+   * from occurrence to occurrence of the problem, except for purposes of
+   * localization.
+   */
   +message: string,
+  /**
+   * If an error can be associated to a particular point in the requested
+   * GraphQL document, it should contain a list of locations.
+   */
   +locations: $ReadOnlyArray<SourceLocation> | void,
+  /**
+   * If an error can be associated to a particular field in the GraphQL result,
+   * it _must_ contain an entry with the key `path` that details the path of
+   * the response field which experienced the error. This allows clients to
+   * identify whether a null result is intentional or caused by a runtime error.
+   */
   +path: $ReadOnlyArray<string | number> | void,
+  /**
+   * Reserved for implementors to extend the protocol however they see fit,
+   * and hence there are no additional restrictions on its contents.
+   */
   +extensions?: { [key: string]: mixed, ... },
 |};

package/error/formatError.mjs

@@ -21,3 +21,6 @@ export function formatError(error) {
     path: path
   };
 }
+/**
+ * @see https://github.com/graphql/graphql-spec/blob/master/spec/Section%207%20--%20Response.md#errors
+ */

package/error/index.d.ts

@@ -1,5 +1,4 @@
-export { GraphQLError } from './GraphQLError';
+export { GraphQLError, printError } from './GraphQLError';
 export { syntaxError } from './syntaxError';
 export { locatedError } from './locatedError';
-export { printError } from './printError';
 export { formatError, GraphQLFormattedError } from './formatError';

package/error/locatedError.d.ts

@@ -1,5 +1,5 @@
-import { GraphQLError } from './GraphQLError';
 import { ASTNode } from '../language/ast';
+import { GraphQLError } from './GraphQLError';
 
 /**
  * Given an arbitrary Error, presumably thrown while attempting to execute a

package/execution/execute.d.ts

@@ -1,13 +1,10 @@
 import Maybe from '../tsutils/Maybe';
-import { GraphQLError, locatedError } from '../error';
-import { GraphQLSchema } from '../type/schema';
-import {
-  GraphQLField,
-  GraphQLFieldResolver,
-  ResponsePath,
-  GraphQLObjectType,
-  GraphQLResolveInfo,
-} from '../type/definition';
+import { PromiseOrValue } from '../jsutils/PromiseOrValue';
+import { Path, addPath, pathToArray } from '../jsutils/Path';
+
+import { GraphQLError } from '../error/GraphQLError';
+import { locatedError } from '../error/locatedError';
+
 import {
   DirectiveNode,
   DocumentNode,
@@ -17,7 +14,14 @@ import {
   InlineFragmentNode,
   FragmentDefinitionNode,
 } from '../language/ast';
-import { PromiseOrValue } from '../jsutils/PromiseOrValue';
+import { GraphQLSchema } from '../type/schema';
+import {
+  GraphQLField,
+  GraphQLFieldResolver,
+  GraphQLResolveInfo,
+  GraphQLTypeResolver,
+  GraphQLObjectType,
+} from '../type/definition';
 
 /**
  * Data that must be available at all points during query execution.
@@ -46,9 +50,10 @@ export interface ExecutionResultDataDefault {
  *   - `errors` is included when any errors occurred as a non-empty array.
  *   - `data` is the result of a successful execution of the query.
  */
+// TS_SPECIFIC: TData and ExecutionResultDataDefault
 export interface ExecutionResult<TData = ExecutionResultDataDefault> {
   errors?: ReadonlyArray<GraphQLError>;
-  data?: TData;
+  data?: TData | null;
 }
 
 export type ExecutionArgs = {
@@ -59,6 +64,7 @@ export type ExecutionArgs = {
   variableValues?: Maybe<{ [key: string]: any }>;
   operationName?: Maybe<string>;
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
 };
 
 /**
@@ -84,26 +90,9 @@ export function execute<TData = ExecutionResultDataDefault>(
   variableValues?: Maybe<{ [key: string]: any }>,
   operationName?: Maybe<string>,
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>,
+  typeResolver?: Maybe<GraphQLTypeResolver<any, any>>,
 ): PromiseOrValue<ExecutionResult<TData>>;
 
-/**
- * Given a ResponsePath (found in the `path` entry in the information provided
- * as the last argument to a field resolver), return an Array of the path keys.
- */
-export function responsePathAsArray(
-  path: ResponsePath,
-): ReadonlyArray<string | number>;
-
-/**
- * Given a ResponsePath and a key, return a new ResponsePath containing the
- * new key.
-
- */
-export function addPath(
-  prev: ResponsePath | undefined,
-  key: string | number,
-): { prev: ResponsePath | undefined; key: string | number };
-
 /**
  * Essential assertions before executing to provide developer feedback for
  * improper use of the GraphQL library.
@@ -128,6 +117,7 @@ export function buildExecutionContext(
   rawVariableValues: Maybe<{ [key: string]: any }>,
   operationName: Maybe<string>,
   fieldResolver: Maybe<GraphQLFieldResolver<any, any>>,
+  typeResolver?: Maybe<GraphQLTypeResolver<any, any>>,
 ): ReadonlyArray<GraphQLError> | ExecutionContext;
 
 /**
@@ -151,11 +141,12 @@ export function buildResolveInfo(
   fieldDef: GraphQLField<any, any>,
   fieldNodes: ReadonlyArray<FieldNode>,
   parentType: GraphQLObjectType,
-  path: ResponsePath,
+  path: Path,
 ): GraphQLResolveInfo;
 
 // Isolates the "ReturnOrAbrupt" behavior to not de-opt the `resolveField`
 // function. Returns the result of resolveFn or the abrupt-return Error object.
+// TS_SPECIFIC: TSource
 export function resolveFieldValueOrError<TSource>(
   exeContext: ExecutionContext,
   fieldDef: GraphQLField<TSource, any>,
@@ -165,6 +156,18 @@ export function resolveFieldValueOrError<TSource>(
   info: GraphQLResolveInfo,
 ): Error | any;
 
+/**
+ * If a resolveType function is not given, then a default resolve behavior is
+ * used which attempts two strategies:
+ *
+ * First, See if the provided value has a `__typename` field defined, if so, use
+ * that value as name of the resolved type.
+ *
+ * Otherwise, test each possible type for the abstract type by calling
+ * isTypeOf for the object being coerced, returning the first type that matches.
+ */
+export const defaultTypeResolver: GraphQLTypeResolver<any, any>;
+
 /**
  * If a resolve function is not given, then a default resolve behavior is used
  * which takes the property of the source object of the same name as the field

package/execution/index.d.ts

@@ -1,7 +1,9 @@
+export { pathToArray as responsePathAsArray } from '../jsutils/Path';
+
 export {
   execute,
   defaultFieldResolver,
-  responsePathAsArray,
+  defaultTypeResolver,
   ExecutionArgs,
   ExecutionResult,
 } from './execute';

package/execution/values.d.ts

@@ -1,22 +1,22 @@
 import Maybe from '../tsutils/Maybe';
 import { GraphQLError } from '../error/GraphQLError';
-import {
-  GraphQLInputType,
-  GraphQLField,
-  GraphQLArgument,
-} from '../type/definition';
-import { GraphQLDirective } from '../type/directives';
-import { GraphQLSchema } from '../type/schema';
 import {
   FieldNode,
   DirectiveNode,
   VariableDefinitionNode,
 } from '../language/ast';
 
-interface CoercedVariableValues {
-  errors: ReadonlyArray<GraphQLError> | undefined;
-  coerced: { [key: string]: any } | undefined;
-}
+import { GraphQLDirective } from '../type/directives';
+import { GraphQLSchema } from '../type/schema';
+import {
+  GraphQLInputType,
+  GraphQLField,
+  GraphQLArgument,
+} from '../type/definition';
+
+type CoercedVariableValues =
+  | { errors: ReadonlyArray<GraphQLError>; coerced?: never }
+  | { errors?: never; coerced: { [key: string]: any } };
 
 /**
  * Prepares an object map of variableValues of the correct type based on the
@@ -31,6 +31,7 @@ export function getVariableValues(
   schema: GraphQLSchema,
   varDefNodes: VariableDefinitionNode[],
   inputs: { [key: string]: any },
+  options?: { maxErrors?: number },
 ): CoercedVariableValues;
 
 /**

package/graphql.d.ts

@@ -1,7 +1,7 @@
 import Maybe from './tsutils/Maybe';
 import { Source } from './language/source';
-import { GraphQLFieldResolver } from './type/definition';
 import { GraphQLSchema } from './type/schema';
+import { GraphQLFieldResolver, GraphQLTypeResolver } from './type/definition';
 import {
   ExecutionResult,
   ExecutionResultDataDefault,
@@ -44,12 +44,13 @@ import {
  */
 export interface GraphQLArgs {
   schema: GraphQLSchema;
-  source: Source | string;
+  source: string | Source;
   rootValue?: any;
   contextValue?: any;
   variableValues?: Maybe<{ [key: string]: any }>;
   operationName?: Maybe<string>;
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
 }
 
 export function graphql<TData = ExecutionResultDataDefault>(
@@ -63,6 +64,7 @@ export function graphql<TData = ExecutionResultDataDefault>(
   variableValues?: Maybe<{ [key: string]: any }>,
   operationName?: Maybe<string>,
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>,
+  typeResolver?: Maybe<GraphQLTypeResolver<any, any>>,
 ): Promise<ExecutionResult<TData>>;
 
 /**
@@ -82,4 +84,5 @@ export function graphqlSync<TData = ExecutionResultDataDefault>(
   variableValues?: Maybe<{ [key: string]: any }>,
   operationName?: Maybe<string>,
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>,
+  typeResolver?: Maybe<GraphQLTypeResolver<any, any>>,
 ): ExecutionResult<TData>;

package/index.d.ts

@@ -1,12 +1,40 @@
 // TypeScript Version: 2.6
 
+/**
+ * GraphQL.js provides a reference implementation for the GraphQL specification
+ * but is also a useful utility for operating on GraphQL files and building
+ * sophisticated tools.
+ *
+ * This primary module exports a general purpose function for fulfilling all
+ * steps of the GraphQL specification in a single operation, but also includes
+ * utilities for every part of the GraphQL specification:
+ *
+ *   - Parsing the GraphQL language.
+ *   - Building a GraphQL type schema.
+ *   - Validating a GraphQL request against a type schema.
+ *   - Executing a GraphQL request against a type schema.
+ *
+ * This also includes utility functions for operating on GraphQL types and
+ * GraphQL documents to facilitate building tools.
+ *
+ * You may also import from each sub-directory directly. For example, the
+ * following two import statements are equivalent:
+ *
+ *     import { parse } from 'graphql';
+ *     import { parse } from 'graphql/language';
+ */
+
+// The GraphQL.js version info.
+export { version, versionInfo } from './version';
+
 // The primary entry point into fulfilling a GraphQL request.
-export { graphql, graphqlSync, GraphQLArgs } from './graphql';
+export { GraphQLArgs, graphql, graphqlSync } from './graphql';
 
 // Create and operate on GraphQL type definitions and schema.
 export {
-  GraphQLSchema,
   // Definitions
+  GraphQLSchema,
+  GraphQLDirective,
   GraphQLScalarType,
   GraphQLObjectType,
   GraphQLInterfaceType,
@@ -15,10 +43,7 @@ export {
   GraphQLInputObjectType,
   GraphQLList,
   GraphQLNonNull,
-  GraphQLDirective,
-  // "Enum" of Type Kinds
-  TypeKind,
-  // Scalars
+  // Standard GraphQL Scalars
   specifiedScalarTypes,
   GraphQLInt,
   GraphQLFloat,
@@ -30,12 +55,10 @@ export {
   GraphQLIncludeDirective,
   GraphQLSkipDirective,
   GraphQLDeprecatedDirective,
+  // "Enum" of Type Kinds
+  TypeKind,
   // Constant Deprecation Reason
   DEFAULT_DEPRECATION_REASON,
-  // Meta-field definitions.
-  SchemaMetaFieldDef,
-  TypeMetaFieldDef,
-  TypeNameMetaFieldDef,
   // GraphQL Types for introspection.
   introspectionTypes,
   __Schema,
@@ -46,6 +69,10 @@ export {
   __InputValue,
   __EnumValue,
   __TypeKind,
+  // Meta-field definitions.
+  SchemaMetaFieldDef,
+  TypeMetaFieldDef,
+  TypeNameMetaFieldDef,
   // Predicates
   isSchema,
   isDirective,
@@ -72,6 +99,8 @@ export {
   isIntrospectionType,
   isSpecifiedDirective,
   // Assertions
+  assertSchema,
+  assertDirective,
   assertType,
   assertScalarType,
   assertObjectType,
@@ -95,7 +124,9 @@ export {
   // Validate GraphQL schema.
   validateSchema,
   assertValidSchema,
-  // type
+} from './type';
+
+export {
   GraphQLType,
   GraphQLInputType,
   GraphQLOutputType,
@@ -107,6 +138,7 @@ export {
   GraphQLNamedType,
   Thunk,
   GraphQLSchemaConfig,
+  GraphQLDirectiveConfig,
   GraphQLArgument,
   GraphQLArgumentConfig,
   GraphQLEnumTypeConfig,
@@ -132,7 +164,6 @@ export {
   GraphQLScalarTypeConfig,
   GraphQLTypeResolver,
   GraphQLUnionTypeConfig,
-  GraphQLDirectiveConfig,
   GraphQLScalarSerializer,
   GraphQLScalarValueParser,
   GraphQLScalarLiteralParser,
@@ -142,6 +173,12 @@ export {
 export {
   Source,
   getLocation,
+  // Print source location
+  printLocation,
+  printSourceLocation,
+  // Lex
+  createLexer,
+  TokenKind,
   // Parse
   parse,
   parseValue,
@@ -153,10 +190,9 @@ export {
   visitInParallel,
   visitWithTypeInfo,
   getVisitFn,
+  BREAK,
   Kind,
-  TokenKind,
   DirectiveLocation,
-  BREAK,
   // Predicates
   isDefinitionNode,
   isExecutableDefinitionNode,
@@ -167,20 +203,26 @@ export {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
-  // type
+} from './language';
+
+export {
   Lexer,
   ParseOptions,
   SourceLocation,
+  Location,
+  Token,
+  TokenKindEnum,
+  KindEnum,
+  DirectiveLocationEnum,
   // Visitor utilities
   ASTVisitor,
   Visitor,
   VisitFn,
   VisitorKeyMap,
   // AST nodes
-  Location,
-  Token,
   ASTNode,
   ASTKindToNode,
+  // Each kind of AST node
   NameNode,
   DocumentNode,
   DefinitionNode,
@@ -234,25 +276,26 @@ export {
   UnionTypeExtensionNode,
   EnumTypeExtensionNode,
   InputObjectTypeExtensionNode,
-  KindEnum,
-  TokenKindEnum,
-  DirectiveLocationEnum,
 } from './language';
 
 // Execute GraphQL queries.
 export {
   execute,
   defaultFieldResolver,
+  defaultTypeResolver,
   responsePathAsArray,
   getDirectiveValues,
-  // type
   ExecutionArgs,
   ExecutionResult,
 } from './execution';
 
-export { subscribe, createSourceEventStream } from './subscription';
+export {
+  subscribe,
+  createSourceEventStream,
+  SubscriptionArgs,
+} from './subscription';
 
-// Validate GraphQL queries.
+// Validate GraphQL documents.
 export {
   validate,
   ValidationContext,
@@ -284,13 +327,16 @@ export {
   ValuesOfCorrectTypeRule,
   VariablesAreInputTypesRule,
   VariablesInAllowedPositionRule,
+  ValidationRule,
 } from './validation';
 
-// Create and format GraphQL errors.
+// Create, format, and print GraphQL errors.
 export {
   GraphQLError,
-  formatError,
+  syntaxError,
+  locatedError,
   printError,
+  formatError,
   GraphQLFormattedError,
 } from './error';
 
@@ -299,13 +345,13 @@ export {
   // Produce the GraphQL query recommended for a full schema introspection.
   // Accepts optional IntrospectionOptions.
   getIntrospectionQuery,
-  // @deprecated: use getIntrospectionQuery - will be removed in v15
+  // @deprecated: use getIntrospectionQuery - will be removed in v15.
   introspectionQuery,
-  // Gets the target Operation from a Document
+  // Gets the target Operation from a Document.
   getOperationAST,
   // Gets the Type for the target Operation AST.
   getOperationRootType,
-  // Convert a GraphQLSchema to an IntrospectionQuery
+  // Convert a GraphQLSchema to an IntrospectionQuery.
   introspectionFromSchema,
   // Build a GraphQLSchema from an introspection result.
   buildClientSchema,
@@ -314,7 +360,7 @@ export {
   // Build a GraphQLSchema from a GraphQL schema language document.
   buildSchema,
   // @deprecated: Get the description from a schema AST node and supports legacy
-  // syntax for specifying descriptions - will be removed in v16
+  // syntax for specifying descriptions - will be removed in v16.
   getDescription,
   // Extends an existing GraphQLSchema from a parsed GraphQL Schema
   // language AST.
@@ -323,11 +369,11 @@ export {
   lexicographicSortSchema,
   // Print a GraphQLSchema to GraphQL Schema language.
   printSchema,
+  // Print a GraphQLType to GraphQL Schema language.
+  printType,
   // Prints the built-in introspection schema in the Schema Language
   // format.
   printIntrospectionSchema,
-  // Print a GraphQLType to GraphQL Schema language.
-  printType,
   // Create a GraphQLType from a GraphQL language AST.
   typeFromAST,
   // Create a JavaScript value from a GraphQL language AST with a Type.
@@ -340,8 +386,10 @@ export {
   // the GraphQL type system.
   TypeInfo,
   // Coerces a JavaScript value to a GraphQL type, or produces errors.
+  coerceInputValue,
+  // @deprecated use coerceInputValue - will be removed in v15
   coerceValue,
-  // @deprecated use coerceValue - will be removed in v15
+  // @deprecated use coerceInputValue - will be removed in v15
   isValidJSValue,
   // @deprecated use validation - will be removed in v15
   isValidLiteralValue,
@@ -349,6 +397,9 @@ export {
   concatAST,
   // Separates an AST into an AST per Operation.
   separateOperations,
+  // Strips characters that are not significant to the validity or execution
+  // of a GraphQL document.
+  stripIgnoredCharacters,
   // Comparators for types
   isEqualType,
   isTypeSubTypeOf,
@@ -358,36 +409,38 @@ export {
   // Determine if a string is a valid GraphQL name.
   isValidNameError,
   // Compares two GraphQLSchemas and detects breaking changes.
-  findBreakingChanges,
-  findDangerousChanges,
   BreakingChangeType,
   DangerousChangeType,
+  findBreakingChanges,
+  findDangerousChanges,
   // Report all deprecated usage within a GraphQL document.
   findDeprecatedUsages,
-  // type
-  BuildSchemaOptions,
-  BreakingChange,
-  DangerousChange,
+} from './utilities';
+
+export {
   IntrospectionOptions,
-  IntrospectionDirective,
+  IntrospectionQuery,
+  IntrospectionSchema,
+  IntrospectionType,
+  IntrospectionInputType,
+  IntrospectionOutputType,
+  IntrospectionScalarType,
+  IntrospectionObjectType,
+  IntrospectionInterfaceType,
+  IntrospectionUnionType,
   IntrospectionEnumType,
-  IntrospectionEnumValue,
-  IntrospectionField,
   IntrospectionInputObjectType,
-  IntrospectionInputType,
+  IntrospectionTypeRef,
   IntrospectionInputTypeRef,
-  IntrospectionInputValue,
-  IntrospectionInterfaceType,
-  IntrospectionListTypeRef,
+  IntrospectionOutputTypeRef,
   IntrospectionNamedTypeRef,
+  IntrospectionListTypeRef,
   IntrospectionNonNullTypeRef,
-  IntrospectionObjectType,
-  IntrospectionOutputType,
-  IntrospectionOutputTypeRef,
-  IntrospectionQuery,
-  IntrospectionScalarType,
-  IntrospectionSchema,
-  IntrospectionType,
-  IntrospectionTypeRef,
-  IntrospectionUnionType,
+  IntrospectionField,
+  IntrospectionInputValue,
+  IntrospectionEnumValue,
+  IntrospectionDirective,
+  BuildSchemaOptions,
+  BreakingChange,
+  DangerousChange,
 } from './utilities';