Support InMemoryCache({ freezeResults: true }) to help enforce immutability.

[benjamn]

Part of the plan I outlined in this comment: #4464 (comment)

If we could trust application code not to modify cache results, we wouldn't have to save deep snapshots of past results in order to implement isDifferentFromLastResult correctly (see #4069).

Aside: why doesn't the cache just return defensive copies of all results? #4031 (comment)

While you might agree that immutability is a worthwhile aspiration, it can be hard to maintain that discipline across your entire application over time, especially in a team of multiple developers.

This commit implements a new freezeResults option for the InMemoryCache constructor, which (when true) causes all cache results to be frozen in development, so you can more easily detect accidental mutations.

Note: mutating frozen objects only throws in strict mode, whereas it fails silently in non-strict code. ECMAScript module code automatically runs in strict mode, and most module transforms add "use strict" at the top of the generated code, so you're probably already using strict mode everywhere, though you might want to double-check.

The beauty of this implementation is that it does not need to repeatedly freeze entire results, because it can shallow-freeze the root of each subtree when that object is first created.

Thanks to result caching, those frozen objects can be shared between multiple different result trees without any additional freezing, and the entire result always ends up deeply frozen.

The freezing happens only in non-production environments, so there is no runtime cost to using { freezeResults: true } in production. Please keep this in mind when benchmarking cache performance!

[hwillson]

Great solution @benjamn - thanks!

[lifeiscontent]

@benjamn can you share an example of what you should do versus what not to do when this option is enabled? I just want to understand the responsibilities necessary for this option in the different surface areas of apollo.

[benjamn]

@lifeiscontent There's a quick example in the Apollo Client 2.6 blog post, in the Rewarding immutability section.

Don't do this:

const data = client.readQuery({
  query: CommentQuery,
});

// Destructive!
data.comments.push(newComment);

client.writeQuery({
  query: CommentQuery,
  data,
});

Do this instead:

const data = client.readQuery({
  query: CommentQuery
});

client.writeQuery({
  query: CommentQuery,
  data: {
    ...data,
    comments: [
      ...data.comments,
      newComment,
    ],
  },
});

Also, if your bundling tools are not already adding "use strict" to the top of your modules, you should find a way to do that, so that mutations of frozen objects will throw (in development), instead of failing silently.

[lifeiscontent]

@benjamn wow, I didn't know about the post, the future of Apollo looks awesome. 🤩