feat(reactivity): add pause/resume methods to ReactiveEffect

packages/reactivity/__tests__/effect.spec.ts

@@ -1074,4 +1074,48 @@ describe('reactivity/effect', () => {
       expect(depC).toHaveLength(1)
     })
   })
+
+  test('should pause/resume effect', () => {
+    const obj = reactive({ foo: 1 })
+    const fnSpy = vi.fn(() => obj.foo)
+    const runner = effect(fnSpy)
+
+    expect(fnSpy).toHaveBeenCalledTimes(1)
+    expect(obj.foo).toBe(1)
+
+    runner.effect.pause()
+    obj.foo++
+    expect(fnSpy).toHaveBeenCalledTimes(1)
+    expect(obj.foo).toBe(2)
+
+    runner.effect.resume()
+    expect(fnSpy).toHaveBeenCalledTimes(2)
+    expect(obj.foo).toBe(2)
+
+    obj.foo++
+    expect(fnSpy).toHaveBeenCalledTimes(3)
+    expect(obj.foo).toBe(3)
+  })
+
+  test('should be executed once immediately when resume is called', () => {
+    const obj = reactive({ foo: 1 })
+    const fnSpy = vi.fn(() => obj.foo)
+    const runner = effect(fnSpy)
+
+    expect(fnSpy).toHaveBeenCalledTimes(1)
+    expect(obj.foo).toBe(1)
+
+    runner.effect.pause()
+    obj.foo++
+    expect(fnSpy).toHaveBeenCalledTimes(1)
+    expect(obj.foo).toBe(2)
+
+    obj.foo++
+    expect(fnSpy).toHaveBeenCalledTimes(1)
+    expect(obj.foo).toBe(3)
+
+    runner.effect.resume()
+    expect(fnSpy).toHaveBeenCalledTimes(2)
+    expect(obj.foo).toBe(3)
+  })
 })

packages/reactivity/__tests__/effectScope.spec.ts

@@ -296,4 +296,31 @@ describe('reactivity/effect/scope', () => {
       expect(getCurrentScope()).toBe(parentScope)
     })
   })
+
+  it('should pause/resume EffectScope', async () => {
+    const counter = reactive({ num: 0 })
+    const fnSpy = vi.fn(() => counter.num)
+    const scope = new EffectScope()
+    scope.run(() => {
+      effect(fnSpy)
+    })
+
+    expect(fnSpy).toHaveBeenCalledTimes(1)
+
+    counter.num++
+    await nextTick()
+    expect(fnSpy).toHaveBeenCalledTimes(2)
+
+    scope.pause()
+    counter.num++
+    await nextTick()
+    expect(fnSpy).toHaveBeenCalledTimes(2)
+
+    counter.num++
+    await nextTick()
+    expect(fnSpy).toHaveBeenCalledTimes(2)
+
+    scope.resume()
+    expect(fnSpy).toHaveBeenCalledTimes(3)
+  })
 })

packages/reactivity/src/effect.ts

