Configure lazy behavior of watch callback on resume

[8ctavio]

• Start Date: 2025-10-27
• Target Version: >3.6
• Reference Issues:
• Implementation PR:

Summary

Introduction of new watch option to configure the eager/lazy behavior of watch upon calling .resume(), that is, whether resuming a paused watcher runs/schedules its callback if its dependencies were triggered while it was paused. Currently, the watcher callback will always be executed/scheduled if dependencies changed (eager behavior).

Basic example

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

pause()          // Pause watcher
src.value++      // Does not schedule `cb`
resume()         // `cb` is scheduled, but marked to skip callback execution
await nextTick() // Runs effect to track depedencies, but `cb` is not called

Motivation

A key feature of watch is that its 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 introduced in version 3.5. With it, 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 also be useful to configure whether the resume method executes/schedules the callback itself.

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/scheduled when a dependency updates. There is a blog article showing a particular use case for this behavior.

Although it is possible to achieve the desired behavior with current public APIs (see Alternatives), some overhead is introduced since non-sync watchers require an additional synchronous watcher.

A note on paused-watcher behavior

It might be worth mentioning that currently, the callback of a
paused watcher can be executed if it was scheduled before the
watcher was paused:
```js
src.value++
pause()
await nextTick() // Executes callback even though watcher is paused
resume()
```
It is my impression that the `watch` callback should be skipped
also while the watcher is paused.

Detailed design

A watch callback is executed by the WatcherEffect.run method. Initially, this method runs the effect to keep track of dependencies. Then, some checks are performed to skip callback execution if required, e.g., on the first run of a watcher with immediate: false. In order to prevent callback execution when a watcher is resumed, a similar check could be added as depicted below:

run(initialRun = false) {
    const oldValue = this.oldValue
    const newValue = this.oldValue = super.run()
    
    if (!this.cb) return
    
    const { immediate, deep, call } = this.options
    if (initialRun && !immediate) return

    if (/* invoked due to resume */) return

    // Run callback...
}

The objective would then be to inform WatcherEffect.run that it is being called because resume was called. For this, the first thing to note is that a watcher's resume method is defined by ReactiveEffect.resume which calls the effect's notify method. In turn, WatcherEffect.notify or RenderWatcherEffect.notify respectively call or schedule calling the WatcherEffect.run method.

For WatcherEffect and synchronous RenderWatcherEffect, a flag could be introduced for WatcherEffect.run to detect the watcher is being resumed. This flag could be defined on the EffectFlags enum:

export enum {
    //...
    RESUME_RUN = 1 << 11
}

To support this flag, ReactiveEffect.resume would become:

resume(): void {
    const flags = (this.flags &= ~EffectFlags.PAUSED)
    if (flags & (ReactiveFlags.Dirty | ReactiveFlags.Pending)) {
        this.flags |= EffectFlags.RESUME_RUN
        try {
            this.notify()
        } finally {
            this.flags &= ~EffectFlags.RESUME_RUN
        }
    }
  }

And the previous WatcherEffect.run check becomes:

run(initialRun = false) {
    // Run effect
    if (this.flags & EffectFlags.RESUME_RUN) return
    // Run callback
}

To make this behavior configurable, a WatchOptions configuration option may be introduced. For this discussion, let the new option be lazyResume:

run(initialRun = false) {
    // Run effect
    const { lazyResume } = this.options
    if (this.flags & EffectFlags.RESUME_RUN && lazyResume) return
    // Run callback
}

For non-synchronous RenderWatcherEffect, the EffectFlags.RESUME_RUN is not enough since it is synchronously reset. Instead, RenderWatcherEffect.notify should be the one detecting RESUME_RUN and then informing the scheduled job that it was scheduled due to resume being called; in that case, the job would need to upadte RESUME_RUN just like ReactiveEffect.resume.

The communication between RenderWatcherEffect.notify and RenderWatcherEffect.job could be made with another flag; this time, consider a private RenderWatcherEffect.#scheduledOnResume property. RenderWatcherEffect.notify turns on the flag when it is called with RESUME_RUN, and RenderWatcherEffect.job updates RESUME_RUN if RenderWatcherEffect.#scheduledOnResume is set:

// RenderWatcherEffect.notify
if (this.options.lazyResume && flush !== 'sync') {
    if (this.flags & EffectFlags.RESUME_RUN) {
        this.#scheduledOnResume = true
    }
}

// RenderWatcherEffect.constructor
const job = () => {
    if (this.dirty) {
        if (this.#scheduledOnResume) {
            this.flags |= EffectFlags.RESUME_RUN
            try {
                this.run()
            } finally {
                this.flags &= ~EffectFlags.RESUME_RUN
            }
        } else {
            this.run()
        }
    }
    this.#scheduledOnResume = false
}

However, any RenderWatcherEffect.notify call after it has been called with RESUME_RUN should unset #scheduledOnResume so that source mutations after resume do not skip the callback:

resume()
await nextTick() // skip callback

resume()
src.value++
await nextTick() // do not skip callback

For this, a third undefined state could be added to #scheduledOnResume:

// RenderWatcherEffect.notify
if (this.options.lazyResume && flush !== 'sync') {
    if (this.flags & EffectFlags.RESUME_RUN) {
        if (this.#scheduledOnResume === undefined) {
            this.#scheduledOnResume = true
        }
    } else if (this.#scheduledOnResume) {
        // reset when notify is called after watcher is resumed
        this.#scheduledOnResume = false
    }
}

and RenderWatcherEffect.job should reset #scheduledOnResume to undefined:

- this.#scheduledOnResume = false
+ this.#scheduledOnResume = undefined

Drawbacks

• Introduction of new effect flags in the form of additional properties or enums.

Alternatives

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

• watchIgnorable
• watchControlled

These alternatives, however, introduce overhead since an additional sync watcher is required for non-sync watchers. See their implementations:

• https://github.com/vueuse/vueuse/blob/v14.0.0/packages/shared/watchIgnorable/index.ts#L24
• https://github.com/8ctavio/vergil/blob/v0.15.0/packages/core/reactivity/watchControlled.js#L54

Unresolved questions

As previously mentioned, RenderWatcherEffect.notify should reset #scheduledOnResume for dependency updates performed after resume to normally execute the watcher callback. However, #scheduledOnResume alone is not enough if, in addition, dependencies are triggered before calling resume:

pause()
src.value++ // calls `notify`, but do not schedule `cb` because effect is paused
resume()    // calls `notify` and sets `#scheduledOnResume` to `true`
src.value++ // does not call `notify`, so `#scheduledOnResume` is not reset
await nextTick() // `cb` would be skipped, but shouldn't

Source updates performed while the watcher is paused, "mark" the effect as notified, so following synchronous updates do not call notify again. Apart from setting #scheduledOnResume to true, RenderWatcherEffect.notify should also ensure subsequent synchronous source updates are able to notify the effect once more.

For illustration, I was able to achieve this by turning off the effect's Pending flag:

if (this.#scheduledOnResume === undefined) {
    this.#scheduledOnResume = true
    // Allow the effect to be synchronously notified again
    this.flags &= ~ReactiveFlags.Pending
}

However, I do not know enough about the reactivity system to tell whether this is sufficient and appropriate.