Improve standalone client.refetchQueries method to support automatic detection of queries needing to be refetched.

[benjamn]

As promised in #7878 (comment) and #7827 (comment), this PR turns the client.refetchQueries method into a one-stop solution for refetching queries (without having to perform a mutation), tying together several previous ways of triggering refetches into a single, flexible API.

This is the last major piece of new functionality that we plan to add to Apollo Client v3.4, and is intended to complement similar functionality added to mutations (options.onQueryUpdated, previously called options.reobserveQuery) in #7827, and builds on the cache.batch primitive added to InMemoryCache in #7819. If this PR is merged, it should conclude 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.

Since the API has changed since I last sketched it out, here's an overview of the current functionality:

const { queries, results } = client.refetchQueries({
  updateCache(cache) {
    // Trigger query updates by updating the client.cache in any way you like.
    // To pick just one possible example:
    cache.evict({
      id: cache.identify(...),
      fieldName,
    });
  },

  // Make sure these queries are included even if they were not affected by the
  // updateCache function (or the updateCache function was not provided). This
  // option is similar to the existing refetchQueries option for mutations.
  include: ["QueryName", "AnotherQueryName"],

  // Optional callback that will be called for every ObservableQuery that was affected
  // by updateCache (or included explicitly by name). If onQueryUpdated is not
  // provided, the affected queries will be refetched by calling obsQuery.refetch().
  onQueryUpdated(obsQuery, diff) {
    if (shouldIgnoreUpdate(obsQuery, diff)) {
      // Returning false causes this query not to be refetched, and omits its result from
      // the client.refetchQueries(...).{queries,updates} arrays.
      return false;
    }
    // Providing an onQueryUpdated function allows dynamically determining whether/how
    // each query should be refetched. Anything you return here will end up in the
    // client.refetchQueries(...).updates array.
    return obsQuery.refetch();
  },

  // Passing optimistic: false (the default) causes the updateCache function to run
  // against the root (non-optimistic) cache layer. Passing optimistic: true causes
  // updateCache to run in a temporary optimistic cache layer that client.refetchQueries
  // removes before returning, which can be useful when you want to use updateCache
  // to trigger some refetches but you don't want to modify cache data permanently.
  optimistic: true,
});

All of these options (updateCache, include, onQueryUpdated, and optimistic) are optional, but you have to pass either updateCache or include to get any queries to be refetched by client.refetchQueries.

This PR is a work-in-progress because this still needs more tests and documentation, but I wanted to share my progress so far, so folks can share their thoughts on this new client.refetchQueries API.

[benjamn]

The removeOptimistic option is a powerful but easy-to-miss new feature of cache.batch, since it allows us to remove optimistic mutation layers at the same time (within the same batch operation) as the final mutation update, triggering only one broadcastWatches call for both the removal and the update. Previously, optimistic layers were removed separately, after the final update, which could trigger more than one broadcast (likely harmless but potentially noisy).

[brainkim]

Likely more review tomorrow but I’m punching out for the day.

[benjamn]

@brainkim @timbotnik @hwillson I added support for including queries by DocumentNode (rather than just by name) in commit 512804c:

client.refetchQueries({
  include: [queryObject],
  onQueryUpdated(obs, diff) {
    return obs.refetch();
  },
})

I'd like to merge this PR soon so I can start working on the docs (which aren't rendering on this branch), so let me know soonish if you have any additional feedback here. Thanks!

[brainkim]

lgtm 🎉