Update migration section with info about the promise (#12961)

Author: jerelmiller

.size-limits.json

@@ -1,6 +1,6 @@
 {
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43936,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38686,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33476,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27519
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43812,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38745,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33456,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27523
 }

docs/source/data/queries.mdx

@@ -502,7 +502,7 @@ The promise resolves with an object that includes the error and any partial data
 const handleClick = async () => {
   const { data, error } = await getDogs();
 
-  if (error && CombinedGraphQLErrors.is(error)) {
+  if (CombinedGraphQLErrors.is(error)) {
     // handle GraphQL errors returned by the query
   }
 };

docs/source/migrating/apollo-client-4-migration.mdx

@@ -1445,6 +1445,58 @@ async function onUserInteraction() {
 
 </Tip>
 
+#### Changes to promise resolution with errors for the `execute` function
+
+The promise returned from the `execute` function is now consistently resolved or rejected based on your configured `errorPolicy` when errors are returned. With an `errorPolicy` of `none`, the promise always rejects. With an `errorPolicy` of `all`, the promise always resolves and sets the `error` property on the result. With an `errorPolicy` of `ignore`, the promise always resolves and discards the errors.
+
+Previously, Apollo Client 3 resolved the promise when GraphQL errors were returned when using an `errorPolicy` of `none`. Network errors always caused the promise to reject, regardless of your configured error policy. This change unifies the error behavior across all error types to ensure errors are handled consistently.
+
+To migrate code that uses an `errorPolicy` of `none`, wrap the call to `execute` in a `try`/`catch` block and use `CombinedGraphQLErrors.is(error)` to check for GraphQL errors.
+
+```ts disableCopy=true
+const [execute] = useLazyQuery(QUERY, {
+  errorPolicy: "none",
+});
+
+async function onUserInteraction() {
+  const { data, error } = await execute({ variables });// [!code --:4]
+  if (error.graphQLErrors) {
+    // handle GraphQL errors
+  }
+
+  try {// [!code ++:6]
+    const { data } = await execute({ variables });
+  } catch (error) {
+    if (CombinedGraphQLErrors.is(error)) {
+      // handle GraphQL errors
+    }
+  }
+}
+```
+
+To migrate code that uses an `errorPolicy` of `all`, read the error from the `error` property returned in the result. You can optionally remove any `try`/`catch` statements because the promise resolves for all error types.
+
+```ts disableCopy=true
+const [execute] = useLazyQuery(QUERY, {
+  errorPolicy: "all",
+});
+
+async function onUserInteraction() {
+  try {// [!code --:7]
+    const { data } = await execute({ variables });
+  } catch (error) {
+    if (error.graphQLErrors) {
+      // handle GraphQL errors
+    }
+  }
+
+  const { data, error } = await execute({ variables });// [!code ++:4]
+  if (CombinedGraphQLErrors.is(error)) {
+    // handle GraphQL errors
+  }
+}
+```
+
 ### Changes to `useMutation`
 
 `useMutation` has been modified to work with our [philosophy](#a-note-about-hook-usage) that React hooks should be used to synchronize hook state with your component.