@augment-vir/assert 30.0.0

package/dist/assertions/equality/json-equality.d.ts

@@ -0,0 +1,42 @@
+import { MaybePromise, NarrowToExpected } from '@augment-vir/core';
+import { WaitUntilOptions } from '../../guard-types/wait-until-function.js';
+/**
+ * Check if the inputs are equal via `JSON.stringify` (property order on objects does not matter).
+ *
+ * @throws `JsonStringifyError` if the inputs fail when passed to `JSON.stringify`.
+ */
+declare function jsonEquals<const Actual, const Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined): asserts actual is Expected;
+declare function notJsonEquals(actual: unknown, expected: unknown, failureMessage?: string | undefined): void;
+export declare const jsonEqualityGuards: {
+    assertions: {
+        /**
+         * Check that two values are deeply equal when stringified into JSON. This will fail or may not
+         * make any sense if the given values are not valid JSON. This internally sorts all given object
+         * keys so it is insensitive to object key order.
+         *
+         * Type guards the first value.
+         */
+        jsonEquals: typeof jsonEquals;
+        /**
+         * Check that two values are _not_ deeply equal when stringified into JSON. This will fail or
+         * may not make any sense if the given values are not valid JSON. This internally sorts all
+         * given object keys so it is insensitive to object key order.
+         *
+         * Performs no type guarding.
+         */
+        notJsonEquals: typeof notJsonEquals;
+    };
+    checkOverrides: {
+        jsonEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => actual is Expected;
+    };
+    assertWrapOverrides: {
+        jsonEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined) => NarrowToExpected<Actual, Expected>;
+    };
+    checkWrapOverrides: {
+        jsonEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => NarrowToExpected<Actual, Expected> | undefined;
+    };
+    waitUntilOverrides: {
+        jsonEquals: <Actual, Expected extends Actual>(expected: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected>>;
+    };
+};
+export {};

package/dist/assertions/equality/json-equality.js

