[pull] 16.x.x from graphql:16.x.x

website/css/globals.css

@@ -126,6 +126,73 @@ div[id^='headlessui-menu-items'] {
   margin: 0 0.35rem;
 }
 
+.upgrade-guide-toc {
+  margin: 1rem 0 2rem;
+  padding: 1rem;
+  border: 1px solid rgb(229 231 235);
+  border-radius: 0.5rem;
+  background: rgb(249 250 251);
+}
+
+.dark .upgrade-guide-toc {
+  border-color: rgb(55 65 81);
+  background: rgb(17 24 39 / 0.35);
+}
+
+.upgrade-guide-toc-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(13.5rem, 1fr));
+  gap: 0.75rem 1rem;
+}
+
+.upgrade-guide-toc-group {
+  display: grid;
+  align-content: start;
+  gap: 0.35rem;
+  min-width: 0;
+  padding: 0.6rem 0.75rem;
+  border-left: 2px solid rgb(209 213 219);
+  border-radius: 0.375rem;
+  background: rgb(255 255 255 / 0.7);
+}
+
+.dark .upgrade-guide-toc-group {
+  border-left-color: rgb(75 85 99);
+  background: rgb(31 41 55 / 0.38);
+}
+
+.upgrade-guide-toc-title {
+  font-size: 0.875rem;
+  font-weight: 650;
+  line-height: 1.35;
+}
+
+.upgrade-guide-toc-links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 0.65rem;
+  font-size: 0.8125rem;
+  line-height: 1.35;
+}
+
+.upgrade-guide-toc a {
+  overflow-wrap: anywhere;
+  text-decoration: none;
+}
+
+.upgrade-guide-toc a:hover {
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.upgrade-guide-toc-links a {
+  color: rgb(75 85 99);
+}
+
+.dark .upgrade-guide-toc-links a {
+  color: rgb(209 213 219);
+}
+
 .api-item-divider {
   margin: 2rem 0;
   border: 0;

website/generate-api.js

@@ -3094,7 +3094,7 @@ function addCategory(comment, category) {
 
   const trailing = comment.match(/\s*$/)?.[0] ?? '';
   const body = comment.slice(0, comment.length - trailing.length);
-  const oneLine = /^(\s*)\/\*\*\s*(.*?)\s*\*\/$/.exec(body);
+  const oneLine = /^(\s*)\/\*\*[^\S\r\n]*(.*?)[^\S\r\n]*\*\/$/.exec(body);
   if (oneLine != null) {
     const [, indent, text] = oneLine;
     return `${indent}/**\n${indent} * ${text}\n${indent} *\n${indent} * @category ${category}\n${indent} */${trailing}`;

website/pages/_meta.ts

@@ -11,6 +11,14 @@ const meta = {
         title: 'v16 to v17',
         href: '/upgrade-guides/v16-v17',
       },
+      'v15-v16': {
+        title: 'v15 to v16',
+        href: '/upgrade-guides/v15-v16',
+      },
+      'v14-v15': {
+        title: 'v14 to v15',
+        href: '/upgrade-guides/v14-v15',
+      },
     },
   },
   api: {

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:**