Reason to use writeFragment instead of toReference

[sebakerckhof]

This is just a remark:

I was looking in the documentation where it says:

The modifier function's second parameter includes an undocumented helper function called toReference, which essentially does the same thing as the entire cache.writeFragment block above. It's much easier to use and produces cleaner and more maintainable code. I am not aware of any reason to use cache.writeFragment in favour of this.

But there is actually a reason to use writeFragment. The problem is that toReference will only deal with scalars. So if you have any custom types (e.g. dates), these will not end up correctly in the cache. writeFragment, although way more verbose, does take care of that.
This is explained by an Apollo dev a bit more extensive here: apollographql/apollo-client#6289 (comment)

[mindnektar]

Hi, thanks so much for your heads-up! I've read through the comment you've linked and its follow-ups, and I can't help but wonder if the described problems are only relevant if you call cache.modify in isolation - meaning not as a reaction to a graphql request. I don't have a single call to cache.writeFragment anywhere in my code, and I've never run into any of these problems before, but I'm also only using cache.modify via the modifiers option in apollo-augmented-hooks' useMutation and useSubscription hooks. That means it only ever gets called after a mutation response or a subscription message comes in. And in both of these cases, @apollo/client is taking care of the cache.writeFragment call internally. Even without calling cache.modify, the mutation response or the subscription message will always end up in the in-memory cache automatically. With cache.modify, I only decide how the cache item is going to be referenced elsewhere.

If you call cache.modify where there is no automatic cache.writeFragment call beforehand, you will indeed have to take care of that yourself. The thing is, off the top of my head I can't think of a scenario where this is going to be necessary. I should probably still update the documentation with this caveat, though. If you have any further input on this topic, I'd be glad to hear it!

[sebakerckhof]

Ok, I think you're right, in the modifiers option it shouldn't make a difference.

I ran into this issue when indeed doing a cache.modify in isolation (some data that comes in over a websocket and should update the cache), but for the use-cases you mention it's indeed a non-issue.

[mindnektar]

Alright, great! I've updated the documentation accordingly (423cdbc). Thanks again for your input!