@augment-vir/assert 30.0.0

package/dist/assertions/nullish.js

@@ -0,0 +1,42 @@
+import { stringify } from '@augment-vir/core';
+import { AssertionError } from '../augments/assertion.error.js';
+import { autoGuard } from '../guard-types/guard-override.js';
+function isDefined(
+/** The value to check. */
+input, 
+/** Message to include in error message if this assertion fails. */
+failureMessage) {
+    if (input == undefined) {
+        throw new AssertionError(`'${stringify(input)}' is not defined.`, failureMessage);
+    }
+}
+function isNullish(
+/** The value to check. */
+input, 
+/** Message to include in error message if this assertion fails. */
+failureMessage) {
+    if (input != undefined) {
+        throw new AssertionError(`'${stringify(input)}' is not a nullish.`, failureMessage);
+    }
+}
+const assertions = {
+    isDefined,
+    isNullish,
+};
+export const nullishGuards = {
+    assertions: assertions,
+    checkOverrides: {
+        isDefined: autoGuard(),
+    },
+    assertWrapOverrides: {
+        isDefined: autoGuard(),
+    },
+    /** Nullish checks don't make any sense on `checkWrap`. */
+    checkWrapOverrides: {
+        isDefined: undefined,
+        isNullish: undefined,
+    },
+    waitUntilOverrides: {
+        isDefined: autoGuard(),
+    },
+};

package/dist/assertions/numeric.d.ts

@@ -0,0 +1,69 @@
+declare function isAbove(actual: number, expected: number, failureMessage?: string | undefined): void;
+declare function isAtLeast(actual: number, expected: number, failureMessage?: string | undefined): void;
+declare function isBelow(actual: number, expected: number, failureMessage?: string | undefined): void;
+declare function isAtMost(actual: number, expected: number, failureMessage?: string | undefined): void;
+declare function isNaNGuard(actual: number, failureMessage?: string | undefined): void;
+declare function isFiniteGuard(actual: number, failureMessage?: string | undefined): void;
+declare function isInfinite(actual: number, failureMessage?: string | undefined): void;
+declare function isApproximately(actual: number, expected: number, delta: number, failureMessage?: string | undefined): void;
+declare function isNotApproximately(actual: number, expected: number, delta: number, failureMessage?: string | undefined): void;
+export declare const numericGuards: {
+    assertions: {
+        /**
+         * Check if a number is above the expectation (`actual > expected`).
+         *
+         * Performs no type guarding.
+         */
+        isAbove: typeof isAbove;
+        /**
+         * Check if a number is at least the expectation (`actual >= expected`).
+         *
+         * Performs no type guarding.
+         */
+        isAtLeast: typeof isAtLeast;
+        /**
+         * Check if a number is below the expectation (`actual < expected`).
+         *
+         * Performs no type guarding.
+         */
+        isBelow: typeof isBelow;
+        /**
+         * Check if a number is at most the expectation (`actual <= expected`).
+         *
+         * Performs no type guarding.
+         */
+        isAtMost: typeof isAtMost;
+        /**
+         * Check if a number is
+         * [`NaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN).
+         *
+         * Performs no type guarding.
+         */
+        isNaN: typeof isNaNGuard;
+        /**
+         * Check if a number is finite: meaning, not `NaN` and not `Infinity` or `-Infinity`.
+         *
+         * Performs no type guarding.
+         */
+        isFinite: typeof isFiniteGuard;
+        /**
+         * Check if a number is either `Infinity` or `-Infinity`.
+         *
+         * Performs no type guarding.
+         */
+        isInfinite: typeof isInfinite;
+        /**
+         * Check if a number is with ±`delta` of the expectation.
+         *
+         * Performs no type guarding.
+         */
+        isApproximately: typeof isApproximately;
+        /**
+         * Check if a number is outside ±`delta` of the expectation.
+         *
+         * Performs no type guarding.
+         */
+        isNotApproximately: typeof isNotApproximately;
+    };
+};
+export {};

package/dist/assertions/numeric.js

