Apollo Client and Last Modified

An example of using a lastModified value to incrementally update the Apollo Client cache; a concrete example of creating an Apollo Link middleware.

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. This application has a Refetch button that re-executes this query and thus updating the list.

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 each time we press the Refresh button, the server has to gather and send the full list of books 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:

• isDeleted: Flag indicating if the book is deleted
• lastModified: Unix timestamp of when the book was last modified

We then create a parameterized GraphQL query, booksUpdate, that returns books that have been updated (modified) on or since a supplied lastModified value.

The React application maintains state, a Unix timestamp initialized to 0, representing the last time it called the booksUpdate query; this value is supplied as the lastModified parameter for the query.

The first time the React application calls booksUpdate query (with a lastModified parameter of 0), the server will return all of the books and the React application simply caches them.

Subsequent times, the server will return only those books that have been modified since the supplied lastModified parameter. The React application iterates over the returned books and updates the cache (creating, updating, or deleting 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 booksUpdate queries.

Likewise the React application is available for download. At its core, it is a manual implementation of Apollo Client (using React Hooks). 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 { Book, BooksData, BOOKS } from '../graphql/books';
...
const Books: FC = () => {
  const { loading, error, data, refetch } = useQuery<BooksData>(BOOKS);
...

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 booksUpdate. There is something tricky here!

Looking carefully at the ApolloClient configuration, src/graphql/client.ts, we see that it is using an custom diffLink module:

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

The diffLink module is 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 diffLink (src/graphql/diffLink.ts), we can see that it is indeed mutating any call to the books query into booksUpdate; implemented in the mutateOperation function.

Likewise it is transforming the updated books response from booksUpdate 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.

Wrap Up

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