TypeScript Mutation Snippets

[jlarmstrongiv]

Previous work:

• mutationOptions
• useOptimisticMutation variations from Dominik and Ganbin

My variations of the functions:

useOptimisticMutation

import {
  queryOptions,
  useMutation,
  useQueryClient,
  type QueryKey,
  type DataTag,
  type MutationOptions,
} from "@tanstack/react-query";

type Updater<TQueryFnData, TVariables> = (
  oldData: TQueryFnData | undefined,
  variables: TVariables
) => TQueryFnData | undefined;

type TRollbackContext = () => void;

type UseOptimisticMutationParameters<
  TData = unknown,
  TError = Error,
  TVariables = unknown,
  TQueryKey extends QueryKey = QueryKey,
  TQueryFnData = unknown,
> = {
  queryKey: TQueryKey;
  updater: Updater<TQueryFnData, TVariables>;
  invalidates: QueryKey;
} & Omit<
  MutationOptions<TData, TError, TVariables, TRollbackContext>,
  "onMutate" | "onError" | "onSettled"
>;

const useOptimisticMutation = <
  TData = unknown,
  TError = Error,
  TVariables = unknown,
  TQueryKey extends QueryKey = QueryKey,
  TQueryFnData = unknown,
  TInferredQueryFnData = TQueryKey extends DataTag<unknown, infer TaggedValue>
    ? TaggedValue
    : TQueryFnData,
>({
  queryKey,
  updater,
  invalidates,
  ...options
}: UseOptimisticMutationParameters<
  TData,
  TError,
  TVariables,
  TQueryKey,
  TInferredQueryFnData
>) => {
  const queryClient = useQueryClient();

  return useMutation({
    onMutate: async (variables) => {
      await queryClient.cancelQueries({
        queryKey,
      });

      const snapshot = queryClient.getQueryData(queryKey);

      queryClient.setQueryData<TInferredQueryFnData>(queryKey, (old) =>
        updater(old, variables)
      );

      return () => {
        queryClient.setQueryData(queryKey, snapshot);
      };
    },
    onError: (_err, _variables, rollback) => {
      rollback?.();
    },
    onSettled: () => {
      return queryClient.invalidateQueries({
        queryKey: invalidates,
      });
    },
    ...options,
  });
};

// example usage

type Todo = { id: number; done: boolean; name: string };

const listOptions = queryOptions({
  queryKey: ["todos", "list", { sort: "asc" }],
  queryFn: (): Promise<Array<Todo>> => Promise.resolve([]),
});

const toggleTodo = (id: number) =>
  Promise.resolve({ id, done: true, name: "" });

const { data, mutate } = useOptimisticMutation({
  mutationFn: toggleTodo,
  queryKey: listOptions.queryKey,
  updater: (previousTodos, id) =>
    previousTodos?.map((todo) =>
      todo.id === id ? { ...todo, done: !todo.done } : todo
    ),
  invalidates: ["todos", "list"],
});

mutate(5);

optimisticMutationOptions

import {
  queryOptions,
  useMutation,
  useQueryClient,
  type QueryClient,
  type QueryKey,
  type DataTag,
} from "@tanstack/react-query";
import { mutationOptions, type CreateMutationOptions } from "./mutationOptions";

type Updater<TQueryFnData, TVariables> = (
  oldData: TQueryFnData | undefined,
  variables: TVariables
) => TQueryFnData | undefined;

type TRollbackContext = () => void;

type OptimisticMutationOptionsParameters<
  TData = unknown,
  TError = Error,
  TVariables = unknown,
  TQueryKey extends QueryKey = QueryKey,
  TQueryFnData = unknown,
> = {
  queryClient: QueryClient;
  queryKey: TQueryKey;
  updater: Updater<TQueryFnData, TVariables>;
  invalidates: QueryKey;
} & Omit<
  CreateMutationOptions<TData, TError, TVariables, TRollbackContext>,
  "onMutate" | "onError" | "onSettled"
