@augment-vir/assert 30.0.0 → 30.0.2

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

@@ -1,42 +1,271 @@
 import { MaybePromise, NarrowToExpected } from '@augment-vir/core';
+import { autoGuardSymbol } from '../../guard-types/guard-override.js';
 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: {
+    assert: {
         /**
-         * 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
+         * Asserts that two values are deeply equal when stringified into JSON. This will fail or 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.
          *
          * Type guards the first value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assert} from '@augment-vir/assert';
+         *
+         * assert.jsonEquals({a: 'a'}, {a: 'a'}); // passes
+         *
+         * assert.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // fails
+         * ```
+         *
+         * @throws {@link AssertionError} If both inputs are not equal.
+         * @see
+         * - {@link assert.notJsonEquals} : the opposite assertion.
+         * - {@link assert.entriesEqual} : another deep equality assertion.
+         * - {@link assert.deepEquals} : the most thorough (but also slow) deep equality assertion.
          */
         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.
+         * Asserts that two values are _not_ deeply equal 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.
          *
          * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assert} from '@augment-vir/assert';
+         *
+         * assert.notJsonEquals({a: 'a'}, {a: 'a'}); // fails
+         *
+         * assert.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // passes
+         * ```
+         *
+         * @throws {@link AssertionError} If both inputs are not equal.
+         * @see
+         * - {@link assert.jsonEquals} : the opposite assertion.
+         * - {@link assert.entriesEqual} : another deep equality assertion.
+         * - {@link assert.deepEquals} : the most thorough (but also slow) deep equality assertion.
          */
         notJsonEquals: typeof notJsonEquals;
     };
-    checkOverrides: {
+    check: {
+        /**
+         * Checks that two values are deeply equal when stringified into JSON. This will fail or 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.
+         *
+         * Type guards the first value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.jsonEquals({a: 'a'}, {a: 'a'}); // true
+         *
+         * check.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // false
+         * ```
+         *
+         * @see
+         * - {@link check.notJsonEquals} : the opposite check.
+         * - {@link check.entriesEqual} : another deep equality check.
+         * - {@link check.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
         jsonEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => actual is Expected;
+        /**
+         * Checks that two values are _not_ deeply equal 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.
+         *
+         * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.notJsonEquals({a: 'a'}, {a: 'a'}); // false
+         *
+         * check.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // true
+         * ```
+         *
+         * @see
+         * - {@link check.jsonEquals} : the opposite check.
+         * - {@link check.entriesEqual} : another deep equality check.
+         * - {@link check.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
+        notJsonEquals: typeof autoGuardSymbol;
     };
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that two values are deeply equal when stringified into JSON. This will fail or
+         * 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. Returns the first value if the
+         * assertion passes.
+         *
+         * Type guards the first value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.jsonEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`
+         *
+         * assertWrap.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // throws an error
+         * ```
+         *
+         * @throws {@link AssertionError} If both inputs are not equal.
+         * @see
+         * - {@link assertWrap.notJsonEquals} : the opposite assertion.
+         * - {@link assertWrap.entriesEqual} : another deep equality assertion.
+         * - {@link assertWrap.deepEquals} : the most thorough (but also slow) deep equality assertion.
+         */
         jsonEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected, failureMessage?: string | undefined) => NarrowToExpected<Actual, Expected>;
+        /**
+         * Asserts that two values are _not_ deeply equal 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. Returns the first value if the assertion
+         * passes.
+         *
+         * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.notJsonEquals({a: 'a'}, {a: 'a'}); // throws an error
+         *
+         * assertWrap.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // returns `{a: {b: 'b'}}`
+         * ```
+         *
+         * @throws {@link AssertionError} If both inputs are not equal.
+         * @see
+         * - {@link assertWrap.jsonEquals} : the opposite assertion.
+         * - {@link assertWrap.entriesEqual} : another deep equality assertion.
+         * - {@link assertWrap.deepEquals} : the most thorough (but also slow) deep equality assertion.
+         */
+        notJsonEquals: typeof autoGuardSymbol;
     };
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Checks that two values are deeply equal when stringified into JSON. This will fail or 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. Returns the first value if the
+         * check passes.
+         *
+         * Type guards the first value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.jsonEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`
+         *
+         * checkWrap.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // returns `undefined`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.notJsonEquals} : the opposite check.
+         * - {@link checkWrap.entriesEqual} : another deep equality check.
+         * - {@link checkWrap.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
         jsonEquals: <Actual, Expected extends Actual>(actual: Actual, expected: Expected) => NarrowToExpected<Actual, Expected> | undefined;
+        /**
+         * Checks that two values are _not_ deeply equal 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. Returns the first value if the check
+         * passes.
+         *
+         * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.notJsonEquals({a: 'a'}, {a: 'a'}); // false
+         *
+         * checkWrap.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // true
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.jsonEquals} : the opposite check.
+         * - {@link checkWrap.entriesEqual} : another deep equality check.
+         * - {@link checkWrap.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
+        notJsonEquals: typeof autoGuardSymbol;
     };
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * 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.
+         *
+         * @example
+         *
+         * ```ts
+         * 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
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.notJsonEquals} : the opposite assertion.
+         * - {@link waitUntil.entriesEqual} : another deep equality assertion.
+         * - {@link waitUntil.deepEquals} : the most thorough (but also slow) deep equality assertion.
+         */
         jsonEquals: <Actual, Expected extends Actual>(expected: Expected, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<NarrowToExpected<Actual, Expected>>;
+        /**
+         * 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.
+         *
+         * @example
+         *
+         * ```ts
+         * 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'}}`
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.jsonEquals} : the opposite assertion.
+         * - {@link waitUntil.entriesEqual} : another not deep equality assertion.
+         * - {@link waitUntil.deepEquals} : the most thorough (but also slow) not deep equality assertion.
+         */
+        notJsonEquals: typeof autoGuardSymbol;
     };
 };
 export {};

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

