Provide more context to nextFetchPolicy functions

[benjamn]

We introduced options.nextFetchPolicy in PR #6712 to allow modifying options.fetchPolicy after first use, and later made the API more powerful by allowing nextFetchPolicy to be a function (PR #6893) which takes the current fetchPolicy and dynamically returns a new policy.

This more advanced functional version of nextFetchPolicy allows implementing a basic state machine where the various fetch policies (cache-first, network-only, etc) are the states, and the current fetchPolicy is the only input/event provided. When there's only one possible event (that is, the current fetchPolicy was just used to fetch the first result), you could argue it doesn't have to be explicitly provided to the state transition function (nextFetchPolicy), but then your state machine will probably be pretty limited/boring. Most state machines have several possible inputs/events triggering a variety of transitions between states, and Apollo Client is already starting to need more than one nextFetchPolicy event (see #8465).

This PR provides additional context to the nextFetchPolicy function as its second parameter (leaving the first parameter untouched for backwards compatibility):

export interface WatchQueryOptions<TVariables = OperationVariables, TData = any>
  extends Omit<QueryOptions<TVariables, TData>, 'fetchPolicy'> {
  /**
   * Specifies the {@link FetchPolicy} to be used for this query.
   */
  fetchPolicy?: WatchQueryFetchPolicy;
  /**
   * Specifies the {@link FetchPolicy} to be used after this query has completed.
   */
  nextFetchPolicy?: WatchQueryFetchPolicy | ((
    currentFetchPolicy: WatchQueryFetchPolicy,
    context: NextFetchPolicyContext<TData, TVariables>,
  ) => WatchQueryFetchPolicy);
}

export interface NextFetchPolicyContext<TData, TVariables> {
  reason:
    | "after-fetch"
    | "variables-changed";
  observable: ObservableQuery<TData, TVariables>;
  options: WatchQueryOptions<TVariables, TData>;
  initialPolicy: WatchQueryFetchPolicy;
}

The context.reason can currently be one of the following strings:

• after-fetch
  • Triggered after any fetch using the current options.fetchPolicy, allowing the usual transition from a network fetch policy like cache-and-network or network-only to a more cache-friendly policy like cache-first or cache-only.
• variables-changed
  • By default, when variables change, context.options.fetchPolicy gets reset to context.initialPolicy, as implemented in Improve processing of options.nextFetchPolicy #8465 to fix [v3.4 Regression] Changing variables uses nextFetchPolicy instead of fetchPolicy #8426. If you provide a nextFetchPolicy transition function, you can override this behavior by ignoring the variables-changed event.

As a consequence of these changes, one way to make sure nextFetchPolicy sticks permanently is to pass a function that ignores the provided fetchPolicy and context and always returns the same constant value:

client.watchQuery({
  query,
  fetchPolicy: "cache-and-network",
  nextFetchPolicy: (fetchPolicy, context) => "cache-first",
})

This is different from

client.watchQuery({
  query,
  fetchPolicy: "cache-and-network",
  nextFetchPolicy: "cache-first",
})

because the second version allows options.fetchPolicy to be reset back to cache-and-network when options.variables change, whereas the first will continually enforce cache-first.

This PR is still a draft because it obviously needs more tests and documentation.

[benjamn]

I expect this interface to continue growing as we come up with new reasons for applying nextFetchPolicy functions, and/or additional contextual information to help nextFetchPolicy make good decisions.

[dancrew32]

Will this change affect this scenario described here?

Wondering the behavior described in 4 will remain consistent:

Discovered that setting fetchPolicy in the useQuery hook, would implicitly set nextFetchPolicy with the same policy, but only if there were no defaultOptions set in the ApolloClient instance.

Thanks for your time and confirmation here.

[benjamn]

@dancrew32 Since you asked this question, I added some tests to verify the behavior should be the same as before, though it's possible I haven't understood/captured exactly what you mean. The tests exercise defaultOptions.watchQuery.nextFetchPolicy in a number of ways, for example. Please take a look at the new tests in src/core/__tests__/fetchPolicies.ts, try modifying them if you like, and let us know if anything seems worth adding to improve the test suite.

One difference that might be worth calling out: if (and only if) you were already using a nextFetchPolicy function (uncommon, but supported since #6893 or AC v3.2.0), that function will now be called to handle the variables-changed event as well as the after-fetch event, whereas previously the fetchPolicy was reset to its initial value when variables changed with no chance to intercept that (possibly unwanted) behavior. I'm mildly concerned this could be a breaking change for existing nextFetchPolicy functions that are not prepared to be called in the variables-changed case, though I'm hopeful most existing nextFetchPolicy functions map their own previous result to itself (so cache-first stays cache-first).

[dancrew32]

My organization has never needed nextFetchPolicy in any useQuery call sites, so this change shouldn't affect us. I can report back after we upgrade in the future, as I am interested in removing defaultOptions overrides in our ApolloClient instantiation. Thanks for getting back to me, testing, and documenting all of this.

[benjamn]

@hwillson @brainkim I added a number of tests here, so I believe this PR is now ready for review. Docs still to be written.

[benjamn]

@StephenBarlow It may be easier to review these docs changes after this PR is merged into release-3.6, unless you know off-hand how to enable the Netlify deploy previews for PRs targeting release-3.6?

[StephenBarlow]

@benjamn I think this looks good! Any small edits I might make can easily happen after 3.6 lands