graphql 17.0.0-beta.0 → 17.0.0-beta.2

package/execution/execute.d.ts

@@ -1,13 +1,12 @@
-import type { Maybe } from '../jsutils/Maybe.js';
-import type { Path } from '../jsutils/Path.js';
-import type { PromiseOrValue } from '../jsutils/PromiseOrValue.js';
-import { GraphQLError } from '../error/GraphQLError.js';
-import type { DocumentNode, FieldNode } from '../language/ast.js';
-import type { GraphQLField, GraphQLFieldResolver, GraphQLObjectType, GraphQLResolveInfo, GraphQLResolveInfoHelpers, GraphQLTypeResolver } from '../type/index.js';
-import type { GraphQLSchema } from '../type/schema.js';
-import type { ExecutionResult, ValidatedExecutionArgs, ValidatedSubscriptionArgs } from './Executor.js';
-import type { ExecutionHooks } from './hooks.js';
-import type { ExperimentalIncrementalExecutionResults } from './incremental/IncrementalExecutor.js';
+/** @category Execution */
+import type { PromiseOrValue } from "../jsutils/PromiseOrValue.js";
+import { GraphQLError } from "../error/GraphQLError.js";
+import type { GraphQLFieldResolver, GraphQLTypeResolver } from "../type/index.js";
+import type { ExecutionArgs, ValidatedExecutionArgs, ValidatedSubscriptionArgs } from "./ExecutionArgs.js";
+import type { ExecutionResult } from "./Executor.js";
+import type { ExperimentalIncrementalExecutionResults } from "./incremental/IncrementalExecutor.js";
+/** Function used to execute a validated root selection set for a subscription event. */
+export type RootSelectionSetExecutor = (validatedExecutionArgs: ValidatedSubscriptionArgs) => PromiseOrValue<ExecutionResult>;
 /**
  * Implements the "Executing requests" section of the GraphQL specification.
  *
@@ -18,11 +17,40 @@ import type { ExperimentalIncrementalExecutionResults } from './incremental/Incr
  * 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.
+ *
  * This function does not support incremental delivery (`@defer` and `@stream`).
- * If an operation which would defer or stream data is executed with this
- * function, it will throw or return a rejected promise.
- * Use `experimentalExecuteIncrementally` if you want to support incremental
- * delivery.
+ * Use `experimentalExecuteIncrementally` to execute operations with
+ * incremental delivery enabled.
+ * @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
+ * 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!' } }
+ * ```
  */
 export declare function execute(args: ExecutionArgs): PromiseOrValue<ExecutionResult>;
 /**
@@ -30,14 +58,38 @@ export declare function execute(args: ExecutionArgs): PromiseOrValue<ExecutionRe
  * including `@defer` and `@stream` as proposed in
  * https://github.com/graphql/graphql-spec/pull/742
  *
- * This function returns a Promise of an ExperimentalIncrementalExecutionResults
- * object. This object either consists of a single ExecutionResult, or an
- * object containing an `initialResult` and a stream of `subsequentResults`.
+ * This function returns either a single ExecutionResult, or an
+ * ExperimentalIncrementalExecutionResults object containing an `initialResult`
+ * and a stream of `subsequentResults`.
  *
  * If the arguments to this function do not result in a legal execution context,
  * a GraphQLError will be thrown immediately explaining the invalid input.
+ * @param args - Execution arguments for the GraphQL operation.
+ * @returns A single execution result or incremental execution results.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { experimentalExecuteIncrementally } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = await experimentalExecuteIncrementally({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: { greeting: 'Hello' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @category Incremental Execution
  */
 export declare function experimentalExecuteIncrementally(args: ExecutionArgs): PromiseOrValue<ExecutionResult | ExperimentalIncrementalExecutionResults>;
+/** @internal */
 export declare function executeIgnoringIncremental(args: ExecutionArgs): PromiseOrValue<ExecutionResult | ExperimentalIncrementalExecutionResults>;
 /**
  * Implements the "Executing operations" section of the spec.
@@ -53,21 +105,121 @@ export declare function executeIgnoringIncremental(args: ExecutionArgs): 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.
+ * @param validatedExecutionArgs - Validated execution arguments.
+ * @returns Execution result for the operation root selection set.
+ * @example
+ * ```ts
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeRootSelectionSet, validateExecutionArgs } from 'graphql/execution';
+ *
+ * const schema = buildSchema('type Query { greeting: String }');
+ * const validatedArgs = validateExecutionArgs({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: { greeting: 'Hello' },
+ * });
+ *
+ * assert('schema' in validatedArgs);
+ *
+ * const result = await executeRootSelectionSet(validatedArgs);
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
  */
 export declare function executeRootSelectionSet(validatedExecutionArgs: ValidatedExecutionArgs): PromiseOrValue<ExecutionResult>;
