fix(angular-query): integrate with Angular PendingTasks for whenStable() support

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 v17+ 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 v18 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/implementation-docs/pending-tasks-integration.md

@@ -0,0 +1,52 @@
+# PendingTasks Integration in TanStack Query for Angular
+
+## Overview
+
+TanStack Query cooperates with Angular's PendingTasks API so `ApplicationRef.whenStable()` waits for ongoing queries and mutations. Full behavior requires Angular v18+; versions without PendingTasks fall back to no-op integration.
+
+## Compatibility
+
+- **Angular v20+**: uses `PendingTasks`
+- **Angular v18–19**: uses `ExperimentalPendingTasks`
+- **Angular v17-**: shim returns no-op cleanup
+
+The token factory in `pending-tasks-compat.ts` auto-detects the available service and returns `{ add: () => cleanup }`, ensuring a stable API either way.
+
+## Implementation Notes
+
+- Queries register a task when `fetchStatus === 'fetching'` and release it once the observer reports `fetchStatus === 'idle'`. Paused retries (offline/focus) therefore keep the task active until they truly settle.
+- Mutations do the same based on `state.isPending`.
+- Cleanup is mirrored in Angular's `DestroyRef` callbacks so destroyed components cannot leak tasks.
+
+```ts
+if (state.fetchStatus === 'fetching' && !task) task = pendingTasks.add()
+if (state.fetchStatus === 'idle' && task) task()
+```
+
+## Testing & Usage
+
+- No additional setup is required; simply using TanStack Query registers PendingTasks when available.
+- With real timers, `await fixture.whenStable()` or `app.whenStable()` is enough to observe final state.
+- Under fake timers (Vitest), advance timers and microtasks before awaiting stability, e.g.
+  ```ts
+  await vi.advanceTimersByTimeAsync(10)
+  await Promise.resolve()
+  await fixture.whenStable()
+  ```
+- Offline retries stay pending until `onlineManager.setOnline(true)` resumes the retry cycle.
+
+## Edge Cases Covered
+
+- Rapid refetches and concurrent queries each obtain their own PendingTask reference.
+- Cancellation restores the query to `pending/idle` without leaking tasks.
+- Component destruction clears outstanding tasks for both queries and mutations.
+- HttpClient scenarios work because PendingTasks is tracked at the query layer, even when `lastValueFrom` detaches Angular’s own PendingTasks hooks.
+
+## Contributing Checklist
+
+When adding new async behavior inside the Angular adapter:
+
+1. Inject `PENDING_TASKS` where the async unit lives.
+2. Call `pendingTasks.add()` when work starts and retain the cleanup ref.
+3. Dispose the ref on completion, cancellation, or destruction.
+4. Test with `whenStable()` plus fake-timer flushing to keep observable behavior consistent.

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')
+    })
   })
 })