graphql 16.14.0 → 16.14.1

package/execution/execute.js

@@ -49,10 +49,14 @@ var _collectFields = require('./collectFields.js');
 
 var _values = require('./values.js');
 
+/** @category Execution */
+
 /**
  * A memoized collection of relevant subfields with regard to the return
  * type. Memoizing ensures the subfields are not repeatedly calculated, which
  * saves overhead when resolving lists of values.
+ *
+ * @internal
  */
 const collectSubfields = (0, _memoize.memoize3)(
   (exeContext, returnType, fieldNodes) =>
@@ -89,11 +93,10 @@ const collectSubfields = (0, _memoize.memoize3)(
  *
  * Namely, schema of the type system that is currently executing,
  * and the fragments defined in the query document
- */
-
-/**
+ *
  * @internal
  */
+
 class CollectedErrors {
   constructor() {
     this._errorPositions = new Set();
@@ -133,11 +136,9 @@ class CollectedErrors {
   }
 }
 /**
- * The result of GraphQL execution.
- *
- *   - `errors` is included when any errors occurred as a non-empty array.
- *   - `data` is the result of a successful execution of the query.
- *   - `extensions` is reserved for adding non-standard properties.
+ * Represents the response produced by executing a GraphQL operation.
+ * @typeParam TData - Shape of the execution data payload.
+ * @typeParam TExtensions - Shape of the extensions payload.
  */
 
 /**
@@ -149,6 +150,139 @@ class CollectedErrors {
  *
  * If the arguments to this function do not result in a legal execution context,
  * a GraphQLError will be thrown immediately explaining the invalid input.
+ *
+ * Field errors are collected into the response instead of rejecting the
+ * returned promise. Only the field that produced the error and its descendants
+ * are omitted; sibling fields continue to execute. Errors from fields of
+ * non-null type may propagate to the nearest nullable parent, which can be the
+ * entire response data.
+ * @param args - The arguments used to perform the operation.
+ * @returns A completed execution result, or a promise resolving to one when execution is asynchronous.
+ * @example
+ * ```ts
+ * // Execute an asynchronous operation with variables.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query ($name: String!) { greeting(name: $name) }'),
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query Viewer { viewer { __typename name } }'),
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   operationName: 'Viewer',
+ *   fieldResolver: (source, _args, contextValue, info) => {
+ *     contextValue.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows how resolver errors become field errors in the result.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     broken: String
+ *   }
+ * `);
+ * const document = parse('{ broken }');
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     broken: () => {
+ *       throw new Error('Resolver failed.');
+ *     },
+ *   },
+ * });
+ *
+ * result.data.broken; // => null
+ * result.errors[0].message; // => 'Resolver failed.'
+ * ```
+ * @example
+ * ```ts
+ * // This variant limits how many variable coercion errors are reported.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   variableValues: {
+ *     first: { stars: 'bad' },
+ *     second: { stars: 'also bad' },
+ *   },
+ *   options: { maxCoercionErrors: 1 },
+ * });
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
 function execute(args) {
   // Temporary for v15 to v16 migration. Remove in v17
@@ -168,17 +302,7 @@ function execute(args) {
     return {
       errors: exeContext,
     };
-  } // Return a Promise that will eventually resolve to the data described by
-  // The "Response" section of the GraphQL specification.
-  //
-  // If errors are encountered while executing a GraphQL field, only that
-  // field and its descendants will be omitted, and sibling fields will still
-  // be executed. An execution which encounters errors will still result in a
-  // resolved Promise.
-  //
-  // Errors from sub-fields of a NonNull type may propagate to the top level,
-  // at which point we still log the error and null the parent field, which
-  // in this case is the entire response.
+  }
 
   try {
     const { operation } = exeContext;
@@ -204,6 +328,53 @@ function execute(args) {
  * Also implements the "Executing requests" section of the GraphQL specification.
  * However, it guarantees to complete synchronously (or throw an error) assuming
  * that all field resolvers are also synchronous.
+ * @param args - The arguments used to perform the operation.
+ * @returns Completed execution output for a synchronous operation.
+ * @example
+ * ```ts
+ * // Execute an operation synchronously when all resolvers are synchronous.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ greeting }');
+ *
+ * const result = executeSync({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     greeting: 'Hello',
+ *   },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows executeSync throwing when a resolver returns a promise.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * executeSync({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: {
+ *     greeting: async () => 'Hello',
+ *   },
+ * }); // throws an error
+ * ```
  */
 
 function executeSync(args) {
@@ -218,6 +389,8 @@ function executeSync(args) {
 /**
  * Given a completed execution context and data, build the `{ errors, data }`
  * response defined by the "Response" section of the GraphQL specification.
+ *
+ * @internal
  */
 
 function buildResponse(data, errors) {
@@ -232,7 +405,9 @@ function buildResponse(data, errors) {
 }
 /**
  * Essential assertions before executing to provide developer feedback for
- * improper use of the GraphQL library.
+ * improper use of the GraphQL library. This deprecated internal helper will be
+ * removed in v17; call `assertValidSchema()` and rely on TypeScript checks
+ * instead.
  *
  * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
  * @internal
@@ -374,6 +549,8 @@ function buildExecutionContext(args) {
 }
 /**
  * Implements the "Executing operations" section of the spec.
+ *
+ * @internal
  */
 
 function executeOperation(exeContext, operation, rootValue) {
@@ -419,6 +596,8 @@ function executeOperation(exeContext, operation, rootValue) {
 /**
  * Implements the "Executing selection sets" section of the spec
  * for fields that must be executed serially.
+ *
+ * @internal
  */
 
 function executeFieldsSerially(
@@ -460,6 +639,8 @@ function executeFieldsSerially(
 /**
  * Implements the "Executing selection sets" section of the spec
  * for fields that may be executed in parallel.
+ *
+ * @internal
  */
 
 function executeFields(exeContext, parentType, sourceValue, path, fields) {
@@ -509,6 +690,8 @@ function executeFields(exeContext, parentType, sourceValue, path, fields) {
  * In particular, this function figures out the value that the field returns by
  * calling its resolve function, then calls completeValue to complete promises,
  * serialize scalars, or execute the sub-selection-set for objects.
+ *
+ * @internal
  */
 
 function executeField(exeContext, parentType, source, fieldNodes, path) {
@@ -588,9 +771,7 @@ function executeField(exeContext, parentType, source, fieldNodes, path) {
     return handleFieldError(error, returnType, path, exeContext);
   }
 }
-/**
- * @internal
- */
+/** @internal */
 
 function buildResolveInfo(exeContext, fieldDef, fieldNodes, parentType, path) {
   // The resolve function's optional fourth argument is a collection of
@@ -640,6 +821,8 @@ function handleFieldError(error, returnType, path, exeContext) {
  *
  * Otherwise, the field type expects a sub-selection set, and will complete the
  * value by executing all sub-selections.
+ *
+ * @internal
  */
 
 function completeValue(exeContext, returnType, fieldNodes, info, path, result) {
@@ -723,6 +906,8 @@ function completeValue(exeContext, returnType, fieldNodes, info, path, result) {
 /**
  * Complete a list value by completing each item in the list with the
  * inner type
+ *
+ * @internal
  */
 
 function completeListValue(
@@ -801,6 +986,8 @@ function completeListValue(
 /**
  * Complete a Scalar or Enum by serializing to a valid value, returning
  * null if serialization is not possible.
+ *
+ * @internal
  */
 
 function completeLeafValue(returnType, result) {
@@ -821,6 +1008,8 @@ function completeLeafValue(returnType, result) {
 /**
  * Complete a value of an abstract type by determining the runtime object type
  * of that value, then complete the value for that type.
+ *
+ * @internal
  */
 
 function completeAbstractValue(
@@ -941,6 +1130,8 @@ function ensureValidRuntimeType(
 }
 /**
  * Complete an Object value by executing all sub-selections.
+ *
+ * @internal
  */
 
 function completeObjectValue(