Is there some sort of documentation for @vue/reactivity?

[earslap]

I know it is used extensively as primitives for vue itself, but can't seem to find much about the API in its standalone form. For instance, for the plain "effect", what is the intended use of the individual options? What is "allowRecurse", or "scheduler" (these are just example questions)? Is any of this documented anywhere?

[Shyam-Chen]

Being refactored...

[earslap]

Sorry, what is being refactored? Some pre-existing docs? Or the reactivity library? Both? Did a separate @vue/reactivity documentation for the primitives exist at any point?

[Shyam-Chen]

#10397
#10407

[LinusBorg]

There are no real end-use docs for this package, really. It's not purposely designed to be used as a drop-in reactivity library, though developers interested in building on top of it can do that. most pieces of the library are essentially documented in the Vue docs - effect() as a central piece is the notable exception.

You can learn how schedulers work by looking at the implementation in runtime-core, yet the reactivity package is usable without a scheduler as well - in that case, effect() (which are the basic version of watchEffect()) just run synchronously, much like watchEffect would with flush: 'sync'

[earslap]

Thank you for the clarification. Yes, I was more or less curious about effect and its options. Tried to track its uses in Vue core but things are too intertwined with Vue's own guts so I got lost pretty quickly.

I think allowRecurse allows you to mutate the tracked variables without retriggering the effect and causing a loop + stack overflow. Am I close?

And my understanding of scheduler is that if it is provided as an option, when any tracked variable changes, reactivity system drops us to the scheduler for us to determine what we want to do. We can delay execution from here. Also it is our own responsibility to reinstate the effect if we provide a scheduler - if not, the effect simply stops working.

lazy: false means the effect runs as soon as it is defined, lazy: true waits for us to call the effect once to start tracking.

we can run the effect in a given effectScope with the scope option.

is there anything wrong with nesting effects? I wanted to create an "untrack" or "peek" primitive to have a section in an effect where the reads in that section are not tracked by the parent effect. I opted to use another effect inside the parent effect to do the job, then call .stop() on it so the tracked variables inside the inner effect are disposed. It works fine, but not sure if it is the right way to do it.