@@ -1,14 +1,9 @@
 import { extractErrorMessage } from '@augment-vir/core';
 import { AssertionError } from '../../augments/assertion.error.js';
-import { autoGuard } from '../../guard-types/guard-override.js';
+import { autoGuard, autoGuardSymbol } 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);
@@ -59,17 +54,218 @@ const assertions = {
     notJsonEquals,
 };
 export const jsonEqualityGuards = {
-    assertions,
-    checkOverrides: {
+    assert: assertions,
+    check: {
+        /**
+         * Checks that two values are deeply equal when stringified into JSON. This will fail or 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.
+         *
+         * Type guards the first value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.jsonEquals({a: 'a'}, {a: 'a'}); // true
+         *
+         * check.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // false
+         * ```
+         *
+         * @see
+         * - {@link check.notJsonEquals} : the opposite check.
+         * - {@link check.entriesEqual} : another deep equality check.
+         * - {@link check.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
         jsonEquals: autoGuard(),
+        /**
+         * Checks that two values are _not_ deeply equal 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.
+         *
+         * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {check} from '@augment-vir/assert';
+         *
+         * check.notJsonEquals({a: 'a'}, {a: 'a'}); // false
+         *
+         * check.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // true
+         * ```
+         *
+         * @see
+         * - {@link check.jsonEquals} : the opposite check.
+         * - {@link check.entriesEqual} : another deep equality check.
+         * - {@link check.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
+        notJsonEquals: autoGuardSymbol,
     },
-    assertWrapOverrides: {
+    assertWrap: {
+        /**
+         * Asserts that two values are deeply equal when stringified into JSON. This will fail or
+         * 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. Returns the first value if the
+         * assertion passes.
+         *
+         * Type guards the first value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.jsonEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`
+         *
+         * assertWrap.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // throws an error
+         * ```
+         *
+         * @throws {@link AssertionError} If both inputs are not equal.
+         * @see
+         * - {@link assertWrap.notJsonEquals} : the opposite assertion.
+         * - {@link assertWrap.entriesEqual} : another deep equality assertion.
+         * - {@link assertWrap.deepEquals} : the most thorough (but also slow) deep equality assertion.
+         */
         jsonEquals: autoGuard(),
+        /**
+         * Asserts that two values are _not_ deeply equal 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. Returns the first value if the assertion
+         * passes.
+         *
+         * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {assertWrap} from '@augment-vir/assert';
+         *
+         * assertWrap.notJsonEquals({a: 'a'}, {a: 'a'}); // throws an error
+         *
+         * assertWrap.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // returns `{a: {b: 'b'}}`
+         * ```
+         *
+         * @throws {@link AssertionError} If both inputs are not equal.
+         * @see
+         * - {@link assertWrap.jsonEquals} : the opposite assertion.
+         * - {@link assertWrap.entriesEqual} : another deep equality assertion.
+         * - {@link assertWrap.deepEquals} : the most thorough (but also slow) deep equality assertion.
+         */
+        notJsonEquals: autoGuardSymbol,
     },
-    checkWrapOverrides: {
+    checkWrap: {
+        /**
+         * Checks that two values are deeply equal when stringified into JSON. This will fail or 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. Returns the first value if the
+         * check passes.
+         *
+         * Type guards the first value.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.jsonEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`
+         *
+         * checkWrap.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // returns `undefined`
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.notJsonEquals} : the opposite check.
+         * - {@link checkWrap.entriesEqual} : another deep equality check.
+         * - {@link checkWrap.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
         jsonEquals: autoGuard(),
+        /**
+         * Checks that two values are _not_ deeply equal 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. Returns the first value if the check
+         * passes.
+         *
+         * Performs no type guarding.
+         *
+         * @example
+         *
+         * ```ts
+         * import {checkWrap} from '@augment-vir/assert';
+         *
+         * checkWrap.notJsonEquals({a: 'a'}, {a: 'a'}); // false
+         *
+         * checkWrap.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // true
+         * ```
+         *
+         * @see
+         * - {@link checkWrap.jsonEquals} : the opposite check.
+         * - {@link checkWrap.entriesEqual} : another deep equality check.
+         * - {@link checkWrap.deepEquals} : the most thorough (but also slow) deep equality check.
+         */
+        notJsonEquals: autoGuardSymbol,
     },
-    waitUntilOverrides: {
+    waitUntil: {
+        /**
+         * 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.
+         *
+         * @example
+         *
+         * ```ts
+         * 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
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.notJsonEquals} : the opposite assertion.
+         * - {@link waitUntil.entriesEqual} : another deep equality assertion.
+         * - {@link waitUntil.deepEquals} : the most thorough (but also slow) deep equality assertion.
+         */
         jsonEquals: autoGuard(),
+        /**
+         * 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.
+         *
+         * @example
+         *
+         * ```ts
+         * 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'}}`
+         * ```
+         *
+         * @returns The callback output once it passes.
+         * @throws {@link AssertionError} On timeout.
+         * @see
+         * - {@link waitUntil.jsonEquals} : the opposite assertion.
+         * - {@link waitUntil.entriesEqual} : another not deep equality assertion.
+         * - {@link waitUntil.deepEquals} : the most thorough (but also slow) not deep equality assertion.
+         */
+        notJsonEquals: autoGuardSymbol,
     },
 };