Relates to: PR #441 ("add error tracking and retry methods to query collection utils")
Scope: DX / reliability / precision
Breaking changes: None proposed

Summary

QueryCollection.utils.refetch() currently uses only queryKey without exact: true, which can cause unintended cascade refetches of queries with shared key prefixes. This issue proposes making refetch target only the intended query.

Current Behavior

// In packages/query-db-collection/src/query.ts:634
const refetch: RefetchFn = (opts) => {
  return queryClient.refetchQueries(
    {
      queryKey: queryKey, // No exact flag - matches prefixes!
    },
    {
      throwOnError: opts?.throwOnError,
    }
  )
}

Problem: Calling refetch() on a collection with key ['todos', 1] also refetches ['todos'] and ['todos', 2].

Proposed Solution

const refetch: RefetchFn = (opts) => {
  return queryClient.refetchQueries(
    {
      queryKey,
      exact: true,        // only this collection's key
      type: 'active',     // only if observed; avoids waking cold queries
    },
    {
      throwOnError: opts?.throwOnError,
    }
  )
}

Acceptance Criteria

• Calling refetch() on a collection with key ['todos', 1] does not refetch ['todos'] or ['todos', 2]
• If no observers exist (or the query is disabled), refetch() is a no-op when type: 'active' is set
• clearError() uses the same exact targeting since it calls refetch()
• Add tests to verify exact targeting behavior

Open Question

Should type: 'active' be the default, or should we allow cold refetch by default and document it?