@augment-vir/assert
Version:
A collection of assertions for test and production code alike.
268 lines (267 loc) • 12.1 kB
TypeScript
import { type MaybePromise, type NarrowToExpected } from '@augment-vir/core';
import { type WaitUntilOptions } from '../../guard-types/wait-until-function.js';
export declare const jsonEqualityGuards: {
assert: {
/**
* 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<const Actual, const Expected extends Actual>(this: void, actual: Actual, expected: Expected, failureMessage?: string | undefined): asserts actual is 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.
*
* 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(this: void, actual: unknown, expected: unknown, failureMessage?: string | undefined): void;
};
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>(this: void, 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(this: void, actual: unknown, expected: unknown): boolean;
};
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>(this: void, 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<Actual>(this: void, actual: Actual, expected: unknown, failureMessage?: string | undefined): Actual;
};
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>(this: void, 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<Actual>(this: void, actual: Actual, expected: unknown): Actual | undefined;
};
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>(this: void, 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: <Actual>(this: void, expected: unknown, callback: () => MaybePromise<Actual>, options?: WaitUntilOptions | undefined, failureMessage?: string | undefined) => Promise<Actual>;
};
};