Implement a relayStylePagination field policy helper function.

[benjamn]

This helper function makes it very easy to consume paginated lists from Relay-friendly GraphQL servers, such as the Artsy search API:

import { InMemoryCache } from "@apollo/client"
import { relayStylePagination } from "@apollo/client/utilities"

const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        // The ["query"] argument keeps searches separated by args.query (but not
        // by any other arguments, since the field policy will handle them).
        search: relayStylePagination(["query"]),
      },
    },
  },
});

With this field policy in place, you never need to provide an updateQuery function when calling fetchMore for the Query.search field, since the merge function handles that logic far more reliably than any updateQuery function can. Also, you do not need to use any @connection directives in your queries for the field, because that information is expressed by the keyArgs passed to the relayStylePagination function (the ["query"] above).

I made this helper function an export of the @apollo/client/utilities entry point (along with concatPagination and offsetLimitPagination from #6464) so those functions will not be included in your application bundle unless you import and use them. We hope you will find them useable and useful, but we also encourage using them for guidance/inspiration when writing your own custom field policy helper functions.

Note that Apollo Client has no hard-coded logic for Relay connections, edges, nodes, pageInfo, cursors, or forward and backward pagination, because it doesn't need to know anything about these concepts. With enough care, anyone could write the field policy generated by this helper function, which is a considerable testament to the power and flexibility of field policies.

[benjamn]

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

@jbaxleyiii I'm not looking for a detailed review from you, but I thought you might like to see how well this ended up working.

[hwillson]

Wow, now that's a test! 😂 Looks great @benjamn - thanks!

[hwillson]

To be removed?

[mattlysf]

I can't see any documentation for this ["query"] keyArgs param to relayStylePagination; I have a screen that both does pagination against a relay-style connection API and refreshes the initial set of results periodically via a pollInterval option to the initial query. This option is the only way I've found to get those co-existing nicely, but I can't find any mention of it in the documentation.