Skip to content

⬅️ Back to Table of Contents

📄 until

📊 Analysis Summary

Metric Count
🔧 Functions 11
📦 Imports 11
⚡ Async/Await Patterns 3
🟢 Vue Composition API 2
📐 Interfaces 4
📑 Type Aliases 1

📚 Table of Contents

🛠️ File Location:

📂 packages/shared/until/index.ts

📦 Imports

Name Source
MaybeRefOrGetter vue
WatchOptions vue
WatchSource vue
ConfigurableFlushSync ../utils
ElementOf ../utils
ShallowUnwrapRef ../utils
isRef vue
nextTick vue
toValue vue
watch vue
promiseTimeout ../utils

Async/Await Patterns

Type Function Await Expressions Promise Chains
promise-chain createUntil none new Promise(...), promiseTimeout(timeout, throwOnTimeout) .then(() => toValue...
promise-chain toMatch none new Promise(...), promiseTimeout(timeout, throwOnTimeout) .then(() => toValue...
promise-chain toBe none new Promise(...), promiseTimeout(timeout, throwOnTimeout) .then(() => toValue...

Vue Composition API

Name Type Reactive Variables Composables
watch watch none none
watch watch none none

Functions

until(r: WatchSource<T> | MaybeRefOrGetter<T>): UntilArrayInstance<T>

Promised one-time watch for changes

Examples:
const { count } = useCounter()

await until(count).toMatch(v => v > 7)

alert('Counter is now larger than 7!')

See: https://vueuse.org/until

Raw JSDoc 
/**
 * 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!')
 * ```
 */
Code 
export function until<T extends unknown[]>(r: WatchSource<T> | MaybeRefOrGetter<T>): UntilArrayInstance<T>

createUntil(r: any, isNot: boolean): UntilArrayInstance<T> | UntilValueInstance<T, boolean>

Parameters:

  • r any
  • isNot boolean

Returns: UntilArrayInstance<T> | UntilValueInstance<T, boolean>

Calls:

  • watch (from vue)
  • condition
  • stop
  • nextTick (from vue)
  • resolve
  • promises.push
  • promiseTimeout(timeout, throwOnTimeout) .then(() => toValue(r)) .finally
  • Promise.race
  • isRef (from vue)
  • toMatch
  • toValue (from vue)
  • Boolean
  • toBe
  • Array.from
  • array.includes
  • changedTimes
  • Array.isArray
  • createUntil
Code 
function createUntil<T>(r: any, isNot = false) {
  function toMatch(
    condition: (v: any) => boolean,
    { flush = 'sync', deep = false, timeout, throwOnTimeout }: UntilToMatchOptions = {},
  ): Promise<T> {
    let stop: (() => void) | null = null
    const watcher = new Promise<T>((resolve) => {
      stop = watch(
        r,
        (v) => {
          if (condition(v) !== isNot) {
            if (stop)
              stop()
            else
              nextTick(() => stop?.())
            resolve(v)
          }
        },
        {
          flush,
          deep,
          immediate: true,
        },
      )
    })

    const promises = [watcher]
    if (timeout != null) {
      promises.push(
        promiseTimeout(timeout, throwOnTimeout)
          .then(() => toValue(r))
          .finally(() => stop?.()),
      )
    }

    return Promise.race(promises)
  }

  function toBe<P>(value: MaybeRefOrGetter<P | T>, options?: UntilToMatchOptions) {
    if (!isRef(value))
      return toMatch(v => v === value, options)

    const { flush = 'sync', deep = false, timeout, throwOnTimeout } = options ?? {}
    let stop: (() => void) | null = null
    const watcher = new Promise<T>((resolve) => {
      stop = watch(
        [r, value],
        ([v1, v2]) => {
          if (isNot !== (v1 === v2)) {
            if (stop)
              stop()
            else
              nextTick(() => stop?.())
            resolve(v1)
          }
        },
        {
          flush,
          deep,
          immediate: true,
        },
      )
    })

    const promises = [watcher]
    if (timeout != null) {
      promises.push(
        promiseTimeout(timeout, throwOnTimeout)
          .then(() => toValue(r))
          .finally(() => {
            stop?.()
            return toValue(r)
          }),
      )
    }

    return Promise.race(promises)
  }

  function toBeTruthy(options?: UntilToMatchOptions) {
    return toMatch(v => Boolean(v), options)
  }

  function toBeNull(options?: UntilToMatchOptions) {
    return toBe<null>(null, options)
  }

  function toBeUndefined(options?: UntilToMatchOptions) {
    return toBe<undefined>(undefined, options)
  }

  function toBeNaN(options?: UntilToMatchOptions) {
    return toMatch(Number.isNaN, options)
  }

  function toContains(
    value: any,
    options?: UntilToMatchOptions,
  ) {
    return toMatch((v) => {
      const array = Array.from(v as any)
      return array.includes(value) || array.includes(toValue(value))
    }, options)
  }

  function changed(options?: UntilToMatchOptions) {
    return changedTimes(1, options)
  }

  function changedTimes(n = 1, options?: UntilToMatchOptions) {
    let count = -1 // skip the immediate check
    return toMatch(() => {
      count += 1
      return count >= n
    }, options)
  }

  if (Array.isArray(toValue(r))) {
    const instance: UntilArrayInstance<T> = {
      toMatch: toMatch as any,
      toContains,
      changed,
      changedTimes,
      get not() {
        return createUntil(r, !isNot) as UntilArrayInstance<T>
      },
    }
    return instance
  }
  else {
    const instance: UntilValueInstance<T, boolean> = {
      toMatch: toMatch as any,
      toBe,
      toBeTruthy: toBeTruthy as any,
      toBeNull: toBeNull as any,
      toBeNaN,
      toBeUndefined: toBeUndefined as any,
      changed,
      changedTimes,
      get not() {
        return createUntil(r, !isNot) as UntilValueInstance<T, boolean>
      },
    }

    return instance
  }
}

Internal helpers

Declared inside another function in this file.

toMatch(condition: (v: any) => boolean, { flush = 'sync', deep = false,…: UntilToMatchOptions): Promise<T>

Parameters:

  • condition (v: any) => boolean
  • { flush = 'sync', deep = false, timeout, throwOnTimeout } UntilToMatchOptions

Returns: Promise<T>

Calls:

  • watch (from vue)
  • condition
  • stop
  • nextTick (from vue)
  • resolve
  • promises.push
  • promiseTimeout(timeout, throwOnTimeout) .then(() => toValue(r)) .finally
  • Promise.race
Code 
function toMatch(
    condition: (v: any) => boolean,
    { flush = 'sync', deep = false, timeout, throwOnTimeout }: UntilToMatchOptions = {},
  ): Promise<T> {
    let stop: (() => void) | null = null
    const watcher = new Promise<T>((resolve) => {
      stop = watch(
        r,
        (v) => {
          if (condition(v) !== isNot) {
            if (stop)
              stop()
            else
              nextTick(() => stop?.())
            resolve(v)
          }
        },
        {
          flush,
          deep,
          immediate: true,
        },
      )
    })

    const promises = [watcher]
    if (timeout != null) {
      promises.push(
        promiseTimeout(timeout, throwOnTimeout)
          .then(() => toValue(r))
          .finally(() => stop?.()),
      )
    }

    return Promise.race(promises)
  }

toBe(value: MaybeRefOrGetter<P | T>, options: UntilToMatchOptions): Promise<T>

Parameters:

  • value MaybeRefOrGetter<P | T>
  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • isRef (from vue)
  • toMatch
  • watch (from vue)
  • stop
  • nextTick (from vue)
  • resolve
  • promises.push
  • promiseTimeout(timeout, throwOnTimeout) .then(() => toValue(r)) .finally
  • toValue (from vue)
  • Promise.race
Code 
function toBe<P>(value: MaybeRefOrGetter<P | T>, options?: UntilToMatchOptions) {
    if (!isRef(value))
      return toMatch(v => v === value, options)

    const { flush = 'sync', deep = false, timeout, throwOnTimeout } = options ?? {}
    let stop: (() => void) | null = null
    const watcher = new Promise<T>((resolve) => {
      stop = watch(
        [r, value],
        ([v1, v2]) => {
          if (isNot !== (v1 === v2)) {
            if (stop)
              stop()
            else
              nextTick(() => stop?.())
            resolve(v1)
          }
        },
        {
          flush,
          deep,
          immediate: true,
        },
      )
    })

    const promises = [watcher]
    if (timeout != null) {
      promises.push(
        promiseTimeout(timeout, throwOnTimeout)
          .then(() => toValue(r))
          .finally(() => {
            stop?.()
            return toValue(r)
          }),
      )
    }

    return Promise.race(promises)
  }

toBeTruthy(options: UntilToMatchOptions): Promise<T>

Parameters:

  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • toMatch
  • Boolean
Code 
function toBeTruthy(options?: UntilToMatchOptions) {
    return toMatch(v => Boolean(v), options)
  }

toBeNull(options: UntilToMatchOptions): Promise<T>

Parameters:

  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • toBe
Code 
function toBeNull(options?: UntilToMatchOptions) {
    return toBe<null>(null, options)
  }

toBeUndefined(options: UntilToMatchOptions): Promise<T>

Parameters:

  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • toBe
Code 
function toBeUndefined(options?: UntilToMatchOptions) {
    return toBe<undefined>(undefined, options)
  }

toBeNaN(options: UntilToMatchOptions): Promise<T>

Parameters:

  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • toMatch
Code 
function toBeNaN(options?: UntilToMatchOptions) {
    return toMatch(Number.isNaN, options)
  }

toContains(value: any, options: UntilToMatchOptions): Promise<T>

Parameters:

  • value any
  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • toMatch
  • Array.from
  • array.includes
  • toValue (from vue)
Code 
function toContains(
    value: any,
    options?: UntilToMatchOptions,
  ) {
    return toMatch((v) => {
      const array = Array.from(v as any)
      return array.includes(value) || array.includes(toValue(value))
    }, options)
  }

changed(options: UntilToMatchOptions): Promise<T>

Parameters:

  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • changedTimes
Code 
function changed(options?: UntilToMatchOptions) {
    return changedTimes(1, options)
  }

changedTimes(n: number, options: UntilToMatchOptions): Promise<T>

Parameters:

  • n number
  • options UntilToMatchOptions

Returns: Promise<T>

Calls:

  • toMatch
Code 
function changedTimes(n = 1, options?: UntilToMatchOptions) {
    let count = -1 // skip the immediate check
    return toMatch(() => {
      count += 1
      return count >= n
    }, options)
  }

Interfaces

UntilToMatchOptions

Interface Code 
export interface UntilToMatchOptions extends ConfigurableFlushSync {
  /**
   * 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

  /**
   * `deep` option for internal watch
   *
   * @default 'false'
   */
  deep?: WatchOptions['deep']
}

Properties

Name Type Optional Description
timeout number ✓ not shown
throwOnTimeout boolean ✓ not shown
deep WatchOptions['deep'] ✓ not shown

UntilBaseInstance<T, Not extends boolean = false>

Interface Code 
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>
}

Properties

Name Type Optional Description
toMatch (<U extends T = T>( condition: (v: T) => v is U, options?: UntilToMatchOption... ✗ not shown
changed (options?: UntilToMatchOptions) => Promise<T> ✗ not shown
changedTimes (n?: number, options?: UntilToMatchOptions) => Promise<T> ✗ not shown

UntilValueInstance<T, Not extends boolean = false>

Interface Code 
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>
}

Properties

Name Type Optional Description
not UntilValueInstance<T, Not extends true ? false : true> ✗ not shown
toBe <P = T>(value: MaybeRefOrGetter<P>, options?: UntilToMatchOptions) => Not ext... ✗ not shown
toBeTruthy (options?: UntilToMatchOptions) => Not extends true ? Promise<T & Falsy> : Pr... ✗ not shown
toBeNull (options?: UntilToMatchOptions) => Not extends true ? Promise<Exclude<T, null... ✗ not shown
toBeUndefined (options?: UntilToMatchOptions) => Not extends true ? Promise<Exclude<T, unde... ✗ not shown
toBeNaN (options?: UntilToMatchOptions) => Promise<T> ✗ not shown

UntilArrayInstance<T>

Interface Code 
export interface UntilArrayInstance<T> extends UntilBaseInstance<T> {
  readonly not: UntilArrayInstance<T>

  toContains: (value: MaybeRefOrGetter<ElementOf<ShallowUnwrapRef<T>>>, options?: UntilToMatchOptions) => Promise<T>
}

Properties

Name Type Optional Description
not UntilArrayInstance<T> ✗ not shown
toContains (value: MaybeRefOrGetter<ElementOf<ShallowUnwrapRef<T>>>, options?: UntilToMa... ✗ not shown

Type Aliases

Falsy

type Falsy = false | void | null | undefined | 0 | 0n | '';

Generated by Syntax Scribe