until
Promised one-time watch for changes
Demo
Usage
Wait for some async data to be ready
import { until, useAsyncState } from '@vueuse/core'
const { state, ready } = useAsyncState(
fetch('https://jsonplaceholder.typicode.com/todos/1').then(t => t.json()),
{},
)
;(async () => {
await until(ready).toBe(true)
console.log(state) // state is now ready!
})()
import { until, useAsyncState } from '@vueuse/core'
const { state, ready } = useAsyncState(
fetch('https://jsonplaceholder.typicode.com/todos/1').then(t => t.json()),
{},
)
;(async () => {
await until(ready).toBe(true)
console.log(state) // state is now ready!
})()
Wait for custom conditions
You can use
invoke
to call the async function.
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!')
})
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
// 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
}
// 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
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()
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
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>
toMatch(
condition: (v: T) => boolean,
options?: UntilToMatchOptions
): Promise<T>
changed(options?: UntilToMatchOptions): Promise<T>
changedTimes(n?: number, options?: UntilToMatchOptions): Promise<T>
}
declare 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: MaybeRef<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: MaybeRef<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> | MaybeRef<T>
): UntilArrayInstance<T>
export declare function until<T>(
r: WatchSource<T> | MaybeRef<T>
): UntilValueInstance<T>
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>
toMatch(
condition: (v: T) => boolean,
options?: UntilToMatchOptions
): Promise<T>
changed(options?: UntilToMatchOptions): Promise<T>
changedTimes(n?: number, options?: UntilToMatchOptions): Promise<T>
}
declare 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: MaybeRef<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: MaybeRef<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> | MaybeRef<T>
): UntilArrayInstance<T>
export declare function until<T>(
r: WatchSource<T> | MaybeRef<T>
): UntilValueInstance<T>