Reactivity Transform Unification

[yyx990803]

Reactivity Transform Unification

We have went through quite a few iterations on the ref transform (latest at #369), and recently also implemented the props transform (also experimental). Based on the feedback, it seems to be better to unify both proposals under a single concept. I'm calling it "Vue Reactivity Transform".

The main concerns we heard for the ref sugar transform is the idea of $ref being the shorthand of $(ref()). Some users seem to think the latter is completely unnecessary, while some think having shorthands for only a subset the API is inconsistent.

I believe these are minor conceptual hurdles and the underlying mental model is solid. But we do need to find the best way to introduce the transform's mental model to new users. Here I am proposing some final tweaks, mostly on how the transform should be explained / documented:

1. Every ref-creating API method will have a $-prefixed equivalent, which creates reactive variables. These methods include:

   • ref
   • computed
   • shallowRef
   • customRef
   • toRef

2. Definition: a reactive variable is a variable that can be used like a normal variable while retaining reactivity in the current function scope. It will be tracked when referenced, and can trigger reactive effects (re-render and watcher callbacks) when assigned. They are compile-time sugar and backed by actual refs under the hood.

3. $() is a utility macro that can be used to:

   • create a reactive variable from any existing refs:

   const countRef = ref(0)
   let count = $(count)

   • destructure a reactive object, or a plain object of refs into multiple reactive variables:

   const { x, y } = $(useMouse())

4. $() also works on defineProps:

   const { foo, bar } = $(defineProps(...))
   
   // foo is a reactive varaible backed by $props.foo
   console.log(foo)

   When used on defineProps, destructure default values will be compiled into runtime prop default values:

   // will compile to runtime props declaration of `{ foo: { defualt: 1 }}`
   const { foo = 1 } = $(defineProps(...))

   This allows declaring props default values even when using pure-TS props declarations, and allows us to get rid of withDefaults.

5. $$() is the reverse of $() which converts reactive variables into raw refs.

   • It can work on single reactive variables:

   let x = $ref(0)
   const xRef = $$(x) // Ref<number>

   • or object literals containing reactive variables:

   let x = $ref(0)
   let y = $ref(0)
   return $$({ x, y }) // { x: Ref<number>, y: Ref<number> }

   • It also works on reactive variable created by destructuring props. In this case it compiles into a toRef call on the props object:

   const { foo } = $(defineProps())
   const fooRef = $$(foo) // toRef(__props, 'foo')

---

Note: this is not a new proposal - it's an amendment / alternative explanation of #369 + props destructure transform. Please make sure to read #369 before posting a comment.

[jods4]

destructure a reactive object, or a plain object of refs into multiple reactive variables

Curious what the implementation you have in mind, as the two transforms are quite different?
At runtime you could peek at stuff like isReactive(), although it might have edge cases with advanced uses...
But I think the transform should happen at compile-time as the codegen depends on it?
Did I miss something?

[yyx990803]

Current impl. of toRef probes every single field in the target object. Depending on the target object, this can unexpectedly trigger side-effects (e.g. inside getters) . I think it would be much better if $ did not have any observable effect.

Again does not - the codegen generates single toRef calls only for the destructured properties, not toRefs

[jods4]

Sorry for the misunderstanding!
Great that you only process what's needed.

If it detects it's wrapping defineProps it will use props-specific codegen.

Are you gonna track the props variable dataflow and use a different codegen everywhere, e.g. if I do this?

const props = defineProps();
// Is this defineProps-specific codegen?
const { name } = $(props);

So I understand you'll have different codegen when unwrapping props (based on props.name) vs unwrapping any other reactive object (based on toRef)?
The efficient props codegen could be used for everything. Also consider that props can end up in the 2nd case anyway:

const props = defineProps()
const state = reactive({})

function reusableLogic(reactiveSource) {
 const { x, y } = $(reactiveSource)
 // ...
}

reusableLogic(props)
reusableLogic(state)

My remark about side-effects remains, although it's now limited to destructured properties.
Depending on your mental model, you may think it's ok or not:

// Is this (1) a macro that creates a variable alias without side-effects, 
// or (2) does actually read values as destructuring usually does?
// Response is (1) for props, (2) for reactive objects.
const { name } = $(source)

A notable side-effect is reactivity itself. I think it's important to have a good mental model for whether you're tracking a dependency or not.
Currently:

• Destructuring props does not track (until variables are read).
• Destructuring an object of refs does not track (until variables are read).
• Destructuring a reactive object does track (immediately + when variables are read).

If $ is understood as a macro, I think it offers more flexibility if it never tracked -- in the sense that you can always force a read, but it's impossible to ignore one.

[yyx990803]

Are you gonna track the props variable dataflow and use a different codegen everywhere, e.g. if I do this?
const props = defineProps();
// Is this defineProps-specific codegen?
const { name } = $(props);

Yes.

My remark about side-effects remains

That's a good point, but is there any real case where the track side effect could lead to unwanted behavior?

The only case would be (1) destructure is called inside a reactive effect AND (2) the destructured properties are not used synchronously in the reactive effect:

watchEffect(() => {
  let { x, y } = $(someReactiveObject)
  // never use x, y here
})

But does such usage make any sense? I can't think of any case where this would make any sense. If you are already inside a reactive effect, a normal destructure would already track so there's no point in using the $() macro; The only places where you'd use a $() macro is outside of reactive effects so that the destructured variable can then be directly used inside reactive effects.

If we want, we can actually use a wrapped version of toRef where it detects the target object to be a non-shallow reactive object and avoid the property access side effect (since non-shallow reactive objects always unwraps so there's no need to check if the value is a ref), but I just don't think that is really necessary.

[yyx990803]

Regarding passing props into another function with $() destrucutre - this can simply be considered a fallback / de-opt since this is going to be quite rare and the perf implication is negligible.

[jods4]

That's a good point, but is there any real case where the track side effect could lead to unwanted behavior?

Hard to say. Nothing obvious springs to mind right now but this is quite new so it's difficult to consider every possible use.

Maybe one case could be that you capture some state with the intention of then manipulating it in a no-tracking effectScope, or in a deferred callback or an event.
A contrived example of such a pattern:

// This might be a clicked handler bound in UI
const clickHandler = computed(() => {
  // `findSelection` tracks the true deps of this effect
  // I like sugar and the fact I can have a "live" amount variable
  // but `amount` was not supposed to be a dependency of the computed.
  const { amount } = $(findSelection())
  // Notice this is a lambda, amount is read in there but is not a dependency of the computed
  return () => console.log("Selected amount = ", amount)
})

Aside: it's kind of cool that the $ sugar can create "live" property shortcuts, regardless of reactivity. 😃

The only case would be (1) destructure is called inside a reactive effect AND (2) the destructured properties are not used synchronously in the reactive effect

Keep in mind that reactive tracking was merely one example of side-effect.
Any getter function in raw underlying objects will run and that could be arbitrary user code.
Another contrived example:

let accessCounter = 0, _val;
const state = reactive({ 
  get val() { accessCounter++; return _val } 
  set val(newValue) { _val = newValue }
})

// I like sugar
const { val } = $(state);
// Let's do something with val
console.log(val)
// As a user, you may consider that you accessed val only once,
// but accessCounter == 2

Granted, this code is just for argument's sake. It's hard to envision every kind of code Vue users will come up with, given that it could be anything.

Besides side-effects, this could also be about the perf/cost of getters, e.g. if they return a reduced or filtered copy of a large array. You may not want to run them more often than required.

At the conceptual level, if you want to use sugar without immediately triggering getter code, it is currently not possible.
I think it's not ideal, but maybe it's an ok trade-off...

Regarding passing props into another function with $() destrucutre - this can simply be considered a fallback / de-opt since this is going to be quite rare and the perf implication is negligible.

In an ideal world, it'd be nice if the optimized props codegen was used for plain reactives as well. The big trade-off is that it'd be hard to keep a unique $() for that :(

I tried to create a contrived example of that as well, but then I realized that you don't really need to reactively destructure random objects that much. Only when you want to pass around individual properties of them in reactive fashion, and props is really the prime example of that.
Maybe that's just not a worthy optimization.

[jods4]

Every ref-creating API method will have a $-prefixed equivalent, which creates reactive variables.

This is nice as these methods are used super-often.

If you define some common ref-generating helpers in your project -- or from a lib -- it'd be nice to be able to reduce the calls nesting by applying a similar treatment to them. I'm thinking of stuff like debounceRef, modelComputed & co.

What if any undefined function call whose name starts with $ was understood as $(f(..)) instead by the compiler?

• That's a consistent pattern with built-ins $ref and co.
• Can work as $defineProps as well!
• On your own functions, there's no auto-import: you still need to import f for the resulting code to work.
• This may create an unused import warning, but that's already something script setup has to handle with templates.
• If you use TS, you need to define $f in your project (libraries can provide types for such helpers they provide).

Example:

import { debounceRef } from "utils"
// Compiled the same way as $(debounceRef("", 300))
const search = $debounceRef("", 300)

[yyx990803]

Again, this doesn't work with TS. Having to manually define the types for custom $xxx functions is more hassle than just using a single $() helper.

[jods4]

Is it that much hassle?

If you use a lib such as vue-composable, the lib can provide those types for you -> nothing to do.

Assuming we have a helper type to unref the return type of a function (this one can be provided by Vue), you only have to declare this once in your project:

type $debounceRef = UnrefReturn<typeof debounceRef>;

In a large project, if you use a few helpers repeatedly, I would do that.
In a smaller context or if the idea doesn't appeal to someone, you are free to stick to $(debounceRef(..)).

I agree it's more magic, though, and I'm a bit torn about it. I am personally more annoyed by the fact that these global declarations don't work unless you have specific imports also in scope and that it adds new tooling requirements to mute unused warnings.

For context, I was motivated to bring this up again when trying to write a generic v-model helper in #394 and my first try looked like this:

const { modelValue } = defineProps()
const val = $(modelRef($$(modelValue), emit))

That's a lot of nested calls for something that should be a single operation.

[posva]

This looks great, I like the removal of withDefaults() and being able to use one single syntaxt $().
What would happen if $(0) or $({ someObjectValue: 0 }) is called? Will the compiler warns and say this is equivalent to 0 and { someObjectValue: 0 } or will it create a ref()? Maybe the latter is too implicit. I think those cases should be added to the RFC too.

[jods4]

How does the removal of withDefaults work when you want to grab the full props object (and define some defaults)?

What would happen if $(0) or $({ someObjectValue: 0 }) is called?

0 is not an object, so this should IMHO be an error.

{ someObjectValue: 0 } is not reactive, but I think it's more flexible if it still works the same (and I believe that's what the current implementation does).

Sometimes you accept a parameter that may or may not be reactive, and it'd be great if you can use the same code anyway.
Example:

// Note that person might be a reactive or a plain object, we don't know / support both.
function upperName(person) {
  const { name } = person
  return computed(() => name.toUpperCase())
}

[yyx990803]

This has now been revised into the original ref sugar v2 discussion #369 .