Ensure InMemoryCache#read{,Query,Fragment} always return T | null.

[benjamn]

Closes apollographql/apollo-feature-requests#1, by making cache.read no longer throw a MissingFieldError under any circumstances. This is a long-standing feature request that I partially addressed in #5930, but this commit goes all the way.

Since the current behavior (sometimes returning T, sometimes null, and sometimes throwing) has been in place for so long, we do not make this change lightly, and we should state precisely what is changing: in every case where cache.read would previously throw a MissingFieldError, it will now return null instead. We believe this change will be backwards-compatible because null was already a possible return value, so existing code should be prepared to handle null. However, this hypothesis will need to be verified empirically, using real applications.

Since these null results have the effect of hiding which fields were missing, you may wish to switch from cache.readQuery to cache.diff to gain more insight into why cache.read returned null. In fact, cache.diff (along with cache.watch) are the primary ApolloCache methods that Apollo Client uses internally, because the cache.diff API provides so much more useful information than cache.read provides.

If you would prefer to allow cache.read to return partial data rather than null, you can now pass returnPartialData: true to cache.readQuery and cache.readFragment, though the default must remain false instead of true, for the reasons explained in the code comments.

In the positive column, null should be easier to handle in update functions that use the readQuery/writeQuery pattern for updating the cache. Not only can you avoid wrapping cache.readQuery with a try-catch block, but you can safely spread ...null into an object literal, which is often something that happens between readQuery and writeQuery.

If you were relying on the exception-throwing behavior, and you have application code that is not prepared to handle null, please leave a comment here describing your use case. We will let these changes bake in AC3.3 betas until we are confident they have been adequately tested.

[hwillson]

Awesome, looks great @benjamn - thanks!

[chriswetterman]

@benjamn Thank you for providing the info about cache.diff. I was chasing an issue using optimisticResponse on a mutation to create an entity where I only have a couple fields the user creates but the response has a slew of additional data. Thanks to cache.diff I saw I was receiving 5 MissingFieldError's.

If I could ask, since the behavior of cache.readQuery has changed can the API docs be updated to include a portion on cache.diff and a reference made to utilize cache.diff for further information on why cache.readQuery may have returned null?

Thanks.

[josnin]

is there an equivalent of cache.diff for readFragment to debug which is causing to return null?