@augment-vir/assert 30.0.0

package/dist/assertions/throws.d.ts

@@ -0,0 +1,109 @@
+import { MaybePromise, PartialWithNullable, TypedFunction } from '@augment-vir/core';
+import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
+declare function isError(actual: unknown, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): asserts actual is Error;
+/**
+ * A type that represents possible error matching patterns. This is used by the `.throws` and
+ * `isError`, guards in `@augment-vir/assert` as well as `itCases` in `@augment-vir/test`. Each
+ * property is optional, and whichever properties are provided will be checked.
+ *
+ * @category Assert : Util
+ * @example
+ *
+ * ```ts
+ * import {assert, type ErrorMatchOptions} from '@augment-vir/assert';
+ *
+ * // define the options
+ * const matchOptions: ErrorMatchOptions = {
+ *     matchConstructor: Error,
+ *     matchMessage: 'some error',
+ * };
+ *
+ * assert.throws(
+ *     () => {
+ *         throw new Error('some error');
+ *     },
+ *     // use the options
+ *     matchOptions,
+ * ); // this assertion will pass
+ * ```
+ *
+ * @package @augment-vir/assert
+ */
+export type ErrorMatchOptions = PartialWithNullable<{
+    /**
+     * A string or RegExp that an error's message will be compared with.
+     *
+     * - If this is a string, the error's message will checked for _containing_ the given string (not
+     *   strictly equalling it): `error.message.includes(options.matchMessage)`
+     * - If this is a RegExp, the error's message will be tested against it:
+     *   `error.message.match(options.matchMessage)`
+     *
+     * If this property is omitted, the error message won't be checked at all.
+     */
+    matchMessage: string | RegExp;
+    /**
+     * A constructor that the error will be compared to with `instanceof`: `error instanceof
+     * options.matchConstructor`. If this property is omitted, the error's constructor or
+     * inheritance will not be checked.
+     */
+    matchConstructor: ErrorConstructor | (new (...args: any[]) => Error);
+}>;
+declare function throws(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): void;
+declare function throws(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<void>;
+declare function throws(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): void;
+declare function throws(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<void>;
+declare function throwsCheck(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined): boolean;
+declare function throwsCheck(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined): Promise<boolean>;
+declare function throwsCheck(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined): boolean;
+declare function throwsCheck(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined): MaybePromise<boolean>;
+declare function throwsAssertWrap(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error;
+declare function throwsAssertWrap(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
+declare function throwsAssertWrap(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error;
+declare function throwsAssertWrap(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<Error>;
+declare function throwsCheckWrap(callbackOrPromise: TypedFunction<void, never>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error | undefined;
+declare function throwsCheckWrap(callbackOrPromise: TypedFunction<void, Promise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Promise<Error | undefined>;
+declare function throwsCheckWrap(callback: TypedFunction<void, any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): Error | undefined;
+declare function throwsCheckWrap(callback: TypedFunction<void, MaybePromise<any>> | Promise<any>, matchOptions?: ErrorMatchOptions | undefined, failureMessage?: string | undefined): MaybePromise<Error | undefined>;
+declare function throwsWaitUntil(callbackOrPromise: TypedFunction<void, any> | Promise<any>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
+declare function throwsWaitUntil(matchOptions: ErrorMatchOptions, callbackOrPromise: TypedFunction<void, any> | Promise<any>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined): Promise<Error>;
+export declare const throwGuards: {
+    assertions: {
+        /**
+         * Checks that the input is an instance of the built-in `Error` class and compares it to the
+         * given {@link ErrorMatchOptions}, if provided.
+         *
+         * Type guards the input.
+         */
+        isError: typeof isError;
+        /**
+         * If a function input is provided:
+         *
+         * Calls that function and checks that the function throw an error, comparing the error with the
+         * given {@link ErrorMatchOptions}, if provided.
+         *
+         * If a promise is provided:
+         *
+         * Awaits the promise and checks that the promise rejected with an error, comparing the error
+         * with the given {@link ErrorMatchOptions}, if provided.
+         *
+         * This method will automatically type itself as async vs async based on the input. (A promise
+         * or async function inputs results in async. Otherwise, sync.)
+         *
+         * Performs no type guarding.
+         */
+        throws: typeof throws;
+    };
+    checkOverrides: {
+        throws: typeof throwsCheck;
+    };
+    assertWrapOverrides: {
+        throws: typeof throwsAssertWrap;
+    };
+    checkWrapOverrides: {
+        throws: typeof throwsCheckWrap;
+    };
+    waitUntilOverrides: {
+        throws: typeof throwsWaitUntil;
+    };
+};
+export {};

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

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

package/dist/assertions/throws.example.js

@@ -0,0 +1,11 @@
+import { assert } from '@augment-vir/assert';
+// define the options
+const matchOptions = {
+    matchConstructor: Error,
+    matchMessage: 'some error',
+};
+assert.throws(() => {
+    throw new Error('some error');
+}, 
+// use the options
+matchOptions); // this assertion will pass

package/dist/assertions/throws.js

@@ -0,0 +1,166 @@
+import { ensureError, extractErrorMessage, stringify, } from '@augment-vir/core';
+import { AssertionError } from '../augments/assertion.error.js';
+import { createWaitUntil } from '../guard-types/wait-until-function.js';
+var ThrowsCheckType;
+(function (ThrowsCheckType) {
+    ThrowsCheckType["Assert"] = "assert";
+    ThrowsCheckType["AssertWrap"] = "assert-wrap";
+    ThrowsCheckType["CheckWrap"] = "check-wrap";
+    ThrowsCheckType["Check"] = "check";
+})(ThrowsCheckType || (ThrowsCheckType = {}));
+function isError(actual, matchOptions, failureMessage) {
+    internalAssertError(actual, {
+        noError: 'No error.',
+        notInstance: `'${stringify(actual)}' is not an error instance.`,
+    }, matchOptions, failureMessage);
+}
+function assertThrownError(actual, matchOptions, failureMessage) {
+    internalAssertError(actual, {
+        noError: 'No Error was thrown.',
+        notInstance: `Thrown value '${stringify(actual)}' is not an error instance.`,
+    }, matchOptions, failureMessage);
+}
+function internalAssertError(actual, errorMessages, matchOptions, failureMessage) {
+    if (!actual) {
+        throw new AssertionError(errorMessages.noError, failureMessage);
+    }
+    else if (!(actual instanceof Error)) {
+        throw new AssertionError(errorMessages.notInstance, failureMessage);
+    }
+    else if (matchOptions?.matchConstructor &&
+        !(actual instanceof matchOptions.matchConstructor)) {
+        const constructorName = actual.constructor.name;
+        throw new AssertionError(`Error constructor '${constructorName}' did not match expected constructor '${matchOptions.matchConstructor.name}'.`, failureMessage);
+    }
+    else if (matchOptions?.matchMessage) {
+        const message = extractErrorMessage(actual);
+        if (typeof matchOptions.matchMessage === 'string') {
+            if (!message.includes(matchOptions.matchMessage)) {
+                throw new AssertionError(`Error message\n\n'${message}'\n\ndoes not contain\n\n'${matchOptions.matchMessage}'.`, failureMessage);
+            }
+        }
+        else if (!message.match(matchOptions.matchMessage)) {
+            throw new AssertionError(`Error message\n\n'${message}'\n\ndoes not match RegExp\n\n'${matchOptions.matchMessage}'.`, failureMessage);
+        }
+    }
+}
+function internalThrowsCheck(checkType, callbackOrPromise, matchOptions, failureMessage) {
+    let caughtError = undefined;
+    try {
+        const result = callbackOrPromise instanceof Promise ? callbackOrPromise : callbackOrPromise();
+        if (result instanceof Promise) {
+            return new Promise(async (resolve, reject) => {
+                try {
+                    await result;
+                }
+                catch (error) {
+                    caughtError = ensureError(error);
+                }
+                try {
+                    assertThrownError(caughtError, matchOptions, failureMessage);
+                    if (checkType === ThrowsCheckType.Assert) {
+                        resolve();
+                    }
+                    else if (checkType === ThrowsCheckType.Check) {
+                        resolve(true);
+                    }
+                    else {
+                        resolve(caughtError);
+                    }
+                }
+                catch (error) {
+                    if (checkType === ThrowsCheckType.CheckWrap) {
+                        resolve(undefined);
+                    }
+                    else if (checkType === ThrowsCheckType.Check) {
+                        resolve(false);
+                    }
+                    else {
+                        reject(ensureError(error));
+                    }
+                }
+            });
+        }
+    }
+    catch (error) {
+        caughtError = ensureError(error);
+    }
+    try {
+        assertThrownError(caughtError, matchOptions, failureMessage);
+        if (checkType === ThrowsCheckType.Check) {
+            return true;
+        }
+        else if (checkType !== ThrowsCheckType.Assert) {
+            return caughtError;
+        }
+        return;
+    }
+    catch (error) {
+        if (checkType === ThrowsCheckType.CheckWrap) {
+            return undefined;
+        }
+        else if (checkType === ThrowsCheckType.Check) {
+            return false;
+        }
+        else {
+            throw error;
+        }
+    }
+}
+function throws(callbackOrPromise, matchOptions, failureMessage) {
+    return internalThrowsCheck(ThrowsCheckType.Assert, callbackOrPromise, matchOptions, failureMessage);
+}
+function throwsCheck(callbackOrPromise, matchOptions) {
+    return internalThrowsCheck(ThrowsCheckType.Check, callbackOrPromise, matchOptions);
+}
+function throwsAssertWrap(callbackOrPromise, matchOptions, failureMessage) {
+    return internalThrowsCheck(ThrowsCheckType.AssertWrap, callbackOrPromise, matchOptions, failureMessage);
+}
+function throwsCheckWrap(callbackOrPromise, matchOptions, failureMessage) {
+    return internalThrowsCheck(ThrowsCheckType.CheckWrap, callbackOrPromise, matchOptions, failureMessage);
+}
+const internalWaitUntilThrows = createWaitUntil(isError);
+function throwsWaitUntil(matchOptionsOrCallbackOrPromise, callbackOrPromiseOrOptions, optionsOrFailureMessage, failureMessage) {
+    const matchOptions = typeof matchOptionsOrCallbackOrPromise === 'function' ||
+        matchOptionsOrCallbackOrPromise instanceof Promise
+        ? undefined
+        : matchOptionsOrCallbackOrPromise;
+    const callbackOrPromise = (matchOptions ? callbackOrPromiseOrOptions : matchOptionsOrCallbackOrPromise);
+    const actualFailureMessage = typeof optionsOrFailureMessage === 'object' ? failureMessage : optionsOrFailureMessage;
+    const waitUntilOptions = typeof optionsOrFailureMessage === 'object'
+        ? optionsOrFailureMessage
+        : callbackOrPromiseOrOptions;
+    return internalWaitUntilThrows(matchOptions, async () => {
+        try {
+            if (typeof callbackOrPromise === 'function') {
+                await callbackOrPromise();
+            }
+            else {
+                await callbackOrPromise;
+            }
+            return undefined;
+        }
+        catch (error) {
+            return ensureError(error);
+        }
+    }, waitUntilOptions, actualFailureMessage);
+}
+const assertions = {
+    throws,
+    isError: isError,
+};
+export const throwGuards = {
+    assertions,
+    checkOverrides: {
+        throws: throwsCheck,
+    },
+    assertWrapOverrides: {
+        throws: throwsAssertWrap,
+    },
+    checkWrapOverrides: {
+        throws: throwsCheckWrap,
+    },
+    waitUntilOverrides: {
+        throws: throwsWaitUntil,
+    },
+};

package/dist/assertions/uuid.d.ts

@@ -0,0 +1,35 @@
+import { MaybePromise, Uuid } from '@augment-vir/core';
+import { WaitUntilOptions } from '../guard-types/wait-until-function.js';
+/** Checks if the input string is a valid v4 UUID. */
+declare function isUuid(actual: unknown, failureMessage?: string | undefined): asserts actual is Uuid;
+declare function isNotUuid<const Actual>(actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, Uuid>;
+export declare const uuidGuards: {
+    assertions: {
+        /**
+         * Check if the given string is a valid UUID. This supports UUID versions 1-8 and does _not_
+         * support the Nil UUID (all zeros) or the Max UUID (all Fs).
+         *
+         * Type guards the input.
+         */
+        isUuid: typeof isUuid;
+        /**
+         * Check if the given string is _not_ a valid UUID.
+         *
+         * Type guards the input.
+         */
+        isNotUuid: typeof isNotUuid;
+    };
+    checkOverrides: {
+        isNotUuid: <const Actual>(actual: Actual, failureMessage?: string | undefined) => actual is Exclude<Actual, Uuid>;
+    };
+    assertWrapOverrides: {
+        isNotUuid: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, Uuid>;
+    };
+    checkWrapOverrides: {
+        isNotUuid: <const Actual>(actual: Actual, failureMessage?: string | undefined) => Exclude<Actual, Uuid> | undefined;
+    };
+    waitUntilOverrides: {
+        isNotUuid: <const Actual>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Uuid>>;
+    };
+};
+export {};

package/dist/assertions/uuid.js

@@ -0,0 +1,33 @@
+import { AssertionError } from '../augments/assertion.error.js';
+import { autoGuard } from '../guard-types/guard-override.js';
+const uuidRegExp = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Checks if the input string is a valid v4 UUID. */
+function isUuid(actual, failureMessage) {
+    if (!String(actual).match(uuidRegExp)) {
+        throw new AssertionError(`'${String(actual)}' is not a UUID.`, failureMessage);
+    }
+}
+function isNotUuid(actual, failureMessage) {
+    if (String(actual).match(uuidRegExp)) {
+        throw new AssertionError(`'${String(actual)}' is a UUID.`, failureMessage);
+    }
+}
+const assertions = {
+    isUuid,
+    isNotUuid,
+};
+export const uuidGuards = {
+    assertions,
+    checkOverrides: {
+        isNotUuid: autoGuard(),
+    },
+    assertWrapOverrides: {
+        isNotUuid: autoGuard(),
+    },
+    checkWrapOverrides: {
+        isNotUuid: autoGuard(),
+    },
+    waitUntilOverrides: {
+        isNotUuid: autoGuard(),
+    },
+};

package/dist/assertions/values.d.ts

@@ -0,0 +1,106 @@
+import type { NarrowToActual, NarrowToExpected } from '@augment-vir/core';
+import { AnyObject, MaybePromise, Values } from '@augment-vir/core';
+import type { EmptyObject } from 'type-fest';
+import type { WaitUntilOptions } from '../guard-types/wait-until-function.js';
+declare function hasValue(parent: object, value: unknown, failureMessage?: string | undefined): void;
+declare function lacksValue(parent: object, value: unknown, failureMessage?: string | undefined): void;
+declare function hasValues(parent: object, values: ReadonlyArray<unknown>, failureMessage?: string | undefined): void;
+declare function lacksValues(parent: object, values: ReadonlyArray<unknown>, failureMessage?: string | undefined): void;
+export declare function isIn<const Parent extends object | string>(child: unknown, parent: Parent, failureMessage?: string | undefined): asserts child is Values<Parent>;
+declare function isNotIn<const Parent extends object | string, const Child>(child: Child, parent: Parent, failureMessage?: string | undefined): asserts child is Exclude<Child, Values<Parent>>;
+/**
+ * All types that can be checked for emptiness. The empty variants of these types are represented in
+ * {@link Empty}.
+ *
+ * @category Assert : Util
+ * @package @augment-vir/assert
+ */
+export type CanBeEmpty = string | Map<any, any> | Set<any> | AnyObject | any[];
+/**
+ * Empty versions of {@link CanBeEmpty}. Note that there is no way to distinguish an empty `Set` or
+ * `Map` from their non-empty counterparts in TypeScript (so you will get no emptiness type safety
+ * for them.)
+ *
+ * @category Assert : Util
+ * @package @augment-vir/assert
+ */
+export type Empty = '' | EmptyObject | [] | Map<any, any> | Set<any>;
+declare function isEmpty<const Actual extends CanBeEmpty>(actual: Actual, failureMessage?: string | undefined): asserts actual is NarrowToActual<Actual, Empty>;
+declare function isNotEmpty<const Actual extends CanBeEmpty>(actual: Actual, failureMessage?: string | undefined): asserts actual is Exclude<Actual, Empty>;
+export declare const valueGuards: {
+    assertions: {
+        /**
+         * Check if an object/array includes the given value through reference equality.
+         *
+         * Performs no type guarding.
+         */
+        hasValue: typeof hasValue;
+        /**
+         * Check if an object/array does _not_ include the given value through reference equality.
+         *
+         * Performs no type guarding.
+         */
+        lacksValue: typeof lacksValue;
+        /**
+         * Check if an object/array includes the given values through reference equality.
+         *
+         * Performs no type guarding.
+         */
+        hasValues: typeof hasValues;
+        /**
+         * Check if an object/array does _not_ include the given values through reference equality.
+         *
+         * Performs no type guarding.
+         */
+        lacksValues: typeof lacksValues;
+        /**
+         * Check if a child value is contained within a parent object, array, or string.
+         *
+         * Type guards the child when possible.
+         */
+        isIn: typeof isIn;
+        /**
+         * Check if a child value is _not_ contained within a parent object, array, or string.
+         *
+         * Type guards the child when possible.
+         */
+        isNotIn: typeof isNotIn;
+        /**
+         * Check if a value is empty.
+         *
+         * Type guards the value.
+         */
+        isEmpty: typeof isEmpty;
+        /**
+         * Check if a value is not empty.
+         *
+         * Type guards the value.
+         */
+        isNotEmpty: typeof isNotEmpty;
+    };
+    checkOverrides: {
+        isIn: <const Parent>(child: unknown, parent: Parent) => child is Values<Parent>;
+        isNotIn: <const Parent, const Child>(child: Child, parent: Parent, failureMessage?: string | undefined) => child is Exclude<Child, Values<Parent>>;
+        isEmpty: <const Actual extends CanBeEmpty>(actual: Actual) => actual is NarrowToActual<Actual, Empty>;
+        isNotEmpty: <const Actual extends CanBeEmpty>(actual: Actual) => actual is Exclude<Actual, Empty>;
+    };
+    assertWrapOverrides: {
+        isIn: <const Child, const Parent>(child: Child, parent: Parent, failureMessage?: string | undefined) => NarrowToExpected<Child, Values<Parent>>;
+        isNotIn: <const Parent, const Child>(child: Child, parent: Parent, failureMessage?: string | undefined) => Exclude<Child, Values<Parent>>;
+        isEmpty: <const Actual extends CanBeEmpty>(actual: Actual, failureMessage?: string | undefined) => NarrowToActual<Actual, Empty>;
+        isNotEmpty: <const Actual extends CanBeEmpty>(actual: Actual) => Exclude<Actual, Empty>;
+    };
+    checkWrapOverrides: {
+        isIn: <const Child, const Parent>(child: Child, parent: Parent) => NarrowToExpected<Child, Values<Parent>> | undefined;
+        isNotIn: <const Parent, const Child>(child: Child, parent: Parent, failureMessage?: string | undefined) => Exclude<Child, Values<Parent>> | undefined;
+        isEmpty: <const Actual extends CanBeEmpty>(actual: Actual) => NarrowToActual<Actual, Empty> | undefined;
+        isNotEmpty: <const Actual extends CanBeEmpty>(actual: Actual) => Exclude<Actual, Empty> | undefined;
+    };
+    waitUntilOverrides: {
+        isIn: <const Child, const Parent>(parent: Parent, callback: () => MaybePromise<Child>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Child, Values<Parent>>>;
+        isNotIn: <const Child, const Parent>(parent: Parent, callback: () => MaybePromise<Child>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Child, Values<Parent>>>;
+        isEmpty: <const Actual extends CanBeEmpty>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToActual<Actual, Empty>>;
+        isNotEmpty: <const Actual extends CanBeEmpty>(callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Exclude<Actual, Empty>>;
+    };
+};
+export {};

package/dist/assertions/values.js

@@ -0,0 +1,113 @@
+import { stringify } from '@augment-vir/core';
+import { AssertionError } from '../augments/assertion.error.js';
+import { autoGuard } from '../guard-types/guard-override.js';
+function hasValue(parent, value, failureMessage) {
+    /** Wrap this in a try/catch because `Reflect.ownKeys` can fail depending on what its input is. */
+    try {
+        const hasValue = Reflect.ownKeys(parent)
+            .map((key) => parent[key])
+            .includes(value);
+        if (!hasValue) {
+            throw new Error('fail');
+        }
+    }
+    catch {
+        throw new AssertionError(`'${stringify(parent)}' does not have value '${stringify(value)}'.`, failureMessage);
+    }
+}
+function lacksValue(parent, value, failureMessage) {
+    try {
+        hasValue(parent, value);
+    }
+    catch {
+        return;
+    }
+    throw new AssertionError(`'${stringify(parent)}' has value '${stringify(value)}'.`, failureMessage);
+}
+function hasValues(parent, values, failureMessage) {
+    values.forEach((value) => hasValue(parent, value, failureMessage));
+}
+function lacksValues(parent, values, failureMessage) {
+    values.forEach((value) => lacksValue(parent, value, failureMessage));
+}
+export function isIn(child, parent, failureMessage) {
+    if (typeof parent === 'string') {
+        if (!parent.includes(child)) {
+            throw new AssertionError(`${stringify(child)} is not in '${parent}'.`, failureMessage);
+        }
+    }
+    else {
+        hasValue(parent, child, failureMessage);
+    }
+}
+function isNotIn(child, parent, failureMessage) {
+    try {
+        isIn(child, parent);
+    }
+    catch {
+        return;
+    }
+    throw new AssertionError(`${stringify(child)} is not in ${stringify(parent)}.`, failureMessage);
+}
+function isEmpty(actual, failureMessage) {
+    const input = actual;
+    if (!input) {
+        return;
+    }
+    else if (typeof input !== 'string' && typeof input !== 'object') {
+        throw new TypeError(`Cannot check if '${stringify(input)}' is empty.`);
+    }
+    else if ((typeof input === 'string' && input) ||
+        (Array.isArray(input) && input.length) ||
+        (input instanceof Map && input.size) ||
+        (input instanceof Set && input.size) ||
+        (input && typeof input === 'object' && Object.keys(input).length)) {
+        throw new AssertionError(`'${stringify(actual)}' is not empty.`, failureMessage);
+    }
+}
+function isNotEmpty(actual, failureMessage) {
+    try {
+        isEmpty(actual);
+    }
+    catch {
+        return;
+    }
+    throw new AssertionError(`'${stringify(actual)}' is empty.`, failureMessage);
+}
+const assertions = {
+    hasValue,
+    lacksValue,
+    hasValues,
+    lacksValues,
+    isIn,
+    isNotIn,
+    isEmpty,
+    isNotEmpty,
+};
+export const valueGuards = {
+    assertions,
+    checkOverrides: {
+        isIn: autoGuard(),
+        isNotIn: autoGuard(),
+        isEmpty: autoGuard(),
+        isNotEmpty: autoGuard(),
+    },
+    assertWrapOverrides: {
+        isIn: autoGuard(),
+        isNotIn: autoGuard(),
+        isEmpty: autoGuard(),
+        isNotEmpty: autoGuard(),
+    },
+    checkWrapOverrides: {
+        isIn: autoGuard(),
+        isNotIn: autoGuard(),
+        isEmpty: autoGuard(),
+        isNotEmpty: autoGuard(),
+    },
+    waitUntilOverrides: {
+        isIn: autoGuard(),
+        isNotIn: autoGuard(),
+        isEmpty: autoGuard(),
+        isNotEmpty: autoGuard(),
+    },
+};

package/dist/augments/assertion-exports.d.ts

@@ -0,0 +1,5 @@
+export type { Falsy, FalsyValue, Truthy } from '../assertions/boolean.js';
+export type { CustomOutputAsserter } from '../assertions/output.js';
+export { RuntimeType, getRuntimeType } from '../assertions/runtime-type.js';
+export type { ErrorMatchOptions } from '../assertions/throws.js';
+export type { CanBeEmpty, Empty } from '../assertions/values.js';

package/dist/augments/assertion-exports.js

@@ -0,0 +1 @@
+export { RuntimeType, getRuntimeType } from '../assertions/runtime-type.js';

package/dist/augments/assertion.error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * An error thrown by the `@augment-vir/assert` package when an assertion fails.
+ *
+ * This requires both a `baseMessage` (the default "this thing failed" error message defined inside
+ * `@augment-vir/assert` for each assert method), and a possibly-undefined `userCustomizedMessage`
+ * (the optional user-defined failure message for any assertion).
+ *
+ * @category Assert : Util
+ * @example
+ *
+ * ```ts
+ * import {AssertionError} from '@augment-vir/assert';
+ *
+ * // the message from this error will be: `'User defined message: The assertion failed.'`
+ * throw new AssertionError('The assertion failed.', 'User defined message.');
+ * ```
+ *
+ * @package @augment-vir/assert
+ */
+export declare class AssertionError extends Error {
+    name: string;
+    constructor(baseMessage: string, userCustomizedMessage: string | undefined);
+}

package/dist/augments/assertion.error.example.d.ts

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

package/dist/augments/assertion.error.example.js

@@ -0,0 +1,3 @@
+import { AssertionError } from '@augment-vir/assert';
+// the message from this error will be: `'User defined message: The assertion failed.'`
+throw new AssertionError('The assertion failed.', 'User defined message.');

package/dist/augments/assertion.error.js

@@ -0,0 +1,26 @@
+import { combineErrorMessages } from '@augment-vir/core';
+/**
+ * An error thrown by the `@augment-vir/assert` package when an assertion fails.
+ *
+ * This requires both a `baseMessage` (the default "this thing failed" error message defined inside
+ * `@augment-vir/assert` for each assert method), and a possibly-undefined `userCustomizedMessage`
+ * (the optional user-defined failure message for any assertion).
+ *
+ * @category Assert : Util
+ * @example
+ *
+ * ```ts
+ * import {AssertionError} from '@augment-vir/assert';
+ *
+ * // the message from this error will be: `'User defined message: The assertion failed.'`
+ * throw new AssertionError('The assertion failed.', 'User defined message.');
+ * ```
+ *
+ * @package @augment-vir/assert
+ */
+export class AssertionError extends Error {
+    name = 'AssertionError';
+    constructor(baseMessage, userCustomizedMessage) {
+        super(combineErrorMessages(userCustomizedMessage, baseMessage) || 'Assertion failed.');
+    }
+}