Deprecate fetchMore updateQuery function, and provide basic field policy helper functions

[benjamn]

What began as an attempt to fix #5951 ultimately turned into the realization that the updateQuery function used by fetchMore is worse in almost every way than an equivalent field policy merge function.

Not only do you have to pass updateQuery every time you call fetchMore, but that repetition encourages a dangerously simplistic strategy of just concatenating the arrays together.

By contrast, a field policy needs to be defined only once, operates at the field level rather than the query level, and has a chance to examine field arguments to guide the merging process. Also, the keyFields: false default configuration allows the field policy to avoid the awful fetchMore hack of cramming additional results into the original array (keyed by the original arguments, which fetchMore does not update).

Since we are in the RC phase of AC3 testing, we are not removing or changing the behavior of updateQuery at this time, but a warning will be displayed (in development, at most once) to encourage switching to a field policy.

The tests included in this PR contain numerous side-by-side examples of the transition from updateQuery to a field policy, using both concatPagination and offsetLimitPagination.

[benjamn]

@hwillson @jcreighton In observation of Juneteenth, please don't worry about reviewing this today!

[hwillson]

This looks awesome @benjamn, and I love the new pagination helpers! I think we're good to LGTM (pending a quick CHANGELOG update mentioning the updateQuery deprecation and new pagination helpers). Thanks!

[henryqdineen]

Is it realistic to call fetchMore() with the same args as the initial query? I assumed in this case there would be an offset argument or something. In that case would we need a custom read() function for this field? Thanks.

[henryqdineen]

Nevermind. I just realized how keyArgs: false allows this to work. Sorry to bother.

[rRaDuCaN]

Hi everyone, I want to create sort of pagination by leveraging fetchMore, it kind of works in some way but is not acceptable. Here is what I'm doing:
-> I got some departments with tons of products described in a query type Subdepartment {
name: String
limit: String
page(p: $p): [String]
}
By default, useQuery fetches the p1 page, const {data} = useQuery(aQuery, {variables: {p: 'p1'}, onComplete(){...}});
That's how fetchMore looks: fetchMore({query: aQuery}, variables: {p: "p2"});
That's the field policy for the query:

typePolicies: {
Query: {
fields: {
shopHomeFurnishing: {
merge(
existing = {},
incoming,
{ mergeObjects }
) {
console.log('existing: ', existing);
console.log('incoming: ', incoming);
return mergeObjects(existing, incoming);
}
},
}
}
}
Besides that I have some client state in this typePolicy

How it should work:

The acual behaviour:

the query is requested twice,
the first time: with p = "p2" variable
and after it: with p = "p1" variable
It's like first runs fetchMore, then after again useQuery.

However if I disable store initialization for fields with @client directory everything works. Anyone has a hint on it?

[Felix-Indoing]

While using 'fetchMore' bundle splitting is obvious since all the logic is inside the lazy components, which will be loaded as needed. If the user do not use the components, their related logic will not download.

How can we achieve code splitting with centralized field policy?

[benjamn]

@Felix-Indoing We are currently working on some documentation for that, though please read my review comments as well as the current draft documentation: #6766