Back to Ragflow

query-cancellation: Implement Query Cancellation Properly

web/.agents/skills/tanstack-query-best-practices/rules/query-cancellation.md

0.25.14.5 KB
Original Source

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

ScenarioCancelled?
Query key changesYes
Component unmountsYes
queryClient.cancelQueries() calledYes
Refetch triggeredPrevious request cancelled
enabled becomes falseYes

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