personal-admin-2026/.agents/skills/tanstack-query-best-practices/rules/query-cancellation.md

# query-cancellation: Implement Query Cancellation Properly

## Priority: MEDIUM

## Explanation

TanStack Query provides an `AbortSignal` to cancel in-flight requests when queries become stale or components unmount. Pass this signal to your fetch calls to prevent memory leaks and wasted bandwidth.

## Bad Example

```tsx
// Not using abort signal - requests complete even when unnecessary
const { data } = useQuery({
  queryKey: ['search', searchTerm],
  queryFn: async () => {
    // User types fast: "a", "ab", "abc"
    // Three requests fire, all complete, wasting bandwidth
    const response = await fetch(`/api/search?q=${searchTerm}`)
    return response.json()
  },
})

// Component unmounts but request keeps running
function UserProfile({ userId }: { userId: string }) {
  const { data } = useQuery({
    queryKey: ['user', userId],
    queryFn: async () => {
      const response = await fetch(`/api/users/${userId}`)
      return response.json()  // Completes even if user navigated away
    },
  })
}
```

## Good Example: Using AbortSignal with Fetch

```tsx
const { data } = useQuery({
  queryKey: ['search', searchTerm],
  queryFn: async ({ signal }) => {
    const response = await fetch(`/api/search?q=${searchTerm}`, {
      signal,  // Pass abort signal to fetch
    })
    return response.json()
  },
})

// Now when user types "a", "ab", "abc" quickly:
// - "a" request is cancelled when "ab" starts
// - "ab" request is cancelled when "abc" starts
// - Only "abc" completes
```

## Good Example: With Axios

```tsx
import axios from 'axios'

const { data } = useQuery({
  queryKey: ['users', userId],
  queryFn: async ({ signal }) => {
    const response = await axios.get(`/api/users/${userId}`, {
      signal,  // Axios supports AbortSignal
    })
    return response.data
  },
})
```

## Good Example: Manual Cancellation

```tsx
function SearchResults() {
  const queryClient = useQueryClient()
  const [searchTerm, setSearchTerm] = useState('')

  const { data } = useQuery({
    queryKey: ['search', searchTerm],
    queryFn: async ({ signal }) => {
      const response = await fetch(`/api/search?q=${searchTerm}`, { signal })
      return response.json()
    },
    enabled: searchTerm.length > 0,
  })

  // Cancel all search queries manually
  const handleClear = () => {
    queryClient.cancelQueries({ queryKey: ['search'] })
    setSearchTerm('')
  }

  return (
    <div>
      <input
        value={searchTerm}
        onChange={(e) => setSearchTerm(e.target.value)}
      />
      <button onClick={handleClear}>Clear</button>
      <Results data={data} />
    </div>
  )
}
```

## Good Example: In Mutations (Before Optimistic Update)

```tsx
const updateTodo = useMutation({
  mutationFn: (todo: Todo) => api.updateTodo(todo),
  onMutate: async (newTodo) => {
    // Cancel outgoing queries to prevent overwriting optimistic update
    await queryClient.cancelQueries({ queryKey: ['todos'] })
    await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })

    // Proceed with optimistic update...
    const previousTodos = queryClient.getQueryData(['todos'])
    queryClient.setQueryData(['todos'], (old) => /* ... */)

    return { previousTodos }
  },
})
```

## Good Example: Custom Cancellable Promise

```tsx
// For non-fetch APIs that need custom cancellation
const { data } = useQuery({
  queryKey: ['expensive-computation', params],
  queryFn: ({ signal }) => {
    return new Promise((resolve, reject) => {
      // Check if already cancelled
      if (signal.aborted) {
        reject(new DOMException('Aborted', 'AbortError'))
        return
      }

      const worker = new Worker('computation.js')
      worker.postMessage(params)

      worker.onmessage = (e) => resolve(e.data)
      worker.onerror = (e) => reject(e)

      // Listen for cancellation
      signal.addEventListener('abort', () => {
        worker.terminate()
        reject(new DOMException('Aborted', 'AbortError'))
      })
    })
  },
})
```

## When Queries Are Cancelled

| Scenario | Cancelled? |
|----------|------------|
| Query key changes | Yes |
| Component unmounts | Yes |
| `queryClient.cancelQueries()` called | Yes |
| Refetch triggered | Previous request cancelled |
| `enabled` becomes false | Yes |

## Context

- Always pass `signal` to fetch/axios for automatic cancellation
- Cancelled queries don't trigger `onError` - they're silently dropped
- Use `queryClient.cancelQueries()` before optimistic updates
- AbortError is thrown when cancelled - handle if needed
- Cancellation prevents wasted bandwidth and race conditions
- Essential for search-as-you-type and fast navigation patterns