add helpers for mutation builder

Author: KurtGokhan

examples/vite/package.json

@@ -10,6 +10,7 @@
     "postinstall": "msw init"
   },
   "dependencies": {
+    "@tanstack/react-query-devtools": "^5.66.9",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-query-builder": "*"

examples/vite/src/App.tsx

@@ -67,6 +67,8 @@ function App() {
   const deletePost = deletePostMutation.useMutation();
   const reset = resetMutation.useMutation();
 
+  const deleteMutations = deletePostMutation.useAllMutations();
+
   const [refresh] = useOperateOnTags({ tags: ['refreshable'], operation: 'refetch' });
 
   if (postId) return <PostPage postId={postId} onBack={() => setPostId(null)} />;
@@ -106,6 +108,10 @@ function App() {
                   Delete
                 </button>
 
+                {deleteMutations.getMutation({ params: { id: post.id } })?.error && (
+                  <span style={{ color: 'red' }}>Error deleting post</span>
+                )}
+
                 <p>{post.body}</p>
               </div>
             ))}

examples/vite/src/client.tsx

@@ -5,6 +5,10 @@ export const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
       staleTime: 1000 * 60,
+      refetchOnWindowFocus: false,
+    },
+    mutations: {
+      gcTime: 5000,
     },
   },
   mutationCache: new BuilderMutationCache(

examples/vite/src/main.tsx

@@ -2,11 +2,13 @@ import { createRoot } from 'react-dom/client';
 import App from './App';
 import './index.css';
 import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import { queryClient } from './client';
 
 const app = (
   <QueryClientProvider client={queryClient}>
     <App />
+    <ReactQueryDevtools initialIsOpen={false} />
   </QueryClientProvider>
 );
 

examples/vite/src/mocks.ts

@@ -167,6 +167,9 @@ const handlers = [
   http.delete(`${baseUrl}/posts/:id`, async (req) => {
     await delay(1000);
     const { id } = req.params;
+    if (id === '7' && Math.random() > 0.1)
+      return HttpResponse.json({ error: '[Mock] Failed to delete' }, { status: 500 });
+
     const postIndex = posts.findIndex((post) => post.id === Number(id));
     if (postIndex === -1) return HttpResponse.json({ error: 'Not found' }, { status: 404 });
 

package-lock.json

@@ -2,18 +2,21 @@ import {
   MutationFilters,
   MutationFunction,
   MutationKey,
+  MutationState,
   QueryClient,
   UseMutationOptions,
   useIsMutating,
   useMutation,
+  useMutationState,
   useQueryClient,
 } from '@tanstack/react-query';
+import { useStableCallback } from '../hooks/useStableCallback';
 import { mergeTagOptions } from '../tags/mergeTagOptions';
 import { QueryInvalidatesMetadata } from '../tags/types';
 import { QueryBuilder } from './QueryBuilder';
 import { BuilderMergeVarsFn, BuilderQueryFn, SetDataType, SetErrorType } from './types';
 import { AppendVarsType, BuilderTypeTemplate } from './types';
-import { mergeMutationOptions, mergeVars } from './utils';
+import { areKeysEqual, mergeMutationOptions, mergeVars } from './utils';
 
 function getRandomKey() {
   return Math.random().toString(36).substring(7);
@@ -58,9 +61,8 @@ export class MutationBuilderFrozen<T extends BuilderTypeTemplate> {
     };
   };
 
-  getMutationKey: (vars: T['vars']) => MutationKey = (vars) => {
-    const mergedVars = this.mergeVars([this.config.vars, vars]);
-    return [this.mutationKeyPrefix, mergedVars];
+  getMutationKey: () => MutationKey = () => {
+    return [this.mutationKeyPrefix];
   };
 
   getMutationOptions: (
@@ -69,6 +71,7 @@ export class MutationBuilderFrozen<T extends BuilderTypeTemplate> {
   ) => UseMutationOptions<T['data'], T['error'], T['vars']> = (queryClient, opts) => {
     return mergeMutationOptions([
       {
+        mutationKey: this.getMutationKey(),
         mutationFn: this.getMutationFn(queryClient, opts?.meta),
         meta: {
           invalidates: this.config.invalidates,
@@ -81,6 +84,22 @@ export class MutationBuilderFrozen<T extends BuilderTypeTemplate> {
     ]);
   };
 
+  getMutationFilters: (
+    vars?: T['vars'],
+    filters?: MutationFilters<T['data'], T['error'], T['vars']>,
+  ) => MutationFilters<T['data'], T['error'], T['vars']> = (vars, filters) => {
+    return {
+      mutationKey: this.getMutationKey(),
+      ...filters,
+      predicate: (m) => {
+        if (filters?.predicate && !filters.predicate(m)) return false;
+        if (vars == null) return true;
+        if (!m.state.variables) return false;
+        return areKeysEqual([m.state.variables], [vars]);
+      },
+    };
+  };
+
   useMutation: (
     opts?: MutationBuilderConfig<T>['options'],
   ) => ReturnType<typeof useMutation<T['data'], T['error'], T['vars']>> = (opts) => {
@@ -92,7 +111,27 @@ export class MutationBuilderFrozen<T extends BuilderTypeTemplate> {
     vars,
     filters,
   ) => {
-    return useIsMutating({ mutationKey: this.getMutationKey(vars), ...filters }, this.config.queryClient);
+    return useIsMutating(this.getMutationFilters(vars, filters), this.config.queryClient);
+  };
+
+  useAllMutations: (filters?: MutationFilters<T['data'], T['error'], T['vars']>) => MutationStateHelper<T> = (
+    filters,
+  ) => {
+    const list = useMutationState({ filters: this.getMutationFilters(undefined, filters) }, this.config.queryClient);
+
+    const getMutation: MutationStateHelper<T>['getMutation'] = useStableCallback(
+      (vars, predicate?: (mutation: MutationState<T['data'], T['error'], T['vars']>) => boolean) =>
+        list.findLast((m) => areKeysEqual([m.variables], [vars]) && (!predicate || predicate(m))),
+    );
+
+    return { list, getMutation };
+  };
+
+  useMutationState: (
+    vars: T['vars'],
+    filters?: MutationFilters<T['data'], T['error'], T['vars']>,
+  ) => MutationState<T['data'], T['error'], T['vars']> | undefined = (vars, filters) => {
+    return useMutationState({ filters: this.getMutationFilters(vars, filters) }, this.config.queryClient)[0];
   };
 
   private _client?: MutationBuilderClient<T>;
@@ -101,14 +140,16 @@ export class MutationBuilderFrozen<T extends BuilderTypeTemplate> {
   }
 }
 
-class MutationBuilderClient<
-  T extends BuilderTypeTemplate,
-  TFilters = MutationFilters<T['data'], T['error'], T['vars']>,
-> {
+export type MutationStateHelper<T extends BuilderTypeTemplate> = {
+  list: MutationState<T['data'], T['error'], T['vars']>[];
+  getMutation(vars: T['vars']): MutationState<T['data'], T['error'], T['vars']> | undefined;
+};
+
+class MutationBuilderClient<T extends BuilderTypeTemplate> {
   constructor(private builder: MutationBuilderFrozen<T>) {}
 
-  readonly isMutating = (vars: T['vars'], filters?: TFilters) =>
-    this.builder.config.queryClient?.isMutating({ mutationKey: this.builder.getMutationKey(vars), ...filters });
+  readonly isMutating = (vars: T['vars'], filters?: MutationFilters<T['data'], T['error'], T['vars']>) =>
+    this.builder.config.queryClient?.isMutating(this.builder.getMutationFilters(vars, filters));
 }
 
 export class MutationBuilder<T extends BuilderTypeTemplate = BuilderTypeTemplate> extends MutationBuilderFrozen<T> {

src/builder/MutationBuilder.ts

@@ -1,4 +1,11 @@
-import type { DefaultError, QueryKey, UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
+import {
+  DefaultError,
+  MutationKey,
+  QueryKey,
+  UseMutationOptions,
+  UseQueryOptions,
+  hashKey,
+} from '@tanstack/react-query';
 import { httpRequest } from '../http/request';
 import { mergeQueryEnabled } from '../tags/mergeQueryEnabled';
 import { mergeTagOptions } from '../tags/mergeTagOptions';
@@ -48,12 +55,14 @@ export function mergeMutationOptions<TData = unknown, TError = DefaultError, TVa
     opts.meta = {
       ...opts.meta,
       ...meta,
-      invalidates: mergeTagOptions([opts.meta?.invalidates, meta?.invalidates]),
-      updates: mergeTagOptions([opts.meta?.updates, meta?.updates]),
-      optimisticUpdates: mergeTagOptions([opts.meta?.optimisticUpdates, meta?.optimisticUpdates]),
     };
   }
 
+  opts.meta ??= {};
+  opts.meta.invalidates = mergeTagOptions(filtered.map((f) => f.meta?.invalidates));
+  opts.meta.updates = mergeTagOptions(filtered.map((f) => f.meta?.updates));
+  opts.meta.optimisticUpdates = mergeTagOptions(filtered.map((f) => f.meta?.optimisticUpdates));
+
   return opts;
 }
 
@@ -90,3 +99,11 @@ export function createHttpQueryFn<T extends HttpBuilderTypeTemplate>(
     return httpRequest<T['data']>({ ...(mergedVars as any), meta, signal });
   };
 }
+
+export function areKeysEqual(
+  a: QueryKey | MutationKey,
+  b: QueryKey | MutationKey,
+  hashFn: typeof hashKey = hashKey,
+): boolean {
+  return hashFn(a) === hashFn(b);
+}

src/builder/utils.ts

@@ -26,12 +26,12 @@ export class BuilderMutationCache extends MutationCache {
         const queryClient = getQueryClient();
 
         const data = !vars || typeof vars !== 'object' ? undefined : Reflect.get(vars, 'body');
-        const updates = resolveTags({ client: queryClient, tags: mutation.meta?.optimisticUpdates, vars, data });
+        const optUpdates = resolveTags({ client: queryClient, tags: mutation.meta?.optimisticUpdates, vars, data });
         const ctx: QueryTagContext<unknown> = { client: queryClient, vars, data };
-        const undos = updateTags({ queryClient, tags: updates, ctx, optimistic: true });
+        const undos = updateTags({ queryClient, tags: optUpdates, ctx, optimistic: true });
         if (undos.length) mutationContexts.set(mutation.mutationId, { undos });
 
-        const tags = updates.filter(
+        const tags = optUpdates.filter(
           (tag) => typeof tag !== 'object' || ['pre', 'both'].includes(tag.invalidate || 'both'),
         );
 

src/tags/cache.ts

@@ -63,6 +63,8 @@ export type QueryTagsMetadata<TVars = void, TData = unknown, TErr = unknown> = {
    * Provides tags for the query, which can be used by mutations to invalidate or optimistically update the query data.
    */
   tags?: QueryTagOption<TVars, TData, TErr>;
+
+  updated?: 'optimistic' | 'pessimistic' | 'undone';
 };
 
 export type QueryInvalidatesMetadata<TVars = void, TData = unknown, TErr = unknown> = {