Add options to cache.gc to enable deleting nonessential/recomputable result caching data

[benjamn]

Ever since #3394, InMemoryCache has taken an approach of trading memory for improved efficiency of repeated cache reads.

More recently (as of #7439), this result caching system also guarantees cache results will be canonical, a technique that uses memory to store previous canonical objects in an efficient lookup structure (the ObjectCanon), to speed up future deep equality comparisons.

Although we continue to believe this memory/speed tradeoff is appropriate in most cases, it is conceivable that you might at some point need to reclaim memory more urgently than you need cache performance.

To release all cached result objects (to be garbage collected by JavaScript if otherwise unused) without resetting any actual cache data, this PR allows calling the cache.gc (#5310) method with a new resetResultCache: true option:

cache.gc({
  resetResultCache: true,
});

By default, resetting the result cache will not reset the ObjectCanon, which provides === continuity of cache results even after the result caching system has been completely replaced (as it is when you pass resetResultCache: true to cache.gc). That preservation is pretty nifty, but if you also want to dump the ObjectCanon for maximum memory savings, then you should also pass resetResultIdentities: true to cache.gc:

cache.gc({
  resetResultCache: true,
  resetResultIdentities: true,
});

These cache.gc options are available only on InMemoryCache (not on ApolloCache), since result caching is an InMemoryCache-specific concept.

The resetResultCache and resetResultIdentities options were the first two options that seemed useful to me, but we can easily add additional options in the future.

[brainkim]

Wrote some thoughts. Again I’m not 100% familiar with how advanced caching stuff is supposed to work so my input is limited. My primary concerns are about the API design. Two new boolean options, which seem to be interrelated, and for an advanced use-case which might hard to search for/understand as a non-Apollo Client maintainer. Maybe we can loop in some advanced users like @sofianhn and the documentation team @StephenBarlow for their thoughts?

Also, if there are any relevant issues from users asking for this that I missed I’d love to see them as this could help with the design process.

[benjamn]

@brainkim Thanks for the review! I think I've addressed your concerns, including writing a FinalizationRegistry-based test that was initially failing before I fixed the bug it caught, so thanks again for that reminder/suggestion.