Merge pull request #3750 from apollographql/hwillson/await-refetch-do…

…c-updates

Add `react-apollo` `awaitRefetchQueries` docs

docs/source/api/react-apollo.md

@@ -1190,7 +1190,11 @@ export default graphql(gql`mutation { ... }`, {
 })(MyComponent);
 ```
 
+Please note that refetched queries are handled asynchronously, and by default are not necessarily completed before the mutation has completed. If you want to make sure refetched queries are completed before the mutation is considered done (or resolved), set [`options.awaitRefetchQueries`](#graphql-mutation-options-awaitRefetchQueries) to `true`.
 
+<h3 id="graphql-mutation-options-awaitRefetchQueries">`options.awaitRefetchQueries`</h3>
+
+Queries refetched using [`options.refetchQueries`](#graphql-mutation-options-refetchQueries) are handled asynchronously, which means by default they are not necessarily completed before the mutation has completed. Setting `options.awaitRefetchQueries` to `true` will make sure refetched queries are completed before the mutation is considered done (or resolved). `options.awaitRefetchQueries` is `false` by default.
 
 <h3 id="graphql-mutation-options-updateQueries">`options.updateQueries`</h3>
 

docs/source/essentials/mutations.md

@@ -236,6 +236,8 @@ The Mutation component accepts the following props. Only `mutation` and `childre
   <dd>Provide a [mutation response](../features/optimistic-ui.html) before the result comes back from the server</dd>
   <dt>`refetchQueries`: (mutationResult: FetchResult) => Array<{ query: DocumentNode, variables?: TVariables}></dt>
   <dd>A function that allows you to specify which queries you want to refetch after a mutation has occurred</dd>
+  <dt>`awaitRefetchQueries`: boolean</dt>
+  <dd>Queries refetched as part of `refetchQueries` are handled asynchronously, and are not waited on before the mutation is completed (resolved). Setting this to `true` will make sure refetched queries are completed before the mutation is considered done. `false` by default.</dd>
   <dt>`onCompleted`: (data: TData) => void</dt>
   <dd>A callback executed once your mutation successfully completes</dd>
   <dt>`onError`: (error: ApolloError) => void</dt>