Allow passing function to useQuery for finer-grained options control

[benjamn]

A pretty serious limitation of the useQuery(query, options) API is that it encourages passing a fresh bag of options as the second parameter every time the component (re)renders, potentially overwriting previous options from previous renders, with no way to tell which options should be taken merely as default values and which should override existing options. This ambiguity becomes especially problematic when options like options.fetchPolicy are updated elsewhere, but that work is undone the next time useQuery(query, { fetchPolicy: <original policy> }) is called:

useQuery(QUERY, {
  // Was this just a default value, or should it become the new fetch policy?
  // With the current useQuery API, there's no safe way to guess!
  fetchPolicy: "cache-and-network",
})

A more minor problem with the useQuery options API is that it's somewhat wasteful (in time and memory) to recreate a new options object on every render, even if it will be safely ignored/discarded. The garbage still has to be collected, so it would be convenient (when it matters) to have a way to avoid recreating options unnecessarily.

This PR introduces the option of passing a function as the second parameter to useQuery, which will be immediately invoked with the existing/current options (an empty object on first render), and should return new options (possibly including some unchanged existing options) to be merged with the existing options.

Crucially, this functional style allows taking existing options into account when determining the new options to use, which means it's now possible to (re)use existing options as default values:

useQuery(QUERY, ({
  fetchPolicy = "cache-and-network",
  notifyOnNetworkStatusChange = true,
}) => ({
  // This option defaults to "cache-and-network" if not previously defined.
  fetchPolicy,

  // This option defaults to true if not previously defined.
  notifyOnNetworkStatusChange,

  // It's probably a good idea to pass fresh onCompleted and/or onError functions,
  // since the callbacks from previous options may have the wrong closure/scope.
  onCompleted() {...},
}))

This function defaults to the current options.fetchPolicy and options.notifyOnNetworkStatusChange to avoid overriding them on subsequent renders, but overrides onCompleted unconditionally.

Note that you do not need to worry about capturing/preserving ...rest properties, as that happens automatically, thanks to merging the returned options with the existing options (mentioned above):

useQuery(QUERY, ({
  fetchPolicy = "cache-and-network",
  ...otherOptions, // Not necessary!
}) => ({
  fetchPolicy,

  // Not necessary, because returned options will be merged with existing options,
  // so existing options remain unchanged by default.
  ...otherOptions,
}))

However, if you really want to take control of things, you can skip this automatic merging by modifying the existing options object and returning it === as given:

useQuery(QUERY, existingOptions => {
  if (typeof existingOptions.fetchPolicy === "undefined") {
    existingOptions.fetchPolicy = "network-only";
  }
  // Perform any other modifications to existingOptions before returning it,
  // including deleting properties...
  return existingOptions;
})

If you only need to provide default values (a common use case) rather than forcing any options (like onCompleted), you could imagine implementing a defaultOptions helper function that makes this a bit more ergonomic:

useQuery(QUERY, defaultOptions({
  fetchPolicy: "cache-and-network",
  notifyOnNetworkStatusChange: true,
}))

I'll leave that implementation as an exercise for the reader, since this description is already running a bit long.

This PR is still a draft because I need to write tests and documentation, but I wanted to get it out there for discussion sooner rather than later.

[benjamn]

Most of this increase comes from #9459, where I have not updated the npm run bundlesize limit yet. The actual net increase from this PR is +0.05kB.

[benjamn]

@hwillson @brainkim I've rebased this PR against the branch for #9459, so we're ready to merge this PR into release-3.6 soon after we merge that PR. I also added a handful of basic tests, so this PR is easier to review and safer to merge.

[hwillson]

Thanks @benjamn, looks great! We'll need docs for this but we can add those after this is merged. Honestly your great PR description could probably just be dropped in the docs as is!