I’ve been playing around with the svelte-query library lately and I’ve enjoyed its approach to caching and integrating mutations with queries. I’ve especially liked how its hooks make optimistic updates easy. (Note that this article should also apply to react-query with little change.)

Optimistic Updates 🔗

Traditionally, a web application implements mutations by sending a request to the server, waiting for the result, and then updating the UI appropriately.

This works fine, but the rise of client-side rendering allows for some nice tricks to make our applications more responsive. The optimistic update technique anticipates success and updates the interface immediately to reflect the anticipated state, even before the server has responded with the confirmation.

This makes for a snappy UI, but it requires extra care when handling errors. With the traditional method of waiting for the server to respond, we just show an error and then don’t have anything more to do. Here, we not only need to show an error, but also undo the optimistic update so that the display accurately reflects the state once again.

Base Implementation 🔗

The svelte-query documentation describes how to implement optimistic updates. This block of code is taken from the example.

import { useQueryClient, useMutation } from '@sveltestack/svelte-query';
const queryClient = useQueryClient();
useMutation(updateTodoFn, {
  // When mutate is called:
  onMutate: async (newTodo) => {
    // Cancel any outgoing refetches (so they don't overwrite our optimistic update)
    await queryClient.cancelQueries('todos');

    // Snapshot the previous value
    const previousTodos = queryClient.getQueryData('todos');

    // Optimistically update to the new value
    queryClient.setQueryData('todos', (old) => [...old, newTodo]);

    // Return a context object with the snapshotted value
    return { previousTodos };
  },
  // If the mutation fails, use the context returned from onMutate to roll back
  onError: (err, newTodo, context) => {
    queryClient.setQueryData('todos', context.previousTodos);
  },
  // Always refetch after error or success:
  onSettled: () => {
    queryClient.invalidateQueries('todos');
  },
});

This works well, but can get a bit inconvenient to write on every single mutation. We can abstract this out into a function to make it easier to enable optimistic updates on multiple mutations.