+/**
+ * Executes the operation root selection set with incremental delivery enabled.
+ * @param validatedExecutionArgs - Validated execution arguments.
+ * @returns A single execution result or incremental execution results.
+ * @example
+ * ```ts
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import {
+ *   experimentalExecuteRootSelectionSet,
+ *   validateExecutionArgs,
+ * } from 'graphql/execution';
+ *
+ * const schema = buildSchema('type Query { greeting: String }');
+ * const validatedArgs = validateExecutionArgs({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: { greeting: 'Hello' },
+ * });
+ *
+ * assert('schema' in validatedArgs);
+ *
+ * const result = await experimentalExecuteRootSelectionSet(validatedArgs);
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @category Incremental Execution
+ */
 export declare function experimentalExecuteRootSelectionSet(validatedExecutionArgs: ValidatedExecutionArgs): PromiseOrValue<ExecutionResult | ExperimentalIncrementalExecutionResults>;
+/** @internal */
 export declare function executeRootSelectionSetIgnoringIncremental(validatedExecutionArgs: ValidatedExecutionArgs): PromiseOrValue<ExecutionResult | ExperimentalIncrementalExecutionResults>;
 /**
  * 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
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema('type Query { greeting: String }');
+ *
+ * const result = executeSync({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: { greeting: 'Hello' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
  */
 export declare function executeSync(args: ExecutionArgs): ExecutionResult;
+/**
+ * Executes a subscription operation once for a single source event.
+ * @param validatedExecutionArgs - Validated subscription execution arguments.
+ * @returns Execution result for the subscription event.
+ * @example
+ * ```ts
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSubscriptionEvent, validateSubscriptionArgs } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ * const validatedArgs = validateSubscriptionArgs({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: 'Hello' },
+ * });
+ *
+ * assert('schema' in validatedArgs);
+ *
+ * const result = await executeSubscriptionEvent(validatedArgs);
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ */
 export declare function executeSubscriptionEvent(validatedExecutionArgs: ValidatedSubscriptionArgs): PromiseOrValue<ExecutionResult>;
 /**
  * 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.
@@ -89,6 +241,93 @@ export declare function executeSubscriptionEvent(validatedExecutionArgs: Validat
  * `@stream` directive.
  *
  * Accepts an object with named arguments.
+ * @param args - Execution arguments for the subscription operation.
+ * @returns A response stream for a valid subscription, or an execution result containing 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' } }
+ * ```
  */
 export declare function subscribe(args: ExecutionArgs): PromiseOrValue<AsyncGenerator<ExecutionResult, void, void> | ExecutionResult>;
 /**
@@ -96,7 +335,7 @@ export declare function subscribe(args: ExecutionArgs): PromiseOrValue<AsyncGene
  * GraphQL specification, resolving the subscription source event stream for a
  * previously validated subscription request.
  *
- * 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 validated
  * execution arguments are invalid, or if the resolved event stream is not an
  * async iterable.
@@ -105,7 +344,7 @@ export declare function subscribe(args: ExecutionArgs): PromiseOrValue<AsyncGene
  * 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`.
  *
@@ -119,31 +358,41 @@ export declare function subscribe(args: ExecutionArgs): PromiseOrValue<AsyncGene
  * 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 validatedExecutionArgs - Validated subscription execution arguments.
+ * @returns A source event stream, or an execution result containing errors.
+ * @example
+ * ```ts
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream, validateSubscriptionArgs } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ * const validatedArgs = validateSubscriptionArgs({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * assert('schema' in validatedArgs);
+ *
+ * const stream = await createSourceEventStream(validatedArgs);
+ * Symbol.asyncIterator in stream; // => true
+ * ```
  */
 export declare function createSourceEventStream(validatedExecutionArgs: ValidatedSubscriptionArgs): PromiseOrValue<AsyncIterable<unknown> | ExecutionResult>;