@@ -61,7 +61,10 @@ export class ReactiveEffect<T = any> {
    * @internal
    */
   _depsLength = 0
-
+  /**
+   * @internal
+   */
+  _isStopped = false
   constructor(
     public fn: () => T,
     public trigger: () => void,
@@ -94,9 +97,27 @@ export class ReactiveEffect<T = any> {
     this._dirtyLevel = v ? DirtyLevels.Dirty : DirtyLevels.NotDirty
   }
 
+  pause() {
+    this.active = false
+  }
+
+  /**
+   * Resumes the execution of the reactive effect.
+   */
+  resume() {
+    if (!this._isStopped) {
+      this.active = true
+      if (pausedQueueEffects.has(this)) {
+        pausedQueueEffects.delete(this)
+        queueEffectSchedulers.push(this.scheduler!)
+        pauseScheduling()
+        resetScheduling()
+      }
+    }
+  }
   run() {
     this._dirtyLevel = DirtyLevels.NotDirty
-    if (!this.active) {
+    if (!this.active || this._isStopped) {
       return this.fn()
     }
     let lastShouldTrack = shouldTrack
@@ -116,11 +137,12 @@ export class ReactiveEffect<T = any> {
   }
 
   stop() {
-    if (this.active) {
+    if (!this._isStopped) {
       preCleanupEffect(this)
       postCleanupEffect(this)
       this.onStop?.()
       this.active = false
+      this._isStopped = true
     }
   }
 }
@@ -278,6 +300,7 @@ export function trackEffect(
 }
 
 const queueEffectSchedulers: (() => void)[] = []
+const pausedQueueEffects = new WeakSet<ReactiveEffect>()
 
 export function triggerEffects(
   dep: Dep,
@@ -304,7 +327,11 @@ export function triggerEffects(
         }
         effect.trigger()
         if (effect.scheduler) {
-          queueEffectSchedulers.push(effect.scheduler)
+          if (!effect.active) {
+            pausedQueueEffects.add(effect)
+          } else {
+            queueEffectSchedulers.push(effect.scheduler)
+          }
         }
       }
     }

packages/reactivity/src/effectScope.ts

@@ -17,6 +17,8 @@ export class EffectScope {
    */
   cleanups: (() => void)[] = []
 
+  private _isPaused = false
+
   /**
    * only assigned by undetached scope
    * @internal
@@ -48,6 +50,39 @@ export class EffectScope {
     return this._active
   }
 
+  pause() {
+    if (this._active) {
+      this._isPaused = true
+      if (this.scopes) {
+        for (let i = 0, l = this.scopes.length; i < l; i++) {
+          this.scopes[i].pause()
+        }
+      }
+      for (let i = 0, l = this.effects.length; i < l; i++) {
+        this.effects[i].pause()
+      }
+    }
+  }
+
+  /**
+   * Resumes the effect scope, including all child scopes and effects.
+   */
+  resume() {
+    if (this._active) {
+      if (this._isPaused) {
+        this._isPaused = false
+        if (this.scopes) {
+          for (let i = 0, l = this.scopes.length; i < l; i++) {
+            this.scopes[i].resume()
+          }
+        }
+        for (let i = 0, l = this.effects.length; i < l; i++) {
+          this.effects[i].resume()
+        }
+      }
+    }
+  }
+
   run<T>(fn: () => T): T | undefined {
     if (this._active) {
       const currentEffectScope = activeEffectScope

packages/runtime-core/__tests__/apiWatch.spec.ts

@@ -1278,4 +1278,43 @@ describe('api: watch', () => {
     expect(spy1).toHaveBeenCalledTimes(1)
     expect(spy2).toHaveBeenCalledTimes(1)
   })
+
+  test('pause / resume', async () => {
+    const count = ref(0)
+    const cb = vi.fn()
+    const { pause, resume } = watch(count, cb)
+
+    count.value++
+    await nextTick()
+    expect(cb).toHaveBeenCalledTimes(1)
+    expect(cb).toHaveBeenLastCalledWith(1, 0, expect.any(Function))
+
+    pause()
+    count.value++
+    await nextTick()
+    expect(cb).toHaveBeenCalledTimes(1)
+    expect(cb).toHaveBeenLastCalledWith(1, 0, expect.any(Function))
+
+    resume()
+    count.value++
+    await nextTick()
+    expect(cb).toHaveBeenCalledTimes(2)
+    expect(cb).toHaveBeenLastCalledWith(3, 1, expect.any(Function))
+
+    count.value++
+    await nextTick()
+    expect(cb).toHaveBeenCalledTimes(3)
+    expect(cb).toHaveBeenLastCalledWith(4, 3, expect.any(Function))
+
+    pause()
+    count.value++
+    await nextTick()
+    expect(cb).toHaveBeenCalledTimes(3)
+    expect(cb).toHaveBeenLastCalledWith(4, 3, expect.any(Function))
+
+    resume()
+    await nextTick()
+    expect(cb).toHaveBeenCalledTimes(4)
+    expect(cb).toHaveBeenLastCalledWith(5, 4, expect.any(Function))
+  })
 })

packages/runtime-core/src/apiWatch.ts

@@ -80,11 +80,17 @@ export interface WatchOptions<Immediate = boolean> extends WatchOptionsBase {
 
 export type WatchStopHandle = () => void
 
+export interface WatchHandle extends WatchStopHandle {
+  pause: () => void
+  resume: () => void
+  stop: () => void
+}
+
 // Simple effect.
 export function watchEffect(
   effect: WatchEffect,
   options?: WatchOptionsBase
-): WatchStopHandle {
+): WatchHandle {
   return doWatch(effect, null, options)
 }
 
@@ -123,7 +129,7 @@ export function watch<
   sources: [...T],
   cb: WatchCallback<MapSources<T, false>, MapSources<T, Immediate>>,
   options?: WatchOptions<Immediate>
-): WatchStopHandle
+): WatchHandle
 
 // overload: multiple sources w/ `as const`
 // watch([foo, bar] as const, () => {})
@@ -135,14 +141,14 @@ export function watch<
   source: T,
   cb: WatchCallback<MapSources<T, false>, MapSources<T, Immediate>>,
   options?: WatchOptions<Immediate>
-): WatchStopHandle
+): WatchHandle
 
 // overload: single source + cb
 export function watch<T, Immediate extends Readonly<boolean> = false>(
   source: WatchSource<T>,
   cb: WatchCallback<T, Immediate extends true ? T | undefined : T>,
   options?: WatchOptions<Immediate>
-): WatchStopHandle
+): WatchHandle
 
 // overload: watching reactive object w/ cb
 export function watch<
