Best practice for composable input argument "MaybeRefOrGetter" does not always guarantee reactivity if computed value is used in the composable

[ryanki-te]

We've recently encountered an reactivity issue with the computed property inside the composable and the specific argument that we pass in to the composable.

From the vue's best practice article related to the input argument states that we should use MaybeRefOrGetter. Then, you can call the composables as such:

useFeature(1)
useFeature(ref(1))
useFeature(() => 1)

But if you define the composable that requires a computed value based on the argument:

function useFeature(num: MaybeRefOrGetter<number>) {
  const num2 = computed(() => toValue(num) + 1);
}

and call useFeature(1), num2 doesn't compute if num changes.

Well, you could think that it's because you passed in the static value, there's no way to change or make it reactive... but often in our use of the composables, we pass in prop values from the component, like useFeature(prop.foo).

What's the issue with this? Well, if we use the prop to get another computed value, i.e. const v2 = computed(() => props.v1); vue automatically figures out that this is reactive and computes the value whenever the prop changes. But if we pass this into our composable, the computed value doesn't change as the prop changes.

It is this difference that I think we shouldn't suggest we pass MaybeRefOrGetter as arguments to composables. The definition of MaybeRefOrGetter type allows a raw value to be passed in. And I believe this can lead to bugs and unexpected behavior, as we have find the hard way... Should passing in of a raw value be recommended for composables?

It was the best practice guide in vue's documentation that we've used MaybeRefOrGetter type, but having to find this exception, I feel pretty strong about this is not the best practice for composable.

@yyx990803 Love to hear your opinion as well, if you have time. Thanks!

Here's a sample program that demonstrates this issue.

[Justineo]

It is this difference

I don’t think there’s actually a difference here. In your example you pass a getter to computed, so Vue can track its dependencies and keep the result reactive.

Composable parameters, by contrast, aren’t always meant to update over time. Using MaybeRefOrGetter just gives the composable the option to accept reactive input. If your own composable is designed to accept values comes from a prop, you are always free to narrow the type and accept only a ref or a getter.

[ryanki-te]

Agreed, we should always narrow the type. Maybe relying on MaybeRefOrGetter was our mistake. But we've only used it because of the best practice documentation... If a composable parameter aren't always meant to update over time, than maybe it shouldn't recommend MaybeRefOrGetter at all. It should just be a static value. And if a parameter should be reactive, then it should be a ref or a getter.

[Justineo]

What I’m getting at is this: a composable should stay decoupled from the calling code and not worry about whether its argument is reactive. It’s generally better design to accept both reactive and plain values and let the caller decide which to use.

[ryanki-te]

While I agree, the mental overhead of using props.foo that sometimes it's reactive and sometimes it's not is not that straight forward, IMO. Also when the static value can be turned into a reactive using a watch, but not in computed, and except for props (in setup)...

Consider this case, too, if you don't mind :) If I have a composable like below, and if I call, useFeature(props.foo).

function useFeature(foo) {
  const bar = computed(() => toValue(foo) + 1);
  watch(() => toValue(foo), { ... });
}

When the props.foo changes from the component, watch effect triggers, but computed value does not change... Is it expected to use toRef on foo value before I can use computed? How can I ensure a consistent behavior with static value? Maybe the best practice documentation should mention this detail...