RFC: Debugging client-cache issues

[Jovi De Croock]

Summary

We have two types of caches that can be used the document cache and the normalised cache. In the document cache we track the __typename properties contained in operations, when a mutation passes by we check the affected __typename and clear those cache entries, any active query will be refetched and our application is fresh again. With a normalised cache we store all entries and mutations will be attempted to reconcile with the data in-memory, custom updaters, resolvers, ... can be written to do advanced reconciliation.

Each has their own set of issues, for instance when we are dealing with the document cache we can have issues with queries that return null or an empty array as we can't derive any __typename properties for them and mutations that return a scalar value won't be used to derive the affected types. In a normalised cache we face the issue that when we do a create mutation that we need a custom updater and similar when a scalar value is returned.

Proposed Solution

We wrap the document cache to warn folks for when a scalar value is returned from a mutation so that they are aware of a potential need for context.additionalTypenames and we warn for when an empty array/null value is returned.

For the normalised cache we do something similar that when we perform a mutation and we can't find the entity in cache that we warn the user, this could prompt them to write a custom updater and similarly when we see a scalar value returned we warn.

These warnings should be disabled in production environments and are means to guide our users to cache issues before they can reach production.