docs: refresh website with broader execution/tracing update (#4794)

Author: yaacovCR

website/pages/api-v17/execution.mdx

@@ -161,8 +161,9 @@ Returns either a synchronous ExecutionResult (if all encountered resolvers
 are synchronous), or a Promise of an ExecutionResult that will eventually be
 resolved and never rejected.
 
-If the arguments to this function do not result in a legal execution context,
-a GraphQLError will be thrown immediately explaining the invalid input.
+If the schema is invalid, an error will be thrown immediately. GraphQL
+request errors, including missing operations and variable coercion errors,
+are returned in an errors-only ExecutionResult.
 
 Field errors are collected into the response instead of rejecting the
 returned promise. Only the field that produced the error and its descendants
@@ -251,17 +252,18 @@ result; // => { data: { greeting: 'Hello, Ada!' } }
 
 Implements the "Executing operations" section of the spec.
 
-Returns a Promise that will eventually resolve to the data described by
-The "Response" section of the GraphQL specification.
+Returns either a synchronous ExecutionResult, or a Promise for an
+ExecutionResult, 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.
+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. These field errors are collected into the returned result instead
+of being thrown or rejecting the returned 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.
+Errors from sub-fields of a NonNull type may propagate to the top level, at
+which point we still collect the error and null the parent field, which in
+this case is the entire response.
 
 **Signature:**
 
@@ -408,6 +410,9 @@ result; // => { data: { greeting: 'Hello' } }
 
 Executes a subscription operation once for a single source event.
 
+Field errors are collected into the returned result instead of being thrown
+or rejecting the returned promise.
+
 **Signature:**
 
 <ApiSignature parts={[["name", "executeSubscriptionEvent"], "(\n  ", ["parameter", "validatedExecutionArgs"], ": ", ["link", "ValidatedSubscriptionArgs", "/api-v17/execution#validatedsubscriptionargs"], ",\n): ", ["type", "PromiseOrValue"], "\u003c", ["link", "ExecutionResult", "/api-v17/execution#executionresult"], "\u003e;"]} />
@@ -489,21 +494,22 @@ result; // => { data: { greeting: 'Hello' } }
 
 Implements the "Subscribe" algorithm described in the GraphQL specification.
 
-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.
+Returns either an AsyncGenerator (if successful), an ExecutionResult (error),
+or a Promise for one of those results. The call will throw immediately if
+the schema is invalid or the selected operation is not a subscription.
 
-If the client-provided arguments to this function do not result in a
-compliant subscription, a GraphQL Response (ExecutionResult) with descriptive
-errors and no data will be returned.
+GraphQL request errors, including missing operations and variable coercion
+errors, return or resolve to a GraphQL Response (ExecutionResult) with
+descriptive errors and no data.
 
 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`.
+logic, a non-async-iterable resolver result, or a system error, the
+function will return or resolve to a single ExecutionResult containing
+`errors` and no `data`.
 
-If the operation succeeded, the promise resolves to an AsyncIterator, which
-yields a stream of ExecutionResults representing the response stream.
+If the operation succeeded, the function returns or resolves to an
+AsyncGenerator, which yields a stream of ExecutionResults representing the
+response stream.
 
 This function does not support incremental delivery (`@defer` and `@stream`).
 If an operation which would defer or stream data is executed with this
@@ -657,21 +663,20 @@ Implements the "CreateSourceEventStream" algorithm described in the
 GraphQL specification, resolving the subscription source event stream for a
 previously validated subscription request.
 
-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.
+Returns either an AsyncIterable (if successful), an ExecutionResult (error),
+or a Promise for one of those results. The call will throw immediately if
+it is not passed validated execution arguments.
 
-If the client-provided arguments to this function do not result in a
-compliant subscription, a GraphQL Response (ExecutionResult) with
-descriptive errors and no data will be returned.
+If the validated arguments do not result in a compliant subscription, a
+GraphQL Response (ExecutionResult) with descriptive errors and no data will
+be returned.
 
 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`.
+resolver logic or a system error, the function will return or
+resolve to a single ExecutionResult containing `errors` and no `data`.
 
-If the operation succeeded, the promise resolves to the AsyncIterable for the
-event stream returned by the resolver.
+If the operation succeeded, the function returns or resolves to the
+AsyncIterable for the event stream returned by the resolver.
 
 A Source Event Stream represents a sequence of events, each of which triggers
 a GraphQL execution for that event.
@@ -764,12 +769,11 @@ Symbol.asyncIterator in stream; // => true
 
 #### validateExecutionArgs()
 
-Constructs a ExecutionContext object from the arguments passed to
-execute, which we will pass throughout the other execution methods.
-
-Throws a GraphQLError if a valid execution context cannot be created.
+Validates the arguments passed to execute, subscribe, and their lower-level
+helpers.
 
-TODO: consider no longer exporting this function
+Throws if the schema is invalid. GraphQL request errors, including variable
+coercion errors, are returned as a GraphQLError array.
 
 **Signature:**
 
@@ -873,6 +877,10 @@ validatedArgs.hideSuggestions; // => true
 
 Validates execution arguments for a subscription operation.
 
+Throws if the schema is invalid or the selected operation is not a
+subscription. GraphQL request errors, including variable coercion errors, are
+returned as a GraphQLError array.
+
 **Signature:**
 
 <ApiSignature parts={[["name", "validateSubscriptionArgs"], "(\n  ", ["parameter", "args"], ": ", ["link", "ExecutionArgs", "/api-v17/execution#executionargs"], ",\n): ", ["link", "ValidatedSubscriptionArgs", "/api-v17/execution#validatedsubscriptionargs"], " \u007c ", ["keyword", "readonly"], " ", ["link", "GraphQLError", "/api-v17/error#graphqlerror"], "[];"]} />
@@ -1556,8 +1564,9 @@ 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.
+If the schema is invalid, an error will be thrown immediately. GraphQL
+request errors, including missing operations and variable coercion errors,
+are returned in an errors-only ExecutionResult.
 
 **Signature:**
 

website/pages/api-v17/graphql.mdx

@@ -135,7 +135,7 @@ isDevModeEnabled(); // => true
 
 #### GraphQLParseContext
 
-**Interface.** Context published on `graphql:parse`.
+**Interface.** Context published on the sync-only `graphql:parse` channel.
 
 <hr className="api-subsection-divider" />
 
@@ -172,7 +172,7 @@ isDevModeEnabled(); // => true
 
 #### GraphQLValidateContext
 
-**Interface.** Context published on `graphql:validate`.
+**Interface.** Context published on the sync-only `graphql:validate` channel.
 
 <hr className="api-subsection-divider" />
 
@@ -216,6 +216,8 @@ isDevModeEnabled(); // => true
 
 **Interface.** Context published on `graphql:execute`.
 
+Returned results may contain GraphQL errors collected during execution.
+
 <hr className="api-subsection-divider" />
 
 <div className="api-subsection-title">Members</div>
@@ -257,12 +259,12 @@ isDevModeEnabled(); // => true
     <tr>
       <td>error?</td>
       <td><ApiType parts={[["keyword", "unknown"]]} /></td>
-      <td>Error thrown while executing, when execution fails abruptly.</td>
+      <td>Error thrown or rejected while executing, when execution fails abruptly.</td>
     </tr>
     <tr>
       <td>result?</td>
       <td><ApiType parts={[["link", "ExecutionResult", "/api-v17/execution#executionresult"], " \u007c ", ["link", "ExperimentalIncrementalExecutionResults", "/api-v17/execution#experimentalincrementalexecutionresults"]]} /></td>
-      <td>Execution result returned by execution.</td>
+      <td>Execution result returned by execution, including GraphQL errors.</td>
     </tr>
   </tbody>
 </table>
@@ -273,6 +275,8 @@ isDevModeEnabled(); // => true
 
 **Interface.** Context published on `graphql:execute:rootSelectionSet`.
 
+Returned results may contain GraphQL errors collected during execution.
+
 <hr className="api-subsection-divider" />
 
 <div className="api-subsection-title">Members</div>
@@ -319,12 +323,13 @@ isDevModeEnabled(); // => true
     <tr>
       <td>error?</td>
       <td><ApiType parts={[["keyword", "unknown"]]} /></td>
-      <td>Error thrown while executing the root selection set.</td>
+      <td>Error thrown or rejected while executing the root selection set.</td>
     </tr>
     <tr>
       <td>result?</td>
       <td><ApiType parts={[["link", "ExecutionResult", "/api-v17/execution#executionresult"], " \u007c ", ["link", "ExperimentalIncrementalExecutionResults", "/api-v17/execution#experimentalincrementalexecutionresults"]]} /></td>
-      <td>Execution result returned from the root selection set.</td>
+      <td>Execution result returned from the root selection set, including GraphQL<br />
+errors.</td>
     </tr>
   </tbody>
 </table>
@@ -335,10 +340,12 @@ isDevModeEnabled(); // => true
 
 **Interface.** Context published on `graphql:execute:variableCoercion`.
 
-Coercion runs synchronously inside argument validation, so only the
-`start`/`end` (and, on a thrown error, [`error`](/api-v17/error)) lifecycle fires. When
-coercion produces variable errors it does not throw; instead `result`
-carries the `errors` array, mirroring `graphql:validate`.
+Coercion runs synchronously while execution arguments are validated, so only
+the `start`/`end` (and, on an abrupt throw, [`error`](/api-v17/error)) lifecycle fires.
+Ordinary variable coercion failures are returned on `result.errors`; when
+execution is invoked through APIs such as `execute()` or `subscribe()`, they
+surface as GraphQL result errors rather than as the tracing [`error`](/api-v17/error)
+lifecycle event.
 
 <hr className="api-subsection-divider" />
 
@@ -402,6 +409,11 @@ carries the `errors` array, mirroring `graphql:validate`.
 
 **Interface.** Context published on `graphql:subscribe`.
 
+Subscription source resolver errors and invalid source stream results are
+returned on `result` as ExecutionResult errors; they do not publish the
+[`error`](/api-v17/error) lifecycle event unless subscription setup fails abruptly before
+GraphQL can form a result.
+
 <hr className="api-subsection-divider" />
 
 <div className="api-subsection-title">Members</div>
@@ -443,12 +455,13 @@ carries the `errors` array, mirroring `graphql:validate`.
     <tr>
       <td>error?</td>
       <td><ApiType parts={[["keyword", "unknown"]]} /></td>
-      <td>Error thrown while subscribing, when subscription setup fails abruptly.</td>
+      <td>Error thrown or rejected while subscribing, when setup fails abruptly.</td>
     </tr>
     <tr>
       <td>result?</td>
       <td><ApiType parts={["\u007c ", ["link", "ExecutionResult", "/api-v17/execution#executionresult"], "\n\u007c ", ["type", "AsyncGenerator"], "\u003c", ["link", "ExecutionResult", "/api-v17/execution#executionresult"], ", ", ["keyword", "void"], ", ", ["keyword", "void"], "\u003e"]} /></td>
-      <td>Subscription response stream or execution result returned by subscribe.</td>
+      <td>Subscription response stream, or an ExecutionResult containing GraphQL<br />
+errors.</td>
     </tr>
   </tbody>
 </table>
@@ -459,6 +472,10 @@ carries the `errors` array, mirroring `graphql:validate`.
 
 **Interface.** Context published on `graphql:resolve`.
 
+Resolver throws and rejections publish the [`error`](/api-v17/error) lifecycle event here.
+The same failure may also be formatted into the enclosing execution or
+subscription result.
+
 <hr className="api-subsection-divider" />
 
 <div className="api-subsection-title">Members</div>
@@ -510,12 +527,12 @@ carries the `errors` array, mirroring `graphql:validate`.
     <tr>
       <td>error?</td>
       <td><ApiType parts={[["keyword", "unknown"]]} /></td>
-      <td>Error thrown by the resolver, when resolution fails.</td>
+      <td>Error thrown or rejected by the resolver, when resolution fails.</td>
     </tr>
     <tr>
       <td>result?</td>
       <td><ApiType parts={[["keyword", "unknown"]]} /></td>
-      <td>Value returned by the resolver.</td>
+      <td>Value returned by the resolver, when resolution succeeds.</td>
     </tr>
   </tbody>
 </table>
@@ -581,7 +598,7 @@ carries the `errors` array, mirroring `graphql:validate`.
 
 #### GraphQLChannels
 
-**Interface.** The collection of tracing channels graphql-js emits on. Application
+**Interface.** The collection of tracing channels GraphQL.js emits on. Application
 performance monitoring (APM) tools subscribe to these by name on their own
 `node:diagnostics_channel` import; both paths land on the same channel
 instance because `tracingChannel(name)` is cached by name.