feat(angular-query): integrate with Angular v19+ PendingTasks for whenStable() support (#9666)

Integrates TanStack Query for Angular with Angular's PendingTasks API to properly track
asynchronous operations, ensuring ApplicationRef.whenStable() waits for queries and
mutations to complete before resolving.

Features:
- Cross-version compatibility (Angular v16+ with graceful degradation)
- Tracks query fetchStatus and mutation isPending state
- Automatic cleanup on component destruction
- Comprehensive test coverage including edge cases

Benefits:
- Improved SSR: Server waits for data fetching before rendering
- Better testing: fixture.whenStable() properly waits for async operations
- Zoneless support: Correct change detection timing

Author: arnoud-dv

docs/framework/angular/zoneless.md

@@ -8,3 +8,5 @@ Because the Angular adapter for TanStack Query is built on signals, it fully sup
 Among Zoneless benefits are improved performance and debugging experience. For details see the [Angular documentation](https://angular.dev/guide/zoneless).
 
 > Besides Zoneless, ZoneJS change detection is also fully supported.
+
+> When using Zoneless, ensure you are on Angular v19 or later to take advantage of the `PendingTasks` integration that keeps `ApplicationRef.whenStable()` in sync with ongoing queries and mutations.

eslint.config.js

@@ -18,21 +18,25 @@ export default [
         {
           cspell: {
             words: [
+              'Promisable', // Our public interface
+              'TSES', // @typescript-eslint package's interface
               'codemod', // We support our codemod
               'combinate', // Library name
+              'datatag', // Query options tagging
               'extralight', // Our public interface
               'jscodeshift',
-              'Promisable', // Our public interface
+              'refetches', // Query refetch operations
               'retryer', // Our public interface
               'solidjs', // Our target framework
               'tabular-nums', // https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric
               'tanstack', // Our package scope
               'todos', // Too general word to be caught as error
-              'TSES', // @typescript-eslint package's interface
               'tsqd', // Our public interface (TanStack Query Devtools shorthand)
               'tsup', // We use tsup as builder
               'typecheck', // Field of vite.config.ts
               'vue-demi', // dependency of @tanstack/vue-query
+              'ɵkind', // Angular specific
+              'ɵproviders', // Angular specific
             ],
           },
         },

packages/angular-query-experimental/eslint.config.js

@@ -9,14 +9,6 @@ export default [
   pluginJsdoc.configs['flat/recommended-typescript'],
   {
     rules: {
-      'cspell/spellchecker': [
-        'warn',
-        {
-          cspell: {
-            ignoreRegExpList: ['\\ɵ.+'],
-          },
-        },
-      ],
       'jsdoc/require-hyphen-before-param-description': 1,
       'jsdoc/sort-tags': 1,
       'jsdoc/require-throws': 1,
@@ -36,6 +28,8 @@ export default [
     files: ['**/__tests__/**'],
     rules: {
       '@typescript-eslint/no-unnecessary-condition': 'off',
+      '@typescript-eslint/require-await': 'off',
+      'jsdoc/require-returns': 'off',
     },
   },
 ]

packages/angular-query-experimental/package.json

@@ -97,6 +97,7 @@
     "@testing-library/angular": "^18.0.0",
     "eslint-plugin-jsdoc": "^50.5.0",
     "npm-run-all2": "^5.0.0",
+    "rxjs": "^7.8.2",
     "vite-plugin-dts": "4.2.3",
     "vite-plugin-externalize-deps": "^0.9.0",
     "vite-tsconfig-paths": "^5.1.4"

packages/angular-query-experimental/src/__tests__/inject-mutation.test.ts

@@ -1,4 +1,5 @@
 import {
+  ApplicationRef,
   Component,
   Injector,
   input,
@@ -466,5 +467,230 @@ describe('injectMutation', () => {
         )
       }).not.toThrow()
     })
+
+    test('should complete mutation before whenStable() resolves', async () => {
+      const app = TestBed.inject(ApplicationRef)
+      let mutationStarted = false
+      let mutationCompleted = false
+
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: ['pendingTasksTest'],
+          mutationFn: async (data: string) => {
+            mutationStarted = true
+            await sleep(50)
+            mutationCompleted = true
+            return `processed: ${data}`
+          },
+        })),
+      )
+
+      // Initial state
+      expect(mutation.data()).toBeUndefined()
+      expect(mutationStarted).toBe(false)
+
+      // Start mutation
+      mutation.mutate('test')
+
+      // Wait for mutation to start and Angular to be "stable"
+      const stablePromise = app.whenStable()
+      await vi.advanceTimersByTimeAsync(60)
+      await stablePromise
+
+      // After whenStable(), mutation should be complete
+      expect(mutationStarted).toBe(true)
+      expect(mutationCompleted).toBe(true)
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('processed: test')
+    })
+
+    test('should handle synchronous mutation with retry', async () => {
+      TestBed.resetTestingModule()
+      TestBed.configureTestingModule({
+        providers: [
+          provideZonelessChangeDetection(),
+          provideTanStackQuery(queryClient),
+        ],
+      })
+
+      const app = TestBed.inject(ApplicationRef)
+      let attemptCount = 0
+
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          retry: 2,
+          retryDelay: 0, // No delay for synchronous retry
+          mutationFn: async (data: string) => {
+            attemptCount++
+            if (attemptCount <= 2) {
+              throw new Error(`Sync attempt ${attemptCount} failed`)
+            }
+            return `processed: ${data}`
+          },
+        })),
+      )
+
+      // Start mutation
+      mutation.mutate('retry-test')
+
+      // Synchronize pending effects for each retry attempt
+      TestBed.tick()
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(10)
+
+      TestBed.tick()
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(10)
+
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(10)
+      await stablePromise
+
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('processed: retry-test')
+      expect(attemptCount).toBe(3) // Initial + 2 retries
+    })
+
+    test('should handle multiple synchronous mutations on same key', async () => {
+      TestBed.resetTestingModule()
+      TestBed.configureTestingModule({
+        providers: [
+          provideZonelessChangeDetection(),
+          provideTanStackQuery(queryClient),
+        ],
+      })
+
+      const app = TestBed.inject(ApplicationRef)
+      let callCount = 0
+
+      const mutation1 = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: ['sync-mutation-key'],
+          mutationFn: async (data: string) => {
+            callCount++
+            return `mutation1: ${data}`
+          },
+        })),
+      )
+
+      const mutation2 = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: ['sync-mutation-key'],
+          mutationFn: async (data: string) => {
+            callCount++
+            return `mutation2: ${data}`
+          },
+        })),
+      )
+
+      // Start both mutations
+      mutation1.mutate('test1')
+      mutation2.mutate('test2')
+
+      // Synchronize pending effects
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      // Flush microtasks to allow TanStack Query's scheduled notifications to process
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(1)
+      await stablePromise
+
+      expect(mutation1.isSuccess()).toBe(true)
+      expect(mutation1.data()).toBe('mutation1: test1')
+      expect(mutation2.isSuccess()).toBe(true)
+      expect(mutation2.data()).toBe('mutation2: test2')
+      expect(callCount).toBe(2)
+    })
+
+    test('should handle synchronous mutation with optimistic updates', async () => {
+      TestBed.resetTestingModule()
+      TestBed.configureTestingModule({
+        providers: [
+          provideZonelessChangeDetection(),
+          provideTanStackQuery(queryClient),
+        ],
+      })
+
+      const app = TestBed.inject(ApplicationRef)
+      const testQueryKey = ['sync-optimistic']
+      let onMutateCalled = false
+      let onSuccessCalled = false
+
+      // Set initial data
+      queryClient.setQueryData(testQueryKey, 'initial')
+
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationFn: async (data: string) => `final: ${data}`, // Synchronous resolution
+          onMutate: async (variables) => {
+            onMutateCalled = true
+            const previousData = queryClient.getQueryData(testQueryKey)
+            queryClient.setQueryData(testQueryKey, `optimistic: ${variables}`)
+            return { previousData }
+          },
+          onSuccess: (data) => {
+            onSuccessCalled = true
+            queryClient.setQueryData(testQueryKey, data)
+          },
+        })),
+      )
+
+      // Start mutation
+      mutation.mutate('test')
+
+      // Synchronize pending effects
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      // Flush microtasks to allow TanStack Query's scheduled notifications to process
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(1)
+      await stablePromise
+
+      expect(onMutateCalled).toBe(true)
+      expect(onSuccessCalled).toBe(true)
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('final: test')
+      expect(queryClient.getQueryData(testQueryKey)).toBe('final: test')
+    })
+
+    test('should handle synchronous mutation cancellation', async () => {
+      TestBed.resetTestingModule()
+      TestBed.configureTestingModule({
+        providers: [
+          provideZonelessChangeDetection(),
+          provideTanStackQuery(queryClient),
+        ],
+      })
+
+      const app = TestBed.inject(ApplicationRef)
+
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: ['cancel-sync'],
+          mutationFn: async (data: string) => `processed: ${data}`, // Synchronous resolution
+        })),
+      )
+
+      // Start mutation
+      mutation.mutate('test')
+
+      // Synchronize pending effects
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      // Flush microtasks to allow TanStack Query's scheduled notifications to process
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(1)
+      await stablePromise
+
+      // Synchronous mutations complete immediately
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('processed: test')
+    })
   })
 })