Storage and invalidation for custom field read functions.

[benjamn]

Custom field read functions might need to perform expensive computations, so caching the results of read functions is encouraged. Unfortunately, there is no good way for the InMemoryCache to provide that caching automatically, since read function results could depend on any/all/some/none of the arguments passed to the field, and only the application developer knows which arguments are important.

At this point you might be thinking, "Doesn't the developer already have an opportunity to tell the cache which arguments are important by configuring keyArgs: [...] in the field policy?" While that statement is true, it's only the beginning of the story. When you specify keyArgs, you're telling the cache how to distinguish multiple values for a given field, but the read and merge functions have access to the complete set of arguments, so keyArgs alone is not enough to differentiate between all possible read function return values.

In fact, a common pattern when implementing custom read and merge functions is to pass keyArgs: false to disable the default argument-based differentiation entirely, so the read and merge functions can take full responsibility for interpreting the arguments passed to the field. In this common scenario, the cache knows nothing about how read results should be stored. In short, read function caching is a responsibility that must be left to the read function.

To resolve this seemingly unresolvable conundrum, I've adopted a simple but flexible policy: every read function now has access to a private options.storage object, which is a Record<string, any> where the read function can stash any information it wants to preserve across multiple invocations of the read function. This options.storage object is unique to the current entity object and the current field name (plus any additional information specified via keyArgs). In other words, you can think of this options.storage object as storing mutable metadata about the immutable existing field value.

Here's an example of a cached read function for a WorkItem.expensiveResult field:

const cache = new InMemoryCache({
  typePolicies: {
    WorkItem: {
      fields: {
        expensiveResult: {
          keyArgs: false, // read function assumes full responsibility for args handling
          read(existing, { args, storage }) {
            const key = makeKeyFromArgs(args); // user-defined
            if (key in storage) return storage[key];
            return storage[key] = expensiveComputation(existing, args);
          },
        },
      },
    },
  },
});

To complement the options.storage object, this PR also introduces an options.invalidate() function that can be called to invalidate any cached query results that previously consumed the field value, which is especially useful when the read function uses external data sources that might change over time. Specifically, calling invalidate() will invalidate any results that were computed using the same options.storage object:

const cache = new InMemoryCache({
  typePolicies: {
    WorkItem: {
      fields: {
        expensiveResult: {
          keyArgs: false,
          read(existing, { args, storage, invalidate }) {
            const key = makeKeyFromArgs(args);
            if (key in storage) return storage[key];
            // Suppose the expensiveComputation takes a callback function that will
            // be called whenever the result of the computation may have changed:
            return storage[key] = expensiveComputation(existing, args, newResult => {
              // If a new result is not available, delete storage[key] instead.
              storage[key] = newResult;
              invalidate();
            });
          },
        },
      },
    },
  },
});

Finally, this PR renames the options.getFieldValue helper function to options.readField, and allows it to invoke custom read functions for any fields that it reads, rather than just retrieving the existing field value. See the commit message and tests included in 5219e36 to understand why this change was important.

[benjamn]

I like this pattern of exporting just the inferred return type of a function, without exporting the function itself.

[benjamn]

We could keep passing in the typename (with a default expression fallback), since we always have to call getFieldValue<string>(objectOrReference, "__typename") in executeSelectionSet, which is the primary caller of this method. That would make reading fields that don't have custom read functions a tiny bit faster.

[benjamn]

In order to be really useful, the options.invalidate function should also schedule a cache.broadcastWatches() call. I'll tackle that in a follow-up PR.

[benjamn]

This is a long test, but I think it's worth reading through it to get a sense for what it's like to implement highly dynamic custom read functions in terms of other custom read functions.

[hwillson]

This looks great @benjamn - super useful! Just a quick note while we're working on the docs: the idea of using a cache (StorageType) while working with the cache (InMemoryCache) might confuse people as they ramp up with the new cache API, so we'll want to make sure this is addressed clearly. Thanks!

[hwillson]

I'm wondering if the use invalidate to help deliver asynchronous results mention here might confuse people, without more context. These are code comments so maybe not (as people in here are grokking the source at the same time), but since we're mentioning it we might want to add another sentence or two that expands on this.