until ​
Promised one-time watch for changes
Demo ​
Usage ​
Wait for some async data to be ready ​
js
import { until, useAsyncState } from '@vueuse/core'
const { state, isReady } = useAsyncState(
fetch('https://jsonplaceholder.typicode.com/todos/1').then(t => t.json()),
{},
)
;(async () => {
await until(isReady).toBe(true)
console.log(state) // state is now ready!
})()
Wait for custom conditions ​
You can use
invoke
to call the async function.
js
import { invoke, until, useCounter } from '@vueuse/core'
const { count } = useCounter()
invoke(async () => {
await until(count).toMatch(v => v > 7)
alert('Counter is now larger than 7!')
})
Timeout ​
ts
// will be resolve until ref.value === true or 1000ms passed
await until(ref).toBe(true, { timeout: 1000 })
// will throw if timeout
try {
await until(ref).toBe(true, { timeout: 1000, throwOnTimeout: true })
// ref.value === true
}
catch (e) {
// timeout
}
More Examples ​
ts
await until(ref).toBe(true)
await until(ref).toMatch(v => v > 10 && v < 100)
await until(ref).changed()
await until(ref).changedTimes(10)
await until(ref).toBeTruthy()
await until(ref).toBeNull()
await until(ref).not.toBeNull()
await until(ref).not.toBeTruthy()
Type Declarations ​
Show Type Declarations
typescript
export interface UntilToMatchOptions {
/**
* Milliseconds timeout for promise to resolve/reject if the when condition does not meet.
* 0 for never timed out
*
* @default 0
*/
timeout?: number
/**
* Reject the promise when timeout
*
* @default false
*/
throwOnTimeout?: boolean
/**
* `flush` option for internal watch
*
* @default 'sync'
*/
flush?: WatchOptions["flush"]
/**
* `deep` option for internal watch
*
* @default 'false'
*/
deep?: WatchOptions["deep"]
}
export interface UntilBaseInstance<T, Not extends boolean = false> {
toMatch: (<U extends T = T>(
condition: (v: T) => v is U,
options?: UntilToMatchOptions,
) => Not extends true ? Promise<Exclude<T, U>> : Promise<U>) &
((
condition: (v: T) => boolean,
options?: UntilToMatchOptions,
) => Promise<T>)
changed: (options?: UntilToMatchOptions) => Promise<T>
changedTimes: (n?: number, options?: UntilToMatchOptions) => Promise<T>
}
type Falsy = false | void | null | undefined | 0 | 0n | ""
export interface UntilValueInstance<T, Not extends boolean = false>
extends UntilBaseInstance<T, Not> {
readonly not: UntilValueInstance<T, Not extends true ? false : true>
toBe: <P = T>(
value: MaybeRefOrGetter<P>,
options?: UntilToMatchOptions,
) => Not extends true ? Promise<T> : Promise<P>
toBeTruthy: (
options?: UntilToMatchOptions,
) => Not extends true ? Promise<T & Falsy> : Promise<Exclude<T, Falsy>>
toBeNull: (
options?: UntilToMatchOptions,
) => Not extends true ? Promise<Exclude<T, null>> : Promise<null>
toBeUndefined: (
options?: UntilToMatchOptions,
) => Not extends true ? Promise<Exclude<T, undefined>> : Promise<undefined>
toBeNaN: (options?: UntilToMatchOptions) => Promise<T>
}
export interface UntilArrayInstance<T> extends UntilBaseInstance<T> {
readonly not: UntilArrayInstance<T>
toContains: (
value: MaybeRefOrGetter<ElementOf<ShallowUnwrapRef<T>>>,
options?: UntilToMatchOptions,
) => Promise<T>
}
/**
* Promised one-time watch for changes
*
* @see https://vueuse.org/until
* @example
* ```
* const { count } = useCounter()
*
* await until(count).toMatch(v => v > 7)
*
* alert('Counter is now larger than 7!')
* ```
*/
export declare function until<T extends unknown[]>(
r: WatchSource<T> | MaybeRefOrGetter<T>,
): UntilArrayInstance<T>
export declare function until<T>(
r: WatchSource<T> | MaybeRefOrGetter<T>,
): UntilValueInstance<T>
Source ​
Contributors ​
Anthony Fu
Anthony Fu
OrbisK
Gianthard-cyh
sun0day
lsdsjy
Mitchell
Jeff Zou
wheat
Shinigami
Alex Kozack
Changelog ​
Pending for release...
59f75
- feat(toValue): deprecate toValue
from @vueuse/shared
in favor of Vue's nativev12.0.0-beta.1
on 11/21/2024v11.0.0-beta.2
on 7/17/2024v10.8.0
on 2/20/2024a086e
- fix: stricter typesv10.0.0-beta.4
on 4/13/20234d757
- feat(types)!: rename MaybeComputedRef
to MaybeRefOrGetter
0a72b
- feat(toValue): rename resolveUnref
to toValue