graphql 16.14.0 → 16.14.1

package/error/locatedError.d.ts

@@ -1,3 +1,4 @@
+/** @category Errors */
 import type { Maybe } from '../jsutils/Maybe';
 import type { ASTNode } from '../language/ast';
 import { GraphQLError } from './GraphQLError';
@@ -5,6 +6,25 @@ import { GraphQLError } from './GraphQLError';
  * Given an arbitrary value, presumably thrown while attempting to execute a
  * GraphQL operation, produce a new GraphQLError aware of the location in the
  * document responsible for the original Error.
+ * @param rawOriginalError - The original error value to wrap.
+ * @param nodes - The AST nodes associated with the error.
+ * @param path - The response path associated with the error.
+ * @returns The GraphQL error.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { locatedError } from 'graphql/error';
+ *
+ * const document = parse('{ viewer { name } }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const error = locatedError(new Error('Resolver failed'), fieldNode, [
+ *   'viewer',
+ * ]);
+ *
+ * error.message; // => 'Resolver failed'
+ * error.locations; // => [{ line: 1, column: 3 }]
+ * error.path; // => ['viewer']
+ * ```
  */
 export declare function locatedError(
   rawOriginalError: unknown,

package/error/locatedError.js

@@ -9,10 +9,31 @@ var _toError = require('../jsutils/toError.js');
 
 var _GraphQLError = require('./GraphQLError.js');
 
+/** @category Errors */
+
 /**
  * Given an arbitrary value, presumably thrown while attempting to execute a
  * GraphQL operation, produce a new GraphQLError aware of the location in the
  * document responsible for the original Error.
+ * @param rawOriginalError - The original error value to wrap.
+ * @param nodes - The AST nodes associated with the error.
+ * @param path - The response path associated with the error.
+ * @returns The GraphQL error.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { locatedError } from 'graphql/error';
+ *
+ * const document = parse('{ viewer { name } }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const error = locatedError(new Error('Resolver failed'), fieldNode, [
+ *   'viewer',
+ * ]);
+ *
+ * error.message; // => 'Resolver failed'
+ * error.locations; // => [{ line: 1, column: 3 }]
+ * error.path; // => ['viewer']
+ * ```
  */
 function locatedError(rawOriginalError, nodes, path) {
   var _nodes;

package/error/locatedError.mjs

@@ -1,9 +1,29 @@
+/** @category Errors */
 import { toError } from '../jsutils/toError.mjs';
 import { GraphQLError } from './GraphQLError.mjs';
 /**
  * Given an arbitrary value, presumably thrown while attempting to execute a
  * GraphQL operation, produce a new GraphQLError aware of the location in the
  * document responsible for the original Error.
+ * @param rawOriginalError - The original error value to wrap.
+ * @param nodes - The AST nodes associated with the error.
+ * @param path - The response path associated with the error.
+ * @returns The GraphQL error.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { locatedError } from 'graphql/error';
+ *
+ * const document = parse('{ viewer { name } }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const error = locatedError(new Error('Resolver failed'), fieldNode, [
+ *   'viewer',
+ * ]);
+ *
+ * error.message; // => 'Resolver failed'
+ * error.locations; // => [{ line: 1, column: 3 }]
+ * error.path; // => ['viewer']
+ * ```
  */
 
 export function locatedError(rawOriginalError, nodes, path) {

package/error/syntaxError.d.ts

@@ -1,8 +1,23 @@
+/** @category Errors */
 import type { Source } from '../language/source';
 import { GraphQLError } from './GraphQLError';
 /**
  * Produces a GraphQLError representing a syntax error, containing useful
  * descriptive information about the syntax error's position in the source.
+ * @param source - The GraphQL source containing the syntax error.
+ * @param position - Character offset where the syntax error was encountered.
+ * @param description - Human-readable description of the syntax error.
+ * @returns A GraphQLError located at the syntax error position.
+ * @example
+ * ```ts
+ * import { Source } from 'graphql/language';
+ * import { syntaxError } from 'graphql/error';
+ *
+ * const error = syntaxError(new Source('query {'), 7, 'Expected Name');
+ *
+ * error.message; // => 'Syntax Error: Expected Name'
+ * error.locations; // => [{ line: 1, column: 8 }]
+ * ```
  */
 export declare function syntaxError(
   source: Source,

package/error/syntaxError.js

@@ -7,9 +7,25 @@ exports.syntaxError = syntaxError;
 
 var _GraphQLError = require('./GraphQLError.js');
 
+/** @category Errors */
+
 /**
  * Produces a GraphQLError representing a syntax error, containing useful
  * descriptive information about the syntax error's position in the source.
+ * @param source - The GraphQL source containing the syntax error.
+ * @param position - Character offset where the syntax error was encountered.
+ * @param description - Human-readable description of the syntax error.
+ * @returns A GraphQLError located at the syntax error position.
+ * @example
+ * ```ts
+ * import { Source } from 'graphql/language';
+ * import { syntaxError } from 'graphql/error';
+ *
+ * const error = syntaxError(new Source('query {'), 7, 'Expected Name');
+ *
+ * error.message; // => 'Syntax Error: Expected Name'
+ * error.locations; // => [{ line: 1, column: 8 }]
+ * ```
  */
 function syntaxError(source, position, description) {
   return new _GraphQLError.GraphQLError(`Syntax Error: ${description}`, {

package/error/syntaxError.mjs

@@ -1,7 +1,22 @@
+/** @category Errors */
 import { GraphQLError } from './GraphQLError.mjs';
 /**
  * Produces a GraphQLError representing a syntax error, containing useful
  * descriptive information about the syntax error's position in the source.
+ * @param source - The GraphQL source containing the syntax error.
+ * @param position - Character offset where the syntax error was encountered.
+ * @param description - Human-readable description of the syntax error.
+ * @returns A GraphQLError located at the syntax error position.
+ * @example
+ * ```ts
+ * import { Source } from 'graphql/language';
+ * import { syntaxError } from 'graphql/error';
+ *
+ * const error = syntaxError(new Source('query {'), 7, 'Expected Name');
+ *
+ * error.message; // => 'Syntax Error: Expected Name'
+ * error.locations; // => [{ line: 1, column: 8 }]
+ * ```
  */
 
 export function syntaxError(source, position, description) {

package/execution/collectFields.js

@@ -167,6 +167,8 @@ function collectFieldsImpl(
 /**
  * Determines if a field should be included based on the `@include` and `@skip`
  * directives, where `@skip` has higher precedence than `@include`.
+ *
+ * @internal
  */
 
 function shouldIncludeNode(variableValues, node) {
@@ -196,6 +198,8 @@ function shouldIncludeNode(variableValues, node) {
 }
 /**
  * Determines if a fragment is applicable to the given type.
+ *
+ * @internal
  */
 
 function doesFragmentConditionMatch(schema, fragment, type) {
@@ -222,6 +226,8 @@ function doesFragmentConditionMatch(schema, fragment, type) {
 }
 /**
  * Implements the logic to compute the key of a given field's entry
+ *
+ * @internal
  */
 
 function getFieldEntryKey(node) {

package/execution/collectFields.mjs

@@ -158,6 +158,8 @@ function collectFieldsImpl(
 /**
  * Determines if a field should be included based on the `@include` and `@skip`
  * directives, where `@skip` has higher precedence than `@include`.
+ *
+ * @internal
  */
 
 function shouldIncludeNode(variableValues, node) {
@@ -183,6 +185,8 @@ function shouldIncludeNode(variableValues, node) {
 }
 /**
  * Determines if a fragment is applicable to the given type.
+ *
+ * @internal
  */
 
 function doesFragmentConditionMatch(schema, fragment, type) {
@@ -206,6 +210,8 @@ function doesFragmentConditionMatch(schema, fragment, type) {
 }
 /**
  * Implements the logic to compute the key of a given field's entry
+ *
+ * @internal
  */
 
 function getFieldEntryKey(node) {

package/execution/execute.d.ts

@@ -1,3 +1,4 @@
+/** @category Execution */
 import type { Maybe } from '../jsutils/Maybe';
 import type { ObjMap } from '../jsutils/ObjMap';
 import type { Path } from '../jsutils/Path';
@@ -42,6 +43,8 @@ import type { GraphQLSchema } from '../type/schema';
  *
  * Namely, schema of the type system that is currently executing,
  * and the fragments defined in the query document
+ *
+ * @internal
  */
 export interface ExecutionContext {
   schema: GraphQLSchema;
@@ -57,9 +60,6 @@ export interface ExecutionContext {
   subscribeFieldResolver: GraphQLFieldResolver<any, any>;
   collectedErrors: CollectedErrors;
 }
-/**
- * @internal
- */
 declare class CollectedErrors {
   private _errorPositions;
   private _errors;
@@ -69,39 +69,58 @@ declare class CollectedErrors {
   private _hasNulledPosition;
 }
 /**
- * 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.
  */
 export interface ExecutionResult<
   TData = ObjMap<unknown>,
   TExtensions = ObjMap<unknown>,
 > {
+  /** Errors raised while parsing, validating, or executing the operation. */
   errors?: ReadonlyArray<GraphQLError>;
+  /** Data returned by execution, or null when execution could not produce data. */
   data?: TData | null;
+  /** Extension fields to include in the formatted result. */
   extensions?: TExtensions;
 }
+/**
+ * A JSON-serializable GraphQL execution result.
+ * @typeParam TData - Shape of the formatted data payload.
+ * @typeParam TExtensions - Shape of the formatted extensions payload.
+ */
 export interface FormattedExecutionResult<
   TData = ObjMap<unknown>,
   TExtensions = ObjMap<unknown>,
 > {
+  /** Errors raised while parsing, validating, or executing the operation. */
   errors?: ReadonlyArray<GraphQLFormattedError>;
+  /** Data returned by execution, or null when execution could not produce data. */
   data?: TData | null;
+  /** Extension fields to include in the formatted result. */
   extensions?: TExtensions;
 }
+/** Arguments accepted by execute and executeSync. */
 export interface ExecutionArgs {
+  /** The schema used for validation or execution. */
   schema: GraphQLSchema;
+  /** The parsed GraphQL document to execute. */
   document: DocumentNode;
+  /** Initial root value passed to the operation. */
   rootValue?: unknown;
+  /** Application context value passed to every resolver. */
   contextValue?: unknown;
+  /** Runtime variable values keyed by variable name. */
   variableValues?: Maybe<{
     readonly [variable: string]: unknown;
   }>;
+  /** Name of the operation to execute when the document contains multiple operations. */
   operationName?: Maybe<string>;
+  /** Resolver used when a field does not define its own resolver. */
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  /** Resolver used when an abstract type does not define its own resolver. */
   typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
+  /** Resolver used for the root subscription field. */
   subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
   /** Additional execution options. */
   options?: {
@@ -118,6 +137,139 @@ export interface ExecutionArgs {
  *
  * 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 declare function execute(
   args: ExecutionArgs,
@@ -126,11 +278,60 @@ export declare function execute(
  * 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 declare function executeSync(args: ExecutionArgs): ExecutionResult;
 /**
  * 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
@@ -153,9 +354,7 @@ export declare function assertValidExecutionArguments(
 export declare function buildExecutionContext(
   args: ExecutionArgs,
 ): ReadonlyArray<GraphQLError> | ExecutionContext;
-/**
- * @internal
- */
+/** @internal */
 export declare function buildResolveInfo(
   exeContext: ExecutionContext,
   fieldDef: GraphQLField<unknown, unknown>,