refactor: replace WatchStopHandle with WatchHandle in watchAtMost, wa…

…tchDebounced, watchIgnorable, watchTriggerable, and watchWithFilter for consistency and improved functionality
vueuse · ArthurDarkstone · Jul 4, 2025 · Jul 4, 2025 · Jul 4, 2025 · Jul 4, 2025
commit cc2b011b9f8db766910ec1a2d651f53b08aff72d
diff --git a/packages/shared/watchAtMost/index.ts b/packages/shared/watchAtMost/index.ts
@@ -1,4 +1,4 @@
-import type { MaybeRefOrGetter, ShallowRef, WatchCallback, WatchSource, WatchStopHandle } from 'vue'
+import type { MaybeRefOrGetter, ShallowRef, WatchCallback, WatchHandle, WatchSource } from 'vue'
 import type { MapOldSources, MapSources } from '../utils'
 import type { WatchWithFilterOptions } from '../watchWithFilter'
 import { nextTick, shallowRef, toValue } from 'vue'
@@ -8,8 +8,7 @@ export interface WatchAtMostOptions<Immediate> extends WatchWithFilterOptions<Im
   count: MaybeRefOrGetter<number>
 }
 
-export interface WatchAtMostReturn {
-  stop: WatchStopHandle
+export interface WatchAtMostReturn extends WatchHandle {
   count: ShallowRef<number>
 }
 
@@ -31,17 +30,21 @@ export function watchAtMost<Immediate extends Readonly<boolean> = false>(
 
   const current = shallowRef(0)
 
-  const stop = watchWithFilter(
+  const watchHandle = watchWithFilter(
     source,
     (...args) => {
       current.value += 1
       if (current.value >= toValue(count))
-        nextTick(() => stop())
+        nextTick(() => watchHandle.stop())
 
       cb(...args)
     },
     watchOptions,
   )
 
-  return { count: current, stop }
+  const res = watchHandle as WatchAtMostReturn
+
+  res.count = current
+
+  return res
 }
diff --git a/packages/shared/watchDebounced/index.ts b/packages/shared/watchDebounced/index.ts
@@ -1,4 +1,4 @@
-import type { MaybeRefOrGetter, WatchCallback, WatchOptions, WatchSource, WatchStopHandle } from 'vue'
+import type { MaybeRefOrGetter, WatchCallback, WatchHandle, WatchOptions, WatchSource, WatchStopHandle } from 'vue'
 import type { DebounceFilterOptions, MapOldSources, MapSources } from '../utils'
 import { debounceFilter } from '../utils'
 import { watchWithFilter } from '../watchWithFilter'
@@ -17,7 +17,7 @@ export function watchDebounced<Immediate extends Readonly<boolean> = false>(
   source: any,
   cb: any,
   options: WatchDebouncedOptions<Immediate> = {},
-): WatchStopHandle {
+): WatchHandle {
   const {
     debounce = 0,
     maxWait = undefined,

diff --git a/packages/shared/watchIgnorable/demo.vue b/packages/shared/watchIgnorable/demo.vue
@@ -5,7 +5,7 @@ import { shallowRef } from 'vue'
 const log = shallowRef('')
 const source = shallowRef(0)
 
-const { ignoreUpdates } = watchIgnorable(
+const { ignoreUpdates, pause, resume } = watchIgnorable(
   source,
   v => (log.value += `Changed to "${v}"\n`),
   { flush: 'sync' },
@@ -33,6 +33,12 @@ function ignoredUpdate() {
   <button class="orange" @click="ignoredUpdate">
     Ignored Update
   </button>
+  <button @click="pause">
+    Pause
+  </button>
+  <button @click="resume">
+    Resume
+  </button>
   <button @click="clear">
     Reset
   </button>

diff --git a/packages/shared/watchIgnorable/index.ts b/packages/shared/watchIgnorable/index.ts
@@ -1,5 +1,5 @@
-import type { WatchCallback, WatchSource, WatchStopHandle } from 'vue'
-import type { Fn, MapOldSources, MapSources } from '../utils'
+import type { WatchCallback, WatchHandle, WatchSource } from 'vue'
+import type { MapOldSources, MapSources } from '../utils'
 import type { WatchWithFilterOptions } from '../watchWithFilter'
 import { watch } from 'vue'
 import { bypassFilter, createFilterWrapper } from '../utils'
@@ -11,10 +11,9 @@ import { bypassFilter, createFilterWrapper } from '../utils'
 export type IgnoredUpdater = (updater: () => void) => void
 export type IgnoredPrevAsyncUpdates = () => void
 
-export interface WatchIgnorableReturn {
+export interface WatchIgnorableReturn extends WatchHandle {
   ignoreUpdates: IgnoredUpdater
   ignorePrevAsyncUpdates: IgnoredPrevAsyncUpdates
-  stop: WatchStopHandle
 }
 
 export function watchIgnorable<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(sources: [...T], cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options?: WatchWithFilterOptions<Immediate>): WatchIgnorableReturn
@@ -38,7 +37,7 @@ export function watchIgnorable<Immediate extends Readonly<boolean> = false>(
 
   let ignoreUpdates: IgnoredUpdater
   let ignorePrevAsyncUpdates: IgnoredPrevAsyncUpdates
-  let stop: WatchStopHandle
+  let watchHandle: WatchHandle
 
   if (watchOptions.flush === 'sync') {
     let ignore = false
@@ -54,7 +53,7 @@ export function watchIgnorable<Immediate extends Readonly<boolean> = false>(
       ignore = false
     }
 
-    stop = watch(
+    watchHandle = watch(
       source,
       (...args) => {
         if (!ignore)
@@ -66,7 +65,7 @@ export function watchIgnorable<Immediate extends Readonly<boolean> = false>(
   else {
     // flush 'pre' and 'post'
 
-    const disposables: Fn[] = []
+    const disposables: WatchHandle[] = []
 
     // counters for how many following changes to be ignored
     // ignoreCounter is incremented before there is a history operation
@@ -121,12 +120,29 @@ export function watchIgnorable<Immediate extends Readonly<boolean> = false>(
       ),
     )
 
-    stop = () => {
+    watchHandle = (() => {
       disposables.forEach(fn => fn())
+    }) as WatchHandle
+
+    watchHandle.stop = () => {
+      disposables.forEach(fn => fn())
+    }
+
+    watchHandle.pause = () => {
+      disposables.forEach(fn => fn.pause())
+    }
+
+    watchHandle.resume = () => {
+      disposables.forEach(fn => fn.resume())
     }
   }
 
-  return { stop, ignoreUpdates, ignorePrevAsyncUpdates }
+  const res = watchHandle as WatchIgnorableReturn
+
+  res.ignoreUpdates = ignoreUpdates
+  res.ignorePrevAsyncUpdates = ignorePrevAsyncUpdates
+
+  return res
 }
 
 // alias

diff --git a/packages/shared/watchTriggerable/demo.vue b/packages/shared/watchTriggerable/demo.vue
@@ -5,7 +5,7 @@ import { shallowRef } from 'vue'
 const log = shallowRef('')
 const source = shallowRef(0)
 
-const { trigger, ignoreUpdates } = watchTriggerable(
+const { trigger, ignoreUpdates, pause, resume } = watchTriggerable(
   source,
   async (v, _, onCleanup) => {
     let canceled = false
@@ -37,6 +37,12 @@ function update() {
   <button class="orange" @click="trigger">
     Manual Trigger
   </button>
+  <button @click="pause">
+    Pause
+  </button>
+  <button @click="resume">
+    Resume
+  </button>
   <button @click="clear">
     Reset
   </button>

diff --git a/packages/shared/watchTriggerable/index.ts b/packages/shared/watchTriggerable/index.ts
@@ -51,8 +51,8 @@ export function watchTriggerable<Immediate extends Readonly<boolean> = false>(
 
     return cb(value, oldValue, onCleanup)
   }
-  const res = watchIgnorable(source, _cb, options)
-  const { ignoreUpdates } = res
+  const watchHandle = watchIgnorable(source, _cb, options)
+  const { ignoreUpdates } = watchHandle
 
   const trigger = () => {
     let res: any
@@ -62,10 +62,11 @@ export function watchTriggerable<Immediate extends Readonly<boolean> = false>(
     return res
   }
 
-  return {
-    ...res,
-    trigger,
-  }
+  const res = watchHandle as WatchTriggerableReturn
+
+  res.trigger = trigger
+
+  return res
 }
 
 function getWatchSources(sources: any) {

diff --git a/packages/shared/watchWithFilter/index.ts b/packages/shared/watchWithFilter/index.ts
@@ -1,4 +1,4 @@
-import type { WatchCallback, WatchOptions, WatchSource, WatchStopHandle } from 'vue'
+import type { WatchCallback, WatchHandle, WatchOptions, WatchSource } from 'vue'
 import type { ConfigurableEventFilter, MapOldSources, MapSources } from '../utils'
 import { watch } from 'vue'
 import { bypassFilter, createFilterWrapper } from '../utils'
@@ -6,16 +6,16 @@
 export interface WatchWithFilterOptions<Immediate> extends WatchOptions<Immediate>, ConfigurableEventFilter {}

 // overloads
 export function watchWithFilter<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(sources: [...T], cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options?: WatchWithFilterOptions<Immediate>): WatchStopHandle
 export function watchWithFilter<T, Immediate extends Readonly<boolean> = false>(source: WatchSource<T>, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: WatchWithFilterOptions<Immediate>): WatchStopHandle
 export function watchWithFilter<T extends object, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: WatchWithFilterOptions<Immediate>): WatchStopHandle

 // implementation
 export function watchWithFilter<Immediate extends Readonly<boolean> = false>(
   source: any,
   cb: any,
   options: WatchWithFilterOptions<Immediate> = {},
-): WatchStopHandle {
+): WatchHandle {
   const {
     eventFilter = bypassFilter,
     ...watchOptions