Document vue-query's reactivity

[KazimirPodolski]

Currently vue-query's part of tanstack completely lacks documentation on it's relations with vue reactivity (unless I'm missing it somehow). There are some ts types, but it's very hard to understand what vue-query actually does to support reactivity. Sources also doesn't particularly scream the idea into your face.

Even worse, vue's best practices for composables doesn't seem to be followed?

For example, say you want to make a composable returning a query, super common IMO:

export const useUserQuery = (id: MaybeRefOrGetter<number>) => useQuery({ // MaybeRefOrGetter as vue docs tell
  queryKey: ['user', ???], // id? toValue(id)? unref(id)? toRef(id)? something else?
  queryFn: async ({queryKey: [_, id]}) => await yourRequest(???) // again, id? toValue(id)? unref(id)? toRef(id)? something else?
});

// wrap it all into useEffect? verbose, stupid and ugly

Something works and something does not, e.g. getters doesn't seem to?.. Very confusing. And maybe that's completely wrong way to use vue-query, but the problem is intended way is not explained anywhere.

Please ignore if I'm the only idiot struggling with it.

[DamianOsipiuk]

I agree that such page might be handy. Especially for people moving from other frameworks.

As a rule of thumb, everything that you are passing to useQuery options should be reactive/ref, so library will be aware of the changes of those values. Vue-Query will unwrap them internally.

As for the queryFn - it's a plain JS function out of control of vue-query, so you have to be aware of what you are using.
id that you are getting from the queryFn context is in unwrapped state already, so can be used as-is. But if you are referencing ref not via context, you need to unwrap it manually.
Typescript should help you with that, hinting what is what.

[KazimirPodolski]

As a rule of thumb, everything that you are passing to useQuery options should be reactive/ref, so library will be aware of the changes of those values. Vue-Query will unwrap them internally.

I see. I believe it should be documented then rather than left for users to explore, especially since vue-query deviates from vue's recommendations.

As for the queryFn - it's a plain JS function out of control of vue-query, so you have to be aware of what you are using.
id that you are getting from the queryFn context is in unwrapped state already, so can be used as-is. But if you are referencing ref not via context, you need to unwrap it manually.
Typescript should help you with that, hinting what is what.

It doesn't, at least in 4.29.25 I currently have. That's part of the problem - types are quite bloated (I know it should be better in v5) and not really correct?

Also for me types for parameters of useQuery are always from the core lib, so they don't have hints for reactivity unless it's just plain passing of a generic. Maybe it's my setup problem somehow...

export type QueryKey = readonly unknown[]

- doesn't help either.

[DamianOsipiuk]

It's very harsh to say that we do not follow best practices, when those best practices were updated 2 months ago - vuejs/docs@dd1ce23

getters were introduced in Vue 3.3 and we have to figure out a way to make them useful without introducing breaking changes, or breaking Vue 2.x compatibility.

As for the typing of queryKey in context it seems to be insufficient, as it will unwrap only if whole queryKey is a ref.
We will need to play around with type and try to fix that.

[KazimirPodolski]

Oh I see, it just recently got my attention.

[bazuka5801]

@KazimirPodolski I also encountered lack of documentation, sometimes I look through react documentation to find some info.
Another case is when I look at the source code of a query.
The vue-query source code uses cloneDeepAndUnref() everywhere, including for keys.

But key reactivity works by computed(() => unref(queryKey)).

You can preserve reactivity if you pass ref, computed.
I don't know for other types.

[DamianOsipiuk]

What happens if you pass:

const someRef = ref(123);
useQuery({
  queryKey: ['foo', {
    nested: {
      key: {
        onlyThisIsRef: someRef
      }
    }
  }],
  queryFn: ...
})

We need to unref every nested value for queryKey serialization to work.
If vue-query would be vue-specific we could approach some things differently, but we have to make some tradeoffs to make it work with agnostic core.

[KazimirPodolski]

We need to unref every nested value for queryKey serialization to work.

I'm not quite experienced with vue v3 yet, but I feel that yes, you to have to deep unref if you accept nested objects in a composable allowing reactivity. People seem to be struggling with it, but there are solutions like vuejs/core#5303 (comment) (I haven't tried it myself yet).

I guess one can start with a simple utility wrapper for useQuery to watch args and unref all what useQuery gets. Maybe it won't work by some obvious reason, I guess I'll see...

If vue-query would be vue-specific we could approach some things differently, but we have to make some tradeoffs to make it work with agnostic core.

Does the core itself rely on some reactivity, or is it only framework-specific frontends' job?

[DamianOsipiuk]

People seem to be struggling with it, but there are solutions like vuejs/core#5303 (comment) (I haven't tried it myself yet).

We have our in-house cloneDeepUnref which better describes what is happening and supports most of the things that might be passed to useQuery.
We perform deep unreffing, while cloning objects or arrays.
This is necessary to not mutate any objects or arrays that user might be using in their code.

Does the core itself rely on some reactivity, or is it only framework-specific frontends' job?

No, core does not rely currently on any reactivity/signals etc. We are using subscriptions to receive updates from the cache and push those to reactive state that is returned to the user. And the other way around we are watch'ing reactive options provided to useQuery and interact with core accordingly.