feat(watchAtMost): new function (vitest-dev#764)

Co-authored-by: webfansplz <>
Co-authored-by: Anthony Fu <anthonyfu117@hotmail.com>

.eslintrc.js

@@ -24,6 +24,7 @@ module.exports = {
         paths: ['vue', '@vue/composition-api'],
       },
     ],
+    'node/no-callback-literal': 'off',
   },
   overrides: [
     {

indexes.json

@@ -411,6 +411,13 @@
       "package": "shared",
       "internal": true
     },
+    {
+      "name": "watchAtMost",
+      "package": "shared",
+      "docs": "https://vueuse.org/shared/watchAtMost/",
+      "category": "Watch",
+      "description": "`watch` with the number of times triggered"
+    },
     {
       "name": "watchWithFilter",
       "package": "shared",

packages/functions.md

@@ -146,6 +146,7 @@
   - [`pausableWatch`](https://vueuse.org/shared/pausableWatch/) — pausable watch
   - [`throttledWatch`](https://vueuse.org/shared/throttledWatch/) — throttled watch
   - [`until`](https://vueuse.org/shared/until/) — promised one-time watch for changes
+  - [`watchAtMost`](https://vueuse.org/shared/watchAtMost/) — `watch` with the number of times triggered
   - [`watchWithFilter`](https://vueuse.org/shared/watchWithFilter/) — `watch` with additional EventFilter control
   - [`whenever`](https://vueuse.org/shared/whenever/) — shorthand for watching value to be truthy
 

packages/shared/index.ts

@@ -39,5 +39,6 @@ export * from './useTimeout'
 export * from './useTimeoutFn'
 export * from './useToggle'
 export * from './utils'
+export * from './watchAtMost'
 export * from './watchWithFilter'
 export * from './whenever'

packages/shared/watchAtMost/index.md

@@ -0,0 +1,23 @@
+---
+category: Watch
+---
+
+# watchAtMost
+
+`watch` with the number of times triggered.
+
+## Usage
+
+Similar to `watch` with an extra option `count` which set up the number of times the callback function is triggered. After the count is reached, the watch will be stopped automatically.
+
+```ts
+import { watchAtMost } from '@vueuse/core'
+
+watchAtMost(
+  source,
+  () => { console.log('trigger!') }, // triggered it at most 3 times
+  {
+    count: 3, // the number of times triggered
+  }
+)
+```

packages/shared/watchAtMost/index.test.ts

@@ -0,0 +1,21 @@
+import { ref, nextTick } from 'vue-demi'
+import { watchAtMost } from '.'
+
+describe('watchAtMost', () => {
+  it('should work', async() => {
+    const num = ref(0)
+    const spy = jest.fn()
+
+    const { count } = watchAtMost(num, spy, {
+      count: 2,
+    })
+    num.value = 1
+    await nextTick()
+    num.value = 2
+    await nextTick()
+    num.value = 3
+    await nextTick()
+    expect(spy).toBeCalledTimes(2)
+    expect(count.value).toBe(2)
+  })
+})

packages/shared/watchAtMost/index.ts

@@ -0,0 +1,46 @@
+import { Ref, WatchSource, ref, unref, WatchStopHandle, WatchCallback } from 'vue-demi'
+import { MapOldSources, MapSources, MaybeRef } from '../utils'
+import { WatchWithFilterOptions, watchWithFilter } from '../watchWithFilter'
+
+export interface WatchAtMostOptions<Immediate> extends WatchWithFilterOptions<Immediate> {
+  count: MaybeRef<number>
+}
+
+export interface WatchAtMostReturn {
+  stop: WatchStopHandle
+  count: Ref<number>
+}
+
+// overlads
+export function watchAtMost<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options: WatchAtMostOptions<Immediate>): WatchAtMostReturn
+
+export function watchAtMost<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options: WatchAtMostOptions<Immediate>): WatchAtMostReturn
+
+export function watchAtMost<T, Immediate extends Readonly<boolean> = false>(sources: WatchSource<T>, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options: WatchAtMostOptions<Immediate>): WatchAtMostReturn
+
+// implementation
+export function watchAtMost<Immediate extends Readonly<boolean> = false>(
+  source: any,
+  cb: any,
+  options: WatchAtMostOptions<Immediate>,
+): WatchAtMostReturn {
+  const {
+    count,
+    ...watchOptions
+  } = options
+
+  const current = ref(0)
+
+  const stop = watchWithFilter(
+    source,
+    (...args) => {
+      current.value += 1
+      if (current.value >= unref(count))
+        stop()
+      cb(...args)
+    },
+    watchOptions,
+  )
+
+  return { count: current, stop }
+}