>;

const optimisticMutationOptions = <
  TData = unknown,
  TError = Error,
  TVariables = unknown,
  TQueryKey extends QueryKey = QueryKey,
  TQueryFnData = unknown,
  TInferredQueryFnData = TQueryKey extends DataTag<unknown, infer TaggedValue>
    ? TaggedValue
    : TQueryFnData,
>({
  queryClient,
  queryKey,
  updater,
  invalidates,
  ...options
}: OptimisticMutationOptionsParameters<
  TData,
  TError,
  TVariables,
  TQueryKey,
  TInferredQueryFnData
>) => {
  return mutationOptions({
    onMutate: async (variables) => {
      await queryClient.cancelQueries({
        queryKey,
      });

      const snapshot = queryClient.getQueryData(queryKey);

      queryClient.setQueryData<TInferredQueryFnData>(queryKey, (old) =>
        updater(old, variables)
      );

      return () => {
        queryClient.setQueryData(queryKey, snapshot);
      };
    },
    onError: (_err, _variables, rollback) => {
      rollback?.();
    },
    onSettled: () => {
      return queryClient.invalidateQueries({
        queryKey: invalidates,
      });
    },
    ...options,
  });
};

// example usage

const queryClient = useQueryClient();

type Todo = { id: number; done: boolean; name: string };

const listOptions = queryOptions({
  queryKey: ["todos", "list", { sort: "asc" }],
  queryFn: (): Promise<Array<Todo>> => Promise.resolve([]),
});

const toggleTodo = (id: number) =>
  Promise.resolve({ id, done: true, name: "" });

const { data, mutate } = useMutation(
  optimisticMutationOptions({
    queryClient,
    mutationFn: toggleTodo,
    queryKey: listOptions.queryKey,
    updater: (previousTodos, id) =>
      previousTodos?.map((todo) =>
        todo.id === id ? { ...todo, done: !todo.done } : todo
      ),
    invalidates: ["todos", "list"],
  })
);

mutate(5);

If you have any improvements, please share!

An example that supports multiple queryKeys and updaters would be interesting.

I hope mutationOptions becomes stable soon.

[Ganbin]

Thanks for the work.

After working again with my version, I noticed that the updater first parameter is always unknown type and thus break my code.

Here is an example

useOptimisticMutation<Item, Error, Omit<Item, "id">, string[] & {
    [dataTagSymbol]: Item[];
    [dataTagErrorSymbol]: Error;
}, unknown, unknown>({ queryKey, updater, invalidates, ...options }:

We can see that TInferredQueryFnData is unknown
I tried your version and the same happen. I'm not sure why I get this error, while I'm sure I didn't have it previously.

It should be inferred as TInferredQueryFnData but it is always unknown. Not sure what is going on.

In this line : updater(old, variables) I got this type for old : old: NoInfer<TInferredQueryFnData> | undefined

Do you have any clue?

[Ganbin]

I finally found the issue, I needed to write it here to find it just after 😄. The issue was with DataTag that needed a third argument : DataTag<unknown, infer TaggedValue, unknown>

Code

import {
  queryOptions,
  type DataTag,
  type MutationFunction,
  type QueryKey,
  useMutation,
  useQueryClient,
} from "@tanstack/react-query";

type OptimisticProps<
  TData = unknown,
  TVariables = unknown,
  TQueryKey extends QueryKey = QueryKey,
  TQueryFnData = unknown,
> = {
  invalidates: QueryKey;
  mutationFn: MutationFunction<TData, TVariables>;
  queryKey: TQueryKey;
  updater: Updater<TQueryFnData, TVariables>;
};

type Updater<TQueryFnData, TVariables> = (
  oldData: TQueryFnData | undefined,
  variables: TVariables,
) => TQueryFnData | undefined;

const useOptimisticMutation = <
  TData = unknown,
  TVariables = unknown,
  TQueryKey extends QueryKey = QueryKey,
  TInferredQueryFnData = TQueryKey extends DataTag<
    unknown,
    infer TaggedValue,
    unknown
  >
    ? TaggedValue
    : unknown,
>({
  invalidates,
  mutationFn,
  queryKey,
  updater,
}: OptimisticProps<TData, TVariables, TQueryKey, TInferredQueryFnData>) => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn,
    onMutate: async (variables) => {
      await queryClient.cancelQueries({
        queryKey,
      });

      const snapshot = queryClient.getQueryData(queryKey);

      queryClient.setQueryData<TInferredQueryFnData>(queryKey, (old) =>
        updater(old, variables),
      );

      return () => {
        queryClient.setQueryData(queryKey, snapshot);
      };
    },
    // onError must come after onMutate in order for rollback to be correctly typed
    // eslint-disable-next-line perfectionist/sort-objects
    onError: (_err, _variables, rollback) => {
      rollback?.();
    },
    onSettled: () => {
      queryClient.invalidateQueries({
        queryKey: invalidates,
      });
    },
  });
};
export { useOptimisticMutation };



