chore(angular-query): add mutationInvalidates verification sample

Author: ScriptType

samples/angular-query/orval.config.ts

@@ -15,6 +15,21 @@ export default defineConfig({
       override: {
         query: {
           useInvalidate: true,
+          /**
+           * mutationInvalidates: Auto-invalidate queries when mutations succeed
+           *
+           * - Simple array: `createPets: ['listPets']`
+           * - Multiple targets: `updatePetById: ['listPets', 'showPetById']`
+           *
+           * After each mutation succeeds, the specified queries are automatically
+           * invalidated via queryClient.invalidateQueries(), triggering a refetch.
+           */
+          mutationInvalidates: {
+            // After creating a pet, invalidate the pets list so it refetches
+            createPets: ['listPets'],
+            // After uploading a file, invalidate multiple queries
+            uploadFile: ['listPets', 'showPetById'],
+          },
         },
         operations: {
           listPets: {

samples/angular-query/src/api/endpoints/pets/pets.ts

@@ -9,6 +9,7 @@ import { HttpClient, HttpParams } from '@angular/common/http';
 import { inject } from '@angular/core';
 
 import {
+  QueryClient,
   injectMutation,
   injectQuery,
 } from '@tanstack/angular-query-experimental';
@@ -19,7 +20,7 @@ import type {
   CreateQueryResult,
   InvalidateOptions,
   MutationFunction,
-  QueryClient,
+  MutationFunctionContext,
   QueryFunction,
 } from '@tanstack/angular-query-experimental';
 
@@ -303,6 +304,7 @@ export const getCreatePetsMutationOptions = <
       : { ...options, mutation: { ...options.mutation, mutationKey } }
     : { mutation: { mutationKey }, fetch: undefined };
   const http = inject(HttpClient);
+  const queryClient = inject(QueryClient);
 
   const mutationFn: MutationFunction<
     Awaited<ReturnType<typeof createPets>>,
@@ -313,7 +315,17 @@ export const getCreatePetsMutationOptions = <
     return createPets(http, data, version, fetchOptions);
   };
 
-  return { mutationFn, ...mutationOptions };
+  const onSuccess = (
+    data: Awaited<ReturnType<typeof createPets>>,
+    variables: { data: CreatePetsBody; version?: number },
+    onMutateResult: TContext,
+    context: MutationFunctionContext,
+  ) => {
+    queryClient.invalidateQueries({ queryKey: getListPetsQueryKey() });
+    mutationOptions?.onSuccess?.(data, variables, onMutateResult, context);
+  };
+
+  return { mutationFn, onSuccess, ...mutationOptions };
 };
 
 export type CreatePetsMutationResult = NonNullable<
@@ -604,6 +616,7 @@ export const getUploadFileMutationOptions = <
       : { ...options, mutation: { ...options.mutation, mutationKey } }
     : { mutation: { mutationKey }, fetch: undefined };
   const http = inject(HttpClient);
+  const queryClient = inject(QueryClient);
 
   const mutationFn: MutationFunction<
     Awaited<ReturnType<typeof uploadFile>>,
@@ -614,7 +627,18 @@ export const getUploadFileMutationOptions = <
     return uploadFile(http, petId, data, version, fetchOptions);
   };
 
-  return { mutationFn, ...mutationOptions };
+  const onSuccess = (
+    data: Awaited<ReturnType<typeof uploadFile>>,
+    variables: { petId: number; data: Blob; version?: number },
+    onMutateResult: TContext,
+    context: MutationFunctionContext,
+  ) => {
+    queryClient.invalidateQueries({ queryKey: getListPetsQueryKey() });
+    queryClient.invalidateQueries({ queryKey: getShowPetByIdQueryKey() });
+    mutationOptions?.onSuccess?.(data, variables, onMutateResult, context);
+  };
+
+  return { mutationFn, onSuccess, ...mutationOptions };
 };
 
 export type UploadFileMutationResult = NonNullable<

samples/angular-query/src/app/app.ts

@@ -1,22 +1,81 @@
 import { Component, signal } from '@angular/core';
-import { injectListPets } from '../api/endpoints/pets/pets';
+import { FormsModule } from '@angular/forms';
+import { injectListPets, injectCreatePets } from '../api/endpoints/pets/pets';
 
 @Component({
   selector: 'app-root',
+  standalone: true,
+  imports: [FormsModule],
   template: `
     <div class="App">
       <h1>Hello, {{ title() }}</h1>
+
       <header class="App-header">
         <img src="logo.svg" class="App-logo" alt="logo" />
+
+        <!-- Demo: Add Pet Form -->
+        <div class="add-pet-form">
+          <h2>Add a New Pet</h2>
+          <p class="notice">
+            <strong>Note:</strong> MSW mocks the API, so new pets won't persist.
+            Watch the pet list reload after clicking "Add" - that's
+            mutationInvalidates working!
+          </p>
+          <input
+            [(ngModel)]="newPetName"
+            placeholder="Pet name"
+            [disabled]="createPetMutation.isPending()"
+          />
+          <button
+            (click)="addPet()"
+            [disabled]="!newPetName() || createPetMutation.isPending()"
+          >
+            {{ createPetMutation.isPending() ? 'Adding...' : 'Add Pet' }}
+          </button>
+          @if (createPetMutation.isError()) {
+            <p class="error">Error adding pet</p>
+          }
+        </div>
+
+        <!-- Pet List (auto-refreshes after mutation via mutationInvalidates) -->
+        <h2>Pets List</h2>
+        @if (pets.isPending()) {
+          <p>Loading pets...</p>
+        }
         @for (pet of pets.data(); track pet.id) {
           <p>{{ pet.name }}</p>
         }
+        @if (pets.data()?.length === 0) {
+          <p>No pets yet. Add one above!</p>
+        }
       </header>
     </div>
   `,
 })
 export class App {
-  protected readonly pets = injectListPets();
+  // Query: Fetches pets list
+  protected readonly pets = injectListPets({ limit: '10' });
+
+  // Mutation: Creates a new pet
+  // The mutationInvalidates config causes listPets to auto-refresh on success
+  protected readonly createPetMutation = injectCreatePets();
 
   protected readonly title = signal('angular-app');
+  protected readonly newPetName = signal('');
+
+  addPet() {
+    const name = this.newPetName();
+    if (!name) return;
+
+    this.createPetMutation.mutate(
+      { data: { name, tag: 'new' } },
+      {
+        onSuccess: () => {
+          // Clear the input after successful creation
+          this.newPetName.set('');
+          // No need to manually invalidate - mutationInvalidates does it!
+        },
+      },
+    );
+  }
 }

samples/angular-query/src/app/mutation-invalidation.spec.ts

@@ -0,0 +1,147 @@
+/**
+ * Tests for mutationInvalidates feature
+ *
+ * This test verifies that mutations with `mutationInvalidates` configuration
+ * correctly invalidate the specified queries when the mutation succeeds.
+ *
+ * Following TanStack Angular Query testing patterns:
+ * https://tanstack.com/query/latest/docs/framework/angular/guides/testing
+ */
+import { provideZonelessChangeDetection } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import {
+  HttpTestingController,
+  provideHttpClientTesting,
+} from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import {
+  provideTanStackQuery,
+  QueryClient,
+} from '@tanstack/angular-query-experimental';
+
+import {
+  getCreatePetsMutationOptions,
+  getListPetsQueryKey,
+} from '../api/endpoints/pets/pets';
+import type { MutationFunctionContext } from '@tanstack/angular-query-experimental';
+
+describe('mutationInvalidates feature', () => {
+  let queryClient: QueryClient;
+  let httpCtrl: HttpTestingController;
+
+  beforeEach(() => {
+    // Create a fresh QueryClient for each test with retry disabled for faster tests
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+
+    TestBed.configureTestingModule({
+      providers: [
+        provideZonelessChangeDetection(),
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        provideTanStackQuery(queryClient),
+      ],
+    });
+
+    httpCtrl = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    httpCtrl.verify();
+  });
+
+  describe('getCreatePetsMutationOptions', () => {
+    it('should include onSuccess callback that invalidates listPets query', () => {
+      const options = TestBed.runInInjectionContext(() =>
+        getCreatePetsMutationOptions(),
+      );
+
+      // Verify the mutation options include an onSuccess callback
+      expect(options.onSuccess).toBeDefined();
+      expect(typeof options.onSuccess).toBe('function');
+    });
+
+    it('should have mutationFn defined', () => {
+      const options = TestBed.runInInjectionContext(() =>
+        getCreatePetsMutationOptions(),
+      );
+
+      expect(options.mutationFn).toBeDefined();
+      expect(typeof options.mutationFn).toBe('function');
+    });
+  });
+
+  describe('query invalidation behavior', () => {
+    it('should invalidate listPets query when onSuccess is called', () => {
+      // Set up an initial query cache entry
+      const queryKey = getListPetsQueryKey();
+      queryClient.setQueryData(queryKey, [{ id: 1, name: 'Existing Pet' }]);
+
+      // Get mutation options
+      const options = TestBed.runInInjectionContext(() =>
+        getCreatePetsMutationOptions(),
+      );
+
+      // Create a mock MutationFunctionContext
+      const mockContext: MutationFunctionContext = {
+        client: queryClient,
+        meta: undefined,
+      };
+
+      // Call onSuccess synchronously (no race condition - this is testing the callback directly)
+      options.onSuccess!(
+        undefined, // data (createPets returns void)
+        { data: { name: 'New Pet', tag: 'dog' } }, // variables
+        undefined as never, // onMutateResult
+        mockContext, // context
+      );
+
+      // After invalidation, the query should be marked as stale
+      const queryState = queryClient.getQueryState(queryKey);
+      expect(queryState?.isInvalidated).toBe(true);
+    });
+
+    it('should call user-provided onSuccess callback with correct arguments', () => {
+      let userCallbackCalled = false;
+      let receivedData: unknown;
+      let receivedVariables: unknown;
+
+      const options = TestBed.runInInjectionContext(() =>
+        getCreatePetsMutationOptions({
+          mutation: {
+            onSuccess: (data, variables, _onMutateResult, _context) => {
+              userCallbackCalled = true;
+              receivedData = data;
+              receivedVariables = variables;
+            },
+          },
+        }),
+      );
+
+      const mockContext: MutationFunctionContext = {
+        client: queryClient,
+        meta: undefined,
+      };
+
+      const mockVariables = { data: { name: 'Test Pet', tag: 'cat' } };
+
+      // Call the generated onSuccess
+      options.onSuccess!(
+        undefined,
+        mockVariables,
+        undefined as never,
+        mockContext,
+      );
+
+      // User's onSuccess should have been called with the same arguments
+      expect(userCallbackCalled).toBe(true);
+      expect(receivedData).toBe(undefined);
+      expect(receivedVariables).toEqual(mockVariables);
+    });
+  });
+});