until

Await a reactive source reaching a condition.


Package	`@vizejs/composable/until`
Own the source	`vize lib pull composable:until`
Runtime exports	`until`
Gzip budget	2048 B

Usage

import { until } from "@vizejs/composable/until";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`until`	reactivity	experimental	safe	not-applicable	caller	web, server, worker, native, desktop, terminal	`globalThis`	—

API

`until`

Await a reactive source reaching a condition. Every matcher resolves immediately when the current value already satisfies it (except changed/changedTimes), and otherwise watches the source (flush: "sync" by default, which also works inside server-side setup). Result types are narrowed by the matcher: toBeTruthy() strips falsy members, not.toBeNull() strips null, toMatch(guard) follows the guard. Because a timeout rejects (it never resolves with an unmatched value), the narrowing is always sound. Watchers and timers are released as soon as the promise settles.

function until<Value>(source: MaybeRefOrGetter<Value>): UntilChain<Value>

const user = await until(currentUser).not.toBeNull({ timeout: 5_000 });
const ready = await until(status).toBe("ready");

Types

`UntilOptions`

Options shared by every until matcher.

Member	Type	Description
`timeout`?	`number`	Reject when the condition is not met within this many milliseconds. `undefined` waits indefinitely (until the owning scope stops watching).
`signal`?	`AbortSignal`	Abort the wait; the promise rejects with the signal's reason.
`flush`?	`"pre" \| "post" \| "sync"`	Watch flush timing. `"sync"` also works during server rendering.
`deep`?	`boolean`	Watch nested properties of the value.
`scheduler`?	`TimeoutScheduler`	Owns the timeout timer.

`UntilTimeoutError`

Rejection reason used when an until wait times out.

Member	Type	Description
`code`	`UntilTimeoutCode`	Stable machine-readable code.

`UntilMatchers`

Matchers that wait for the source to satisfy a condition.

Member	Type	Description
`toMatch`	`(condition: (value: Value) => value is Narrowed, options?: UntilOptions) => Promise<Narrowed> \| (condition: (value: Value) => boolean, options?: UntilOptions) => Promise<Value>`	Resolve once the value satisfies the type guard, narrowing the result.
`toBe`	`(expected: MaybeRefOrGetter<Expected>, options?: UntilOptions) => Promise<Expected>`	Resolve once the value is `Object.is`-equal to `expected` (itself possibly reactive).
`toBeTruthy`	`(options?: UntilOptions) => Promise<Exclude<Value, UntilFalsy>>`	Resolve once the value is truthy.
`toBeNull`	`(options?: UntilOptions) => Promise<Extract<Value, null>>`	Resolve once the value is `null`.
`toBeUndefined`	`(options?: UntilOptions) => Promise<Extract<Value, undefined>>`	Resolve once the value is `undefined`.
`toBeNaN`	`(options?: UntilOptions) => Promise<Value>`	Resolve once the value is `NaN`.
`toContain`	`(element: Value extends readonly (infer Element)[] ? Element : Value extends string ? string : never, options?: UntilOptions) => Promise<Value>`	Resolve once an array or string value includes `element`.
`changed`	`(options?: UntilOptions) => Promise<Value>`	Resolve after the value changed once.
`changedTimes`	`(count: number, options?: UntilOptions) => Promise<Value>`	Resolve after the value changed `count` times.

`UntilNegatedMatchers`

Negated matchers available through UntilChain.not.

Member	Type	Description
`toBe`	`(unexpected: MaybeRefOrGetter<Value>, options?: UntilOptions) => Promise<Value>`	Resolve once the value is no longer `Object.is`-equal to `unexpected`.
`toBeTruthy`	`(options?: UntilOptions) => Promise<Extract<Value, UntilFalsy>>`	Resolve once the value is falsy.
`toBeNull`	`(options?: UntilOptions) => Promise<Exclude<Value, null>>`	Resolve once the value is not `null`.
`toBeUndefined`	`(options?: UntilOptions) => Promise<Exclude<Value, undefined>>`	Resolve once the value is not `undefined`.
`toMatch`	`(condition: (value: Value) => boolean, options?: UntilOptions) => Promise<Value>`	Resolve once the value no longer satisfies the predicate.

`UntilChain`

Fluent wait builder returned by until.

Member	Type	Description
`toMatch`	`(condition: (value: Value) => value is Narrowed, options?: UntilOptions) => Promise<Narrowed> \| (condition: (value: Value) => boolean, options?: UntilOptions) => Promise<Value>`	Resolve once the value satisfies the type guard, narrowing the result.
`toBe`	`(expected: MaybeRefOrGetter<Expected>, options?: UntilOptions) => Promise<Expected>`	Resolve once the value is `Object.is`-equal to `expected` (itself possibly reactive).
`toBeTruthy`	`(options?: UntilOptions) => Promise<Exclude<Value, UntilFalsy>>`	Resolve once the value is truthy.
`toBeNull`	`(options?: UntilOptions) => Promise<Extract<Value, null>>`	Resolve once the value is `null`.
`toBeUndefined`	`(options?: UntilOptions) => Promise<Extract<Value, undefined>>`	Resolve once the value is `undefined`.
`toBeNaN`	`(options?: UntilOptions) => Promise<Value>`	Resolve once the value is `NaN`.
`toContain`	`(element: Value extends readonly (infer Element)[] ? Element : Value extends string ? string : never, options?: UntilOptions) => Promise<Value>`	Resolve once an array or string value includes `element`.
`changed`	`(options?: UntilOptions) => Promise<Value>`	Resolve after the value changed once.
`changedTimes`	`(count: number, options?: UntilOptions) => Promise<Value>`	Resolve after the value changed `count` times.
`not`	`UntilNegatedMatchers<Value>`	Inverted matchers.