I've released a package which attempts to make complex cache modification as painless as possible

You can find it here: apollo-augmented-hooks - npm

It also contains a guide on how exactly Apollo Cache works, what problems there are in large applications and how to solve them. The most prominent problem being how to update the cache if there are numerous parameterized queries. This is the guide: apollo-augmented-hooks/CACHING.md at master · appmotion/apollo-augmented-hooks · GitHub

There are also a couple of features improving query performance (reduced queries and cache inflation) that might be interesting to some people.

I would greatly appreciate feedback, particularly on the guides - I wish for them to be as easily understandable as possible, but I’ve spent so much time on the Apollo Cache in the last years that it’s occasionally difficult to see if I’m providing too much or too little information.

I hope I can lighten up some people’s days with this and make development in large graphql applications a bit easier.

4 Likes

@mindnektar Just wanted to say that this is absolutely incredible!

I’m hacking on RedwoodJS, a full-stack framework that comes configured with Apollo Client by default (the client is swappable, but it’s Apollo out-of-the-box), and since the framework puts a priority on DX, updating Apollo Client’s cache has always kind of stood out like a sore thumb.

I tried to shed some light on how the cache works with a post of my own: Configuring InMemoryCache, or making updates to the cache more tractable - RedwoodJS Community. I came to a similar realization that cached != referenced, and it wasn’t until I grasped parametrized queries did I sympathize with the “why isn’t my todo just being added to the todos?!” problem. I actually think there’s an error in that post now—I’m not converting the incoming todo to a reference, which is a point you bring up in one of your docs.

I want to reiterate that both your CACHING.md doc and your npm package are godsends. The CACHING.md doc alone is incredibly readable and rings with clarity.

I think I’m going to propose that as long as Redwood comes with Apollo Client out-of-the-box, that it also comes with your hooks package. At the very least I plan on referencing it in our documentation—I think it’ll save people countless hours.

I wrote this post mostly just to give you what I hope was effusive praise. But if you have any future plans for the package or any other thoughts around updating-the-cache DX, I’d love to hear them!

1 Like

Wow, thank you so much! That alone was more praise than I’d expected coming my way. :sweat_smile:

I firmly believe that Apollo does many things right, and most of the time developing with it is a real joy - but the road to get to that point was so rocky and painful that it took me several years of very gradually gaining a better understanding of cache manipulation. apollo-augmented-hooks is actually my second package for solving these issues (but the first one I open-sourced), and the first one is completely deprecated now and will never be made public, because while it mostly did the job for Apollo 2, I’d made some fundamentally wrong decisions building it based on an incomplete understanding of Apollo’s interna, and those bit me in the rearside when our application grew sufficiently large. With apollo-augmented-hooks, I feel confident that I went in the right direction this time. We’ve migrated about 75% of our application from the old package to the new one, and it’s a joy to behold how little actual cache modification code is needed to keep the application state up to date. It has become a lot more maintainable.

The issue is that the beauty and simplicity is still lost on someone who has an incomplete grasp of Apollo’s cache. My colleagues who were less experienced with Apollo still had trouble writing proper cache updates before I trained them or before I had written the caching guide. No matter how potentially easy it is to manipulate the cache, you’re required to internalize a lot of fundamentals before you can be efficient. That’s a shame, but I guess it’s the nature of cache invalidation and not something I can solve.

Thanks again for your kind words, and I’m thrilled that you’re planning to integrate/reference my package in Redwood!

As for my future plans: apollo-augmented-hooks has been developed primarily with our internal use cases in mind, but it is generic enough that any Apollo 3 user could benefit from it. That said, I’m looking forward to feedback from adopters, so I can learn if there are things that I’ve overlooked and fix them. For the time being, the package is feature-complete, but if I stumble across more ways to improve DX or add sensible performance features, I’ll happily do that. One thing I can imagine spending more time on down the road is pagination - the package already includes something to make pagination easier, but it is very opinionated and depends on a certain way for the server to be implemented, which is why I’ve marked it as experimental in the readme. If you can think of any suggestions, let me hear them!