// usage:

type Todo = { id: number, done: boolean, name: string }

const listOptions = queryOptions({
  queryKey: ['todos', 'list', { sort: 'asc' }],
  queryFn: (): Promise<Array<Todo>> => Promise.resolve([])
})

const toggleTodo = (id: number) => Promise.resolve({ id: 5, done: true, name: '' })

const { data, mutate } = useOptimisticMutation({
   mutationFn: toggleTodo,
   queryKey: listOptions.queryKey,
   updater: (previousTodos, id) => previousTodos?.map((todo) =>
     todo.id === id
       ? { ...todo, done: !todo.done }
       : todo
   ),
   invalidates: ['todos', 'list'],
 })

 mutate(5)

Output

import { queryOptions, useMutation, useQueryClient, } from "@tanstack/react-query";
const useOptimisticMutation = ({ invalidates, mutationFn, queryKey, updater, }) => {
    const queryClient = useQueryClient();
    return useMutation({
        mutationFn,
        onMutate: async (variables) => {
            await queryClient.cancelQueries({
                queryKey,
            });
            const snapshot = queryClient.getQueryData(queryKey);
            queryClient.setQueryData(queryKey, (old) => updater(old, variables));
            return () => {
                queryClient.setQueryData(queryKey, snapshot);
            };
        },
        // onError must come after onMutate in order for rollback to be correctly typed
        // eslint-disable-next-line perfectionist/sort-objects
        onError: (_err, _variables, rollback) => {
            rollback === null || rollback === void 0 ? void 0 : rollback();
        },
        onSettled: () => {
            queryClient.invalidateQueries({
                queryKey: invalidates,
            });
        },
    });
};
export { useOptimisticMutation };
const listOptions = queryOptions({
    queryKey: ['todos', 'list', { sort: 'asc' }],
    queryFn: () => Promise.resolve([])
});
const toggleTodo = (id) => Promise.resolve({ id: 5, done: true, name: '' });
const { data, mutate } = useOptimisticMutation({
    mutationFn: toggleTodo,
    queryKey: listOptions.queryKey,
    updater: (previousTodos, id) => previousTodos === null || previousTodos === void 0 ? void 0 : previousTodos.map((todo) => todo.id === id
        ? Object.assign(Object.assign({}, todo), { done: !todo.done }) : todo),
    invalidates: ['todos', 'list'],
});
mutate(5);

Compiler Options

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictPropertyInitialization": true,
    "strictBindCallApply": true,
    "noImplicitThis": true,
    "noImplicitReturns": true,
    "alwaysStrict": true,
    "esModuleInterop": true,
    "declaration": true,
    "target": "ES2017",
    "jsx": "react",
    "module": "ESNext",
    "moduleResolution": "node"
  }
}

Playground Link: Provided

[Ganbin]

For a follow up this is since this commit 4989399