@augment-vir/assert
Version:
A collection of assertions for test and production code alike.
1,559 lines • 87.3 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 array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isArray([]); // passes
* assert.isArray({length: 4}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotArray} : the opposite assertion.
*/
isArray(actual, failureMessage) {
if (!Array.isArray(actual)) {
throw new AssertionError(`'${stringify(actual)}' is not an array.`, failureMessage);
}
},
/**
* Asserts that a value is a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isBigInt(123n); // passes
* assert.isBigInt(123); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotBigInt} : the opposite assertion.
*/
isBigInt(actual, failureMessage) {
if (typeof actual !== 'bigint') {
throw new AssertionError(`'${stringify(actual)}' is not a bigint.`, failureMessage);
}
},
/**
* Asserts that a value is a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isBoolean(true); // passes
* assert.isBoolean('true'); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotBoolean} : the opposite assertion.
*/
isBoolean(actual, failureMessage) {
if (typeof actual !== 'boolean') {
throw new AssertionError(`'${stringify(actual)}' is not a boolean.`, failureMessage);
}
},
/**
* Asserts that a value is a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isFunction(() => {}); // passes
* assert.isFunction({}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotFunction} : the opposite assertion.
*/
isFunction(actual, failureMessage) {
if (typeof actual !== 'function') {
throw new AssertionError(`'${stringify(actual)}' is not a function.`, failureMessage);
}
},
/**
* Asserts that a value is exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNull(null); // passes
* assert.isNull(undefined); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotNull} : the opposite assertion.
*/
isNull(actual, failureMessage) {
if (actual !== null) {
throw new AssertionError(`'${stringify(actual)}' is not nul.`, failureMessage);
}
},
/**
* Asserts that a value is a number. This excludes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNumber(123); // passes
* assert.isNumber(123n); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotNumber} : the opposite assertion.
*/
isNumber(actual, failureMessage) {
if (typeof actual !== 'number' || isNaN(actual)) {
throw new AssertionError(`'${stringify(actual)}' is not a number.`, failureMessage);
}
},
/**
* Asserts that a value is an object. This excludes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isObject({}); // passes
* assert.isObject([]); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotObject} : the opposite assertion.
*/
isObject(actual, failureMessage) {
if (Array.isArray(actual) || typeof actual !== 'object' || !actual) {
throw new AssertionError(`'${stringify(actual)}' is not a non-null object.`, failureMessage);
}
},
/**
* Asserts that a value is a plain object. This excludes arrays and class instances.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPlainObject({}); // passes
* assert.isPlainObject({value: 'key'}); // passes
* assert.isPlainObject(null); // fails
* assert.isPlainObject(new RegExp()); // fails
* assert.isPlainObject(new Date()); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotPlainObject} : the opposite assertion.
* - {@link assert.isObject} : a more generic object assertion.
*/
isPlainObject(actual, failureMessage) {
const prototype = Object.getPrototypeOf(actual);
if (typeof actual !== 'object' ||
actual == undefined ||
!((prototype == undefined ||
prototype === Object.prototype ||
Object.getPrototypeOf(prototype) == undefined) &&
!(Symbol.toStringTag in actual) &&
!(Symbol.iterator in actual))) {
throw new AssertionError(`'${stringify(actual)}' is not a plain object.`, failureMessage);
}
},
/**
* Asserts that a value is a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isString(''); // passes
* assert.isString(5); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotString} : the opposite assertion.
*/
isString(actual, failureMessage) {
if (typeof actual !== 'string') {
throw new AssertionError(`'${stringify(actual)}' is not a string.`, failureMessage);
}
},
/**
* Asserts that a value is a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isSymbol(Symbol('my-symbol')); // passes
* assert.isSymbol('my-symbol'); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotSymbol} : the opposite assertion.
*/
isSymbol(actual, failureMessage) {
if (typeof actual !== 'symbol') {
throw new AssertionError(`'${stringify(actual)}' is not a symbol.`, failureMessage);
}
},
/**
* Asserts that a value is exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isUndefined(undefined); // passes
* assert.isUndefined(null); // fails
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNotUndefined} : the opposite assertion.
*/
isUndefined(actual, failureMessage) {
if (typeof actual !== 'undefined') {
throw new AssertionError(`'${stringify(actual)}' is not a undefined.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ an array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotArray([]); // fails
* assert.isNotArray({length: 4}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isArray} : the opposite assertion.
*/
isNotArray(actual, failureMessage) {
if (Array.isArray(actual)) {
throw new AssertionError(`'${stringify(actual)}' is an array.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotBigInt(123n); // fails
* assert.isNotBigInt(123); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isBigInt} : the opposite assertion.
*/
isNotBigInt(actual, failureMessage) {
if (typeof actual === 'bigint') {
throw new AssertionError(`'${stringify(actual)}' is a bigint.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotBoolean(true); // fails
* assert.isNotBoolean('true'); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isBoolean} : the opposite assertion.
*/
isNotBoolean(actual, failureMessage) {
if (typeof actual === 'boolean') {
throw new AssertionError(`'${stringify(actual)}' is a boolean.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotFunction(() => {}); // fails
* assert.isNotFunction({}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotFunction(actual, failureMessage) {
if (typeof actual === 'function') {
throw new AssertionError(`'${stringify(actual)}' is a function.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotNull(null); // fails
* assert.isNotNull(undefined); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed. @see
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotNull(actual, failureMessage) {
if (actual === null) {
throw new AssertionError(`'${stringify(actual)}' is a null.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ a number. This includes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotNumber(123); // fails
* assert.isNotNumber(123n); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isNumber} : the opposite assertion.
*/
isNotNumber(actual, failureMessage) {
if (typeof actual === 'number') {
throw new AssertionError(`'${stringify(actual)}' is a number.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ an object. This includes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotObject({}); // fails
* assert.isNotObject([]); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotObject(actual, failureMessage) {
if (!Array.isArray(actual) && typeof actual === 'object' && !!actual) {
throw new AssertionError(`'${stringify(actual)}' is a non-null object.`, failureMessage);
}
},
/**
* Asserts that a value is not a plain object. This includes arrays and class instances.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotPlainObject({}); // fails
* assert.isNotPlainObject({value: 'key'}); // fails
* assert.isNotPlainObject(null); // passes
* assert.isNotPlainObject(new RegExp()); // passes
* assert.isNotPlainObject(new Date()); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isPlainObject} : the opposite assertion.
* - {@link assert.isNotObject} : a more generic non-object assertion.
*/
isNotPlainObject(actual, failureMessage) {
const prototype = Object.getPrototypeOf(actual);
if (typeof actual !== 'object' ||
actual == undefined ||
!((prototype == undefined ||
prototype === Object.prototype ||
Object.getPrototypeOf(prototype) == undefined) &&
!(Symbol.toStringTag in actual) &&
!(Symbol.iterator in actual))) {
return;
}
throw new AssertionError(`'${stringify(actual)}' is a plain object.`, failureMessage);
},
/**
* Asserts that a value is _not_ a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotString(''); // fails
* assert.isNotString(5); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotString(actual, failureMessage) {
if (typeof actual === 'string') {
throw new AssertionError(`'${stringify(actual)}' is a string.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotSymbol(Symbol('my-symbol')); // fails
* assert.isNotSymbol('my-symbol'); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotSymbol(actual, failureMessage) {
if (typeof actual === 'symbol') {
throw new AssertionError(`'${stringify(actual)}' is a symbol.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotUndefined(undefined); // fails
* assert.isNotUndefined(null); // passes
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assert.isFunction} : the opposite assertion.
*/
isNotUndefined(actual, failureMessage) {
if (typeof actual === 'undefined') {
throw new AssertionError(`'${stringify(actual)}' is a undefined.`, failureMessage);
}
},
};
export const runtimeTypeGuards = {
assert: assertions,
check: {
/**
* Checks that a value is an array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isArray([]); // returns `true`
* check.isArray({length: 4}); // returns `false`
* ```
*
* @see
* - {@link check.isNotArray} : the opposite check.
*/
isArray(actual) {
return Array.isArray(actual);
},
/**
* Checks that a value is a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isBigInt(123n); // returns `true`
* check.isBigInt(123); // returns `false`
* ```
*
* @see
* - {@link check.isNotBigInt} : the opposite check.
*/
isBigInt(actual) {
return typeof actual === 'bigint';
},
/**
* Checks that a value is a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isBoolean(true); // returns `true`
* check.isBoolean('true'); // returns `false`
* ```
*
* @see
* - {@link check.isNotBoolean} : the opposite check.
*/
isBoolean(actual) {
return typeof actual === 'boolean';
},
/**
* Checks that a value is a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isFunction(() => {}); // returns `true`
* check.isFunction({}); // returns `false`
* ```
*
* @see
* - {@link check.isNotFunction} : the opposite check.
*/
isFunction(actual) {
return typeof actual === 'function';
},
/**
* Checks that a value is exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNull(null); // returns `true`
* check.isNull(undefined); // returns `false`
* ```
*
* @see
* - {@link check.isNotNull} : the opposite check.
*/
isNull(actual) {
return actual === null;
},
/**
* Checks that a value is a number. This excludes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNumber(123); // returns `true`
* check.isNumber(123n); // returns `false`
* ```
*
* @see
* - {@link check.isNotNumber} : the opposite check.
*/
isNumber(actual) {
return typeof actual === 'number';
},
/**
* Checks that a value is an object. This excludes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isObject({}); // returns `true`
* check.isObject([]); // returns `false`
* ```
*
* @see
* - {@link check.isNotObject} : the opposite check.
*/
isObject(actual) {
return !Array.isArray(actual) && typeof actual === 'object' && !!actual;
},
/**
* Checks that a value is a plain object. This excludes arrays and class instances.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isPlainObject({}); // returns `true`
* check.isPlainObject({value: 'key'}); // returns `true`
* check.isPlainObject(null); // returns `false`
* check.isPlainObject(new RegExp()); // returns `false`
* check.isPlainObject(new Date()); // returns `false`
* ```
*
* @see
* - {@link check.isNotPlainObject} : the opposite check.
* - {@link check.isObject} : a more generic object check.
*/
isPlainObject(actual) {
if (typeof actual !== 'object' || actual == undefined) {
return false;
}
const prototype = Object.getPrototypeOf(actual);
return ((prototype == undefined ||
prototype === Object.prototype ||
Object.getPrototypeOf(prototype) == undefined) &&
!(Symbol.toStringTag in actual) &&
!(Symbol.iterator in actual));
},
/**
* Checks that a value is a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isString(''); // returns `true`
* check.isString(5); // returns `false`
* ```
*
* @see
* - {@link check.isNotString} : the opposite check.
*/
isString(actual) {
return typeof actual === 'string';
},
/**
* Checks that a value is a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isSymbol(Symbol('my-symbol')); // returns `true`
* check.isSymbol('my-symbol'); // returns `false`
* ```
*
* @see
* - {@link check.isNotSymbol} : the opposite check.
*/
isSymbol(actual) {
return typeof actual === 'symbol';
},
/**
* Checks that a value is exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isUndefined(undefined); // returns `true`
* check.isUndefined(null); // returns `false`
* ```
*
* @see
* - {@link check.isNotUndefined} : the opposite check.
*/
isUndefined(actual) {
return actual === undefined;
},
/**
* Checks that a value is _not_ an array.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotArray([]); // returns `false`
* check.isNotArray({length: 4}); // returns `true`
* ```
*
* @see
* - {@link check.isArray} : the opposite check.
*/
isNotArray(actual) {
return !Array.isArray(actual);
},
/**
* Checks that a value is _not_ a BigInt.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotBigInt(123n); // returns `false`
* check.isNotBigInt(123); // returns `true`
* ```
*
* @see
* - {@link check.isBigInt} : the opposite check.
*/
isNotBigInt(actual) {
return typeof actual !== 'bigint';
},
/**
* Checks that a value is _not_ a boolean.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotBoolean(true); // returns `false`
* check.isNotBoolean('true'); // returns `true`
* ```
*
* @see
* - {@link check.isBoolean} : the opposite check.
*/
isNotBoolean(actual) {
return typeof actual !== 'boolean';
},
/**
* Checks that a value is _not_ a function.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotFunction(() => {}); // returns `false`
* check.isNotFunction({}); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotFunction(actual) {
return typeof actual !== 'function';
},
/**
* Checks that a value is _not_ exactly `null`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotNull(null); // returns `false`
* check.isNotNull(undefined); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotNull(actual) {
return actual !== null;
},
/**
* Checks that a value is _not_ a number. This includes `NaN`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotNumber(123); // returns `false`
* check.isNotNumber(123n); // returns `true`
* ```
*
* @see
* - {@link check.isNumber} : the opposite check.
*/
isNotNumber(actual) {
return typeof actual !== 'number';
},
/**
* Checks that a value is _not_ an object. This includes arrays.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotObject({}); // returns `false`
* check.isNotObject([]); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotObject(actual) {
return Array.isArray(actual) || typeof actual !== 'object' || !actual;
},
/**
* Checks that a value is not a plain object. This includes arrays and class instances.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* check.isNotPlainObject({}); // returns `false`
* check.isNotPlainObject({value: 'key'}); // returns `false`
* check.isNotPlainObject(null); // returns `true`
* check.isNotPlainObject(new RegExp()); // returns `true`
* check.isNotPlainObject(new Date()); // returns `true`
* ```
*
* @see
* - {@link check.isPlainObject} : the opposite check.
* - {@link check.isNotObject} : a more generic non-object check.
*/
isNotPlainObject(actual) {
if (typeof actual !== 'object' || actual == undefined) {
return true;
}
const prototype = Object.getPrototypeOf(actual);
return !((prototype == undefined ||
prototype === Object.prototype ||
Object.getPrototypeOf(prototype) == undefined) &&
!(Symbol.toStringTag in actual) &&
!(Symbol.iterator in actual));
},
/**
* Checks that a value is _not_ a string.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotString(''); // returns `false`
* check.isNotString(5); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotString(actual) {
return typeof actual !== 'string';
},
/**
* Checks that a value is _not_ a symbol.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotSymbol(Symbol('my-symbol')); // returns `false`
* check.isNotSymbol('my-symbol'); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotSymbol(actual) {
return typeof actual !== 'symbol';
},
/**
* Checks that a value is _not_ exactly `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotUndefined(undefined); // returns `false`
* check.isNotUndefined(null); // returns `true`
* ```
*
* @see
* - {@link check.isFunction} : the opposite check.
*/
isNotUndefined(actual) {
return typeof actual !== 'undefined';
},
},
assertWrap: {
/**
* Asserts that a value is an array. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isArray([]); // returns `[]`
* assertWrap.isArray({length: 4}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotArray} : the opposite assertion.
*/
isArray(actual, failureMessage) {
if (!Array.isArray(actual)) {
throw new AssertionError(`'${stringify(actual)}' is not an array.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a BigInt. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isBigInt(123n); // returns `123n`
* assertWrap.isBigInt(123); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotBigInt} : the opposite assertion.
*/
isBigInt(actual, failureMessage) {
if (typeof actual !== 'bigint') {
throw new AssertionError(`'${stringify(actual)}' is not a bigint.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a boolean. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isBoolean(true); // returns `true`
* assertWrap.isBoolean('true'); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotBoolean} : the opposite assertion.
*/
isBoolean(actual, failureMessage) {
if (typeof actual !== 'boolean') {
throw new AssertionError(`'${stringify(actual)}' is not a boolean.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a function. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isFunction(() => {}); // returns `() => {}`
* assertWrap.isFunction({}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotFunction} : the opposite assertion.
*/
isFunction(actual, failureMessage) {
if (typeof actual !== 'function') {
throw new AssertionError(`'${stringify(actual)}' is not a function.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is exactly `null. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNull(null); // returns `null`
* assertWrap.isNull(undefined); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotNull} : the opposite assertion.
*/
isNull(actual, failureMessage) {
if (actual !== null) {
throw new AssertionError(`'${stringify(actual)}' is not nul.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a number. This excludes `NaN. Returns the value if the assertion
* passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNumber(123); // returns `123`
* assertWrap.isNumber(123n); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotNumber} : the opposite assertion.
*/
isNumber(actual, failureMessage) {
if (typeof actual !== 'number' || isNaN(actual)) {
throw new AssertionError(`'${stringify(actual)}' is not a number.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is an object. This excludes arrays. Returns the value if the
* assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isObject({}); // returns `{}`
* assertWrap.isObject([]); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotObject} : the opposite assertion.
*/
isObject(actual, failureMessage) {
if (Array.isArray(actual) || typeof actual !== 'object' || !actual) {
throw new AssertionError(`'${stringify(actual)}' is not a non-null object.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a plain object. This excludes arrays and class instances. Returns
* the value if the assertion passes.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPlainObject({}); // returns `{}`
* assertWrap.isPlainObject({value: 'key'}); // returns `{value: 'key'}`
* assertWrap.isPlainObject(null); // throws an error
* assertWrap.isPlainObject(new RegExp()); // throws an error
* assertWrap.isPlainObject(new Date()); // throws an error
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotPlainObject} : the opposite assertion.
* - {@link assertWrap.isObject} : a more generic object assertion.
*/
isPlainObject(actual, failureMessage) {
const prototype = Object.getPrototypeOf(actual);
if (typeof actual !== 'object' ||
actual == undefined ||
!((prototype == undefined ||
prototype === Object.prototype ||
Object.getPrototypeOf(prototype) == undefined) &&
!(Symbol.toStringTag in actual) &&
!(Symbol.iterator in actual))) {
throw new AssertionError(`'${stringify(actual)}' is not a plain object.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a string. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isString(''); // returns `''`
* assertWrap.isString(5); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotString} : the opposite assertion.
*/
isString(actual, failureMessage) {
if (typeof actual !== 'string') {
throw new AssertionError(`'${stringify(actual)}' is not a string.`, failureMessage);
}
return actual;
},
/**
* Trying to assign a unique symbol to another variable kills the `unique` part of the
* symbol. this seems to be a bug with TypeScript itself.
*
* For some reason `checkWrap` does not suffer from this issue though.
*
* @example Const mySymbol = Symbol('mine'); const mySymbol2 = mySymbol; // this is no
* longer `unique symbol`
*/
/**
* Asserts that a value is a symbol. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isSymbol(Symbol('my-symbol')); // returns the created symbol
* assertWrap.isSymbol('my-symbol'); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotSymbol} : the opposite assertion.
*/
isSymbol(actual, failureMessage) {
if (typeof actual !== 'symbol') {
throw new AssertionError(`'${stringify(actual)}' is not a symbol.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is exactly `undefined. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isUndefined(undefined); // returns `undefined`
* assertWrap.isUndefined(null); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNotUndefined} : the opposite assertion.
*/
isUndefined(actual, failureMessage) {
if (typeof actual !== 'undefined') {
throw new AssertionError(`'${stringify(actual)}' is not a undefined.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ an array. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotArray([]); // throws an error
* assertWrap.isNotArray({length: 4}); // returns `{length: 4}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isArray} : the opposite assertion.
*/
isNotArray(actual, failureMessage) {
if (Array.isArray(actual)) {
throw new AssertionError(`'${stringify(actual)}' is an array.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ a BigInt. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotBigInt(123n); // throws an error
* assertWrap.isNotBigInt(123); // returns `123`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isBigInt} : the opposite assertion.
*/
isNotBigInt(actual, failureMessage) {
if (typeof actual === 'bigint') {
throw new AssertionError(`'${stringify(actual)}' is a bigint.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ a boolean. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotBoolean(true); // throws an error
* assertWrap.isNotBoolean('true'); // returns `'true'`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isBoolean} : the opposite assertion.
*/
isNotBoolean(actual, failureMessage) {
if (typeof actual === 'boolean') {
throw new AssertionError(`'${stringify(actual)}' is a boolean.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ a function. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotFunction(() => {}); // throws an error
* assertWrap.isNotFunction({}); // returns `{}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotFunction(actual, failureMessage) {
if (typeof actual === 'function') {
throw new AssertionError(`'${stringify(actual)}' is a function.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ exactly `null. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotNull(null); // throws an error
* assertWrap.isNotNull(undefined); // returns `undefined`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed. @see
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotNull(actual, failureMessage) {
if (actual === null) {
throw new AssertionError(`'${stringify(actual)}' is a null.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ a number. This includes `NaN. Returns the value if the
* assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotNumber(123); // throws an error
* assertWrap.isNotNumber(123n); // returns `123n`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isNumber} : the opposite assertion.
*/
isNotNumber(actual, failureMessage) {
if (typeof actual === 'number') {
throw new AssertionError(`'${stringify(actual)}' is a number.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ an object. This includes arrays. Returns the value if the
* assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotObject({}); // throws an error
* assertWrap.isNotObject([]); // returns `[]`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotObject(actual, failureMessage) {
if (!Array.isArray(actual) && typeof actual === 'object' && !!actual) {
throw new AssertionError(`'${stringify(actual)}' is a non-null object.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a not plain object. This includes arrays and class instances.
* Returns the value if the assertion passes.
*
* Type guards the value but does not exclude class instances from the type guard (because
* that's impossible).
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotPlainObject({}); // throws an error
* assertWrap.isNotPlainObject({value: 'key'}); // throws an error
* assertWrap.isNotPlainObject(null); // returns `null`
* assertWrap.isNotPlainObject(new RegExp()); // returns the RegExp instance
* assertWrap.isNotPlainObject(new Date()); // returns the Date instance
* ```
*
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isPlainObject} : the opposite assertion.
* - {@link assertWrap.isObject} : a more generic non-object assertion.
*/
isNotPlainObject(actual, failureMessage) {
const prototype = Object.getPrototypeOf(actual);
if (typeof actual !== 'object' ||
actual == undefined ||
!((prototype == undefined ||
prototype === Object.prototype ||
Object.getPrototypeOf(prototype) == undefined) &&
!(Symbol.toStringTag in actual) &&
!(Symbol.iterator in actual))) {
return actual;
}
throw new AssertionError(`'${stringify(actual)}' is a plain object.`, failureMessage);
},
/**
* Asserts that a value is _not_ a string. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotString(''); // throws an error
* assertWrap.isNotString(5); // returns `5`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotString(actual, failureMessage) {
if (typeof actual === 'string') {
throw new AssertionError(`'${stringify(actual)}' is a string.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ a symbol. Returns the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotSymbol(Symbol('my-symbol')); // throws an error
* assertWrap.isNotSymbol('my-symbol'); // returns `'my-symbol'`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion failed.
* @see
* - {@link assertWrap.isFunction} : the opposite assertion.
*/
isNotSymbol(actual, failureMessage) {
if (typeof ac