-export interface ExecutionArgs {
-    schema: GraphQLSchema;
-    document: DocumentNode;
-    rootValue?: unknown;
-    contextValue?: unknown;
-    variableValues?: Maybe<{
-        readonly [variable: string]: unknown;
-    }>;
-    operationName?: Maybe<string>;
-    fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
-    typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
-    subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
-    perEventExecutor?: Maybe<(validatedExecutionArgs: ValidatedSubscriptionArgs) => PromiseOrValue<ExecutionResult>>;
-    hideSuggestions?: Maybe<boolean>;
-    abortSignal?: Maybe<AbortSignal>;
-    enableEarlyExecution?: Maybe<boolean>;
-    hooks?: Maybe<ExecutionHooks>;
-    /** Additional execution options. */
-    options?: {
-        /** Set the maximum number of errors allowed for coercing (defaults to 50). */
-        maxCoercionErrors?: number;
-    };
-}
 /**
  * Constructs a ExecutionContext object from the arguments passed to
  * execute, which we will pass throughout the other execution methods.
@@ -151,9 +400,88 @@ export interface ExecutionArgs {
  * Throws a GraphQLError if a valid execution context cannot be created.
  *
  * TODO: consider no longer exporting this function
- * @internal
+ * @param args - Execution arguments to validate.
+ * @returns Validated execution arguments, or validation errors.
+ * @example
+ * ```ts
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { validateExecutionArgs } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ * const abortController = new AbortController();
+ * const validatedArgs = validateExecutionArgs({
+ *   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;
+ *   },
+ *   hideSuggestions: true,
+ *   abortSignal: abortController.signal,
+ *   enableEarlyExecution: true,
+ *   hooks: {
+ *     asyncWorkFinished: () => {},
+ *   },
+ *   options: { maxCoercionErrors: 1 },
+ * });
+ *
+ * assert('operation' in validatedArgs);
+ *
+ * validatedArgs.operation.name?.value; // => 'Viewer'
+ * validatedArgs.hideSuggestions; // => true
+ * ```
  */
 export declare function validateExecutionArgs(args: ExecutionArgs): ReadonlyArray<GraphQLError> | ValidatedExecutionArgs;
+/**
+ * Validates execution arguments for a subscription operation.
+ * @param args - Execution arguments to validate.
+ * @returns Validated subscription execution arguments, or validation errors.
+ * @example
+ * ```ts
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { validateSubscriptionArgs } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ * const validatedArgs = validateSubscriptionArgs({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('operation' in validatedArgs);
+ *
+ * validatedArgs.operation.operation; // => 'subscription'
+ * ```
+ */
 export declare function validateSubscriptionArgs(args: ExecutionArgs): ReadonlyArray<GraphQLError> | ValidatedSubscriptionArgs;
 /**
  * If a resolveType function is not given, then a default resolve behavior is
@@ -174,7 +502,44 @@ export declare const defaultTypeResolver: GraphQLTypeResolver<unknown, unknown>;
  */
 export declare const defaultFieldResolver: GraphQLFieldResolver<unknown, unknown>;
 /**
- * TODO: consider no longer exporting this function
- * @internal
+ * Implements the "MapSourceToResponseEvent" algorithm described in the
+ * GraphQL specification, mapping each event from a subscription source event
+ * stream to an ExecutionResult in the response stream.
+ * @param validatedExecutionArgs - Validated subscription execution arguments.
+ * @param sourceEventStream - Source event stream returned by the subscription resolver.
+ * @param rootSelectionSetExecutor - Function used to execute each source event.
+ * @returns A response stream of execution results.
+ * @example
+ * ```ts
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { mapSourceToResponseEvent, validateSubscriptionArgs } from 'graphql/execution';
+ *
+ * async function* events() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ * const validatedArgs = validateSubscriptionArgs({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('schema' in validatedArgs);
+ *
+ * const responseStream = mapSourceToResponseEvent(validatedArgs, events());
+ * const firstPayload = await responseStream.next();
+ *
+ * firstPayload.value; // => { data: { greeting: 'Hello' } }
+ * ```
  */
-export declare function buildResolveInfo(validatedExecutionArgs: ValidatedExecutionArgs, fieldDef: GraphQLField<unknown, unknown>, fieldNodes: ReadonlyArray<FieldNode>, parentType: GraphQLObjectType, path: Path, getAbortSignal: () => AbortSignal | undefined, getAsyncHelpers: () => GraphQLResolveInfoHelpers): GraphQLResolveInfo;
+export declare function mapSourceToResponseEvent(validatedExecutionArgs: ValidatedSubscriptionArgs, sourceEventStream: AsyncIterable<unknown>, rootSelectionSetExecutor?: RootSelectionSetExecutor): AsyncGenerator<ExecutionResult, void, void>;