Optimistic Updates - a proof of concept / demo / call for ideas

[JonLoesch]

So I've been plugging away at this concept for a bit, and I'm curious what people think. It involves optimistic updates, or the idea of updating data in the cache of a query based of the prospective state of a mutation. Here's the link to the to the official docs section on this subject.

I'm really bad at being direct and to the point, but I'll try. Here's my three main points about how this proof of concept does things:

1 - It is done application wide once, instead of having it passed in everywhere where you run a certain mutation (this would mainly matter if you have the same mutation being used in multiple places)
2 - It uses an "immutable data mapper" (or function of type signature (data: Immutable<T>) => Immutable<T>) as its core abstraction. These functions are inserted into a post-fetch step in the TanStack Query process, and this means that it handles plenty of race conditions completely (two mutations at once, query while mutation is active, etc...)
3 - It interfaces with @tanstack/query-core instead of @tanstack/react-query. This means that the optimization logic doesn't have to worry about react hooks, or any other UI framework at all.

I started this project as a TRPC plugin and I was focused on point #1. But as the idea has evolved I think it's more appropriate at the TanStack Query level, and I think actually points #2 and #3 are way more important than #1. So I'm starting a new discussion about it here.

Here's what optimistic update logic might look like in my system:

queryClient = new InjectableQueryClient();
    // ^ the magic (a subclass of QueryClient, although that's an implementation detail)


queryClient.optimisticData({
  // call this function for a single (mutation => query) data pair.
  // this should probably happen somewhere near where you instantiate
  // the queryClient before providing it to the rest of the application.
  // can call as many times as necessary to set up all your optimistic logic at once
  from: { mutationKey: ["addTodo"] },
  to: { queryKey: ["todos"] },
  emptyDefaultIfMutationBeforeQuery: [],
  inject: (valueFromServer, mutationState) => {
    if (mutationState.isError) {
      return stopInjection;
      // a signal to remove this injection function from
      // the list of post-fetch processors attached to the query

      // technically this is already handled by the library so this
      // if branch is unnecessary, but I'm leaving it in the example for clarity
    } else if (
      mutationState.isSuccess &&
      valueFromServer.find((x) => x.id === mutationState.data.id)
    ) {
      return stopInjection;
      // a signal to remove this injection function from
      // the list of post-fetch processors attached to the query
    } else {
      return [...valueFromServer, { ...mutationState.variables }];
      // until we stop, inject that the parameters to this mutation 
      // are at the end of the list.  obviously this only works if
      // they have the same types
    }
  },
});



// And then in your component it's as simple as (for example):
const mutation = useMutation({mutationKey: ['addTodo']});
mutation.mutate({content: 'content'});

I'll stop the explanation there. If you want to see a whole lot more excruciating over-explained detail, there's a github repo I published as a POC. But there's a lot there and it's messy (And it's also incomplete and the example code doesn't line up exactly. And it works via some really hacky javascript modification of prototypes to extend functionality. Crucially though, it does actually work).

So here's my question for the TanStack community: Should I pursue this as an optional componion module for tanstack query? Or as a fork/PR? Or at all?