optimistic updates requiring hinting params

[ashen gate]

When writing an optimistic update for a mutation, its common to be optimistically updating a query that accepts different parameters to the mutation you are performing. this means that the 2nd parameter of withOptimisticUpdate rarely has all the fields required for the optimistic part of the update. so when defining a custom hook to do that, its hard to optimise it heavily. is there an accepted solution/pattern for this problem? do i have to go around adding optional params as hinting params to all my mutations?

[tepid mason]

Hi @ashen gate. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

The knowledge sources don’t describe a formal “accepted pattern” for adding extra / hinting params to mutation args just to support optimistic updates, so I can’t point to an official recommendation either way.

What is documented is:

• An optimistic update only receives two things: the localStore and the mutation’s args. [OptimisticUpdate; ReactMutation]
• You’re expected to derive everything you need for the local update from those args (plus whatever is already in the localStore). [React optimistic]

In the complex chat example, they simply pass exactly the fields they need for the optimistic update (channel, body) as mutation args, and then use those directly in the optimistic update to find and update the right query: [React optimistic]

const sendMessage = useMutation(api.messages.send).withOptimisticUpdate(
  (localStore, args) => {
    const { channel, body } = args;
    const existingMessages = localStore.getQuery(api.messages.list, { channel });
    if (existingMessages !== undefined) {
      const now = Date.now();
      const newMessage = {
        _id: crypto.randomUUID() as Id<"messages">,
        _creationTime: now,
        channel,
        body,
      };
      localStore.setQuery(api.messages.list, { channel }, [
        ...existingMessages,
        newMessage,
      ]);
    }
  },
);

So, based on the docs:

• There’s no alternative hook signature or pattern where the optimistic update gets extra context beyond the mutation args.
• The examples do model “hinting” data as part of the mutation args when it’s needed for optimistic updates (e.g. channel above).

Given that, the documented approach is effectively:

• Design your mutation arguments to include whatever you’ll need both on the server and in the optimistic update.
• If that means adding some fields that are only used client‑side for optimistic behavior, the docs don’t show a different pattern to avoid that.

If you’re trying to build reusable/custom hooks around withOptimisticUpdate, the sources don’t show a more advanced pattern (like a third parameter or a context object), so I can’t suggest anything beyond composing helpers that still ultimately take (localStore, args) and derive what they need from there.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: