@augment-vir/assert
Version:
A collection of assertions for test and production code alike.
575 lines (574 loc) • 21 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 a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type
* which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPropertyKey('key'); // passes
* assert.isPropertyKey(true); // fails
* assert.isPropertyKey({}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isNotPropertyKey} : the opposite assertion.
*/
isPropertyKey(actual, failureMessage) {
if (typeof actual !== 'string' &&
typeof actual !== 'number' &&
typeof actual !== 'symbol') {
throw new AssertionError(`'${stringify(actual)}' is not a PropertyKey.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript
* type which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isNotPropertyKey('key'); // fails
* assert.isNotPropertyKey(true); // passes
* assert.isNotPropertyKey({}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isPropertyKey} : the opposite assertion.
*/
isNotPropertyKey(actual, failureMessage) {
if (typeof actual === 'string' ||
typeof actual === 'number' ||
typeof actual === 'symbol') {
throw new AssertionError(`'${stringify(actual)}' is a PropertyKey.`, failureMessage);
}
},
/**
* Asserts that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPrimitive('key'); // passes
* assert.isPrimitive(true); // passes
* assert.isPrimitive({}); // fails
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isNotPrimitive} : the opposite assertion.
*/
isPrimitive(actual, failureMessage) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
if (actual !== null && (typeof actual === 'object' || typeof actual === 'function')) {
throw new AssertionError(`'${stringify(actual)}' is not a Primitive.`, failureMessage);
}
},
/**
* Asserts that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assert} from '@augment-vir/assert';
*
* assert.isPrimitive('key'); // fails
* assert.isPrimitive(true); // fails
* assert.isPrimitive({}); // passes
* ```
*
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assert.isPrimitive} : the opposite assertion.
*/
isNotPrimitive(actual, failureMessage) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
if (actual === null || (typeof actual !== 'object' && typeof actual !== 'function')) {
throw new AssertionError(`'${stringify(actual)}' is not a Primitive.`, failureMessage);
}
},
};
export const primitiveGuards = {
assert: assertions,
check: {
/**
* Checks that a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type
* which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotPrimitive('key'); // returns `false`
* check.isNotPrimitive(true); // returns `false`
* check.isNotPrimitive({}); // returns `true`
* ```
*
* @see
* - {@link check.isPrimitive} : the opposite check.
*/
isNotPrimitive(actual) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
return actual !== null && (typeof actual === 'object' || typeof actual === 'function');
},
/**
* Checks that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in
* TypeScript type which refers to all possible key types for a JavaScript object.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isNotPropertyKey('key'); // returns `false`
* check.isNotPropertyKey(true); // returns `true`
* check.isNotPropertyKey({}); // returns `true`
* ```
*
* @see
* - {@link check.isPropertyKey} : the opposite check.
*/
isNotPropertyKey(actual) {
return (typeof actual !== 'string' &&
typeof actual !== 'number' &&
typeof actual !== 'symbol');
},
/**
* Checks that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isPrimitive('key'); // returns `true`
* check.isPrimitive(true); // returns `true`
* check.isPrimitive({}); // returns `false`
* ```
*
* @see
* - {@link check.isNotPrimitive} : the opposite check.
*/
isPrimitive(actual) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
return actual === null || (typeof actual !== 'object' && typeof actual !== 'function');
},
/**
* Checks that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive).
*
* Type guards the value.
*
* @example
*
* ```ts
* import {check} from '@augment-vir/assert';
*
* check.isPropertyKey('key'); // returns `true`
* check.isPropertyKey(true); // returns `false`
* check.isPropertyKey({}); // returns `false`
* ```
*
* @see
* - {@link check.isNotPropertyKey} : the opposite check.
*/
isPropertyKey(actual) {
return (typeof actual === 'string' ||
typeof actual === 'number' ||
typeof actual === 'symbol');
},
},
assertWrap: {
/**
* Asserts that a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript
* type which refers to all possible key types for a JavaScript object. Returns the value if
* the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPropertyKey('key'); // returns `'key'`
* assertWrap.isPropertyKey(true); // throws an error
* assertWrap.isPropertyKey({}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isNotPropertyKey} : the opposite assertion.
*/
isNotPrimitive(actual, failureMessage) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
if (actual === null || (typeof actual !== 'object' && typeof actual !== 'function')) {
throw new AssertionError(`'${stringify(actual)}' is not a Primitive.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in
* TypeScript type which refers to all possible key types for a JavaScript object. Returns
* the value if the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isNotPropertyKey('key'); // throws an error
* assertWrap.isNotPropertyKey(true); // returns `true`
* assertWrap.isNotPropertyKey({}); // returns `{}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isPropertyKey} : the opposite assertion.
*/
isNotPropertyKey(actual, failureMessage) {
if (typeof actual === 'string' ||
typeof actual === 'number' ||
typeof actual === 'symbol') {
throw new AssertionError(`'${stringify(actual)}' is a PropertyKey.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPrimitive('key'); // returns `'key'`
* assertWrap.isPrimitive(true); // returns `true`
* assertWrap.isPrimitive({}); // throws an error
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isNotPrimitive} : the opposite assertion.
*/
isPrimitive(actual, failureMessage) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
if (actual !== null && (typeof actual === 'object' || typeof actual === 'function')) {
throw new AssertionError(`'${stringify(actual)}' is not a Primitive.`, failureMessage);
}
return actual;
},
/**
* Asserts that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the assertion passes.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {assertWrap} from '@augment-vir/assert';
*
* assertWrap.isPrimitive('key'); // throws an error
* assertWrap.isPrimitive(true); // throws an error
* assertWrap.isPrimitive({}); // returns `{}`
* ```
*
* @returns The value if the assertion passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link assertWrap.isPrimitive} : the opposite assertion.
*/
isPropertyKey(actual, failureMessage) {
if (typeof actual !== 'string' &&
typeof actual !== 'number' &&
typeof actual !== 'symbol') {
throw new AssertionError(`'${stringify(actual)}' is not a PropertyKey.`, failureMessage);
}
return actual;
},
},
checkWrap: {
/**
* Checks that a value is a valid `PropertyKey`. `PropertyKey` is a built-in TypeScript type
* which refers to all possible key types for a JavaScript object. Returns the value if the
* check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isNotPrimitive('key'); // returns `undefined`
* checkWrap.isNotPrimitive(true); // returns `undefined`
* checkWrap.isNotPrimitive({}); // returns `{}`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isPrimitive} : the opposite check.
*/
isNotPrimitive(actual) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
if (actual !== null && (typeof actual === 'object' || typeof actual === 'function')) {
return actual;
}
else {
return undefined;
}
},
/**
* Checks that a value is _not_ a valid `PropertyKey`. `PropertyKey` is a built-in
* TypeScript type which refers to all possible key types for a JavaScript object. Returns
* the value if the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isNotPropertyKey('key'); // returns `undefined`
* checkWrap.isNotPropertyKey(true); // returns `true`
* checkWrap.isNotPropertyKey({}); // returns `{}`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isPropertyKey} : the opposite check.
*/
isNotPropertyKey(actual) {
if (typeof actual !== 'string' &&
typeof actual !== 'number' &&
typeof actual !== 'symbol') {
return actual;
}
else {
return undefined;
}
},
/**
* Checks that a value is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isPrimitive('key'); // returns `'key'`
* checkWrap.isPrimitive(true); // returns `true`
* checkWrap.isPrimitive({}); // returns `undefined`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isNotPrimitive} : the opposite check.
*/
isPrimitive(actual) {
/**
* `null` is a primitive but `typeof null` gives `'object'` so we have to special case
* `null` here.
*/
if (actual === null || (typeof actual !== 'object' && typeof actual !== 'function')) {
return actual;
}
else {
return undefined;
}
},
/**
* Checks that a value is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). Returns the value if
* the check passes, otherwise `undefined`.
*
* Type guards the value.
*
* @example
*
* ```ts
* import {checkWrap} from '@augment-vir/assert';
*
* checkWrap.isPrimitive('key'); // returns `undefined`
* checkWrap.isPrimitive(true); // returns `undefined`
* checkWrap.isPrimitive({}); // returns `{}`
* ```
*
* @returns The value if the check passes, otherwise `undefined`.
* @see
* - {@link checkWrap.isPrimitive} : the opposite check.
*/
isPropertyKey(actual) {
if (typeof actual === 'string' ||
typeof actual === 'number' ||
typeof actual === 'symbol') {
return actual;
}
else {
return undefined;
}
},
},
waitUntil: {
/**
* Repeatedly calls a callback until its output is a valid `PropertyKey`. `PropertyKey` is a
* built-in TypeScript type which refers to all possible key types for a JavaScript object.
* 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.isPropertyKey('key'); // returns `'key'`
* await waitUntil.isPropertyKey(true); // throws an error
* await waitUntil.isPropertyKey({}); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isNotPropertyKey} : the opposite assertion.
*/
isNotPrimitive: createWaitUntil(assertions.isNotPrimitive),
/**
* Repeatedly calls a callback until its output is _not_ a valid `PropertyKey`.
* `PropertyKey` is a built-in TypeScript type which refers to all possible key types for a
* JavaScript object. 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.isNotPropertyKey('key'); // throws an error
* await waitUntil.isNotPropertyKey(true); // returns `true`
* await waitUntil.isNotPropertyKey({}); // returns `{}`
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isPropertyKey} : the opposite assertion.
*/
isNotPropertyKey: createWaitUntil(assertions.isNotPropertyKey),
/**
* Repeatedly calls a callback until its output is a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). 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.isPrimitive('key'); // returns `'key'`
* await waitUntil.isPrimitive(true); // returns `true`
* await waitUntil.isPrimitive({}); // throws an error
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isNotPrimitive} : the opposite assertion.
*/
isPrimitive: createWaitUntil(assertions.isPrimitive),
/**
* Repeatedly calls a callback until its output is _not_ a JavaScript
* [primitive](https://developer.mozilla.org/docs/Glossary/Primitive). 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.isPrimitive('key'); // throws an error
* await waitUntil.isPrimitive(true); // throws an error
* await waitUntil.isPrimitive({}); // returns `{}`
* ```
*
* @returns The callback output once it passes.
* @throws {@link AssertionError} If the assertion fails.
* @see
* - {@link waitUntil.isPrimitive} : the opposite assertion.
*/
isPropertyKey: createWaitUntil(assertions.isPropertyKey),
},
};