graphql 16.14.0 → 16.14.1

package/execution/execute.mjs

@@ -1,3 +1,4 @@
+/** @category Execution */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
@@ -34,6 +35,8 @@ import { getArgumentValues, getVariableValues } from './values.mjs';
  * 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 = memoize3((exeContext, returnType, fieldNodes) =>
@@ -70,11 +73,10 @@ const collectSubfields = memoize3((exeContext, returnType, fieldNodes) =>
  *
  * 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();
@@ -114,11 +116,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.
  */
 
 /**
@@ -130,6 +130,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/
+ * ```
  */
 export function execute(args) {
   // Temporary for v15 to v16 migration. Remove in v17
@@ -149,17 +282,7 @@ export 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;
@@ -185,6 +308,53 @@ export 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
+ * ```
  */
 
 export function executeSync(args) {
@@ -199,6 +369,8 @@ export 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) {
@@ -213,7 +385,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
@@ -355,6 +529,8 @@ export function buildExecutionContext(args) {
 }
 /**
  * Implements the "Executing operations" section of the spec.
+ *
+ * @internal
  */
 
 function executeOperation(exeContext, operation, rootValue) {
@@ -400,6 +576,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(
@@ -441,6 +619,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) {
@@ -490,6 +670,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) {
@@ -561,9 +743,7 @@ function executeField(exeContext, parentType, source, fieldNodes, path) {
     return handleFieldError(error, returnType, path, exeContext);
   }
 }
-/**
- * @internal
- */
+/** @internal */
 
 export function buildResolveInfo(
   exeContext,
@@ -619,6 +799,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) {
@@ -701,6 +883,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(
@@ -775,6 +959,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) {
@@ -792,6 +978,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(
@@ -911,6 +1099,8 @@ function ensureValidRuntimeType(
 }
 /**
  * Complete an Object value by executing all sub-selections.
+ *
+ * @internal
  */
 
 function completeObjectValue(

package/execution/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Execute GraphQL operations and produce GraphQL execution results.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { pathToArray as responsePathAsArray } from '../jsutils/Path';
 export {
   execute,

package/execution/index.mjs

@@ -1,3 +1,9 @@
+/**
+ * Execute GraphQL operations and produce GraphQL execution results.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { pathToArray as responsePathAsArray } from '../jsutils/Path.mjs';
 export {
   execute,

package/execution/mapAsyncIterator.d.ts

@@ -2,6 +2,8 @@ import type { PromiseOrValue } from '../jsutils/PromiseOrValue';
 /**
  * Given an AsyncIterable and a callback function, return an AsyncIterator
  * which produces values mapped via calling the callback function.
+ *
+ * @internal
  */
 export declare function mapAsyncIterator<T, U, R = undefined>(
   iterable: AsyncGenerator<T, R, void> | AsyncIterable<T>,

package/execution/mapAsyncIterator.js

@@ -8,6 +8,8 @@ exports.mapAsyncIterator = mapAsyncIterator;
 /**
  * Given an AsyncIterable and a callback function, return an AsyncIterator
  * which produces values mapped via calling the callback function.
+ *
+ * @internal
  */
 function mapAsyncIterator(iterable, callback) {
   const iterator = iterable[Symbol.asyncIterator]();

package/execution/mapAsyncIterator.mjs

@@ -1,6 +1,8 @@
 /**
  * Given an AsyncIterable and a callback function, return an AsyncIterator
  * which produces values mapped via calling the callback function.
+ *
+ * @internal
  */
 export function mapAsyncIterator(iterable, callback) {
   const iterator = iterable[Symbol.asyncIterator]();

package/execution/subscribe.d.ts

@@ -1,3 +1,4 @@
+/** @category Subscriptions */
 import type { Maybe } from '../jsutils/Maybe';
 import type { DocumentNode } from '../language/ast';
 import type { GraphQLFieldResolver } from '../type/definition';
@@ -6,7 +7,7 @@ import type { ExecutionArgs, ExecutionResult } from './execute';
 /**
  * Implements the "Subscribe" algorithm described in the GraphQL specification.
  *
- * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * Returns a Promise that resolves to either an AsyncIterator (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
  * other arguments to this function are invalid, or if the resolved event stream
  * is not an async iterable.
@@ -22,7 +23,122 @@ import type { ExecutionArgs, ExecutionResult } from './execute';
  * If the operation succeeded, the promise resolves to an AsyncIterator, which
  * yields a stream of ExecutionResults representing the response stream.
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * Each payload yielded by the source event stream is executed with the payload
+ * as the root value. This maps the subscription source stream into the response
+ * stream described by the GraphQL specification.
+ *
+ * Accepts an object with named arguments.
+ * @param args - The arguments used to perform the operation.
+ * @returns A source stream mapped to execution results, or an execution result
+ * containing subscription errors.
+ * @example
+ * ```ts
+ * // Use a same-named rootValue function to provide the source event stream.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies events through a custom subscribeFieldResolver.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* defaultGreetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * async function* frenchGreetings() {
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting(locale: String): String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse(
+ *     'subscription Greeting($locale: String) { greeting(locale: $locale) }',
+ *   ),
+ *   rootValue: {
+ *     greeting: (args, contextValue) => {
+ *       const locale = args.locale ?? contextValue.defaultLocale;
+ *       return locale === 'fr' ? frenchGreetings() : defaultGreetings();
+ *     },
+ *   },
+ *   contextValue: { defaultLocale: 'fr' },
+ *   variableValues: { locale: 'fr' },
+ *   operationName: 'Greeting',
+ *   subscribeFieldResolver: (rootValue, args, contextValue, info) => {
+ *     args.locale; // => 'fr'
+ *     return rootValue[info.fieldName](args, contextValue);
+ *   },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Bonjour' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows the error result when the schema has no subscription root.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('errors' in result);
+ *
+ * result.errors[0].message; // => 'Schema is not configured to execute subscription operation.'
+ * ```
  */
 export declare function subscribe(
   args: ExecutionArgs,
@@ -31,7 +147,7 @@ export declare function subscribe(
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
  *
- * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * Returns a Promise that resolves to either an AsyncIterable (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
  * other arguments to this function are invalid, or if the resolved event stream
  * is not an async iterable.
@@ -40,7 +156,7 @@ export declare function subscribe(
  * compliant subscription, a GraphQL Response (ExecutionResult) with
  * descriptive errors and no data will be returned.
  *
- * If the the source stream could not be created due to faulty subscription
+ * If the source stream could not be created due to faulty subscription
  * resolver logic or underlying systems, the promise will resolve to a single
  * ExecutionResult containing `errors` and no `data`.
  *
@@ -54,11 +170,85 @@ export declare function subscribe(
  * different process or machine than the stateless GraphQL execution engine,
  * or otherwise separating these two steps. For more on this, see the
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
+ * @param args - The arguments used to perform the operation.
+ * @returns The source event stream, or an execution result containing subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const stream = await createSourceEventStream({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
  */
 export declare function createSourceEventStream(
   args: ExecutionArgs,
 ): Promise<AsyncIterable<unknown> | ExecutionResult>;
-/** @deprecated will be removed in next major version in favor of named arguments */
+/**
+ * Creates the source event stream for a subscription operation using the legacy
+ * positional argument overload. This deprecated overload will be removed in the
+ * next major version; use the args object overload instead.
+ * @param schema - GraphQL schema to use.
+ * @param document - The parsed GraphQL document containing the subscription
+ * operation.
+ * @param rootValue - Initial root value passed to the subscription resolver.
+ * @param contextValue - Application context value passed to resolvers.
+ * @param variableValues - Runtime variable values keyed by variable name.
+ * @param operationName - Name of the subscription operation to execute when
+ * the document contains multiple operations.
+ * @param subscribeFieldResolver - Resolver used for the root subscription
+ * field.
+ * @returns The source event stream, or an execution result containing
+ * subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('subscription { greeting }');
+ *
+ * const stream = await createSourceEventStream(schema, document, {
+ *   greeting: () => greetings(),
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
+ * @deprecated Will be removed in next major version in favor of named arguments.
+ */
 export declare function createSourceEventStream(
   schema: GraphQLSchema,
   document: DocumentNode,