@augment-vir/assert
Version:
A collection of assertions for test and production code alike.
262 lines (261 loc) • 8.89 kB
JavaScript
import { stringify } from '@augment-vir/core';
import { AssertionError } from '../augments/assertion.error.js';
import { createWaitUntil } from '../guard-types/wait-until-function.js';
const assertions = {
/**
* Asserts that a value is an instance of the given class constructor.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.instanceOf(/abc/, RegExp); // passes
* assert.instanceOf('abc', RegExp); // fails
* ```
*
* @throws {@link AssertionError} If the value is not an instance of the given class
* constructor.
* @see
* - {@link assert.notInstanceOf} : the opposite assertion.
*/
instanceOf(instance,
/** The constructor that the "instance" input will be checked against. */
constructor,
/** Message to include in error message if this assertion fails. */
failureMessage) {
if (!(instance instanceof constructor)) {
throw new AssertionError(`'${stringify(instance)}' is not an instance of '${constructor.name}'`, failureMessage);
}
},
/**
* Asserts that a value is _not_ an instance of the given class constructor.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.notInstanceOf(/abc/, RegExp); // fails
* assert.notInstanceOf('abc', RegExp); // passes
* ```
*
* @throws {@link AssertionError} If the value is an instance of the given class constructor.
* @see
* - {@link assert.instanceOf} : the opposite assertion.
*/
notInstanceOf(instance, constructor, failureMessage) {
if (instance instanceof constructor) {
throw new AssertionError(`'${stringify(instance)}' is an instance of '${constructor.name}'`, failureMessage);
}
},
};
export const instanceGuards = {
assert: assertions,
check: {
/**
* Checks that a value is an instance of the given class constructor.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.instanceOf(/abc/, RegExp); // returns `true`
* check.instanceOf('abc', RegExp); // returns `false`
* ```
*
* @see
* - {@link check.notInstanceOf} : the opposite check.
*/
instanceOf(instance, constructor) {
return instance instanceof constructor;
},
/**
* Checks that a value is _not_ an instance of the given class constructor.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.notInstanceOf(/abc/, RegExp); // returns `false`
* check.notInstanceOf('abc', RegExp); // returns `true`
* ```
*
* @see
* - {@link check.instanceOf} : the opposite check.
*/
notInstanceOf(instance, constructor) {
return !(instance instanceof constructor);
},
},
assertWrap: {
/**
* Asserts that a value is an instance of the given class constructor. Returns the value if
* the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.instanceOf(/abc/, RegExp); // returns `/abc/`
* assertWrap.instanceOf('abc', RegExp); // throws an error
* ```
*
* @throws {@link AssertionError} If the value is not an instance of the given class
* constructor.
* @see
* - {@link assertWrap.notInstanceOf} : the opposite assertion.
*/
instanceOf(instance, constructor, failureMessage) {
if (instance instanceof constructor) {
return instance;
}
else {
throw new AssertionError(`'${stringify(instance)}' is not an instance of '${constructor.name}'`, failureMessage);
}
},
/**
* Asserts that a value is _not_ an instance of the given class constructor. Returns the
* value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.notInstanceOf(/abc/, RegExp); // throws an error
* assertWrap.notInstanceOf('abc', RegExp); // returns `'abc'`
* ```
*
* @throws {@link AssertionError} If the value is an instance of the given class
* constructor.
* @see
* - {@link assertWrap.instanceOf} : the opposite assertion.
*/
notInstanceOf(instance, constructor, failureMessage) {
if (instance instanceof constructor) {
throw new AssertionError(`'${stringify(instance)}' is an instance of '${constructor.name}'`, failureMessage);
}
else {
return instance;
}
},
},
checkWrap: {
/**
* Checks that a value is an instance of the given class constructor. Returns the value if
* the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.instanceOf(/abc/, RegExp); // returns `/abc/`
* checkWrap.instanceOf('abc', RegExp); // returns `undefined`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.notInstanceOf} : the opposite check.
*/
instanceOf(instance, constructor) {
if (instance instanceof constructor) {
return instance;
}
else {
return undefined;
}
},
/**
* Checks that a value is _not_ an instance of the given class constructor. Returns the
* value if the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.notInstanceOf(/abc/, RegExp); // returns `undefined`
* checkWrap.notInstanceOf('abc', RegExp); // returns `'abc'`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.instanceOf} : the opposite check.
*/
notInstanceOf(instance, constructor) {
if (instance instanceof constructor) {
return undefined;
}
else {
return instance;
}
},
},
waitUntil: {
/**
* Repeatedly calls a callback until its output is an instance of the given class
* constructor. Once the callback output passes, it is returned. If the attempts time out,
* an error is thrown.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {waitUntil} from '@augment-vir/assert';
*
* await waitUntil.instanceOf(RegExp, () => /abc/); // returns `/abc/`
* await waitUntil.instanceOf(RegExp, () => 'abc'); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} On timeout.
* @see
* - {@link waitUntil.notInstanceOf} : the opposite assertion.
*/
instanceOf: createWaitUntil(assertions.instanceOf),
/**
* Repeatedly calls a callback until its output is not an instance of the given class
* constructor. Once the callback output passes, it is returned. If the attempts time out,
* an error is thrown.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {waitUntil} from '@augment-vir/assert';
*
* await waitUntil.instanceOf(RegExp, () => /abc/); // throws an error
* await waitUntil.instanceOf(RegExp, () => 'abc'); // returns `'abc'`
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} On timeout.
* @see
* - {@link waitUntil.instanceOf} : the opposite assertion.
*/
notInstanceOf: createWaitUntil(assertions.notInstanceOf),
},
};