feat(watchOnce): use vue's native once behaviour (#4750)

ferferga · web-flow · commit 08f7dc4ae763 · 2025-05-14T04:44:48.000Z
diff --git a/packages/shared/watchOnce/index.md b/packages/shared/watchOnce/index.md
@@ -4,17 +4,12 @@ category: Watch
 
 # watchOnce
 
-`watch` that only triggers once.
-
-::: tip
-
-[Once Watcher](https://vuejs.org/guide/essentials/watchers.html#once-watchers) has been added to Vue [since 3.4](https://github.com/vuejs/core/pull/9034), use `watch(watchSource, callback, { once: true })` instead on supported versions.
-
-:::
+Shorthand for watching value with `{ once: true }`. Once the callback fires once, the watcher will be stopped.
+See [Vue's docs](https://vuejs.org/guide/essentials/watchers.html#once-watchers) for full details.
 
 ## Usage
 
-After the callback function has been triggered once, the watch will be stopped automatically.
+Similar to `watch`, but with `{ once: true }`
 
 ```ts
 import { watchOnce } from '@vueuse/core'
diff --git a/packages/shared/watchOnce/index.ts b/packages/shared/watchOnce/index.ts
@@ -1,23 +1,38 @@
 import type { WatchCallback, WatchOptions, WatchSource, WatchStopHandle } from 'vue'
 import type { MapOldSources, MapSources } from '../utils'
-import { nextTick, watch } from 'vue'
+import { watch } from 'vue'
 
 // overloads
-export function watchOnce<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(source: [...T], cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options?: WatchOptions<Immediate>): WatchStopHandle
+export function watchOnce<T extends Readonly<WatchSource<unknown>[]>>(
+  source: [...T],
+  cb: WatchCallback<MapSources<T>, MapOldSources<T, true>>,
+  options?: Omit<WatchOptions<true>, 'once'>
+): WatchStopHandle
 
-export function watchOnce<T, Immediate extends Readonly<boolean> = false>(sources: WatchSource<T>, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: WatchOptions<Immediate>): WatchStopHandle
+export function watchOnce<T>(
+  source: WatchSource<T>,
+  cb: WatchCallback<T, T | undefined>,
+  options?: Omit<WatchOptions<true>, 'once'>
+): WatchStopHandle
 
-// implementation
-export function watchOnce<Immediate extends Readonly<boolean> = false>(
-  source: any,
-  cb: any,
-  options?: WatchOptions<Immediate>,
-): WatchStopHandle {
-  const stop = watch(source, (...args) => {
-    nextTick(() => stop())
+export function watchOnce<T extends object>(
+  source: T,
+  cb: WatchCallback<T, T | undefined>,
+  options?: Omit<WatchOptions<true>, 'once'>
+): WatchStopHandle
 
-    return cb(...args)
-  }, options)
-
-  return stop
+/**
+ * Shorthand for watching value with { once: true }
+ *
+ * @see https://vueuse.org/watchOnce
+ */
+export function watchOnce<T = any>(source: T, cb: any, options?: Omit<WatchOptions, 'once'>) {
+  return watch(
+    source as any,
+    cb,
+    {
+      ...options,
+      once: true,
+    },
+  )
 }
