feat(whenever): new function (#418)

README.md

@@ -7,7 +7,7 @@ Collection of essential Vue Composition Utilities
 <a href="https://www.npmjs.com/package/@vueuse/core" target="__blank"><img src="https://img.shields.io/npm/v/@vueuse/core?color=a1b858&label=" alt="NPM version"></a>
 <a href="https://www.npmjs.com/package/@vueuse/core" target="__blank"><img alt="NPM Downloads" src="https://img.shields.io/npm/dm/@vueuse/core?color=50a36f&label="></a>
 <a href="https://vueuse.org" target="__blank"><img src="https://img.shields.io/static/v1?label=&message=docs%20%26%20demos&color=1e8a7a" alt="Docs & Demos"></a>
-<img alt="Function Count" src="https://img.shields.io/badge/-109%20functions-13708a">
+<img alt="Function Count" src="https://img.shields.io/badge/-110%20functions-13708a">
 <br>
 <a href="https://github.com/vueuse/vueuse" target="__blank"><img alt="GitHub stars" src="https://img.shields.io/github/stars/vueuse/vueuse?style=social"></a>
 </p>

indexes.json

@@ -298,6 +298,13 @@
       "category": "Watch",
       "description": "`watch` with additional EventFilter control"
     },
+    {
+      "name": "whenever",
+      "package": "shared",
+      "docs": "https://vueuse.org/shared/whenever/",
+      "category": "Watch",
+      "description": "shorthand for watching value to be truthy"
+    },
     {
       "name": "asyncComputed",
       "package": "core",

packages/functions.md

@@ -118,6 +118,7 @@
   - [`throttledWatch`](https://vueuse.org/shared/throttledWatch/) — throttled watch
   - [`until`](https://vueuse.org/shared/until/) — promised one-time watch for changes
   - [`watchWithFilter`](https://vueuse.org/shared/watchWithFilter/) — `watch` with additional EventFilter control
+  - [`whenever`](https://vueuse.org/shared/whenever/) — shorthand for watching value to be truthy
 
 
 <!--FUNCTIONS_LIST_ENDS-->

packages/shared/index.ts

@@ -27,3 +27,4 @@ export * from './useTimeoutFn'
 export * from './useToggle'
 export * from './utils'
 export * from './watchWithFilter'
+export * from './whenever'

packages/shared/whenever/index.md

@@ -0,0 +1,80 @@
+---
+category: Watch
+---
+
+# whenever
+
+Shorthand for watching value to be truthy.
+
+## Usage
+
+```js
+import { whenever, useAsyncState } from '@vueuse/core'
+
+const { state, ready } = useAsyncState(
+  fetch('https://jsonplaceholder.typicode.com/todos/1').then(t => t.json()),
+  {},
+)
+
+whenever(ready, () => console.log(state))
+```
+
+```ts
+// this
+whenever(ready, () => console.log(state))
+
+// is equivalent to:
+watch(ready, (isReady) => {
+  if (isReady) {
+    console.log(state)
+  }
+})
+```
+
+### Computed
+
+Same as `watch`, you can pass a getter function to calculate on each change.
+
+```ts
+// this
+whenever(
+  () => counter.value === 7, 
+  () => console.log('counter is 7 now!'),
+)
+```
+
+### Options
+
+Options and defaults are same with `watch`.
+
+```ts
+// this
+whenever(
+  () => counter.value === 7, 
+  () => console.log('counter is 7 now!'),
+  { flush: 'sync' }
+)
+```
+
+<!--FOOTER_STARTS-->
+## Type Declarations
+
+```typescript
+/**
+ * Shorthand for watching value to be truthy
+ *
+ * @link https://vueuse.js.org/whenever
+ */
+export declare function whenever<T = boolean>(
+  source: WatchSource<T>,
+  cb: Fn,
+  options?: WatchOptions
+): WatchStopHandle
+```
+
+## Source
+
+[Source](https://github.com/vueuse/vueuse/blob/main/packages/shared/whenever/index.ts) • [Docs](https://github.com/vueuse/vueuse/blob/main/packages/shared/whenever/index.md)
+
+
+<!--FOOTER_ENDS-->

packages/shared/whenever/index.ts

@@ -0,0 +1,15 @@
+import { WatchOptions, watch, WatchSource } from 'vue-demi'
+import { Fn } from '../utils'
+
+/**
+ * Shorthand for watching value to be truthy
+ *
+ * @link https://vueuse.js.org/whenever
+ */
+export function whenever<T = boolean>(source: WatchSource<T>, cb: Fn, options?: WatchOptions) {
+  return watch(
+    source,
+    (v) => { if (v) cb() },
+    options,
+  )
+}