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 NPM version NPM Downloads Docs & Demos -Function Count +Function Count
GitHub stars

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, + ) +}