From d6775e4b3230b0053053c74ca8ba83e49a0b814b Mon Sep 17 00:00:00 2001
From: Anthony Fu
Date: Sun, 4 Apr 2021 22:40:25 +0800
Subject: [PATCH] feat(whenever): new function (#418)
---
README.md | 2 +-
indexes.json | 7 +++
packages/functions.md | 1 +
packages/shared/index.ts | 1 +
packages/shared/whenever/index.md | 80 +++++++++++++++++++++++++++++++
packages/shared/whenever/index.ts | 15 ++++++
6 files changed, 105 insertions(+), 1 deletion(-)
create mode 100644 packages/shared/whenever/index.md
create mode 100644 packages/shared/whenever/index.ts
diff --git a/README.md b/README.md
index 4f7f46b27bc..11ce6557b77 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Collection of essential Vue Composition Utilities
-
+
diff --git a/indexes.json b/indexes.json
index 865938b502e..5b3e9e7c080 100644
--- a/indexes.json
+++ b/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",
diff --git a/packages/functions.md b/packages/functions.md
index c86bfbf87a4..1d903266d59 100644
--- a/packages/functions.md
+++ b/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
diff --git a/packages/shared/index.ts b/packages/shared/index.ts
index 724a8832fe8..771e8b38a7f 100644
--- a/packages/shared/index.ts
+++ b/packages/shared/index.ts
@@ -27,3 +27,4 @@ export * from './useTimeoutFn'
export * from './useToggle'
export * from './utils'
export * from './watchWithFilter'
+export * from './whenever'
diff --git a/packages/shared/whenever/index.md b/packages/shared/whenever/index.md
new file mode 100644
index 00000000000..178641fda8f
--- /dev/null
+++ b/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' }
+)
+```
+
+
+## Type Declarations
+
+```typescript
+/**
+ * Shorthand for watching value to be truthy
+ *
+ * @link https://vueuse.js.org/whenever
+ */
+export declare function whenever(
+ source: WatchSource,
+ 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)
+
+
+
diff --git a/packages/shared/whenever/index.ts b/packages/shared/whenever/index.ts
new file mode 100644
index 00000000000..dac64d3472e
--- /dev/null
+++ b/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(source: WatchSource, cb: Fn, options?: WatchOptions) {
+ return watch(
+ source,
+ (v) => { if (v) cb() },
+ options,
+ )
+}