function mutationOptions({ key }) {
  let queryClient = useQueryClient();
  return {
    onMutate: async (newData) => {
      await queryClient.cancelQueries(key);
      let existingData = client.getQueryData(key);
      client.setQueryData((existing) => ({
        ...existing,
        [newData.id]: {
          ...newData,
          isUpdating: true,
        }
      });

      return { previousData };
    },
    onSettled: (data, error, variables, context) => {
      if(error) {
        queryClient.setQueryData(key, context.previousData);
        // In real code, also notify the user somehow.
      } else {
        // It succeeded, so just unset isUpdating.
        client.setQueryData((existing) => ({
          ...existing,
          [data.id]: data
        });
      }
    }
  };
}

Here we also have updated the function to set an isUpdating flag on an item, so that the UI can mark it specially until the update is complete.

Updating Multiple Queries 🔗

Sometimes a piece of data may reside in multiple queries. This mostly comes up when we have a query for a collection of items as well as a query for each individual item, and the svelte-query documentation provides an example of this. In this case, the optimistic update should update the item in both places.

The really nice thing about handling it this way is that we also automatically handle updating the data for real in both places, so there’s no risk of them getting out of sync.

Since not every mutation will need to update multiple queries, we can change mutationOptions to take a list of update functions, and also provide functions to handle the common cases.

Here’s a Svelte REPL example demoing the concept.

And now for a detailed walkthrough of the code.

import {
  QueryClient,
  QueryKey,
  UseMutationOptions,
  useQueryClient,
} from '@sveltestack/svelte-query';
import { HTTPError } from 'ky-universal';

export interface HasId {
  id: string | number;
}

export type DataRestorer = () => void;

export async function optimisticUpdateSingleton<T extends HasId>(
  client: QueryClient,
  key: QueryKey,
  data: T,
  isUpdating: boolean
): Promise<DataRestorer> {
  await client.cancelQueries(key);
  let original = client.getQueryData(key);
  client.setQueryData(key, { ...data, isUpdating });
  return () => client.setQueryData(key, original);
}

export async function optimisticUpdateCollectionMember<T extends HasId>(
  client: QueryClient,
  key: QueryKey,
  data: T,
  isUpdating: boolean
): Promise<DataRestorer> {
  await client.cancelQueries(key);
  let overall = client.getQueryData(key) || {};
  let originalItem = overall[data.id];

  client.setQueryData(key, {
    ...overall,
    [data.id]: {
      ...data,
      isUpdating,
    },
  });

  return () => client.setQueryData(key, (overall) => {
    if(originalItem) {
      return {
        ...overall,
        [data.id]: originalItem,
      };
    } else {
      // The item was absent in the original data, so just delete it.
      let { [data.id]: _, ...rest } = overall;
      return rest;
    }
  });
}

export async function optimisticDeleteCollectionMember<T extends HasId>(
  client: QueryClient,
  key: QueryKey,
  id: string,
  _isDeleting: boolean
): Promise<DataRestorer> {

await client.cancelQueries(key);
  let overall = client.getQueryData(key);
  let { [id]: originalItem, ...rest } = overall ?? {};
  client.setQueryData(key, rest);

  // The restore function puts the item back.
  return () => client.setQueryData((overall) => ({
    ...overall,
    [id]: originalItem,
  }));
}

export interface MutationOptions<
  DATA extends HasId,
  VARIABLES = DATA,
  CONTEXT extends { previousData?: DataRestorer[] } = {
    previousData?: DataRestorer[];
  }
> {
  /** Invalidate and refetch these query keys after the mutation is done. */
  invalidate?: (item: VARIABLES) => QueryKey[];
  /** A function that uses one or more of the optimisitic update functions above. */
  optimisticUpdates?: (
    client: QueryClient,
    item: VARIABLES,
    isUpdating: boolean
  ) => Promise<DataRestorer[]>;

  onMutate?: UseMutationOptions<
    DATA,
    HTTPError,
    VARIABLES,
    Omit<CONTEXT, 'previousData'>
  >['onMutate'];

  onSettled?: UseMutationOptions<DATA, HTTPError, VARIABLES, CONTEXT>['onSettled'];
}

export function mutationOptions<
  DATA extends HasId,
  CONTEXT extends { previousData?: DataRestorer[] } = {
    previousData?: DataRestorer[];
  }
>(
  options: MutationOptions<DATA, DATA, CONTEXT>
): Partial<UseMutationOptions<DATA, HTTPError, DATA, CONTEXT>> {
  let queryClient = useQueryClient();

  return {
    async onMutate(data: DATA) {
      let previousData: DataRestorer[] | undefined;

      if (options.optimisticUpdates) {
        previousData = await options.optimisticUpdates(queryClient, data, true);
      }

      let c = options.onMutate ? await options.onMutate(data) : {};
      return { ...c || {}, previousData };
    },
    async onSettled(data, error, variables, context) {

      if(error && context?.previousData) {
        // Undo the optimistic update
        for (let restorer of context.previousData) {
            restorer();
        }

      } else if(options.optimisticUpdates) {
        await options.optimisticUpdates(queryClient, data, false);
      }

      if(options.invalidate) {
        for (let key of options.invalidate(variables)) {
          queryClient.invalidateQueries(key);
        }
      }

      return options.onSettled?.(data, error, variables, context);
    },
  };
}

With all this in place, it’s relatively simple to create a mutation with optimistic updates for all the relevant queries.

export function updateTodoMutation() {
  return useMutation(
    (todo: Todo) =>
      ky.put(`api/todos/${todo.id}`, { json: todo }).json<Todo>(),
    mutationOptions({
      optimisticUpdates:
        (queryClient: QueryClient, todo: Todo, isUpdating: boolean) =>
          Promise.all([
            optimisticUpdateCollectionMember(queryClient, 'todos',
              todo, isUpdating),
            optimisticUpdateSingleton(queryClient, ['todos', todo.id],
              todo, isUpdating),
          ]),
    })
  );
}

Here the optimisticUpdates function just calls both optimisticUpdateSingleton and optimisticUpdateCollectionMember with the necessary parameters. There’s still a bit of boilerplate, but doing it this way makes it easy to add some custom behavior for a special case.

Deleting an item works similarly. We make a mutation in much the same way, but use optimisticDeleteCollectionMember instead.

An alternative version of the deletion function might add an isDeleting flag to the item, and then only actually remove it once the server confirms the deletion. This allows the application to look responsive, but prevents things from jumping around too much if a deletion fails.

Both approaches are valid; it mostly depends on how likely it is for the server to reject a deletion in your particular application.

So with that, we have a reusable system for building optimistic updates into our queries. With such a system in place, it’s easy to then add additional functionality to all mutations, such as notifications or error reporting.