@@ -152,14 +158,14 @@ export function watch<
   source: T,
   cb: WatchCallback<T, Immediate extends true ? T | undefined : T>,
   options?: WatchOptions<Immediate>
-): WatchStopHandle
+): WatchHandle
 
 // implementation
 export function watch<T = any, Immediate extends Readonly<boolean> = false>(
   source: T | WatchSource<T>,
   cb: any,
   options?: WatchOptions<Immediate>
-): WatchStopHandle {
+): WatchHandle {
   if (__DEV__ && !isFunction(cb)) {
     warn(
       `\`watch(fn, options?)\` signature has been moved to a separate API. ` +
@@ -174,7 +180,7 @@ function doWatch(
   source: WatchSource | WatchSource[] | WatchEffect | object,
   cb: WatchCallback | null,
   { immediate, deep, flush, once, onTrack, onTrigger }: WatchOptions = EMPTY_OBJ
-): WatchStopHandle {
+): WatchHandle {
   if (cb && once) {
     const _cb = cb
     cb = (...args) => {
@@ -315,7 +321,11 @@ function doWatch(
       const ctx = useSSRContext()!
       ssrCleanup = ctx.__watcherHandles || (ctx.__watcherHandles = [])
     } else {
-      return NOOP
+      const watchHandle: WatchHandle = () => {}
+      watchHandle.stop = NOOP
+      watchHandle.resume = NOOP
+      watchHandle.pause = NOOP
+      return watchHandle
     }
   }
 
@@ -386,6 +396,11 @@ function doWatch(
     }
   }
 
+  const watchHandle: WatchHandle = () => unwatch()
+  watchHandle.pause = effect.pause.bind(effect)
+  watchHandle.resume = effect.resume.bind(effect)
+  watchHandle.stop = unwatch
+
   if (__DEV__) {
     effect.onTrack = onTrack
     effect.onTrigger = onTrigger
@@ -408,7 +423,7 @@ function doWatch(
   }
 
   if (__SSR__ && ssrCleanup) ssrCleanup.push(unwatch)
-  return unwatch
+  return watchHandle
 }
 
 // this.$watch