Prevent watch callback from being triggered on resume

[8ctavio]

Use the pause and resume methods of a regular watch to completely prevent the watcher callback from being executed when the sources change.

const src = ref()
const { pause, resume } =  watch(src, cb1)
watch(src, cb2)
// later...
pause()
src.value = newValue // do not schedule cb1 for execution
resume()

This resembles the lazy default behaviour of the regular watch callback. However, current implementation adds the reactive effect of the first watcher to a paused-effect queue, and would always run (for the given example) when resume is called.

Suggested API

There are at least two approaches to configure the watch callback behavior (lazy or eager) on resume.

1. Confire through a watch option; either immediate or a new one.

const { pause, resume } = watch(src, callback, {
  immediate: true // callback executed on resume
})

2. Configure through a resume's boolean argument

 const { pause, resume } = watch(src, callback)
 resume(true) // executes callback (if previously paused)

The feature only controls whether the callback itself is executed, but tracking the sources should still be managed while the watcher is paused.

Motivation

Prior art

VueUse's watchIgnorable achieves the described behavior. See Ignorable watch for an use case.

Another application

The use case I'm trying to address by completely ignoring an effect subscribed to a reactive value is to implement custom form components with an approach that separately handles user-interaction-events and developer-programmatic-mutations (which I think, at least conceptually, is similar to JavaScript's approach). To clarify, consider a high overview of what v-model does to an input element:

  <input v-model="model"/>
  <!-- Turns into -->
  <input :value="model" @input="e => model = e.target.value"/>

That's the approach: an event handler for user-interaction events and a side effect for programmatic mutations. However, the effect that updates the input's value gets executed after the model is updated in the event handler, which is not necessary. For this and other simple cases as those covered by Vue, this is not really a problem. But following this approach becomes not so straightforward as component complexity increases. By completely ignoring the side effect when the model is updated in the event handler, the unnecessary execution of the effect is simply prevented.

Here is a simple demo of how the input example would look with the described approach.

As I mentioned, I think that, in a way, this approach is similar to how form elements works natively. With a text input, for instance, JavaScript on the one hand listens for user interaction and only then dispatches an input event while, on the other hand programmatic mutations of the input element's value do not trigger an event. Then, user-interaction-event and programmatic-mutations are handled separately.