@@ -0,0 +1,60 @@
+import { AssertionError } from '../augments/assertion.error.js';
+function isAbove(actual, expected, failureMessage) {
+    if (actual <= expected) {
+        throw new AssertionError(`${actual} is not above ${expected}`, failureMessage);
+    }
+}
+function isAtLeast(actual, expected, failureMessage) {
+    if (actual < expected) {
+        throw new AssertionError(`${actual} is not at least ${expected}`, failureMessage);
+    }
+}
+function isBelow(actual, expected, failureMessage) {
+    if (actual >= expected) {
+        throw new AssertionError(`${actual} is not below ${expected}`, failureMessage);
+    }
+}
+function isAtMost(actual, expected, failureMessage) {
+    if (actual > expected) {
+        throw new AssertionError(`${actual} is not at most ${expected}`, failureMessage);
+    }
+}
+function isNaNGuard(actual, failureMessage) {
+    if (!isNaN(actual)) {
+        throw new AssertionError(`${actual} is not NaN`, failureMessage);
+    }
+}
+function isFiniteGuard(actual, failureMessage) {
+    if (isNaN(actual) || actual === Infinity || actual === -Infinity) {
+        throw new AssertionError(`${actual} is not finite`, failureMessage);
+    }
+}
+function isInfinite(actual, failureMessage) {
+    if (actual !== Infinity && actual !== -Infinity) {
+        throw new AssertionError(`${actual} is not infinite`, failureMessage);
+    }
+}
+function isApproximately(actual, expected, delta, failureMessage) {
+    if (actual < expected - delta || actual > expected + delta) {
+        throw new AssertionError(`${actual} is not within ±${delta} of ${expected}`, failureMessage);
+    }
+}
+function isNotApproximately(actual, expected, delta, failureMessage) {
+    if (actual >= expected - delta && actual <= expected + delta) {
+        throw new AssertionError(`${actual} is within ±${delta} of ${expected}`, failureMessage);
+    }
+}
+const assertions = {
+    isAbove,
+    isAtLeast,
+    isBelow,
+    isAtMost,
+    isNaN: isNaNGuard,
+    isFinite: isFiniteGuard,
+    isInfinite,
+    isApproximately,
+    isNotApproximately,
+};
+export const numericGuards = {
+    assertions,
+};

package/dist/assertions/output.d.ts