@@ -0,0 +1,75 @@
+import { extractErrorMessage } from '@augment-vir/core';
+import { AssertionError } from '../../augments/assertion.error.js';
+import { autoGuard } from '../../guard-types/guard-override.js';
+function baseJsonEquals(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Check if the inputs are equal via `JSON.stringify` (property order on objects does not matter).
+ *
+ * @throws `JsonStringifyError` if the inputs fail when passed to `JSON.stringify`.
+ */
+function jsonEquals(actual, expected, failureMessage) {
+    try {
+        recursiveJsonEquals(actual, expected);
+    }
+    catch (error) {
+        throw new AssertionError(extractErrorMessage(error), failureMessage);
+    }
+}
+function notJsonEquals(actual, expected, failureMessage) {
+    try {
+        jsonEquals(actual, expected);
+    }
+    catch {
+        return;
+    }
+    throw new AssertionError('Values are JSON equal.', failureMessage);
+}
+function recursiveJsonEquals(actual, expected) {
+    const isBaseJsonEqual = baseJsonEquals(actual, expected);
+    if (actual === expected || isBaseJsonEqual) {
+        return;
+    }
+    if (actual != null &&
+        expected != null &&
+        typeof actual === 'object' &&
+        typeof expected === 'object') {
+        const aKeys = Object.keys(actual).sort();
+        const bKeys = Object.keys(expected).sort();
+        if (aKeys.length || bKeys.length) {
+            const areKeysEqual = baseJsonEquals(aKeys, bKeys);
+            if (!areKeysEqual) {
+                throw new Error('Values are JSON equal.');
+            }
+            Object.keys(actual).forEach((key) => {
+                try {
+                    jsonEquals(actual[key], expected[key]);
+                }
+                catch (error) {
+                    throw new Error(`JSON objects are not equal at key '${key}': ${extractErrorMessage(error)}`);
+                }
+            });
+        }
+    }
+    throw new Error('Values are not JSON equal.');
+}
+const assertions = {
+    jsonEquals,
+    notJsonEquals,
+};
+export const jsonEqualityGuards = {
+    assertions,
+    checkOverrides: {
+        jsonEquals: autoGuard(),
+    },
+    assertWrapOverrides: {
+        jsonEquals: autoGuard(),
+    },
+    checkWrapOverrides: {
+        jsonEquals: autoGuard(),
+    },
+    waitUntilOverrides: {
+        jsonEquals: autoGuard(),
+    },
+};

package/dist/assertions/equality/simple-equality.d.ts

@@ -0,0 +1,85 @@
+import { MaybePromise, NarrowToExpected } from '@augment-vir/core';
+import { WaitUntilOptions } from '../../guard-types/wait-until-function.js';
+export declare function strictEquals<const Actual, const Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined): asserts actual is Expected;
+declare function notStrictEquals(actual: unknown, expected: unknown, failureMessage?: string | undefined): void;
+declare function looseEquals(actual: unknown, expected: unknown, failureMessage?: string | undefined): void;
+declare function notLooseEquals(actual: unknown, expected: unknown, failureMessage?: string | undefined): void;
+export declare function deepEquals<const Actual, const Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined): asserts actual is NarrowToExpected<Actual, Expected>;
+declare function notDeepEquals(actual: unknown, expected: unknown, failureMessage?: string | undefined): void;
+export declare const simpleEqualityGuards: {
+    assertions: {
+        /**
+         * Check that two values are strictly equal (using
+         * [`===`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#strict_equality_using)).
+         *
+         * Type guards the first value.
+         */
+        strictEquals: typeof strictEquals;
+        /**
+         * Check that two values are _not_ strictly equal (using
+         * [`===`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#strict_equality_using)).
+         *
+         * Performs no type guarding.
+         */
+        notStrictEquals: typeof notStrictEquals;
+        /**
+         * Check that two values are loosely equal (using
+         * [`==`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#loose_equality_using)).
+         *
+         * Performs no type guarding.
+         */
+        looseEquals: typeof looseEquals;
+        /**
+         * Check that two values are _not_ loosely equal (using
+         * [`==`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#loose_equality_using)).
+         *
+         * Performs no type guarding.
+         */
+        notLooseEquals: typeof notLooseEquals;
+        /**
+         * Check that two values are deeply equal using the
+         * [deep-eql](https://www.npmjs.com/package/deep-eql) package.
+         *
+         * Note that this check will be _expensive_. Whenever possible, use simpler equality checks
+         * instead, such as:
+         *
+         * - `.strictEquals()`
+         * - `.entriesEqual()`
+         * - `.jsonEquals()`
+         *
+         * Type guards the first value.
+         */
+        deepEquals: typeof deepEquals;
+        /**
+         * Check that two values are _not_ deeply equal using the
+         * [deep-eql](https://www.npmjs.com/package/deep-eql) package.
+         *
+         * Note that this check will be _expensive_. Whenever possible, use simpler equality checks
+         * instead, such as:
+         *
+         * - `.notStrictEquals()`
+         * - `.notEntriesEqual()`
+         * - `.notJsonEquals()`
+         *
+         * Performs no type guarding.
+         */
+        notDeepEquals: typeof notDeepEquals;
+    };
+    checkOverrides: {
+        strictEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => actual is Expected;
+        deepEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => actual is Expected;
+    };
+    assertWrapOverrides: {
+        strictEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined) => NarrowToExpected<Actual, Expected>;
+        deepEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined) => NarrowToExpected<Actual, Expected>;
+    };
+    checkWrapOverrides: {
+        strictEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => Expected | undefined;
+        deepEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => NarrowToExpected<Actual, Expected> | undefined;
+    };
+    waitUntilOverrides: {
+        strictEquals: <Actual, Expected extends Actual>(expected: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected>>;
+        deepEquals: <Actual, Expected extends Actual>(expected: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected>>;
+    };
+};
+export {};

package/dist/assertions/equality/simple-equality.js

@@ -0,0 +1,61 @@
+import { stringify } from '@augment-vir/core';
+import deepEqual from 'deep-eql';
+import { AssertionError } from '../../augments/assertion.error.js';
+import { autoGuard } from '../../guard-types/guard-override.js';
+export function strictEquals(actual, expected, failureMessage) {
+    if (actual !== expected) {
+        throw new AssertionError(`\n\n${stringify(actual)}\n\ndoes not strictly equal\n\n${stringify(expected)}\n\n`, failureMessage);
+    }
+}
+function notStrictEquals(actual, expected, failureMessage) {
+    if (actual === expected) {
+        throw new AssertionError(`\n\n${stringify(actual)}\n\nstrictly equals\n\n${stringify(expected)}\n\n`, failureMessage);
+    }
+}
+function looseEquals(actual, expected, failureMessage) {
+    if (actual != expected) {
+        throw new AssertionError(`\n\n${stringify(actual)}\n\ndoes not loosely equal\n\n${stringify(expected)}\n\n`, failureMessage);
+    }
+}
+function notLooseEquals(actual, expected, failureMessage) {
+    if (actual == expected) {
+        throw new AssertionError(`\n\n${stringify(actual)}\n\nloosely equals\n\n${stringify(expected)}\n\n`, failureMessage);
+    }
+}
+export function deepEquals(actual, expected, failureMessage) {
+    if (!deepEqual(actual, expected)) {
+        throw new AssertionError(`\n\n${stringify(actual)}\n\ndoes not deeply equal\n\n${stringify(expected)}\n\n`, failureMessage);
+    }
+}
+function notDeepEquals(actual, expected, failureMessage) {
+    if (deepEqual(actual, expected)) {
+        throw new AssertionError(`\n\n${stringify(actual)}\n\ndeeply equals\n\n${stringify(expected)}\n\n`, failureMessage);
+    }
+}
+const assertions = {
+    strictEquals,
+    notStrictEquals,
+    looseEquals,
+    notLooseEquals,
+    deepEquals,
+    notDeepEquals,
+};
+export const simpleEqualityGuards = {
+    assertions,
+    checkOverrides: {
+        strictEquals: autoGuard(),
+        deepEquals: autoGuard(),
+    },
+    assertWrapOverrides: {
+        strictEquals: autoGuard(),
+        deepEquals: autoGuard(),
+    },
+    checkWrapOverrides: {
+        strictEquals: autoGuard(),
+        deepEquals: autoGuard(),
+    },
+    waitUntilOverrides: {
+        strictEquals: autoGuard(),
+        deepEquals: autoGuard(),
+    },
+};

package/dist/assertions/equality/ts-type-equality.d.ts

@@ -0,0 +1,42 @@
+import { ExpectTypeOf } from 'expect-type';
+type AssertTypeOf<TestingType> = {
+    equals: ExpectTypeOf<TestingType, {
+        positive: true;
+    }>['toEqualTypeOf'];
+    notEquals: ExpectTypeOf<TestingType, {
+        positive: false;
+    }>['toEqualTypeOf'];
+    matches: ExpectTypeOf<TestingType, {
+        positive: true;
+    }>['toMatchTypeOf'];
+    notMatches: ExpectTypeOf<TestingType, {
+        positive: false;
+    }>['toMatchTypeOf'];
+};
+declare function tsType<Actual>(
+/** Run-time value to type check. */
+input: Actual): AssertTypeOf<Actual>;
+/** Uses the expect-type package to assert type matching. */
+declare function tsType<Actual>(): AssertTypeOf<Actual>;
+export declare const tsTypeGuards: {
+    assertions: {
+        /**
+         * Check if a value or type matches type expectations. Use this to write type tests.
+         *
+         * This should not be used in production code. It won't cause any issues there, but it also
+         * provides no value there.
+         *
+         * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assert} from '@augment-vir/assert';
+         *
+         * assert.tsType('hello').equals<string>();
+         * ```
+         */
+        tsType: typeof tsType;
+    };
+};
+export {};

package/dist/assertions/equality/ts-type-equality.js

@@ -0,0 +1,18 @@
+/** Uses the expect-type package to assert type matching. */
+function tsType(
+/** Run-time value to type check. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+input) {
+    return {
+        equals: () => { },
+        notEquals: () => { },
+        matches: () => { },
+        notMatches: () => { },
+    };
+}
+const assertions = {
+    tsType,
+};
+export const tsTypeGuards = {
+    assertions,
+};