Support options.reobserveQuery callback for mutations.

[benjamn]

Building on #7819, this PR implements the reobserveQuery option I described in #7060 (comment), which allows mutations to override the refetching logic for any watched queries invalidated by the mutation update function.

The word "invalidated" is important here, since it means reobserveQuery will fire for any queries affected by cache writes, even if the result of the query does not end up changing. This is why it was previously difficult to make use of the INVALIDATE sentinel object added in #6991, as reported in #7060. Using cache.modify and INVALIDATE in the mutation update function should work smoothly with reobserveQuery, hopefully resolving #7060.

Similar functionality is achievable using just cache.batch and onDirty, so reobserveQuery-style behavior does not absolutely require a mutation, but reobserveQuery should greatly reduce the need for manual query enumeration after mutations, a la refetchQueries. Also, since you can simply return a Promise from reobserveQuery to make the mutation await async work, the need to use awaitRefetchQueries should be (mostly) eliminated.

As foretold in #7819, this PR continues (finishes? 🤞) the implementation of the following item from the Apollo Client v3.4 ROADMAP.md section:

• A new API for reobserving/refetching queries after a mutation, eliminating the need for updateQueries, refetchQueries, and awaitRefetchQueries in a lot of cases.

[benjamn]

This is the test that wasn't passing without the changes from #7887 (against which I just rebased this PR), since #7887 solves some problems with the intersection of result caching and optimistic updates, and React hooks are especially sensitive to those kind of problems.

[benjamn]

As I mentioned in #7878 (comment), I'm now thinking about supporting a standalone client.reobserveQueries method, not requiring a mutation:

client.reobserveQueries(
  // This callback invalidates some fields in the cache.
  cache => {
    // Modify the cache somehow, using writeQuery, writeFragment,
    // evict, modify, etc. Anything that invalidates fields.
  },
  // This callback gets called for any ObservableQuery objects
  // affected by the invalidation.
  (observableQuery, diff) => {
    // Force any affected queries to be refetched from the network.
    return observableQuery.refetch();
  },
);

[benjamn]

@hwillson @jcreighton @brainkim I think this PR is ready for review now? I can tackle #7827 (comment) in a follow-up PR.

[hwillson]

Awesome @benjamn - 👍 from me! We'll want to add docs for this before we finalize 3.4 (but those can definitely be handled in a separate PR). Thanks!

[benjamn]

Wow, just noticed some of these commits are timestamped from August 2020. Guess I've been rebasing this branch locally for a while now!