@@ -0,0 +1,83 @@
+import { AnyFunction } from '@augment-vir/core';
+import type { IsAny } from 'type-fest';
+import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
+/**
+ * A customer asserter for `.output` guards (`assert.output`, `check.output`, etc.). This is
+ * typically not necessary, as the `.output` guards already perform deep equality checks by
+ * default.
+ *
+ * @category Assert : Util
+ * @example
+ *
+ * ```ts
+ * import {assert, AssertionError, CustomOutputAsserter} from '@augment-vir/assert';
+ *
+ * function myFunctionToTest(name: string) {
+ *     return `Hello there ${name}`;
+ * }
+ *
+ * const myCustomAsserter: CustomOutputAsserter<typeof myFunctionToTest> = (
+ *     actual,
+ *     expected,
+ *     failureMessage,
+ * ) => {
+ *     // Write your assertion in an `if`.
+ *     if (!actual.startsWith('hello there') || actual.endsWith(expected)) {
+ *         // Throw an `AssertionError` if the `if` fails.
+ *         throw new AssertionError('', failureMessage);
+ *     }
+ * };
+ * // Use your custom asserter as the first input to any `.output` guard.
+ * assert.output(myCustomAsserter, myFunctionToTest, ['John'], 'John', 'Name insertion failed');
+ * ```
+ *
+ * @param FunctionToCall The function type that your custom asserter will be run on.
+ * @package @augment-vir/assert
+ */
+export type CustomOutputAsserter<FunctionToCall extends AnyFunction> = (actual: Awaited<ReturnType<FunctionToCall>>, expected: Awaited<ReturnType<FunctionToCall>>, failureMessage?: string | undefined) => void;
+type OutputReturn<FunctionToCall extends AnyFunction, Return> = Promise<any> extends ReturnType<NoInfer<FunctionToCall>> ? IsAny<ReturnType<FunctionToCall>> extends true ? Return : Promise<Return> : Return;
+export type OutputAssertWithoutAsserter = <const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, void>;
+export type OutputAssertWithAsserter = <const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, void>;
+declare function assertOutput<const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<NoInfer<FunctionToCall>, void>;
+declare function assertOutput<const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<NoInfer<FunctionToCall>, void>;
+export type OutputCheckWithoutAsserter = <const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, boolean>;
+export type OutputCheckWithAsserter = <const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, boolean>;
+declare function checkOutput<const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<FunctionToCall, boolean>;
+declare function checkOutput<const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<FunctionToCall, boolean>;
+export type OutputAssertWrapWithoutAsserter = <const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+export type OutputAssertWrapWithAsserter = <const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+declare function assertWrapOutput<const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<FunctionToCall, Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+declare function assertWrapOutput<const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<FunctionToCall, Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+export type OutputCheckWrapWithoutAsserter = <const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, Awaited<ReturnType<NoInfer<FunctionToCall>>> | undefined>;
+export type OutputCheckWrapWithAsserter = <const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined) => OutputReturn<NoInfer<FunctionToCall>, Awaited<ReturnType<NoInfer<FunctionToCall>>> | undefined>;
+declare function checkWrapOutput<const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<FunctionToCall, Awaited<ReturnType<NoInfer<FunctionToCall>>> | undefined>;
+declare function checkWrapOutput<const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string | undefined): OutputReturn<FunctionToCall, Awaited<ReturnType<NoInfer<FunctionToCall>>> | undefined>;
+export type OutputWaitUntilWithoutAsserter = <const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+export type OutputWaitUntilWithAsserter = <const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+export declare function waitUntilOutput<const FunctionToCall extends AnyFunction>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+export declare function waitUntilOutput<const FunctionToCall extends AnyFunction>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Awaited<ReturnType<NoInfer<FunctionToCall>>>>;
+export declare const outputGuards: {
+    assertions: {
+        /**
+         * Checks that the output of the given function deeply equals expectations. A custom asserter
+         * can optionally be provided as the first argument to change the expectation checking from
+         * "deeply equals" to whatever you want.
+         *
+         * Performs no type guarding.
+         */
+        output: typeof assertOutput;
+    };
+    checkOverrides: {
+        output: typeof checkOutput;
+    };
+    assertWrapOverrides: {
+        output: typeof assertWrapOutput;
+    };
+    checkWrapOverrides: {
+        output: typeof checkWrapOutput;
+    };
+    waitUntilOverrides: {
+        output: typeof waitUntilOutput;
+    };
+};
+export {};

package/dist/assertions/output.example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/assertions/output.example.js

@@ -0,0 +1,13 @@
+import { assert, AssertionError } from '@augment-vir/assert';
+function myFunctionToTest(name) {
+    return `Hello there ${name}`;
+}
+const myCustomAsserter = (actual, expected, failureMessage) => {
+    // Write your assertion in an `if`.
+    if (!actual.startsWith('hello there') || actual.endsWith(expected)) {
+        // Throw an `AssertionError` if the `if` fails.
+        throw new AssertionError('', failureMessage);
+    }
+};
+// Use your custom asserter as the first input to any `.output` guard.
+assert.output(myCustomAsserter, myFunctionToTest, ['John'], 'John', 'Name insertion failed');

package/dist/assertions/output.js

