Apollo Client and Throttling (Paging)

An example of using a paginated API to throttle updating the Apollo Client cache; a concrete example of creating an Apollo Link middleware.

This article closely resembles another article that I recently wrote; Apollo Client and Last Modified. It turns out that they address two separate performance issues related to querying large data sets. This article focuses on the first query and the earlier article on subsequent queries.

The Problem

Let us say we have a GraphQL server providing a query, books, that serves up books.

And we have a React application that executes this query; displaying a list of books.

Let us also say that we have a lot of books and the UI / UX requires that we display all the books; not paginated.

note: This example is artificial for simplicity; a better use case would be that we are required to query all the books for offline use.

The problem is that we load the application, the server has to gather and send the full list of books through a single API call to the React application; putting a high demand on both the server and network.

The Solution

The solution, maybe better said, a solution, is that we begin by adding two fields to the Book object / API:

• created: Unix timestamp of when the book was created
• isDeleted: Flag indicating if the book is deleted

note: The lastModified field is another Unix timestamp that is not relevant for this particular solution; left over from the earlier related article.

We then create a parameterized GraphQL query, booksPage, that returns books (ordered by the created date and isDeleted is false) starting at the supplied offset parameter and limited in length by the first parameter (creating a paginated API).

Observations:

• The key to this solution is that regardless of create, update, or delete operations, the list (ordered by created) of books is unchanged
• Created books are appended to end of the list
• Deleted books’ isDeleted flag is set; remains in the same point in the list
• A critical behavior is that the API first slices out all the books (including those with isDeleted true) in the range and then filters out those with isDeleted true

The React application consuming this API maintains global state:

• pageCount: A zero-index count of the next page (offset to offset plus a fixed limit) of books to download
• pageLoading: A boolean indicating if the API is loading
• pageError: A boolean indicating if the API had an error

On startup, the application loops through the pages to download all the books.

Observation:

• In this case, we use global state for pageLoading and pageError as there are multiple graphQL API calls (one per page) to download all the books.

The Code

The GraphQL server is available for download. It is a basic implementation of Apollo Server with an in-memory database of books; nothing particularly interesting. It serves up both the books and booksPage queries.

Likewise the React application is available for download. At its core, it is a manual implementation of Apollo Client (using React Hooks). It uses Redux for global state. A couple of interesting observations:

The Books (src/components/Books.tsx) component executes the books query (or at least appears to… wink wink).

import { useQuery } from '@apollo/react-hooks';
import React, { FC, useCallback } from 'react';
import { useSelector } from 'react-redux';
import { Book, BooksData, BOOKS } from '../graphql/books';
import { getPageError } from '../store/ducks/pageError';
import { getPageLoading } from '../store/ducks/pageLoading';
...
const Books: FC = () => {
  const pageError = useSelector(getPageError);
  const pageLoading = useSelector(getPageLoading);
  const { data, refetch } = useQuery<BooksData>(BOOKS)
...

Observation:

• Again, we are using the global pageLoading and pageError instead of the loading and error provided by useQuery

We see that it is indeed appears to be using the books query (src/graphql/books.ts):

...
export const BOOKS = gql`
  query books {
    books {
      author
      id
      title
    }
  }
`;
...

Using Apollo Client Developer Tools, it does also appear to be using the books query.

But… The actual API all sent to the GraphQL server is booksPage (and there are four of them). There is something tricky here!

Looking carefully at the ApolloClient configuration, src/graphql/client.ts, we see that it is using two custom modules: pageLink and pageErrorLink.

...
import pageLink from './pageLink';
import pageErrorLink from './pageErrorLink';
...
export default new ApolloClient({
  link: ApolloLink.from([
    pageErrorLink,
    pageLink,
    onError(({ graphQLErrors, networkError }) => {
...

These modules are an implementation of an Apollo Link middleware:

Apollo Link is a simple yet powerful way to describe how you want to get the result of a GraphQL operation, and what you want to do with the results. You’ve probably come across “middleware” that might transform a request and its result: Apollo Link is an abstraction that’s meant to solve similar problems in a much more flexible and elegant way.

— Apollo Team — Apollo Link

Looking carefully at pageLink (src/graphql/pageLink.ts), we can see that it is indeed mutating any call to the books query into booksPage; implemented in the mutateOperation function.

Likewise it is transforming the paged books response from booksPage into a valid response for the books query (returning all the books); implemented in the transformedData function. With the updated books query response, Apollo Client does the work to update the cache.

Also, the transformedData function, when not on the last page, queues up the next call to the books query; thus iterating through the pages.

Finally, pageErrorLink (src/graphql/pageErrorLink.ts), handles errors in the pagination.

Wrap Up

If nothing else, this article demonstrates the power of the Apollo Link middleware pattern