Function waitUntil

A group of guard methods that run the given callback multiple times until its return value matches expectations. Callback interval and timeout can be customized with WaitUntilOptions.

This can also be called as a standalone wait until function which waits until the callback's returned value is truthy.

import {waitUntil} from '@augment-vir/assert';

// `result` will eventually be `'123'`
const result = await waitUntil.isString(
() => {
if (Math.random() < 0.5) {
return 123;
} else {
return '123';
}
},
{
interval: {milliseconds: 100},
timeout: {seconds: 10},
},
);

AssertionError When the assertion fails.

  • Type Parameters

    • T

    Parameters

    • callback: () => T
    • Optionaloptions: PartialWithUndefined<
          {
              interval: Partial<Record<DurationUnit, undefined | number>>;
              timeout: Partial<Record<DurationUnit, undefined | number>>;
          },
      >
    • OptionalfailureMessage: string

    Returns Promise<T>

    The successful callback return value.

Properties

deepEquals: <Actual, Expected>(
    this: void,
    expected: Expected,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, Expected>> = ...

Repeatedly calls a callback until its output deeply equals (using the deep-eql package) the first input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Note that this check may be expensive, depending on what values it is passed. Whenever possible, use simpler equality checks instead (see the see section below).

Type guards the first value.

Type declaration

    • <Actual, Expected>(
          this: void,
          expected: Expected,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Actual, Expected>>
    • Type Parameters

      • Actual
      • Expected

      Parameters

      • this: void
      • expected: Expected
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Actual, Expected>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.deepEquals('a', () => 'a'); // returns `'a'`

await waitUntil.deepEquals(1, () => '1'); // throws an error

await waitUntil.deepEquals({a: 'a'}, () => {
return {a: 'a'};
}); // returns `{a: 'a'}`

const objectExample = {a: 'a'};
await waitUntil.deepEquals(objectExample, () => objectExample); // returns `{a: 'a'}`

AssertionError On timeout.

endsWith: {
    <const ArrayElement>(
        child: ArrayElement,
        callback: () => MaybePromise<readonly ArrayElement[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<ReadonlyArray<ArrayElement>>;
    (
        child: string,
        callback: () => MaybePromise<string>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string>;
    (
        child: string,
        callback: () => MaybePromise<string | readonly string[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string | ReadonlyArray<string>>;
} = ...

Repeatedly calls a callback until its output string or array ends with the first input child value. This uses reference equality when the parent is an array. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.endsWith('b', () => 'ab'); // returns `'ab'`
await waitUntil.endsWith('a', () => 'ab'); // throws an error
await waitUntil.endsWith('b', () => ['a', 'b']); // returns `['a', 'b']`
await waitUntil.endsWith('a', () => ['a', 'b']); // throws an error

The callback output once it passes.

AssertionError On timeout.

endsWithout: {
    <const ArrayElement>(
        child: ArrayElement,
        callback: () => MaybePromise<readonly ArrayElement[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<ReadonlyArray<ArrayElement>>;
    (
        child: string,
        callback: () => MaybePromise<string>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string>;
    (
        child: string,
        callback: () => MaybePromise<string | readonly string[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string | ReadonlyArray<string>>;
} = ...

Repeatedly calls a callback until its output string or array does not end with the first input child value. This uses reference equality when the parent is an array. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.endsWith('b', () => 'ab'); // throws an error
await waitUntil.endsWith('a', () => 'ab'); // returns `'ab'`
await waitUntil.endsWith('b', () => ['a', 'b']); // throws an error
await waitUntil.endsWith('a', () => ['a', 'b']); // returns `['a', 'b']`

The callback output once it passes.

AssertionError On timeout.

entriesEqual: <Actual extends AnyObject, Expected extends AnyObject>(
    this: void,
    expected: Expected,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, Expected>> = ...

Repeatedly calls a callback until its output is deeply equal to the first input by checking only their top-level values for strict (non-deep, reference, using ===) equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the first value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.entriesEqual({a: 'a'}, () => {
return {a: 'a'};
}); // returns `{a: 'a'}`

await waitUntil.entriesEqual({a: {b: 'b'}}, () => {
return {a: {b: 'b'}};
}); // throws an error

const bExample = {b: 'b'};
await waitUntil.entriesEqual({a: bExample}, () => {
return {a: bExample};
}); // returns `{a: {b: 'b'}}`

AssertionError On timeout.

hasKey: <const Parent, const Key extends PropertyKey>(
    this: void,
    key: Key,
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<CombineTypeWithKey<Key, Parent>> = ...

Repeatedly calls a callback until its output is a parent value that has the first, key input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the parent value.

Type declaration

    • <const Parent, const Key extends PropertyKey>(
          this: void,
          key: Key,
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<CombineTypeWithKey<Key, Parent>>
    • Type Parameters

      • const Parent
      • const Key extends PropertyKey

      Parameters

      • this: void
      • key: Key
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<CombineTypeWithKey<Key, Parent>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.hasKey('a', () => {
return {a: 0, b: 1};
}); // returns `{a: 0, b: 1}`
await waitUntil.hasKey('c', () => {
return {a: 0, b: 1};
}); // throws an error

AssertionError On timeout.

hasKeys: <const Keys extends PropertyKey, const Parent>(
    this: void,
    keys: readonly Keys[],
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<CombineTypeWithKey<Keys, Parent>> = ...

Repeatedly calls a callback until its output is a parent value that has all of the first, keys input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the parent value.

Type declaration

    • <const Keys extends PropertyKey, const Parent>(
          this: void,
          keys: readonly Keys[],
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<CombineTypeWithKey<Keys, Parent>>
    • Type Parameters

      • const Keys extends PropertyKey
      • const Parent

      Parameters

      • this: void
      • keys: readonly Keys[]
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<CombineTypeWithKey<Keys, Parent>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.hasKeys(['a', 'b'], () => {
return {a: 0, b: 1};
}); // returns `{a: 0, b: 1}`
await waitUntil.hasKeys(['b', 'c'], () => {
return {a: 0, b: 1};
}); // throws an error

AssertionError On timeout.

hasValue: <Parent extends string | object>(
    this: void,
    value: unknown,
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Parent> = ...

Repeatedly calls a callback until its output is an object/array parent includes a child value through reference equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Parent extends string | object>(
          this: void,
          value: unknown,
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Parent>
    • Type Parameters

      • Parent extends string | object

      Parameters

      • this: void
      • value: unknown
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Parent>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

const child = {a: 'a'};

await waitUntil.hasValue(child, () => {
return {child};
}); // returns `{child}`;
await waitUntil.hasValue(child, () => {
return {child: {a: 'a'}};
}); // throws an error
await waitUntil.hasValue(child, () => [child]); // returns `[child]`;

AssertionError On timeout.

hasValues: <Parent extends string | object>(
    this: void,
    value: unknown[],
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Parent> = ...

Repeatedly calls a callback until its output is an object/array parent includes all child values through reference equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Parent extends string | object>(
          this: void,
          value: unknown[],
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Parent>
    • Type Parameters

      • Parent extends string | object

      Parameters

      • this: void
      • value: unknown[]
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Parent>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

const child = {a: 'a'};
const child2 = {b: 'b'};

await waitUntil.hasValues([child, child2], () => {
return {child, child2};
}); // returns `{child, child2}`;
await waitUntil.hasValues([child, child2], () => {
return {child: {a: 'a'}, child2};
}); // throws an error
await waitUntil.hasValues([child, child2], () => [child]); // returns `[child]`;

AssertionError On timeout.

instanceOf: <const Instance>(
    this: void,
    constructor: Constructor<Instance>,
    callback: () => unknown,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Instance> = ...

Repeatedly calls a callback until its output is an instance of the given class constructor. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <const Instance>(
          this: void,
          constructor: Constructor<Instance>,
          callback: () => unknown,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Instance>
    • Type Parameters

      • const Instance

      Parameters

      • this: void
      • constructor: Constructor<Instance>
      • callback: () => unknown
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Instance>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.instanceOf(RegExp, () => /abc/); // returns `/abc/`
await waitUntil.instanceOf(RegExp, () => 'abc'); // throws an error

AssertionError On timeout.

isAbove: <Actual extends number>(
    this: void,
    expected: number,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is above the expectation (actual > expected). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          expected: number,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • expected: number
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isAbove(5, () => 10); // returns `10`
await waitUntil.isAbove(5, () => 5); // throws an error
await waitUntil.isAbove(10, () => 5); // throws an error

AssertionError On timeout.

isApproximately: <Actual extends number>(
    this: void,
    expected: number,
    delta: number,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is within ±delta of the expectation. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          expected: number,
          delta: number,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • expected: number
      • delta: number
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isApproximately(8, 4, () => 10); // returns `10`
await waitUntil.isApproximately(12, 4, () => 10); // returns `10`
await waitUntil.isApproximately(8, 1, () => 10); // throws an error
await waitUntil.isApproximately(12, 1, () => 10); // throws an error

AssertionError If the assertion fails.

isArray: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<ArrayNarrow<Actual>> = ...

Repeatedly calls a callback until its output is an array. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isArray(() => []); // passes
await waitUntil.isArray(() => {
return {length: 4};
}); // throws an error

AssertionError If the assertion failed.

isAtLeast: <Actual extends number>(
    this: void,
    expected: number,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is at least the expectation (actual >= expected). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          expected: number,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • expected: number
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isAtLeast(5, () => 10); // returns `10`
await waitUntil.isAtLeast(5, () => 5); // returns `5`
await waitUntil.isAtLeast(10, () => 5); // throws an error

AssertionError On timeout.

isAtMost: <Actual extends number>(
    this: void,
    expected: number,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is at most the expectation (actual <= expected). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          expected: number,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • expected: number
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isAtMost(5, () => 10); // throws an error
await waitUntil.isAtMost(5, () => 5); // returns `5`
await waitUntil.isAtMost(10, () => 5); // returns `5`

AssertionError On timeout.

isBelow: <Actual extends number>(
    this: void,
    expected: number,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is below the expectation (actual < expected). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          expected: number,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • expected: number
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isBelow(5, () => 10); // throws an error
await waitUntil.isBelow(5, () => 5); // throws an error
await waitUntil.isBelow(10, () => 5); // returns `5`

AssertionError On timeout.

isBigInt: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, bigint>> = ...

Repeatedly calls a callback until its output is a BigInt. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isBigInt(() => 123n); // returns `123n`
await waitUntil.isBigInt(() => 123); // throws an error

AssertionError If the assertion failed.

isBoolean: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, boolean>> = ...

Repeatedly calls a callback until its output is a boolean. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isBoolean(() => true); // returns `true`
await waitUntil.isBoolean(() => 'true'); // throws an error

AssertionError If the assertion failed.

isDefined: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, undefined | null>> = ...

Repeatedly calls a callback until its output is a value that is defined (not null and not undefined). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, undefined | null>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, undefined | null>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isDefined(() => 0); // returns `0`
await waitUntil.isDefined(() => ''); // returns `''`
await waitUntil.isDefined(() => null); // throws an error
await waitUntil.isDefined(() => undefined); // throws an error

AssertionError On timeout.

isEmpty: <Actual extends CanBeEmpty>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToActual<Actual, Empty>> = ...

Repeatedly calls a callback until its output is a value is empty. Supports strings, Maps, Sets, objects, and arrays. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual extends CanBeEmpty>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToActual<Actual, Empty>>
    • Type Parameters

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToActual<Actual, Empty>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isEmpty(() => {
return {};
}); // returns `{}`;
await waitUntil.isEmpty(() => ''); // returns `''`;
await waitUntil.isEmpty(() => []); // returns `[]`;

await waitUntil.isEmpty(() => 'a'); // throws an error
await waitUntil.isEmpty(() => {
return {a: 'a'};
}); // throws an error

AssertionError On timeout.

isEnumValue: <const Actual, const Expected extends EnumBaseType>(
    this: void,
    checkEnum: Expected,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, Expected[keyof Expected]>> = ...

Repeatedly calls a callback until its output is an enum member. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

import {waitUntil} from '@augment-vir/assert';

enum MyEnum {
A = 'a',
B = 'b',
}

await waitUntil.isEnumValue(MyEnum, () => 'a'); // returns `'a'`
await waitUntil.isEnumValue(MyEnum, () => 'A'); // throws an error

AssertionError On timeout.

isError: <Actual>(
    this: void,
    matchOptions:
        | undefined
        | PartialWithNullable<
            {
                matchConstructor: ErrorConstructor
                | new (...args: any[]) => Error;
                matchMessage: string | RegExp;
            },
        >,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, Error>> = ...

Repeatedly calls a callback until is output is an instance of the built-in Error class and compares it to the given ErrorMatchOptions, if provided. Once the callback output passes, that Error is returned. If the attempts time out, an error is thrown.

Type guards the input.

Type declaration

    • <Actual>(
          this: void,
          matchOptions:
              | undefined
              | PartialWithNullable<
                  {
                      matchConstructor: ErrorConstructor
                      | new (...args: any[]) => Error;
                      matchMessage: string | RegExp;
                  },
              >,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Actual, Error>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • matchOptions:
            | undefined
            | PartialWithNullable<
                {
                    matchConstructor: ErrorConstructor
                    | new (...args: any[]) => Error;
                    matchMessage: string | RegExp;
                },
            >
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Actual, Error>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isError(new Error()); // returns the error instance
await waitUntil.isError(new Error(), {matchMessage: 'hi'}); // throws an error
await waitUntil.isError({message: 'not an error'}); // throws an error

AssertionError On timeout.

isFalse: (
    this: void,
    callback: () => unknown,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<false> = ...

Repeatedly calls a callback until its output is exactly false. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • (
          this: void,
          callback: () => unknown,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<false>
    • Parameters

      • this: void
      • callback: () => unknown
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<false>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isFalse(() => true); // throws an error
await waitUntil.isFalse(() => false); // returns `false`
await waitUntil.isFalse(() => 1); // throws an error
await waitUntil.isFalse(() => 0); // throws an error

AssertionError On timeout.

isFalsy: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, FalsyValue>> = ...

Repeatedly calls a callback until its output is falsy. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Actual, FalsyValue>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Actual, FalsyValue>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isFalsy(() => true); // throws an error
await waitUntil.isFalsy(() => false); // returns `false`
await waitUntil.isFalsy(() => 1); // throws an error
await waitUntil.isFalsy(() => 0); // returns `0`

AssertionError On timeout.

isFinite: <Actual extends number>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is finite: meaning, not NaN and not Infinity or -Infinity. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isFinite(() => 10); // returns `10`
await waitUntil.isFinite(() => parseInt('invalid')); // throws an error
await waitUntil.isFinite(() => Infinity); // throws an error
await waitUntil.isFinite(() => -Infinity); // throws an error

AssertionError If the assertion fails.

isFunction: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToActual<Actual, AnyFunction>> = ...

Repeatedly calls a callback until its output is a function. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isFunction(() => () => {
return {};
}); // returns `{}`
await waitUntil.isFunction(() => {
return {};
}); // throws an error

AssertionError If the assertion failed.

isHttpStatus: <const Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, HttpStatus>> = ...

Repeatedly calls a callback until its output is an HttpStatus. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <const Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Actual, HttpStatus>>
    • Type Parameters

      • const Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Actual, HttpStatus>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isHttpStatus(() => 400); // returns `400`
await waitUntil.isHttpStatus(() => 500); // returns `500`
await waitUntil.isHttpStatus(() => 99); // throws an error

AssertionError On timeout.

isHttpStatusCategory: <const Actual, const Category extends HttpStatusCategory>(
    this: void,
    category: Category,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, HttpStatusByCategory<Category>>> = ...

Repeatedly calls a callback until its output is an HttpStatus within a specific HttpStatusCategory. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isHttpStatusCategory(HttpStatusCategory.ClientError, () => 400); // returns `400`
await waitUntil.isHttpStatusCategory(HttpStatusCategory.Success, () => 500); // throws an error more
await waitUntil.isHttpStatusCategory(HttpStatusCategory.Information, () => 99); // throws an error more

AssertionError On timeout.

isIn: <Child, Parent>(
    this: void,
    parent: Parent,
    callback: () => MaybePromise<Child>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Child, Values<Parent>>> = ...

Repeatedly calls a callback until its output is child value is contained within a parent object, array, or string through reference equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the child when possible.

Type declaration

    • <Child, Parent>(
          this: void,
          parent: Parent,
          callback: () => MaybePromise<Child>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Child, Values<Parent>>>
    • Type Parameters

      • Child
      • Parent

      Parameters

      • this: void
      • parent: Parent
      • callback: () => MaybePromise<Child>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Child, Values<Parent>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

const child = {a: 'a'};

await waitUntil.isIn({child}, () => child); // returns `child`
await waitUntil.isIn('ab', () => 'a'); // returns `'a'`
await waitUntil.isIn(child, () => [child]); // returns `child`

await waitUntil.isIn({child: {a: 'a'}}, () => child); // throws an error
await waitUntil.isIn('bc', () => 'a'); // throws an error

AssertionError On timeout.

isInBounds: <Actual extends number>(
    this: void,
    __namedParameters: MinMax,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number is inside the provided min and max bounds, inclusive. If the attempts time out, an error is thrown.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

waitUntil.isInBounds(5, {min: 1, max: 10}); // passes
waitUntil.isInBounds(10, {min: 1, max: 10}); // passes
waitUntil.isInBounds(11, {min: 1, max: 10}); // fails
waitUntil.isInBounds(0, {min: 1, max: 10}); // fails

AssertionError If the assertion fails.

isInfinite: <Actual extends number>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is either Infinity or -Infinity. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isInfinite(() => 10); // throws an error
await waitUntil.isInfinite(() => parseInt('invalid')); // throws an error
await waitUntil.isInfinite(() => Infinity); // returns `Infinity`
await waitUntil.isInfinite(() => -Infinity); // returns `-Infinity`

AssertionError If the assertion fails.

isInteger: <Actual extends number>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is an integer. This has the same limitations as https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger. If the attempts time out, an error is thrown.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

waitUntil.isInteger(5); // passes
waitUntil.isInteger(5.0000000000000001); // passes
waitUntil.isInteger(5.1); // fails
waitUntil.isInteger(NaN); // fails

AssertionError If the assertion fails.

isKeyOf: <const Key extends PropertyKey, const Parent>(
    this: void,
    parent: Parent,
    callback: () => MaybePromise<Key>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Key, keyof Parent>> = ...

Repeatedly calls a callback until its output is a key that is contained within the first, parent value. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the key.

Type declaration

    • <const Key extends PropertyKey, const Parent>(
          this: void,
          parent: Parent,
          callback: () => MaybePromise<Key>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Key, keyof Parent>>
    • Type Parameters

      • const Key extends PropertyKey
      • const Parent

      Parameters

      • this: void
      • parent: Parent
      • callback: () => MaybePromise<Key>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Key, keyof Parent>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isKeyof({a: 0, b: 1}, () => 'a'); // returns `'a'`
await waitUntil.isKeyof({a: 0, b: 1}, () => 'c'); // throws an error

AssertionError On timeout.

isLengthAtLeast: {
    <Element, Length extends number>(
        length: Length,
        callback: () => MaybePromise<readonly (undefined | Element)[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<AtLeastTuple<Element, Length>>;
    <Actual extends string | AnyObject>(
        length: number,
        callback: () => MaybePromise<Actual>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<Actual>;
} = ...

Repeatedly calls a callback until its output is an array or string that has at least the given length. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards an array into an AtLeastTuple. Performs no type guarding on a string.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isLengthAtLeast(2, () => ['a', 'b', 'c']); // returns `['a', 'b', 'c']`
await waitUntil.isLengthAtLeast(3, () => ['a', 'b', 'c']); // returns `['a', 'b', 'c']`
await waitUntil.isLengthAtLeast(3, () => ['a', 'b']); // throws an error

The callback output once it passes.

AssertionError On timeout.

isLengthExactly: {
    <Element, Length extends number>(
        length: Length,
        callback: () => MaybePromise<readonly (undefined | Element)[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<Tuple<Element, Length>>;
    <Actual extends string | AnyObject>(
        length: number,
        callback: () => MaybePromise<Actual>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<Actual>;
} = ...

Repeatedly calls a callback until its output is an array or string that has exactly the given length. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards an array into a Tuple. Performs no type guarding on a string.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isLengthAtLeast(2, () => ['a', 'b', 'c']); // throws an error
await waitUntil.isLengthAtLeast(3, () => ['a', 'b', 'c']); // returns `['a', 'b', 'c']`
await waitUntil.isLengthAtLeast(3, () => ['a', 'b']); // throws an error

The callback output once it passes.

AssertionError On timeout.

isNaN: <Actual extends number>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is NaN. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNaN(() => 10); // throws an error
await waitUntil.isNaN(() => parseInt('invalid')); // returns `NaN`
await waitUntil.isNaN(() => Infinity); // throws an error

AssertionError If the assertion fails.

isNotApproximately: <Actual extends number>(
    this: void,
    expected: number,
    delta: number,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is a number that is outside ±delta of the expectation. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends number>(
          this: void,
          expected: number,
          delta: number,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual extends number

      Parameters

      • this: void
      • expected: number
      • delta: number
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotApproximately(8, 4, () => 10); // throws an error
await waitUntil.isNotApproximately(12, 4, () => 10); // throws an error
await waitUntil.isNotApproximately(8, 1, () => 10); // returns `10`
await waitUntil.isNotApproximately(12, 1, () => 10); // returns `10`

AssertionError If the assertion fails.

isNotArray: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, readonly unknown[]>> = ...

Repeatedly calls a callback until its output is not an array. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotArray(() => []); // throws an error
await waitUntil.isNotArray(() => {
return {length: 4};
}); // returns `{length: 4}`

AssertionError If the assertion failed.

isNotBigInt: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, bigint>> = ...

Repeatedly calls a callback until its output is not a BigInt. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotBigInt(() => 123n); // throws an error
await waitUntil.isNotBigInt(() => 123); // returns `123`

AssertionError If the assertion failed.

isNotBoolean: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, boolean>> = ...

Repeatedly calls a callback until its output is not a boolean. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotBoolean(() => true); // throws an error
await waitUntil.isNotBoolean(() => 'true'); // returns `'true'`

AssertionError If the assertion failed.

isNotEmpty: <Actual extends CanBeEmpty>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, Empty>> = ...

Repeatedly calls a callback until its output is a value is not empty. Supports strings, Maps, Sets, objects, and arrays. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual extends CanBeEmpty>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, Empty>>
    • Type Parameters

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, Empty>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotEmpty(() => {
return {};
}); // throws an error
await waitUntil.isNotEmpty(() => ''); // throws an error
await waitUntil.isNotEmpty(() => []); // throws an error

await waitUntil.isNotEmpty(() => 'a'); // returns `'a'`;
await waitUntil.isNotEmpty(() => {
return {a: 'a'};
}); // returns `{a: 'a'}`;

AssertionError On timeout.

isNotEnumValue: <const Actual, const Expected extends EnumBaseType>(
    this: void,
    checkEnum: Expected,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<
    Exclude<
        Actual,
        Expected[keyof Expected]
        | `${Expected[keyof Expected]}`,
    >,
> = ...

Repeatedly calls a callback until its output is not an enum member. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <const Actual, const Expected extends EnumBaseType>(
          this: void,
          checkEnum: Expected,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<
          Exclude<
              Actual,
              Expected[keyof Expected]
              | `${Expected[keyof Expected]}`,
          >,
      >
    • Type Parameters

      Parameters

      • this: void
      • checkEnum: Expected
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<
          Exclude<
              Actual,
              Expected[keyof Expected]
              | `${Expected[keyof Expected]}`,
          >,
      >

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

enum MyEnum {
A = 'a',
B = 'b',
}

await waitUntil.isNotEnumValue(MyEnum, () => 'a'); // throws an error
await waitUntil.isNotEnumValue(MyEnum, () => 'A'); // returns `'A'`

AssertionError On timeout.

isNotFunction: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, AnyFunction>> = ...

Repeatedly calls a callback until its output is not a function. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotFunction(() => () => {
return {};
}); // throws an error
await waitUntil.isNotFunction(() => {
return {};
}); // returns `{}`

AssertionError If the assertion failed.

isNotIn: <Child, Parent>(
    this: void,
    parent: Parent,
    callback: () => MaybePromise<Child>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Child, Values<Parent>>> = ...

Repeatedly calls a callback until its output is child value is not contained within a parent object, array, or string through reference equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the child when possible.

Type declaration

    • <Child, Parent>(
          this: void,
          parent: Parent,
          callback: () => MaybePromise<Child>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Child, Values<Parent>>>
    • Type Parameters

      • Child
      • Parent

      Parameters

      • this: void
      • parent: Parent
      • callback: () => MaybePromise<Child>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Child, Values<Parent>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

const child = {a: 'a'};

await waitUntil.isNotIn({child}, () => child); // throws an error
await waitUntil.isNotIn('ab', () => 'a'); // throws an error
await waitUntil.isNotIn([child], () => child); // throws an error

await waitUntil.isNotIn({child: {a: 'a'}}, () => child); // returns `child`;
await waitUntil.isNotIn('bc', () => 'a'); // returns `'a'`;

AssertionError On timeout.

isNotInteger: <Actual extends number>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is not an integer. This has the same limitations, as https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger. If the attempts time out, an error is thrown.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

waitUntil.isNotInteger(5); // fails
waitUntil.isNotInteger(5.0000000000000001); // fails
waitUntil.isNotInteger(5.1); // passes
waitUntil.isNotInteger(NaN); // passes

AssertionError If the assertion fails.

isNotKeyOf: <const Key extends PropertyKey, const Parent>(
    this: void,
    parent: Parent,
    callback: () => MaybePromise<Key>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Key, RequiredKeysOf<Parent>>> = ...

Repeatedly calls a callback until its output is a key that is not contained within the first, parent value. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the key.

Type declaration

    • <const Key extends PropertyKey, const Parent>(
          this: void,
          parent: Parent,
          callback: () => MaybePromise<Key>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Key, RequiredKeysOf<Parent>>>
    • Type Parameters

      • const Key extends PropertyKey
      • const Parent

      Parameters

      • this: void
      • parent: Parent
      • callback: () => MaybePromise<Key>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Key, RequiredKeysOf<Parent>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isKeyof({a: 0, b: 1}, () => 'a'); // throws an error
await waitUntil.isKeyof({a: 0, b: 1}, () => 'c'); // returns `'c'`

AssertionError On timeout.

isNotNull: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, null>> = ...

Repeatedly calls a callback until its output is not exactly null. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotNull(() => null); // throws an error
await waitUntil.isNotNull(() => undefined); // returns `undefined`

AssertionError If the assertion failed.

isNotNumber: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, number>> = ...

Repeatedly calls a callback until its output is not a number. This includes NaN. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotNumber(() => 123); // throws an error
await waitUntil.isNotNumber(() => 123n); // returns `123n`

AssertionError If the assertion failed.

isNotObject: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, UnknownObject>> = ...

Repeatedly calls a callback until its output is not an object. This includes arrays. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotObject(() => {
return {};
}); // throws an error
await waitUntil.isNotObject(() => []); // returns `[]`

AssertionError If the assertion failed.

isNotPrimitive: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, Primitive>> = ...

Repeatedly calls a callback until its output is a valid PropertyKey. PropertyKey is a built-in TypeScript type which refers to all possible key types for a JavaScript object. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, Primitive>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, Primitive>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isPropertyKey('key'); // returns `'key'`
await waitUntil.isPropertyKey(true); // throws an error
await waitUntil.isPropertyKey({}); // throws an error

AssertionError If the assertion fails.

isNotPromise: <const Actual>(
    this: void,
    callback: () => Actual,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, Promise<any>>> = ...

Repeatedly calls a callback until its output is a not Promise instance. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <const Actual>(
          this: void,
          callback: () => Actual,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, Promise<any>>>
    • Type Parameters

      • const Actual

      Parameters

      • this: void
      • callback: () => Actual
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, Promise<any>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

class CustomThenable {
constructor(public value: any) {}

then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
return new CustomThenable(
onFulfilled ? onFulfilled(this.value) : this.value,
);
}
}

await waitUntil.isNotPromise(() => Promise.resolve(5)); // throws an error
await waitUntil.isNotPromise(() => new CustomThenable(5)); // returns the resolved `5`
await waitUntil.isNotPromise(() => 5); // returns the resolved `5`

AssertionError If the assertion fails.

isNotPromiseLike: <const Actual>(
    this: void,
    callback: () => Actual,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, PromiseLike<any>>> = ...

Repeatedly calls a callback until its output is not a PromiseLike. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

PromiseLike is TypeScript built-in type that has a .then method and thus behaves like a promise. This is also referred to as a "thenable". This enables the use of third-party promise implementations that aren't instances of the built-in Promise class.

Type guards the value.

Type declaration

    • <const Actual>(
          this: void,
          callback: () => Actual,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, PromiseLike<any>>>
    • Type Parameters

      • const Actual

      Parameters

      • this: void
      • callback: () => Actual
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, PromiseLike<any>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

class CustomThenable {
constructor(public value: any) {}

then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
return new CustomThenable(
onFulfilled ? onFulfilled(this.value) : this.value,
);
}
}

await waitUntil.isNotPromiseLike(() => Promise.resolve(5)); // throws an error
await waitUntil.isNotPromiseLike(() => new CustomThenable(5)); // throws an error
await waitUntil.isNotPromiseLike(() => 5); // returns `5`

AssertionError If the assertion fails.

isNotPropertyKey: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, PropertyKey>> = ...

Repeatedly calls a callback until its output is not a valid PropertyKey. PropertyKey is a built-in TypeScript type which refers to all possible key types for a JavaScript object. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, PropertyKey>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, PropertyKey>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotPropertyKey('key'); // throws an error
await waitUntil.isNotPropertyKey(true); // returns `true`
await waitUntil.isNotPropertyKey({}); // returns `{}`

AssertionError If the assertion fails.

isNotString: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, string>> = ...

Repeatedly calls a callback until its output is not a string. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotString(() => ''); // throws an error
await waitUntil.isNotString(() => 5); // returns `5`

AssertionError If the assertion failed.

isNotSymbol: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, symbol>> = ...

Repeatedly calls a callback until its output is not a symbol. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotSymbol(() => Symbol('my-symbol')); // throws an error
await waitUntil.isNotSymbol(() => 'my-symbol'); // returns `'my-symbol'`

AssertionError If the assertion failed.

isNotUndefined: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, undefined>> = ...

Repeatedly calls a callback until its output is not exactly undefined. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNotUndefined(() => undefined); // throws an error
await waitUntil.isNotUndefined(() => null); // returns `null`

AssertionError If the assertion failed.

isNotUuid: <const Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<
    Exclude<Actual, `${string}-${string}-${string}-${string}-${string}`>,
> = ...

Repeatedly calls a callback until its output is not a valid UUID. The nil or max UUIDs are included as not valid. Returns the value if the assertion passes. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <const Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<
          Exclude<Actual, `${string}-${string}-${string}-${string}-${string}`>,
      >
    • Type Parameters

      • const Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, `${string}-${string}-${string}-${string}-${string}`>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';
import {createUuidV4} from '@augment-vir/common';

await waitUntil.isNotUuid(() => createUuidV4()); // throws an error
await waitUntil.isNotUuid(() => '29e0f18e-6115-4982-8342-0afcadf5d611'); // throws an error
await waitUntil.isNotUuid(() => '00000000-0000-0000-0000-000000000000'); // returns `'00000000-0000-0000-0000-000000000000'`
await waitUntil.isNotUuid(() => 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // returns `'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'`
await waitUntil.isNotUuid(() => 'not-a-uuid'); // returns `'not-a-uuid'`

AssertionError On timeout.

isNull: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, null>> = ...

Repeatedly calls a callback until its output is exactly null. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNull(() => null); // returns `null`
await waitUntil.isNull(() => undefined); // throws an error

AssertionError If the assertion failed.

isNullish: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Extract<Actual, undefined | null>> = ...

Repeatedly calls a callback until its output is a value that is nullish (null or undefined). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Extract<Actual, undefined | null>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Extract<Actual, undefined | null>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNullish(() => 0); // throws an error
await waitUntil.isNullish(() => ''); // throws an error
await waitUntil.isNullish(() => null); // returns `null`
await waitUntil.isNullish(() => undefined); // returns `undefined`

AssertionError On timeout.

isNumber: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, number>> = ...

Repeatedly calls a callback until its output is a number. This excludes NaN. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isNumber(() => 123); // returns `123`
await waitUntil.isNumber(() => 123n); // throws an error

AssertionError If the assertion failed.

isObject: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, UnknownObject>> = ...

Repeatedly calls a callback until its output is an object. This excludes arrays. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isObject(() => {
return {};
}); // returns `{}`
await waitUntil.isObject(() => []); // throws an error

AssertionError If the assertion failed.

isOutBounds: <Actual extends number>(
    this: void,
    __namedParameters: MinMax,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is outside the provided min and max bounds, exclusive. If the attempts time out, an error is thrown.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

waitUntil.isOutBounds(5, {min: 1, max: 10}); // fails
waitUntil.isOutBounds(10, {min: 1, max: 10}); // fails
waitUntil.isOutBounds(11, {min: 1, max: 10}); // passes
waitUntil.isOutBounds(0, {min: 1, max: 10}); // passes

AssertionError If the assertion fails.

isPrimitive: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Extract<Actual, Primitive>> = ...

Repeatedly calls a callback until its output is a JavaScript primitive. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Extract<Actual, Primitive>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Extract<Actual, Primitive>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isPrimitive('key'); // returns `'key'`
await waitUntil.isPrimitive(true); // returns `true`
await waitUntil.isPrimitive({}); // throws an error

AssertionError If the assertion fails.

isPromise: <const Actual>(
    this: void,
    callback: () => Actual,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Extract<Actual, Promise<any>>> = ...

Repeatedly calls a callback until its output is a Promise instance. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <const Actual>(
          this: void,
          callback: () => Actual,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Extract<Actual, Promise<any>>>
    • Type Parameters

      • const Actual

      Parameters

      • this: void
      • callback: () => Actual
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Extract<Actual, Promise<any>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

class CustomThenable {
constructor(public value: any) {}

then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
return new CustomThenable(
onFulfilled ? onFulfilled(this.value) : this.value,
);
}
}

await waitUntil.isPromise(() => Promise.resolve(5)); // returns the resolved `5`
await waitUntil.isPromise(() => new CustomThenable(5)); // throws an error
await waitUntil.isPromise(() => 5); // throws an error

AssertionError If the assertion fails.

isPromiseLike: <const Actual>(
    this: void,
    callback: () => Actual,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Extract<Actual, PromiseLike<any>>> = ...

Repeatedly calls a callback until its output is a PromiseLike. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

PromiseLike is TypeScript built-in type that has a .then method and thus behaves like a promise. This is also referred to as a "thenable". This enables the use of third-party promise implementations that aren't instances of the built-in Promise class.

Type guards the value.

Type declaration

    • <const Actual>(
          this: void,
          callback: () => Actual,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Extract<Actual, PromiseLike<any>>>
    • Type Parameters

      • const Actual

      Parameters

      • this: void
      • callback: () => Actual
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Extract<Actual, PromiseLike<any>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

class CustomThenable {
constructor(public value: any) {}

then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
return new CustomThenable(
onFulfilled ? onFulfilled(this.value) : this.value,
);
}
}

await waitUntil.isPromiseLike(() => Promise.resolve(5)); // returns the resolved `5`
await waitUntil.isPromiseLike(() => new CustomThenable(5)); // returns the resolved `5`
await waitUntil.isPromiseLike(() => 5); // throws an error

AssertionError If the assertion fails.

isPropertyKey: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Extract<Actual, PropertyKey>> = ...

Repeatedly calls a callback until its output is not a JavaScript primitive. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Extract<Actual, PropertyKey>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Extract<Actual, PropertyKey>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isPrimitive('key'); // throws an error
await waitUntil.isPrimitive(true); // throws an error
await waitUntil.isPrimitive({}); // returns `{}`

AssertionError If the assertion fails.

isString: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, string>> = ...

Repeatedly calls a callback until its output is a string. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isString(() => ''); // returns `''`
await waitUntil.isString(() => 5); // throws an error

AssertionError If the assertion failed.

isSymbol: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, symbol>> = ...

Repeatedly calls a callback until its output is a symbol. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isSymbol(() => Symbol('my-symbol')); // returns the created symbol
await waitUntil.isSymbol(() => 'my-symbol'); // throws an error

AssertionError If the assertion failed.

isTrue: (
    this: void,
    callback: () => unknown,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<true> = ...

Repeatedly calls a callback until its output is exactly true. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • (
          this: void,
          callback: () => unknown,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<true>
    • Parameters

      • this: void
      • callback: () => unknown
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<true>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isTrue(() => true); // returns `true`
await waitUntil.isTrue(() => false); // throws an error
await waitUntil.isTrue(() => 1); // throws an error
await waitUntil.isTrue(() => 0); // throws an error

AssertionError On timeout.

isTruthy: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, FalsyValue>> = ...

Repeatedly calls a callback until its output is truthy. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, FalsyValue>>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, FalsyValue>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isTruthy(() => true); // returns `true`
await waitUntil.isTruthy(() => false); // throws an error
await waitUntil.isTruthy(() => 1); // returns `1`
await waitUntil.isTruthy(() => 0); // throws an error

AssertionError On timeout.

isUndefined: <Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, undefined>> = ...

Repeatedly calls a callback until its output is exactly undefined. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.isUndefined(() => undefined); // returns `undefined`
await waitUntil.isUndefined(() => null); // throws an error

AssertionError If the assertion failed.

isUuid: <const Actual>(
    this: void,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<
    NarrowToExpected<
        Actual,
        `${string}-${string}-${string}-${string}-${string}`,
    >,
> = ...

Repeatedly calls a callback until its output is a valid UUID. Does not accept the nil or max UUIDs. Returns the value if the assertion passes. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <const Actual>(
          this: void,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<
          NarrowToExpected<
              Actual,
              `${string}-${string}-${string}-${string}-${string}`,
          >,
      >
    • Type Parameters

      • const Actual

      Parameters

      • this: void
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<
          NarrowToExpected<
              Actual,
              `${string}-${string}-${string}-${string}-${string}`,
          >,
      >

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';
import {createUuidV4} from '@augment-vir/common';

await waitUntil.isUuid(() => createUuidV4()); // returns the generated value
await waitUntil.isUuid(() => '29e0f18e-6115-4982-8342-0afcadf5d611'); // returns `'29e0f18e-6115-4982-8342-0afcadf5d611'`
await waitUntil.isUuid(() => '00000000-0000-0000-0000-000000000000'); // throws an error
await waitUntil.isUuid(() => 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // throws an error
await waitUntil.isUuid(() => 'not-a-uuid'); // throws an error

AssertionError On timeout.

jsonEquals: <Actual, Expected>(
    this: void,
    expected: Expected,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, Expected>> = ...

Repeatedly calls a callback until its output is deeply equal to the first input when stringified into JSON. This may not make any sense if the values are not valid JSON. This internally sorts all given object keys so it is insensitive to object key order. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the first value.

Type declaration

    • <Actual, Expected>(
          this: void,
          expected: Expected,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Actual, Expected>>
    • Type Parameters

      • Actual
      • Expected

      Parameters

      • this: void
      • expected: Expected
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Actual, Expected>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.jsonEquals({a: 'a'}, () => {
return {a: 'a'};
}); // returns `{a: 'a'}`

await waitUntil.jsonEquals({a: {b: 'c'}}, () => {
return {a: {b: 'b'}};
}); // throws an error

AssertionError On timeout.

lacksKey: <const Parent, const Key extends PropertyKey>(
    this: void,
    key: Key,
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Parent, Record<Key, any>>> = ...

Repeatedly calls a callback until its output is a parent value that does not have the first, key input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the parent value.

Type declaration

    • <const Parent, const Key extends PropertyKey>(
          this: void,
          key: Key,
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Parent, Record<Key, any>>>
    • Type Parameters

      • const Parent
      • const Key extends PropertyKey

      Parameters

      • this: void
      • key: Key
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Parent, Record<Key, any>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.hasKey('a', () => {
return {a: 0, b: 1};
}); // throws an error
await waitUntil.hasKey('c', () => {
return {a: 0, b: 1};
}); // returns `{a: 0, b: 1}`

AssertionError On timeout.

lacksKeys: <const Parent, const Keys extends PropertyKey>(
    this: void,
    keys: readonly Keys[],
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Parent, Partial<Record<Keys, any>>>> = ...

Repeatedly calls a callback until its output is a parent value that does not have any of the first, keys input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the parent value.

Type declaration

    • <const Parent, const Keys extends PropertyKey>(
          this: void,
          keys: readonly Keys[],
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Parent, Partial<Record<Keys, any>>>>
    • Type Parameters

      • const Parent
      • const Keys extends PropertyKey

      Parameters

      • this: void
      • keys: readonly Keys[]
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Parent, Partial<Record<Keys, any>>>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.hasKeys(['a', 'b'], () => {
return {a: 0, b: 1};
}); // throws an error
await waitUntil.hasKeys(['b', 'c'], () => {
return {a: 0, b: 1};
}); // returns `{a: 0, b: 1}`

AssertionError On timeout.

lacksValue: <Parent extends string | object>(
    this: void,
    value: unknown,
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Parent> = ...

Repeatedly calls a callback until its output is an object/array parent does not include a child value through reference equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Parent extends string | object>(
          this: void,
          value: unknown,
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Parent>
    • Type Parameters

      • Parent extends string | object

      Parameters

      • this: void
      • value: unknown
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Parent>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

const child = {a: 'a'};

await waitUntil.lacksValue(child, () => {
return {child};
}); // throws an error
await waitUntil.lacksValue(child, () => {
return {child: {a: 'a'}};
}); // returns `{child: {a: 'a'}}`;
await waitUntil.lacksValue(child, () => [child]); // throws an error

AssertionError On timeout.

lacksValues: <Parent extends string | object>(
    this: void,
    value: unknown[],
    callback: () => MaybePromise<Parent>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Parent> = ...

Repeatedly calls a callback until its output is an object/array parent includes none of the provided child values through reference equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Parent extends string | object>(
          this: void,
          value: unknown[],
          callback: () => MaybePromise<Parent>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Parent>
    • Type Parameters

      • Parent extends string | object

      Parameters

      • this: void
      • value: unknown[]
      • callback: () => MaybePromise<Parent>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Parent>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

const child = {a: 'a'};
const child2 = {b: 'b'};

await waitUntil.lacksValues([child, child2], () => {
return {};
}); // returns `{}`;
await waitUntil.lacksValues([child, child2], () => {
return {child, child2};
}); // throws an error
await waitUntil.lacksValues([child, child2], () => {
return {child: {a: 'a'}, child2};
}); // throws an error

AssertionError On timeout.

looseEquals: <Actual>(
    this: void,
    expected: unknown,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output loosely equals (using ==) the first input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the first value.

Type declaration

    • <Actual>(
          this: void,
          expected: unknown,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • expected: unknown
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.looseEquals('a', () => 'a'); // returns `'a'`

await waitUntil.looseEquals(1, () => '1'); // returns `'1'`

await waitUntil.looseEquals({a: 'a'}, () => {
return {a: 'a'};
}); // throws an error

const objectExample = {a: 'a'};
await waitUntil.looseEquals(objectExample, () => objectExample); // returns `{a: 'a'}`

AssertionError On timeout.

matches: (
    this: void,
    expected: RegExp,
    callback: () => MaybePromise<string>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<string> = ...

Repeatedly calls a callback until its output is a string that matches a RegExp (first input, expected). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • (
          this: void,
          expected: RegExp,
          callback: () => MaybePromise<string>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<string>
    • Parameters

      • this: void
      • expected: RegExp
      • callback: () => MaybePromise<string>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<string>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.matches(/^h/, () => 'hi'); // returns `'hi'`
await waitUntil.matches(/^g/, () => 'hi'); // throws an error

AssertionError If the assertion fails.

mismatches: (
    this: void,
    expected: RegExp,
    callback: () => MaybePromise<string>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<string> = ...

Repeatedly calls a callback until its output is a string that does not match a RegExp (first input, expected). Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • (
          this: void,
          expected: RegExp,
          callback: () => MaybePromise<string>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<string>
    • Parameters

      • this: void
      • expected: RegExp
      • callback: () => MaybePromise<string>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<string>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.mismatches(/^h/, () => 'hi'); // throws an error
await waitUntil.mismatches(/^g/, () => 'hi'); // returns `'hi'`

AssertionError If the assertion fails.

notDeepEquals: <Actual>(
    this: void,
    expected: unknown,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output does not deeply equal (using the deep-eql package) the first input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Note that this check may be expensive, depending on what values it is passed. Whenever possible, use simpler equality checks instead (see the see section below).

Type guards the first value.

Type declaration

    • <Actual>(
          this: void,
          expected: unknown,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • expected: unknown
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.notDeepEquals('a', () => 'a'); // throws an error

await waitUntil.notDeepEquals(1, () => '1'); // returns `'1'`

await waitUntil.notDeepEquals({a: 'a'}, () => {
return {a: 'a'};
}); // throws an error

const objectExample = {a: 'a'};
await waitUntil.notDeepEquals(objectExample, () => objectExample); // throws an error

AssertionError On timeout.

notEntriesEqual: <Actual extends AnyObject>(
    this: void,
    expected: unknown,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is not deeply equal to the first input by checking only their top-level values for strict (non-deep, reference, using ===) equality. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual extends AnyObject>(
          this: void,
          expected: unknown,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      Parameters

      • this: void
      • expected: unknown
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.notEntriesEqual({a: 'a'}, () => {
return {a: 'a'};
}); // throws an error

await waitUntil.notEntriesEqual({a: {b: 'b'}}, () => {
return {a: {b: 'b'}};
}); // returns `{a: {b: 'b'}}`

const bExample = {b: 'b'};
await waitUntil.notEntriesEqual({a: bExample}, () => {
return {a: bExample};
}); // throws an error

AssertionError If both inputs are equal.

notInstanceOf: <const Actual, const Instance>(
    this: void,
    constructor: Constructor<Instance>,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Exclude<Actual, Instance>> = ...

Repeatedly calls a callback until its output is not an instance of the given class constructor. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the value.

Type declaration

    • <const Actual, const Instance>(
          this: void,
          constructor: Constructor<Instance>,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Exclude<Actual, Instance>>
    • Type Parameters

      • const Actual
      • const Instance

      Parameters

      • this: void
      • constructor: Constructor<Instance>
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Exclude<Actual, Instance>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.instanceOf(RegExp, () => /abc/); // throws an error
await waitUntil.instanceOf(RegExp, () => 'abc'); // returns `'abc'`

AssertionError On timeout.

notJsonEquals: <Actual>(
    this: void,
    expected: unknown,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output is not deeply equal to the first input when stringified into JSON. This may not make any sense if the values are not valid JSON. This internally sorts all given object keys so it is insensitive to object key order. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual>(
          this: void,
          expected: unknown,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • expected: unknown
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.notJsonEquals({a: 'a'}, () => {
return {a: 'a'};
}); // throws an error

await waitUntil.notJsonEquals({a: {b: 'c'}}, () => {
return {a: {b: 'b'}};
}); // returns `{a: {b: 'b'}}`

AssertionError On timeout.

notLooseEquals: <Actual>(
    this: void,
    expected: unknown,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output does not loosely equal (using ==) the first input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the first value.

Type declaration

    • <Actual>(
          this: void,
          expected: unknown,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • expected: unknown
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.notLooseEquals('a', () => 'a'); // throws an error

await waitUntil.notLooseEquals(1, () => '1'); // throws an error

await waitUntil.notLooseEquals({a: 'a'}, () => {
return {a: 'a'};
}); // returns `{a: 'a'}`

const objectExample = {a: 'a'};
await waitUntil.notLooseEquals(objectExample, () => objectExample); // throws an error

AssertionError On timeout.

notStrictEquals: <Actual>(
    this: void,
    expected: unknown,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<Actual> = ...

Repeatedly calls a callback until its output does not strictly equal (using ===) the first input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

Type declaration

    • <Actual>(
          this: void,
          expected: unknown,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<Actual>
    • Type Parameters

      • Actual

      Parameters

      • this: void
      • expected: unknown
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<Actual>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.notStrictEquals('a', () => 'a'); // throws an error

await waitUntil.notStrictEquals(1, () => '1'); // returns `'1'`

await waitUntil.notStrictEquals({a: 'a'}, () => {
return {a: 'a'};
}); // returns `{a: 'a'}`

const objectExample = {a: 'a'};
await waitUntil.notStrictEquals(objectExample, () => objectExample); // throws an error

AssertionError On timeout.

output: {
    <const FunctionToCall extends AnyFunction>(
        functionToCall: FunctionToCall,
        inputs: Parameters<NoInfer<FunctionToCall>>,
        expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
    <const FunctionToCall extends AnyFunction>(
        asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>,
        functionToCall: FunctionToCall,
        inputs: Parameters<NoInfer<FunctionToCall>>,
        expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
} = waitUntilOutput

Repeatedly calls a callback until its output deeply equals expectations. A custom asserter can optionally be provided as the first argument to change the expectation checking from the default "deeply equals" to whatever you want.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.output((input: number) => String(input), [5], '5'); // returns `'5'`
await waitUntil.output((input: number) => String(input), [10], '5'); // throws an error

await waitUntil.output(
assert.isLengthAtLeast,
(input: number) => String(input),
[5],
2,
); // throws an error
await waitUntil.output(
assert.isLengthAtLeast,
(input: number) => String(input),
[10],
2,
); // returns `10`

AssertionError If the assertion fails.

startsWith: {
    <const ArrayElement>(
        child: ArrayElement,
        callback: () => MaybePromise<readonly ArrayElement[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<ReadonlyArray<ArrayElement>>;
    (
        child: string,
        callback: () => MaybePromise<string>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string>;
    (
        child: string,
        callback: () => MaybePromise<string | readonly string[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string | ReadonlyArray<string>>;
} = ...

Repeatedly calls a callback until its output string or array starts with the first input child value. This uses reference equality when the parent is an array. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.endsWith('b', () => 'ab'); // throws an error
await waitUntil.endsWith('a', () => 'ab'); // returns `'ab'`
await waitUntil.endsWith('b', () => ['a', 'b']); // throws an error
await waitUntil.endsWith('a', () => ['a', 'b']); // returns `['a', 'b']`

The callback output once it passes.

AssertionError On timeout.

startsWithout: {
    <const ArrayElement>(
        child: ArrayElement,
        callback: () => MaybePromise<readonly ArrayElement[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<ReadonlyArray<ArrayElement>>;
    (
        child: string,
        callback: () => MaybePromise<string>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string>;
    (
        child: string,
        callback: () => MaybePromise<string | readonly string[]>,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<string | ReadonlyArray<string>>;
} = ...

Repeatedly calls a callback until its output string or array does not start with the first input child value. This uses reference equality when the parent is an array. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Performs no type guarding.

await waitUntil.endsWith('b', () => 'ab'); // returns `'ab'`
await waitUntil.endsWith('a', () => 'ab'); // throws an error
await waitUntil.endsWith('b', () => ['a', 'b']); // returns `['a', 'b']`
await waitUntil.endsWith('a', () => ['a', 'b']); // throws an error

The callback output once it passes.

AssertionError On timeout.

strictEquals: <Actual, Expected>(
    this: void,
    expected: Expected,
    callback: () => MaybePromise<Actual>,
    options?: PartialWithUndefined<
        {
            interval: Partial<Record<DurationUnit, undefined | number>>;
            timeout: Partial<Record<DurationUnit, undefined | number>>;
        },
    >,
    failureMessage?: string,
) => Promise<NarrowToExpected<Actual, Expected>> = ...

Repeatedly calls a callback until its output strictly equals (using ===) the first input. Once the callback output passes, it is returned. If the attempts time out, an error is thrown.

Type guards the first value.

Type declaration

    • <Actual, Expected>(
          this: void,
          expected: Expected,
          callback: () => MaybePromise<Actual>,
          options?: PartialWithUndefined<
              {
                  interval: Partial<Record<DurationUnit, undefined | number>>;
                  timeout: Partial<Record<DurationUnit, undefined | number>>;
              },
          >,
          failureMessage?: string,
      ): Promise<NarrowToExpected<Actual, Expected>>
    • Type Parameters

      • Actual
      • Expected

      Parameters

      • this: void
      • expected: Expected
      • callback: () => MaybePromise<Actual>
      • Optionaloptions: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >
      • OptionalfailureMessage: string

      Returns Promise<NarrowToExpected<Actual, Expected>>

      The callback output once it passes.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.strictEquals('a', () => 'a'); // returns `'a'`

await waitUntil.strictEquals(1, () => '1'); // throws an error

await waitUntil.strictEquals({a: 'a'}, () => {
return {a: 'a'};
}); // throws an error

const objectExample = {a: 'a'};
await waitUntil.strictEquals(objectExample, () => objectExample); // returns `{a: 'a'}`

AssertionError On timeout.

throws: {
    (
        this: void,
        callback: () => any,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<Error>;
    (
        this: void,
        matchOptions: PartialWithNullable<
            {
                matchConstructor: ErrorConstructor
                | new (...args: any[]) => Error;
                matchMessage: string | RegExp;
            },
        >,
        callback: () => any,
        options?: PartialWithUndefined<
            {
                interval: Partial<Record<DurationUnit, undefined | number>>;
                timeout: Partial<Record<DurationUnit, undefined | number>>;
            },
        >,
        failureMessage?: string,
    ): Promise<Error>;
} = throwsWaitUntil

Repeatedly calls a callback until it throws an error, comparing the error with the given ErrorMatchOptions, if provided (as the first input). Once the callback throws an Error, that Error is returned. If the attempts time out, an error is thrown.

This assertion will automatically type itself as async vs async based on the input. (A promise or async function inputs results in async. Otherwise, sync.)

Unlike the other .throws guards, waitUntil.throws does not allow a Promise input, only a callback input.

Performs no type guarding.

import {waitUntil} from '@augment-vir/assert';

await waitUntil.throws(() => {
throw new Error();
}); // returns the thrown error
await waitUntil.throws(Promise.reject()); // not allowed
await waitUntil.throws(() => {}); // throws an error
await waitUntil.throws({matchMessage: 'hi'}, () => {
throw new Error('bye');
}); // throws an error

The Error once it passes.

AssertionError On timeout.