Configure lazy behavior of watch callback on resume

[8ctavio]

Feature Description

A key feature of watch is that the sources and callback function are handled separately. As such, when watch is called, it is not required to run the provided callback. The immediate option allows to configure the eager behavior of the callback when the watcher is first set up; if set to true, immediate causes the callback to be (eagerly) executed upon calling watch.

An API to pause and resume watchers was recently introduced. If a paused watcher's sources change, the watcher's callback will be executed once the watcher is resumed. This is partly required to properly keep track of dependencies. However, the ability to configure the callback's behavior is lost. As mentioned before, an advantage of watch is that sources and callback are independent. Thus, it should be possible to configure whether the callback itself gets executed when a watcher is resumed.

Currently, it could be said that a watcher's callback executes eagerly on resume; if its laziness could be configured, the pause and resume methods could be used to have more precise control over when may a watcher callback be executed. In particular, pause and resume could be used to fully prevent the execution of the callback while the watcher is paused. Without the lazy behavior, the callback may or may not execute on resume. With lazy behavior, resuming becomes more similar to first setting up a watcher; it indicates that, from that point on, the callback should be executed when a dependency updates.

Prior Art

The target functionality could be achieved with the public API only. See, for example, the two following projects' solutions:

• watchIgnorable
• watchControlled

There's a blog article showing a particular use case for this feature.

Motivation

These alternatives, however, introduce overhead; for non-sync watchers, two watchers are required. See their implementations:

• https://github.com/vueuse/vueuse/blob/main/packages/shared/watchIgnorable/index.ts#L23
• https://github.com/8ctavio/vergil/blob/main/packages/core/reactivity/watchControlled.js#L54

Target API

I think that the most conservative way to support this feature is through a new watch option. Here, I'll use lazyResume. The target API is shown below:

const src = ref(0)
const { pause, resume } = watch(src, cb, { lazyResume: true })

pause()      // Pause watcher
src.value++  // Does not run `cb`
resume()     // Runs internal effect to properly track dependencies, but doesn't run `cb`

Detailed design

In principle, only two files in the reactivity package (from 3.6 minor branch) could be refactored to implement this feature:

• effect.ts
• watch.ts

First, a watcher must be able to identify that its scheduler function was called from its effect's resume method. For this, the ReactiveEffect.resume method could be refactored as depicted below.

resume() {
    //...
-   this.notify()
+   this.flags |= EffectFlags.SCHEDULED_ON_RESUME
+   try { this.scheduler() }
+   finally {
+       this.flags &= ~EffectFlags.SCHEDULED_ON_RESUME  
+   }
    //...
}

• The scheduler method can be directly called instead of notify since the latter, when called from resume, is guaranteed to simply call scheduler.
• A new SCHEDULED_ON_RESUME flag is introduced for custom scheduler methods to detect whether they were invoked from resume. An scheduler boolean parameter could be used instead, but more type adjustments would be required since ReactiveEffect.scheduler's signature would change.

Secondly, inside watch.ts, on the watch function implementation, the watcher's effect.scheduler method should be defined in the following way when a callback is provided (i.e., when using the watch(src, cb) signature).

let scheduledOnResume: undefined | boolean
effect.scheduler = () => {
    if (effect.flags & EffectFlags.SCHEDULED_ON_RESUME) {
        scheduledOnResume ??= true
    } else if (scheduledOnResume !== false) {
        scheduledOnResume = false
    }
    return scheduler(job, false)
}

The scheduledOnResume variable will be used to inform the job whether it was first scheduled by the resume method. In addition, when resume is called and lazyResume is true, scheduler might need to clear the effect's DIRTY flag so that further sync source updates are able to re-run the scheduler. Alternatively, a new ReactiveEffect flag might be set to ensure a subsequent sync dependency update notifies the watcher's effect.

Finally, a simple check can be performed inside the watcher's job to determine if the callback should be run. The scheduledOnResume variable should also be reset.

const job = (immediateFirstRun) => {
    //...
    if (cb) {
        const newValue = effect.run() // effect is always run to properly track dependencies
        if (lazyResume && scheduledOnResume) {
            oldValue = newValue
        } else if (/*...*/) {
            // Execute callback
        }
        scheduledOnResume = undefined // Reset variable
    }
    //...
}