@@ -0,0 +1,173 @@
+import { combineErrorMessages, ensureError, ensureErrorAndPrependMessage, extractErrorMessage, stringify, wait, } from '@augment-vir/core';
+import { convertDuration, DurationUnit } from '@date-vir/duration';
+import { AssertionError } from '../augments/assertion.error.js';
+import { parseWaitUntilOptions } from '../guard-types/wait-until-function.js';
+import { deepEquals } from './equality/simple-equality.js';
+function assertOutput(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage) {
+    return innerAssertOutput(...extractOutputArgs(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage), false);
+}
+function extractOutputArgs(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage) {
+    const usingCustomAsserter = Array.isArray(expectedOutputOrInputs);
+    const asserter = usingCustomAsserter
+        ? functionToCallOrAsserter
+        : deepEquals;
+    const functionToCall = usingCustomAsserter
+        ? inputsOrFunctionToCall
+        : functionToCallOrAsserter;
+    const inputs = usingCustomAsserter
+        ? expectedOutputOrInputs
+        : inputsOrFunctionToCall;
+    const expectedOutput = usingCustomAsserter
+        ? failureMessageOrExpectedOutput
+        : expectedOutputOrInputs;
+    const failureMessage = usingCustomAsserter
+        ? emptyOrFailureMessage
+        : failureMessageOrExpectedOutput;
+    return [
+        asserter,
+        functionToCall,
+        inputs,
+        expectedOutput,
+        failureMessage,
+    ];
+}
+function innerAssertOutput(asserter, functionToCall, inputs, expectedOutput, failureMessage, shouldReturnResult) {
+    const result = functionToCall(...inputs);
+    if (result instanceof Promise) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                const awaitedResult = await result;
+                asserter(awaitedResult, expectedOutput);
+                if (shouldReturnResult) {
+                    resolve(awaitedResult);
+                }
+                else {
+                    resolve();
+                }
+            }
+            catch (error) {
+                reject(new AssertionError(`Output from '${functionToCall.name}' did not produce expected output with input: ${stringify(inputs)}: ${extractErrorMessage(error)}`, failureMessage));
+            }
+        });
+    }
+    else {
+        try {
+            asserter(result, expectedOutput);
+            if (shouldReturnResult) {
+                return result;
+            }
+            else {
+                return;
+            }
+        }
+        catch (error) {
+            throw new AssertionError(`Output from '${functionToCall.name}' did not produce expected output with input: ${stringify(inputs)}: ${extractErrorMessage(error)}`, failureMessage);
+        }
+    }
+}
+function checkOutput(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage) {
+    try {
+        const assertionResult = innerAssertOutput(...extractOutputArgs(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage), false);
+        if (assertionResult instanceof Promise) {
+            return new Promise(async (resolve) => {
+                try {
+                    await assertionResult;
+                    resolve(true);
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+        }
+        else {
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+function assertWrapOutput(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage) {
+    return innerAssertOutput(...extractOutputArgs(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage), true);
+}
+function checkWrapOutput(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage) {
+    try {
+        const assertionResult = innerAssertOutput(...extractOutputArgs(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, failureMessageOrExpectedOutput, emptyOrFailureMessage), true);
+        if (assertionResult instanceof Promise) {
+            return new Promise(async (resolve) => {
+                try {
+                    resolve(await assertionResult);
+                }
+                catch {
+                    resolve(undefined);
+                }
+            });
+        }
+        else {
+            return assertionResult;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+const notSetSymbol = Symbol('not set');
+export async function waitUntilOutput(functionToCallOrAsserter, inputsOrFunctionToCall, expectedOutputOrInputs, optionsOrExpectedOutput, emptyOrFailureMessageOrOptions, emptyOrFailureMessage) {
+    const usingCustomAsserter = Array.isArray(expectedOutputOrInputs);
+    const asserter = usingCustomAsserter
+        ? functionToCallOrAsserter
+        : deepEquals;
+    const functionToCall = usingCustomAsserter
+        ? inputsOrFunctionToCall
+        : functionToCallOrAsserter;
+    const inputs = usingCustomAsserter
+        ? expectedOutputOrInputs
+        : inputsOrFunctionToCall;
+    const expectedOutput = usingCustomAsserter
+        ? optionsOrExpectedOutput
+        : expectedOutputOrInputs;
+    const options = parseWaitUntilOptions((usingCustomAsserter ? emptyOrFailureMessageOrOptions : optionsOrExpectedOutput));
+    const failureMessage = usingCustomAsserter
+        ? emptyOrFailureMessage
+        : emptyOrFailureMessageOrOptions;
+    const timeout = convertDuration(options.timeout, DurationUnit.Milliseconds).milliseconds;
+    const interval = convertDuration(options.interval, DurationUnit.Milliseconds);
+    let lastCallbackOutput = notSetSymbol;
+    let lastError = undefined;
+    async function checkCondition() {
+        try {
+            lastCallbackOutput = await innerAssertOutput(asserter, functionToCall, inputs, expectedOutput, undefined, true);
+        }
+        catch (error) {
+            lastCallbackOutput = notSetSymbol;
+            lastError = ensureError(error);
+        }
+    }
+    const startTime = Date.now();
+    while (lastCallbackOutput === notSetSymbol) {
+        await checkCondition();
+        await wait(interval);
+        if (Date.now() - startTime >= timeout) {
+            throw ensureErrorAndPrependMessage(lastError, combineErrorMessages(failureMessage, `Timeout of '${timeout}' milliseconds exceeded waiting for callback value to match expectations`));
+        }
+    }
+    return lastCallbackOutput;
+}
+const assertions = {
+    output: assertOutput,
+};
+export const outputGuards = {
+    assertions,
+    checkOverrides: {
+        output: checkOutput,
+    },
+    assertWrapOverrides: {
+        output: assertWrapOutput,
+    },
+    checkWrapOverrides: {
+        output: checkWrapOutput,
+    },
+    waitUntilOverrides: {
+        output: waitUntilOutput,
+    },
+};

package/dist/assertions/primitive.d.ts

@@ -0,0 +1,58 @@
+import type { MaybePromise } from '@augment-vir/core';
+import { Primitive } from 'type-fest';
+import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
+export type { Primitive } from 'type-fest';
+/** Asserts that the given value is a primitive. */
+declare function isPrimitive(input: unknown, failureMessage?: string | undefined): asserts input is Primitive;
+declare function isNotPrimitive<const Actual>(input: Actual, failureMessage?: string | undefined): asserts input is Exclude<Actual, Primitive>;
+/** Asserts that the given value is a PropertyKey ( string | number | symbol). */
+declare function isPropertyKey(input: unknown, failureMessage?: string | undefined): asserts input is PropertyKey;
+declare function isNotPropertyKey<const Actual>(input: Actual, failureMessage?: string | undefined): asserts input is Exclude<Actual, PropertyKey>;
+export declare const primitiveGuards: {
+    assertions: {
+        /**
+         * Check if a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type which
+         * refers to all possible key types for a JavaScript object.
+         *
+         * Type guards the value.
+         */
+        isPropertyKey: typeof isPropertyKey;
+        /**
+         * Check if a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type
+         * which refers to all possible key types for a JavaScript object.
+         *
+         * Type guards the value.
+         */
+        isNotPropertyKey: typeof isNotPropertyKey;
+        /**
+         * Check if a value is a JavaScript
+         * [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+         *
+         * Type guards the value.
+         */
+        isPrimitive: typeof isPrimitive;
+        /**
+         * Check if a value is _not_ a JavaScript
+         * [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+         *
+         * Type guards the value.
+         */
+        isNotPrimitive: typeof isNotPrimitive;
+    };
+    checkOverrides: {
+        isNotPrimitive: <const Actual>(input: Actual) => input is Exclude<Actual, Primitive>;
+        isNotPropertyKey: <const Actual>(input: Actual) => input is Exclude<Actual, PropertyKey>;
+    };
+    assertWrapOverrides: {
+        isNotPrimitive: <const Actual>(input: Actual, failureMessage?: string | undefined) => Exclude<Actual, Primitive>;
+        isNotPropertyKey: <const Actual>(input: Actual, failureMessage?: string | undefined) => Exclude<Actual, PropertyKey>;
+    };
+    checkWrapOverrides: {
+        isNotPrimitive: <const Actual>(input: Actual) => Exclude<Actual, Primitive> | undefined;
+        isNotPropertyKey: <const Actual>(input: Actual) => Exclude<Actual, PropertyKey> | undefined;
+    };
+    waitUntilOverrides: {
+        isNotPrimitive: <const Actual>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Primitive>>;
+        isNotPropertyKey: <const Actual>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, PropertyKey>>;
+    };
+};

package/dist/assertions/primitive.js

@@ -0,0 +1,62 @@
+import { stringify } from '@augment-vir/core';
+import { AssertionError } from '../augments/assertion.error.js';
+import { autoGuard } from '../guard-types/guard-override.js';
+/** Asserts that the given value is a primitive. */
+function isPrimitive(input, failureMessage) {
+    /**
+     * `null` is a primitive but `typeof null` gives `'object'` so we have to special case `null`
+     * here.
+     */
+    if (input !== null && (typeof input === 'object' || typeof input === 'function')) {
+        throw new AssertionError(`'${stringify(input)}' is not a Primitive.`, failureMessage);
+    }
+}
+function isNotPrimitive(input, failureMessage) {
+    try {
+        isPrimitive(input);
+    }
+    catch {
+        return;
+    }
+    throw new AssertionError(`'${stringify(input)}' is a Primitive.`, failureMessage);
+}
+/** Asserts that the given value is a PropertyKey ( string | number | symbol). */
+function isPropertyKey(input, failureMessage) {
+    if (typeof input !== 'string' && typeof input !== 'number' && typeof input !== 'symbol') {
+        throw new AssertionError(`'${stringify(input)}' is not a PropertyKey.`, failureMessage);
+    }
+}
+function isNotPropertyKey(input, failureMessage) {
+    try {
+        isPropertyKey(input);
+    }
+    catch {
+        return;
+    }
+    throw new AssertionError(`'${stringify(input)}' is a PropertyKey.`, failureMessage);
+}
+const assertions = {
+    isPropertyKey,
+    isNotPropertyKey,
+    isPrimitive,
+    isNotPrimitive,
+};
+export const primitiveGuards = {
+    assertions,
+    checkOverrides: {
+        isNotPrimitive: autoGuard(),
+        isNotPropertyKey: autoGuard(),
+    },
+    assertWrapOverrides: {
+        isNotPrimitive: autoGuard(),
+        isNotPropertyKey: autoGuard(),
+    },
+    checkWrapOverrides: {
+        isNotPrimitive: autoGuard(),
+        isNotPropertyKey: autoGuard(),
+    },
+    waitUntilOverrides: {
+        isNotPrimitive: autoGuard(),
+        isNotPropertyKey: autoGuard(),
+    },
+};

package/dist/assertions/promise.d.ts

@@ -0,0 +1,65 @@
+import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
+declare function isPromiseLike(actual: unknown, failureMessage?: string | undefined): asserts actual is PromiseLike<any>;
+declare function isNotPromiseLike<const Actual>(actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, PromiseLike<any>>;
+/**
+ * Checks if a value is an actual `Promise` object. In reality this is just a simple wrapper for
+ * `instanceof Promise`, but it makes checking a bit more ergonomic.
+ */
+declare function isPromise(actual: unknown, failureMessage?: string | undefined): asserts actual is Promise<any>;
+declare function isNotPromise<const Actual>(actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, Promise<any>>;
+export declare const promiseGuards: {
+    assertions: {
+        /**
+         * Check if a value is a `PromiseLike`. `PromiseLike` is TypeScript built-in type that simply
+         * includes a `.then` method. This enables the use of third-party promise implementations that
+         * aren't instances of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         */
+        isPromiseLike: typeof isPromiseLike;
+        /**
+         * Check if a value is _not_ a `PromiseLike`. `PromiseLike` is TypeScript built-in type that
+         * simply includes a `.then` method.
+         *
+         * Type guards the value.
+         */
+        isNotPromiseLike: typeof isNotPromiseLike;
+        /**
+         * Check if a value is an instance of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         */
+        isPromise: typeof isPromise;
+        /**
+         * Check if a value is _not_ an instance of the built-in `Promise` class.
+         *
+         * Type guards the value.
+         */
+        isNotPromise: typeof isNotPromise;
+    };
+    checkOverrides: {
+        isNotPromise: <const Actual>(actual: Actual, failureMessage?: string | undefined) => actual is Exclude<Actual, Promise<any>>;
+        isNotPromiseLike: <const Actual>(actual: Actual, failureMessage?: string | undefined) => actual is Exclude<Actual, PromiseLike<any>>;
+    };
+    assertWrapOverrides: {
+        isPromise: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Extract<Actual, Promise<any>>;
+        isNotPromise: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, Promise<any>>;
+        isPromiseLike: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Extract<Actual, PromiseLike<any>>;
+        isNotPromiseLike: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, PromiseLike<any>>;
+    };
+    checkWrapOverrides: {
+        isNotPromise: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, Promise<any>> | undefined;
+        isNotPromiseLike: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, PromiseLike<any>> | undefined;
+    };
+    /**
+     * These overrides must explicitly use `createWaitUntil` so they can pass in `true` for the
+     * second parameter, `requireSynchronousResult`.
+     */
+    waitUntilOverrides: {
+        isPromise: <const Actual>(callback: () => Actual, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Extract<Actual, Promise<any>>>;
+        isNotPromise: <const Actual>(callback: () => Actual, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Promise<any>>>;
+        isPromiseLike: <const Actual>(callback: () => Actual, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Extract<Actual, PromiseLike<any>>>;
+        isNotPromiseLike: <const Actual>(callback: () => Actual, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, PromiseLike<any>>>;
+    };
+};
+export {};