Hey Ahrnee, so I don’t believe there is any proper documentation for cache.modify yet… I got most of my information from Apollo Client pull requests, you can read some information about the up in this PR #5909. I’ve also found the unit tests to be helpful in learning how the new features work.

RE: References, here is a quite from Previewing the Apollo Client 3 Cache by Hugh Willson:

Previous versions of the InMemoryCache would generate identifiers for entities that lack one in order to enable normalization. In Apollo Client 3, theInMemoryCache uses a new, reference-ID-based approach that only normalizes entities that have an ID. Entities without an ID are instead stored within their parent object in the cache. Initial tests with production data sets show a dramatic reduction in cache size, and an increase in overall cache performance.

References are objects to that refer to items in the cache with just a reference ID, it’s a new strategy for managing the cache that is more lightweight… refs look like this: { __ref: <entity ID> } ,See 01e0cc5 where the Reference class was replaced with a { __ref: string } interface type. PR #5146 .

I have a apollo server/client 3 start kit called BrainStrike that has some code that may make it easier to follow, I have a test where I mock the cache and you can see how refs are stored, it’s quite different to AC2, see that mock here. The examples in this article are taken from that repo.

I’m sure there will be more official docs soon. Thanks for reading!