1---
2category: Watch
3---
4 
5# until
6 
7Promised one-time watch for changes
8 
9## Usage
10 
11#### Wait for some async data to be ready
12 
13```ts
14import { until, useAsyncState } from '@vueuse/core'
15 
16const { state, isReady } = useAsyncState(
17  fetch('https://jsonplaceholder.typicode.com/todos/1').then(t => t.json()),
18  {},
19)
20 
21;(async () => {
22  await until(isReady).toBe(true)
23 
24  console.log(state) // state is now ready!
25})()
26```
27 
28#### Wait for custom conditions
29 
30> You can use `invoke` to call the async function.
31 
32```ts
33import { invoke, until, useCounter } from '@vueuse/core'
34 
35const { count } = useCounter()
36 
37invoke(async () => {
38  await until(count).toMatch(v => v > 7)
39 
40  alert('Counter is now larger than 7!')
41})
42```
43 
44#### Timeout
45 
46```ts
47import { until } from '@vueuse/core'
48// ---cut---
49// will be resolve until ref.value === true or 1000ms passed
50await until(ref).toBe(true, { timeout: 1000 })
51 
52// will throw if timeout
53try {
54  await until(ref).toBe(true, { timeout: 1000, throwOnTimeout: true })
55  // ref.value === true
56}
57catch (e) {
58  // timeout
59}
60```
61 
62#### More Examples
63 
64```ts
65import { until } from '@vueuse/core'
66// ---cut---
67await until(ref).toBe(true)
68await until(ref).toMatch(v => v > 10 && v < 100)
69await until(ref).changed()
70await until(ref).changedTimes(10)
71await until(ref).toBeTruthy()
72await until(ref).toBeNull()
73 
74await until(ref).not.toBeNull()
75await until(ref).not.toBeTruthy()
76```
77 
78## Type Declarations
79 
80```ts
81export interface UntilToMatchOptions extends ConfigurableFlushSync {
82  /**
83   * Milliseconds timeout for promise to resolve/reject if the when condition does not meet.
84   * 0 for never timed out
85   *
86   * @default 0
87   */
88  timeout?: number
89  /**
90   * Reject the promise when timeout
91   *
92   * @default false
93   */
94  throwOnTimeout?: boolean
95  /**
96   * `deep` option for internal watch
97   *
98   * @default 'false'
99   */
100  deep?: WatchOptions["deep"]
101}
102export interface UntilBaseInstance<T, Not extends boolean = false> {
103  toMatch: (<U extends T = T>(
104    condition: (v: T) => v is U,
105    options?: UntilToMatchOptions,
106  ) => Not extends true ? Promise<Exclude<T, U>> : Promise<U>) &
107    ((
108      condition: (v: T) => boolean,
109      options?: UntilToMatchOptions,
110    ) => Promise<T>)
111  changed: (options?: UntilToMatchOptions) => Promise<T>
112  changedTimes: (n?: number, options?: UntilToMatchOptions) => Promise<T>
113}
114type Falsy = false | void | null | undefined | 0 | 0n | ""
115export interface UntilValueInstance<
116  T,
117  Not extends boolean = false,
118> extends UntilBaseInstance<T, Not> {
119  readonly not: UntilValueInstance<T, Not extends true ? false : true>
120  toBe: <P = T>(
121    value: MaybeRefOrGetter<P>,
122    options?: UntilToMatchOptions,
123  ) => Not extends true ? Promise<T> : Promise<P>
124  toBeTruthy: (
125    options?: UntilToMatchOptions,
126  ) => Not extends true ? Promise<T & Falsy> : Promise<Exclude<T, Falsy>>
127  toBeNull: (
128    options?: UntilToMatchOptions,
129  ) => Not extends true ? Promise<Exclude<T, null>> : Promise<null>
130  toBeUndefined: (
131    options?: UntilToMatchOptions,
132  ) => Not extends true ? Promise<Exclude<T, undefined>> : Promise<undefined>
133  toBeNaN: (options?: UntilToMatchOptions) => Promise<T>
134}
135export interface UntilArrayInstance<T> extends UntilBaseInstance<T> {
136  readonly not: UntilArrayInstance<T>
137  toContains: (
138    value: MaybeRefOrGetter<ElementOf<ShallowUnwrapRef<T>>>,
139    options?: UntilToMatchOptions,
140  ) => Promise<T>
141}
142/**
143 * Promised one-time watch for changes
144 *
145 * @see https://vueuse.org/until
146 * @example
147 * ```
148 * const { count } = useCounter()
149 *
150 * await until(count).toMatch(v => v > 7)
151 *
152 * alert('Counter is now larger than 7!')
153 * ```
154 */
155export declare function until<T extends unknown[]>(
156  r: WatchSource<T> | MaybeRefOrGetter<T>,
157): UntilArrayInstance<T>
158export declare function until<T>(
159  r: WatchSource<T> | MaybeRefOrGetter<T>,
160): UntilValueInstance<T>
161```
162