Function assert

A group of guard methods that assert their conditions and do nothing else.

This can also be called as a standalone assertion function which asserts that its input is truthy.

Example

import {assert} from '@augment-vir/assert';

const value: unknown = 'some value' as unknown;
assert.isString(value);
// `value` will now be typed as a `string`

Throws

AssertionError When the assertion fails.

Package

@augment-vir/assert

assert(input, failureMessage?): void
Parameters
- input: unknown
- OptionalfailureMessage: string
Returns void
- Defined in packages/assert/src/augments/guards/assert.ts:53

Index

Properties

deepEquals endsWith endsWithout entriesEqual fail hasKey hasKeys hasValue hasValues instanceOf isAbove isApproximately isArray isAtLeast isAtMost isBelow isBigInt isBoolean isDefined isEmpty isEnumValue isError isFalse isFalsy isFinite isFunction isHttpStatus isHttpStatusCategory isIn isInBounds isInfinite isInteger isKeyOf isLengthAtLeast isLengthExactly isNaN isNotApproximately isNotArray isNotBigInt isNotBoolean isNotEmpty isNotEnumValue isNotFunction isNotIn isNotInteger isNotKeyOf isNotNull isNotNumber isNotObject isNotPrimitive isNotPromise isNotPromiseLike isNotPropertyKey isNotString isNotSymbol isNotUndefined isNotUuid isNull isNullish isNumber isObject isOutBounds isPrimitive isPromise isPromiseLike isPropertyKey isString isSymbol isTrue isTruthy isUndefined isUuid jsonEquals lacksKey lacksKeys lacksValue lacksValues looseEquals matches mismatches notDeepEquals notEntriesEqual notInstanceOf notJsonEquals notLooseEquals notStrictEquals output startsWith startsWithout strictEquals throws tsType

Properties

deepEquals

deepEquals: (<const Actual, const Expected>(actual: Actual, expected: Expected, failureMessage?: string) => asserts actual is NarrowToExpected<Actual, Expected>)

Asserts that two values are deeply equal using the deep-eql package.

Note that this check may be expensive, depending on what values it is passed. Whenever possible, use simpler equality checks instead (see the see section below).

Type guards the first value.

Example

import {assert} from '@augment-vir/assert';

assert.deepEquals('a', 'a'); // passes

assert.deepEquals('1', 1); // fails

assert.deepEquals({a: 'a'}, {a: 'a'}); // passes

const objectExample = {a: 'a'};
assert.deepEquals(objectExample, objectExample); // passes

Throws

AssertionError If both inputs are not deeply equal.

See

assert.notDeepEquals : the opposite assertion.
assert.entriesEqual : a less expensive (but less thorough) deep equality assertion.
assert.jsonEquals : a less expensive (but less thorough) deep equality assertion.

endsWith

endsWith: {
    <const ArrayElement>(parent: readonly ArrayElement[], child: ArrayElement, failureMessage?: string): void;
    (parent: string, child: string, failureMessage?: string): void;
    (parent: string | readonly string[], child: string, failureMessage?: string): void;
}

Asserts that a parent string or array ends with a specific child. This uses reference equality when the parent is an array.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.endsWith('ab', 'b'); // passes
assert.endsWith('ab', 'a'); // fails
assert.endsWith(
    [
        'a',
        'b',
    ],
    'b',
); // passes
assert.endsWith(
    [
        'a',
        'b',
    ],
    'a',
); // fails

Throws

AssertionError If the parent does not end with the child.

See

assert.endsWithout : the opposite assertion.
assert.startsWith : assertion on the other end.

endsWithout

endsWithout: {
    <const ArrayElement>(parent: readonly ArrayElement[], child: ArrayElement, failureMessage?: string): void;
    (parent: string, child: string, failureMessage?: string): void;
    (parent: string | readonly string[], child: string, failureMessage?: string): void;
}

Asserts that a parent string or array does not end with a specific child. This uses reference equality when the parent is an array.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.endsWithout('ab', 'b'); // fails
assert.endsWithout('ab', 'a'); // passes
assert.endsWithout(
    [
        'a',
        'b',
    ],
    'b',
); // fails
assert.endsWithout(
    [
        'a',
        'b',
    ],
    'a',
); // passes

Throws

AssertionError If the parent ends with the child.

See

assert.endsWith : the opposite assertion.
assert.startsWithout : assertion on the other end.

entriesEqual

entriesEqual: (<const Actual, const Expected>(actual: Actual, expected: Expected, failureMessage?: string) => asserts actual is Expected)

Asserts that two objects are deeply equal by checking only their top-level values for strict (non-deep, reference, using ===) equality.

Type guards the first value.

Example

import {assert} from '@augment-vir/assert';

assert.entriesEqual({a: 'a'}, {a: 'a'}); // passes

assert.entriesEqual({a: {b: 'b'}}, {a: {b: 'b'}}); // fails

const bExample = {b: 'b'};
assert.entriesEqual({a: bExample}, {a: bExample}); // passes

Throws

AssertionError If both inputs are not equal.

See

assert.notEntriesEqual : the opposite assertion.
assert.jsonEquals : another deep equality assertion.
assert.deepEquals : the most thorough (but also slow) deep equality assertion.

fail

fail: ((failureMessage?: string) => never) = ...

Immediately throw an assertion error.

Example

import {assert} from '@augment-vir/assert';

assert.fail(); // throws an `AssertionError`

Throws

AssertionError

hasKey

hasKey: (<const Key, const Parent>(parent: Parent, key: Key, failureMessage?: string) => asserts parent is CombineTypeWithKey<Key, Parent>)

Asserts that a parent value has the key.

Type guards the parent value.

Type declaration

- <const Key, const Parent>(parent, key, failureMessage?): asserts parent is CombineTypeWithKey<Key, Parent>
- Check if an object has the given property.
  Type Parameters
  - const Key extends PropertyKey
  - const Parent
  Parameters
  - parent: Parent
  - key: Key
  - OptionalfailureMessage: string
  Returns asserts parent is CombineTypeWithKey<Key, Parent>

Example

import {assert} from '@augment-vir/assert';

assert.hasKey({a: 0, b: 1}, 'a'); // passes
assert.hasKey({a: 0, b: 1}, 'c'); // fails

Throws

AssertionError If the parent does not have the key.

See

assert.lacksKey : the opposite assertion.
assert.hasKeys : the multi-key assertion.

hasKeys

hasKeys: (<const Keys, const Parent>(parent: Parent, keys: readonly Keys[], failureMessage?: string) => asserts parent is CombineTypeWithKey<Keys, Parent>)

Asserts that a parent value has all the keys.

Type guards the parent value.

Type declaration

- <const Keys, const Parent>(parent, keys, failureMessage?): asserts parent is CombineTypeWithKey<Keys, Parent>
- Check if an object has all the given properties.
  Type Parameters
  - const Keys extends PropertyKey
  - const Parent
  Parameters
  - parent: Parent
  - keys: readonly Keys[]
  - OptionalfailureMessage: string
  Returns asserts parent is CombineTypeWithKey<Keys, Parent>

Example

import {assert} from '@augment-vir/assert';

assert.hasKeys({a: 0, b: 1}, [
    'a',
    'b',
]); // passes
assert.hasKeys({a: 0, b: 1}, [
    'b',
    'c',
]); // fails

Throws

AssertionError If the parent does not have all the keys.

See

assert.lacksKeys : the opposite assertion.
assert.hasKey : the single-key assertion.

hasValue

hasValue: ((parent: object, value: unknown, failureMessage?: string) => void)

Asserts that an object/array parent includes a child value through reference equality.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

const child = {a: 'a'};

assert.hasValue({child}, child); // passes
assert.hasValue({child: {a: 'a'}}, child); // fails
assert.hasValue([child], child); // passes

Throws

AssertionError If the assertion fails.

See

assert.lacksValue : the opposite assertion.
assert.hasValues : the multi-value assertion.

hasValues

hasValues: ((parent: object, values: readonly unknown[], failureMessage?: string) => void)

Asserts that an object/array parent includes all child values through reference equality.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

const child = {a: 'a'};
const child2 = {b: 'b'};

assert.hasValues({child, child2}, [
    child,
    child2,
]); // passes
assert.hasValues({child: {a: 'a'}, child2}, [
    child,
    child2,
]); // fails
assert.hasValues(
    [child],
    [
        child,
        child2,
    ],
); // passes

Throws

AssertionError If the assertion fails.

See

assert.lacksValues : the opposite assertion.
assert.hasValue : the single-value assertion.

instanceOf

instanceOf: (<const Instance>(instance: unknown, constructor: Constructor<Instance>, failureMessage?: string) => asserts instance is Instance)

Asserts that a value is an instance of the given class constructor.

Type guards the value.

Type declaration

- <const Instance>(instance, constructor, failureMessage?): asserts instance is Instance
- Wraps the JavaScript built-in "instanceof" in a type guard assertion.
  Type Parameters
  - const Instance
  Parameters
  - instance: unknown
  - constructor: Constructor<Instance>
    The constructor that the "instance" input will be checked against.
  - OptionalfailureMessage: string
    Message to include in error message if this assertion fails.
  Returns asserts instance is Instance

Example

import {assert} from '@augment-vir/assert';

assert.instanceOf(/abc/, RegExp); // passes
assert.instanceOf('abc', RegExp); // fails

Throws

AssertionError If the value is not an instance of the given class constructor.

See

assert.notInstanceOf : the opposite assertion.

isAbove

isAbove: ((actual: number, expected: number, failureMessage?: string) => void)

Asserts that a number is above the expectation (actual > expected).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isAbove(10, 5); // passes
assert.isAbove(5, 5); // fails
assert.isAbove(5, 10); // fails

Throws

AssertionError If the assertion fails.

See

assert.isBelow : the opposite assertion.
assert.isAtLeast : the more lenient assertion.

isApproximately

isApproximately: ((actual: number, expected: number, delta: number, failureMessage?: string) => void)

Asserts that a number is within ±delta of the expectation.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isApproximately(10, 8, 4); // passes
assert.isApproximately(10, 12, 4); // passes
assert.isApproximately(10, 8, 1); // fails
assert.isApproximately(10, 12, 1); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotApproximately : the opposite assertion.

isArray

isArray: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is ArrayNarrow<Actual>)

Asserts that a value is an array.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isArray([]); // passes
assert.isArray({length: 4}); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotArray : the opposite assertion.

isAtLeast

isAtLeast: ((actual: number, expected: number, failureMessage?: string) => void)

Asserts that a number is at least the expectation (actual >= expected).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isAtLeast(10, 5); // passes
assert.isAtLeast(5, 5); // passes
assert.isAtLeast(5, 10); // fails

Throws

AssertionError If the assertion fails.

See

assert.isAtMost : the opposite assertion.
assert.isAbove : the more restrictive assertion.

isAtMost

isAtMost: ((actual: number, expected: number, failureMessage?: string) => void)

Asserts that a number is at most the expectation (actual <= expected).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isAtMost(10, 5); // fails
assert.isAtMost(5, 5); // passes
assert.isAtMost(5, 10); // passes

Throws

AssertionError If the assertion fails.

See

assert.isAtLeast : the opposite assertion.
assert.isBelow : the more restrictive assertion.

isBelow

isBelow: ((actual: number, expected: number, failureMessage?: string) => void)

Asserts that a number is below the expectation (actual < expected).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isBelow(10, 5); // fails
assert.isBelow(5, 5); // fails
assert.isBelow(5, 10); // passes

Throws

AssertionError If the assertion fails.

See

assert.isAbove : the opposite assertion.
assert.isAtMost : the more lenient assertion.

isBigInt

isBigInt: ((actual: unknown, failureMessage?: string) => asserts actual is bigint)

Asserts that a value is a BigInt.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isBigInt(123n); // passes
assert.isBigInt(123); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotBigInt : the opposite assertion.

isBoolean

isBoolean: ((actual: unknown, failureMessage?: string) => asserts actual is boolean)

Asserts that a value is a boolean.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isBoolean(true); // passes
assert.isBoolean('true'); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotBoolean : the opposite assertion.

isDefined

isDefined: (<const Actual>(input: Actual, failureMessage?: string) => asserts input is Exclude<Actual, undefined | null>)

Asserts that a value is defined (not null and not undefined).

Type guards the value.

Type declaration

- <const Actual>(input, failureMessage?): asserts input is Exclude<Actual, undefined | null>
- Type Parameters
  - const Actual
  Parameters
  - input: Actual
    The value to check.
  - OptionalfailureMessage: string
    Message to include in error message if this assertion fails.
  Returns asserts input is Exclude<Actual, undefined | null>

Example

import {assert} from '@augment-vir/assert';

assert.isDefined(0); // passes
assert.isDefined(''); // passes
assert.isDefined(null); // fails
assert.isDefined(undefined); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNullish : the opposite assertion.

isEmpty

isEmpty: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is NarrowToActual<Actual, Empty>)

Asserts that a value is empty. Supports strings, Maps, Sets, objects, and arrays.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isEmpty({}); // passes
assert.isEmpty(''); // passes
assert.isEmpty([]); // passes

assert.isEmpty('a'); // fails
assert.isEmpty({a: 'a'}); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotEmpty : the opposite assertion.

isEnumValue

isEnumValue: (<const Expected>(child: unknown, checkEnum: Expected, failureMessage?: string) => asserts child is Expected[keyof Expected])

Asserts that a child value is an enum member.

Type guards the child value.

Example

import {assert} from '@augment-vir/assert';

enum MyEnum {
    A = 'a',
    B = 'b',
}

assert.isEnumValue('a', MyEnum); // passes
assert.isEnumValue('A', MyEnum); // fails

Throws

AssertionError If the child is not an enum member.

See

assert.isNotEnumValue : the opposite assertion.

isError

isError: ((actual: unknown, matchOptions?: PartialWithNullable<{
matchConstructor: ErrorConstructor | (new (...args: any[]) => Error);
matchMessage: string | RegExp;
}>, failureMessage?: string) => asserts actual is Error)

Asserts that a value is an instance of the built-in Error class and compares it to the given ErrorMatchOptions, if provided.

Type guards the input.

Example

import {assert} from '@augment-vir/assert';

assert.isError(new Error()); // passes
assert.isError(new Error(), {matchMessage: 'hi'}); // fails
assert.isError({message: 'not an error'}); // fails

Throws

AssertionError If the assertion fails.

isFalse

isFalse: ((input: unknown, failureMessage?: string) => asserts input is false)

Asserts that a value is exactly false.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isFalse(true); // fails
assert.isFalse(false); // passes
assert.isFalse(1); // fails
assert.isFalse(0); // fails

Throws

AssertionError If the value is not false.

See

assert.isTrue : the opposite assertion.
assert.isFalsy : a less exact assertion.

isFalsy

isFalsy: ((input: unknown, failureMessage?: string) => asserts input is FalsyValue)

Asserts that a value is falsy.

Type guards the value when possible.

Example

import {assert} from '@augment-vir/assert';

assert.isFalsy(true); // fails
assert.isFalsy(false); // passes
assert.isFalsy(1); // fails
assert.isFalsy(0); // passes

Throws

AssertionError If the value is not falsy.

See

assert.isTruthy : the opposite assertion.
assert.isFalse : a more exact assertion.

isFinite

isFinite: ((actual: number, failureMessage?: string) => void)

Asserts that a number is finite: meaning, not NaN and not Infinity or -Infinity.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isFinite(10); // passes
assert.isFinite(parseInt('invalid')); // fails
assert.isFinite(Infinity); // fails
assert.isFinite(-Infinity); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNaN : an opposite assertion.
assert.isInfinite : an opposite assertion.

isFunction

isFunction: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is NarrowToActual<Actual, AnyFunction>)

Asserts that a value is a function.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isFunction(() => {}); // passes
assert.isFunction({}); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isHttpStatus

isHttpStatus: ((actual: unknown, failureMessage?: string) => asserts actual is HttpStatus)

Asserts that a value is an HttpStatus.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isHttpStatus(400); // passes
assert.isHttpStatus(500); // passes
assert.isHttpStatus(99); // fails

Throws

AssertionError If the value is not an HttpStatus.

See

assert.isHttpStatusCategory : the category assertion.
HttpStatus : all included statuses.
HttpStatusCategory : all status categories.

isHttpStatusCategory

isHttpStatusCategory: (<const Actual, const Category>(actual: Actual, category: Category, failureMessage?: string) => asserts actual is NarrowToExpected<Actual, HttpStatusByCategory<Category>>)

Asserts that a value is an HttpStatus within a specific HttpStatusCategory.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // passes
assert.isHttpStatusCategory(500, HttpStatusCategory.Success); // fails
assert.isHttpStatusCategory(99, HttpStatusCategory.Information); // fails

Throws

AssertionError If the value is not an HttpStatus within the HttpStatusCategory.

See

assert.isHttpStatus : the status assertion.
HttpStatus : all included statuses.
HttpStatusCategory : all status categories.

isIn

isIn: (<const Parent>(child: unknown, parent: Parent, failureMessage?: string) => asserts child is Values<Parent>)

Asserts that child value is contained within a parent object, array, or string through reference equality.

Type guards the child when possible.

Example

import {assert} from '@augment-vir/assert';

const child = {a: 'a'};

assert.isIn(child, {child}); // passes
assert.isIn('a', 'ab'); // passes
assert.isIn(child, [child]); // passes

assert.isIn(child, {child: {a: 'a'}}); // fails
assert.isIn('a', 'bc'); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotIn : the opposite assertion.

isInBounds

isInBounds: ((actual: number, __namedParameters: MinMax, failureMessage?: string) => void)

Asserts that a number is inside the provided min and max bounds, inclusive.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isInBounds(5, {min: 1, max: 10}); // passes
assert.isInBounds(10, {min: 1, max: 10}); // passes
assert.isInBounds(11, {min: 1, max: 10}); // fails
assert.isInBounds(0, {min: 1, max: 10}); // fails

Throws

AssertionError If the assertion fails.

See

assert.isOutBounds : the opposite assertion.

isInfinite

isInfinite: ((actual: number, failureMessage?: string) => void)

Asserts that a number is either Infinity or -Infinity.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isInfinite(10); // fails
assert.isInfinite(parseInt('invalid')); // fails
assert.isInfinite(Infinity); // passes
assert.isInfinite(-Infinity); // passes

Throws

AssertionError If the assertion fails.

See

assert.isNaN : an opposite assertion.
assert.isInfinite : an opposite assertion.

isInteger

isInteger: ((actual: number, failureMessage?: string) => void)

Asserts that a number is an integer. This has the same limitations as https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isInteger(5); // passes
assert.isInteger(5.0000000000000001); // passes
assert.isInteger(5.1); // fails
assert.isInteger(NaN); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotInteger : the opposite assertion.

isKeyOf

isKeyOf: (<const Parent>(key: PropertyKey, parent: Parent, failureMessage?: string) => asserts key is keyof Parent)

Asserts that a key is contained within a parent value.

Type guards the key.

Example

import {assert} from '@augment-vir/assert';

assert.isKeyof('a', {a: 0, b: 1}); // passes
assert.isKeyof('c', {a: 0, b: 1}); // fails

Throws

AssertionError If the key is not in the parent.

See

assert.isNotKeyOf : the opposite assertion.

isLengthAtLeast

isLengthAtLeast: {
<const Element, const Length>(actual: readonly (undefined | Element)[], length: Length, failureMessage?: string): asserts actual is readonly [Tuple<Element, Length>, Element];
(actual: string | AnyObject, length: number, failureMessage?: string): void;
}

Asserts that an array or string has at least the given length.

Type guards an array into an AtLeastTuple. Performs no type guarding on a string.

Example

import {assert} from '@augment-vir/assert';

assert.isLengthAtLeast(
    [
        'a',
        'b',
        'c',
    ],
    2,
); // passes
assert.isLengthAtLeast(
    [
        'a',
        'b',
        'c',
    ],
    3,
); // passes
assert.isLengthAtLeast(
    [
        'a',
        'b',
    ],
    3,
); // fails

Throws

AssertionError If the value is less than the given length.

See

assert.isLengthExactly : the more exact assertion.

isLengthExactly

isLengthExactly: {
<const Element, const Length>(actual: readonly (undefined | Element)[], length: Length, failureMessage?: string): asserts actual is Tuple<Element, Length>;
(actual: string | AnyObject, length: number, failureMessage?: string): void;
}

Asserts that an array or string has exactly the given length.

Type guards an array into a Tuple. Performs no type guarding on a string.

Example

import {assert} from '@augment-vir/assert';

assert.isLengthExactly(
    [
        'a',
        'b',
        'c',
    ],
    2,
); // fails
assert.isLengthExactly(
    [
        'a',
        'b',
        'c',
    ],
    3,
); // passes
assert.isLengthExactly(
    [
        'a',
        'b',
    ],
    3,
); // fails

Throws

AssertionError If the value is not exactly the given length.

See

assert.isLengthAtLeast : the more flexible assertion.

isNaN

isNaN: ((actual: number, failureMessage?: string) => void)

Asserts that a number is NaN.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isNaN(10); // fails
assert.isNaN(parseInt('invalid')); // passes
assert.isNaN(Infinity); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNumber : can be used as the opposite assertion.

isNotApproximately

isNotApproximately: ((actual: number, expected: number, delta: number, failureMessage?: string) => void)

Asserts that a number is outside ±delta of the expectation.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isNotApproximately(10, 8, 4); // fails
assert.isNotApproximately(10, 12, 4); // fails
assert.isNotApproximately(10, 8, 1); // passes
assert.isNotApproximately(10, 12, 1); // passes

Throws

AssertionError If the assertion fails.

See

assert.isApproximately : the opposite assertion.

isNotArray

isNotArray: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, readonly unknown[]>)

Asserts that a value is not an array.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotArray([]); // fails
assert.isNotArray({length: 4}); // passes

Throws

AssertionError If the assertion failed.

See

assert.isArray : the opposite assertion.

isNotBigInt

isNotBigInt: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, bigint>)

Asserts that a value is not a BigInt.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotBigInt(123n); // fails
assert.isNotBigInt(123); // passes

Throws

AssertionError If the assertion failed.

See

assert.isBigInt : the opposite assertion.

isNotBoolean

isNotBoolean: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, boolean>)

Asserts that a value is not a boolean.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotBoolean(true); // fails
assert.isNotBoolean('true'); // passes

Throws

AssertionError If the assertion failed.

See

assert.isBoolean : the opposite assertion.

isNotEmpty

isNotEmpty: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, Empty>)

Asserts that a value is not empty. Supports strings, Maps, Sets, objects, and arrays.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotEmpty({}); // fails
assert.isNotEmpty(''); // fails
assert.isNotEmpty([]); // fails

assert.isNotEmpty('a'); // passes
assert.isNotEmpty({a: 'a'}); // passes

Throws

AssertionError If the assertion fails.

See

assert.isEmpty : the opposite assertion.

isNotEnumValue

isNotEnumValue: (<const Actual, const Expected>(child: Actual, checkEnum: Expected, failureMessage?: string) => asserts child is Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>)

Asserts that a child value is not an enum member.

Type guards the child value.

Example

import {assert} from '@augment-vir/assert';

enum MyEnum {
    A = 'a',
    B = 'b',
}

assert.isNotEnumValue('a', MyEnum); // fails
assert.isNotEnumValue('A', MyEnum); // passes

Throws

AssertionError If the child is an enum member.

See

assert.isEnumValue : the opposite assertion.

isNotFunction

isNotFunction: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, AnyFunction>)

Asserts that a value is not a function.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotFunction(() => {}); // fails
assert.isNotFunction({}); // passes

Throws

AssertionError If the assertion failed.

See

assert.isFunction : the opposite assertion.

isNotIn

isNotIn: (<const Parent, const Child>(child: Child, parent: Parent, failureMessage?: string) => asserts child is Exclude<Child, Values<Parent>>)

Asserts that child value is not contained within a parent object, array, or string through reference equality.

Type guards the child when possible.

Example

import {assert} from '@augment-vir/assert';

const child = {a: 'a'};

assert.isNotIn(child, {child}); // fails
assert.isNotIn('a', 'ab'); // fails
assert.isNotIn(child, [child]); // fails

assert.isNotIn(child, {child: {a: 'a'}}); // passes
assert.isNotIn('a', 'bc'); // passes

Throws

AssertionError If the assertion fails.

See

assert.isIn : the opposite assertion.

isNotInteger

isNotInteger: ((actual: number, failureMessage?: string) => void)

Asserts that a number is not an integer. This has the same limitations, as https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isNotInteger(5); // fails
assert.isNotInteger(5.0000000000000001); // fails
assert.isNotInteger(5.1); // passes
assert.isNotInteger(NaN); // passes

Throws

AssertionError If the assertion fails.

See

assert.isInteger : the opposite assertion.

isNotKeyOf

isNotKeyOf: (<const Key, const Parent>(key: Key, parent: Parent, failureMessage?: string) => asserts key is Exclude<Key, RequiredKeysOf<Parent>>)

Asserts that a key is not contained within a parent value.

Type guards the key.

Example

import {assert} from '@augment-vir/assert';

assert.isNotKeyOf('a', {a: 0, b: 1}); // fails
assert.isNotKeyOf('c', {a: 0, b: 1}); // passes

Throws

AssertionError If the key is in the parent.

See

assert.isKeyOf : the opposite assertion.

isNotNull

isNotNull: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, null>)

Asserts that a value is not exactly null.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotNull(null); // fails
assert.isNotNull(undefined); // passes

Throws

AssertionError If the assertion failed.

See

- assert.isFunction : the opposite assertion.

isNotNumber

isNotNumber: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, number>)

Asserts that a value is not a number. This includes NaN.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotNumber(123); // fails
assert.isNotNumber(123n); // passes

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isNotObject

isNotObject: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, UnknownObject>)

Asserts that a value is not an object. This includes arrays.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotObject({}); // fails
assert.isNotObject([]); // passes

Throws

AssertionError If the assertion failed.

See

assert.isFunction : the opposite assertion.

isNotPrimitive

isNotPrimitive: (<const Actual>(input: Actual, failureMessage?: string) => asserts input is Exclude<Actual, Primitive>)

Asserts that a value is not a JavaScript primitive.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isPrimitive('key'); // fails
assert.isPrimitive(true); // fails
assert.isPrimitive({}); // passes

Throws

AssertionError If the assertion fails.

See

assert.isPrimitive : the opposite assertion.

isNotPromise

isNotPromise: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, Promise<any>>)

Asserts that a value is a not Promise instance.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

class CustomThenable {
    constructor(public value: any) {}

    then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
        return new CustomThenable(onFulfilled ? onFulfilled(this.value) : this.value);
    }
}

assert.isNotPromise(Promise.resolve(5)); // fails
assert.isNotPromise(new CustomThenable(5)); // passes
assert.isNotPromise(5); // passes

Throws

AssertionError If the assertion fails.

See

assert.isPromise : the opposite assertion.
assert.isNotPromiseLike : the more lenient assertion.

isNotPromiseLike

isNotPromiseLike: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, PromiseLike<any>>)

Asserts that a value is not a PromiseLike.

PromiseLike is TypeScript built-in type that has a .then method and thus behaves like a promise. This is also referred to as a "thenable". This enables the use of third-party promise implementations that aren't instances of the built-in Promise class.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

class CustomThenable {
    constructor(public value: any) {}

    then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
        return new CustomThenable(onFulfilled ? onFulfilled(this.value) : this.value);
    }
}

assert.isNotPromiseLike(Promise.resolve(5)); // fails
assert.isNotPromiseLike(new CustomThenable(5)); // fails
assert.isNotPromiseLike(5); // passes

Throws

AssertionError If the assertion fails.

See

assert.isPromiseLike : the opposite assertion.
assert.isNotPromise : the more precise assertion.

isNotPropertyKey

isNotPropertyKey: (<const Actual>(input: Actual, failureMessage?: string) => asserts input is Exclude<Actual, PropertyKey>)

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

import {assert} from '@augment-vir/assert';

assert.isNotPropertyKey('key'); // fails
assert.isNotPropertyKey(true); // passes
assert.isNotPropertyKey({}); // passes

Throws

AssertionError If the assertion fails.

See

assert.isPropertyKey : the opposite assertion.

isNotString

isNotString: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, string>)

Asserts that a value is not a string.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotString(''); // fails
assert.isNotString(5); // passes

Throws

AssertionError If the assertion failed.

See

assert.isFunction : the opposite assertion.

isNotSymbol

isNotSymbol: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, symbol>)

Asserts that a value is not a symbol.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotSymbol(Symbol('my-symbol')); // fails
assert.isNotSymbol('my-symbol'); // passes

Throws

AssertionError If the assertion failed.

See

assert.isFunction : the opposite assertion.

isNotUndefined

isNotUndefined: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, undefined>)

Asserts that a value is not exactly undefined.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNotUndefined(undefined); // fails
assert.isNotUndefined(null); // passes

Throws

AssertionError If the assertion failed.

See

assert.isFunction : the opposite assertion.

isNotUuid

isNotUuid: (<const Actual>(actual: Actual, failureMessage?: string) => asserts actual is Exclude<Actual, `${string}-${string}-${string}-${string}-${string}`>)

Asserts that a value is not a valid UUID. The nil or max UUIDs are included as not valid.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';
import {createUuidV4} from '@augment-vir/common';

assert.isNotUuid(createUuidV4()); // fails
assert.isNotUuid('29e0f18e-6115-4982-8342-0afcadf5d611'); // fails
assert.isNotUuid('00000000-0000-0000-0000-000000000000'); // passes
assert.isNotUuid('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // passes
assert.isNotUuid('not-a-uuid'); // passes

Throws

AssertionError If the assertion fails.

See

assert.isUuid : the opposite assertion.

isNull

isNull: ((actual: unknown, failureMessage?: string) => asserts actual is null)

Asserts that a value is exactly null.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNull(null); // passes
assert.isNull(undefined); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isNullish

isNullish: ((input: unknown, failureMessage?: string) => asserts input is undefined | null)

Asserts that a value is nullish (null or undefined).

Type guards the value.

Type declaration

- (input, failureMessage?): asserts input is undefined | null
- Parameters
  - input: unknown
    The value to check.
  - OptionalfailureMessage: string
    Message to include in error message if this assertion fails.
  Returns asserts input is undefined | null

Example

import {assert} from '@augment-vir/assert';

assert.isNullish(0); // fails
assert.isNullish(''); // fails
assert.isNullish(null); // passes
assert.isNullish(undefined); // passes

Throws

AssertionError If the assertion fails.

See

assert.isDefined : the opposite assertion.

isNumber

isNumber: ((actual: unknown, failureMessage?: string) => asserts actual is number)

Asserts that a value is a number. This excludes NaN.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isNumber(123); // passes
assert.isNumber(123n); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isObject

isObject: ((actual: unknown, failureMessage?: string) => asserts actual is UnknownObject)

Asserts that a value is an object. This excludes arrays.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isObject({}); // passes
assert.isObject([]); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isOutBounds

isOutBounds: ((actual: number, __namedParameters: MinMax, failureMessage?: string) => void)

Asserts that a number is outside the provided min and max bounds, exclusive.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.isOutBounds(5, {min: 1, max: 10}); // fails
assert.isOutBounds(10, {min: 1, max: 10}); // fails
assert.isOutBounds(11, {min: 1, max: 10}); // passes
assert.isOutBounds(0, {min: 1, max: 10}); // passes

Throws

AssertionError If the assertion fails.

See

assert.isInBounds : the opposite assertion.

isPrimitive

isPrimitive: ((input: unknown, failureMessage?: string) => asserts input is Primitive)

Asserts that a value is a JavaScript primitive.

Type guards the value.

Type declaration

- (input, failureMessage?): asserts input is Primitive
- Asserts that the given value is a primitive.
  Parameters
  - input: unknown
  - OptionalfailureMessage: string
  Returns asserts input is Primitive

Example

import {assert} from '@augment-vir/assert';

assert.isPrimitive('key'); // passes
assert.isPrimitive(true); // passes
assert.isPrimitive({}); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotPrimitive : the opposite assertion.

isPromise

isPromise: ((actual: unknown, failureMessage?: string) => asserts actual is Promise<any>)

Asserts that a value is a Promise instance.

Type guards the value.

Type declaration

- (actual, failureMessage?): asserts actual is Promise<any>
- Checks if a value is an actual Promise object. In reality this is just a simple wrapper for instanceof Promise, but it makes checking a bit more ergonomic.
  Parameters
  - actual: unknown
  - OptionalfailureMessage: string
  Returns asserts actual is Promise<any>

Example

import {assert} from '@augment-vir/assert';

class CustomThenable {
    constructor(public value: any) {}

    then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
        return new CustomThenable(onFulfilled ? onFulfilled(this.value) : this.value);
    }
}

assert.isPromise(Promise.resolve(5)); // passes
assert.isPromise(new CustomThenable(5)); // fails
assert.isPromise(5); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotPromise : the opposite assertion.
assert.isPromiseLike : the more lenient assertion.

isPromiseLike

isPromiseLike: ((actual: unknown, failureMessage?: string) => asserts actual is PromiseLike<any>)

Asserts that a value is a PromiseLike.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

class CustomThenable {
    constructor(public value: any) {}

    then(onFulfilled?: AnyFunction, onRejected?: AnyFunction) {
        return new CustomThenable(onFulfilled ? onFulfilled(this.value) : this.value);
    }
}

assert.isPromiseLike(Promise.resolve(5)); // passes
assert.isPromiseLike(new CustomThenable(5)); // passes
assert.isPromiseLike(5); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotPromiseLike : the opposite assertion.
assert.isPromise : the more precise assertion.

isPropertyKey

isPropertyKey: ((input: unknown, failureMessage?: string) => asserts input is PropertyKey)

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.

Type declaration

- (input, failureMessage?): asserts input is PropertyKey
- Asserts that the given value is a PropertyKey ( string | number | symbol).
  Parameters
  - input: unknown
  - OptionalfailureMessage: string
  Returns asserts input is PropertyKey

Example

import {assert} from '@augment-vir/assert';

assert.isPropertyKey('key'); // passes
assert.isPropertyKey(true); // fails
assert.isPropertyKey({}); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotPropertyKey : the opposite assertion.

isString

isString: ((actual: unknown, failureMessage?: string) => asserts actual is string)

Asserts that a value is a string.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isString(''); // passes
assert.isString(5); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isSymbol

isSymbol: ((actual: unknown, failureMessage?: string) => asserts actual is symbol)

Asserts that a value is a symbol.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isSymbol(Symbol('my-symbol')); // passes
assert.isSymbol('my-symbol'); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isTrue

isTrue: ((input: unknown, failureMessage?: string) => asserts input is true)

Asserts that a value is exactly true.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isTrue(true); // passes
assert.isTrue(false); // fails
assert.isTrue(1); // fails
assert.isTrue(0); // fails

Throws

AssertionError If the value is not true.

See

assert.isFalse : the opposite assertion.
assert.isTruthy : a less exact assertion.

isTruthy

isTruthy: (<const Actual>(input: Actual, failureMessage?: string) => asserts input is Exclude<Actual, FalsyValue>)

Asserts that a value is truthy.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isTruthy(true); // passes
assert.isTruthy(false); // fails
assert.isTruthy(1); // passes
assert.isTruthy(0); // fails

Throws

AssertionError If the value is not truthy.

See

assert.isFalsy : the opposite assertion.
assert.isTrue : a more exact assertion.

isUndefined

isUndefined: ((actual: unknown, failureMessage?: string) => asserts actual is undefined)

Asserts that a value is exactly undefined.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.isUndefined(undefined); // passes
assert.isUndefined(null); // fails

Throws

AssertionError If the assertion failed.

See

assert.isNotFunction : the opposite assertion.

isUuid

isUuid: ((actual: unknown, failureMessage?: string) => asserts actual is `${string}-${string}-${string}-${string}-${string}`)

Asserts that a value is a valid UUID. Does not accept the nil or max UUIDs.

Type guards the value.

Type declaration

- (actual, failureMessage?): asserts actual is `${string}-${string}-${string}-${string}-${string}`
- Checks if the input string is a valid v4 UUID.
  Parameters
  - actual: unknown
  - OptionalfailureMessage: string
  Returns asserts actual is `${string}-${string}-${string}-${string}-${string}`

Example

import {assert} from '@augment-vir/assert';
import {createUuidV4} from '@augment-vir/common';

assert.isUuid(createUuidV4()); // passes
assert.isUuid('29e0f18e-6115-4982-8342-0afcadf5d611'); // passes
assert.isUuid('00000000-0000-0000-0000-000000000000'); // fails
assert.isUuid('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // fails
assert.isUuid('not-a-uuid'); // fails

Throws

AssertionError If the assertion fails.

See

assert.isNotUuid : the opposite assertion.

jsonEquals

jsonEquals: (<const Actual, const Expected>(actual: Actual, expected: Expected, failureMessage?: string) => asserts actual is Expected)

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

import {assert} from '@augment-vir/assert';

assert.jsonEquals({a: 'a'}, {a: 'a'}); // passes

assert.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // fails

Throws

AssertionError If both inputs are not equal.

See

assert.notJsonEquals : the opposite assertion.
assert.entriesEqual : another deep equality assertion.
assert.deepEquals : the most thorough (but also slow) deep equality assertion.

lacksKey

lacksKey: (<const Parent, const Key>(parent: Parent, key: Key, failureMessage?: string) => asserts parent is Exclude<Parent, Record<Key, any>>)

Asserts that a parent value does not have the key.

Type guards the parent value.

Example

import {assert} from '@augment-vir/assert';

assert.lacksKey({a: 0, b: 1}, 'a'); // fails
assert.lacksKey({a: 0, b: 1}, 'c'); // passes

Throws

AssertionError If the parent has the key.

See

assert.hasKey : the opposite assertion.
assert.lacksKeys : the multi-key assertion.

lacksKeys

lacksKeys: (<const Parent, const Key>(parent: Parent, keys: readonly Key[], failureMessage?: string) => asserts parent is Exclude<Parent, Partial<Record<Key, any>>>)

Asserts that a parent value none of the keys.

Type guards the parent value.

Example

import {assert} from '@augment-vir/assert';

assert.lacksKeys({a: 0, b: 1}, [
    'b',
    'c',
]); // fails
assert.lacksKeys({a: 0, b: 1}, [
    'c',
    'd',
]); // passes

Throws

AssertionError If the parent has any of the keys.

See

assert.hasKeys : the opposite assertion.
assert.lacksKey : the single-key assertion.

lacksValue

lacksValue: ((parent: object, value: unknown, failureMessage?: string) => void)

Asserts that an object/array parent does not include a child value through reference equality.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

const child = {a: 'a'};

assert.lacksValue({child}, child); // fails
assert.lacksValue({child: {a: 'a'}}, child); // passes
assert.lacksValue([child], child); // fails

Throws

AssertionError If the assertion fails.

See

assert.hasValue : the opposite assertion.
assert.lacksValues : the multi-value assertion.

lacksValues

lacksValues: ((parent: object, values: readonly unknown[], failureMessage?: string) => void)

Asserts that an object/array parent includes none of the provided child values through reference equality.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

const child = {a: 'a'};
const child2 = {b: 'b'};

assert.lacksValues({}, [
    child,
    child2,
]); // passes
assert.lacksValues({child, child2}, [
    child,
    child2,
]); // fails
assert.lacksValues({child: {a: 'a'}, child2}, [
    child,
    child2,
]); // fails

Throws

AssertionError If the assertion fails.

See

assert.lacksValues : the opposite assertion.
assert.hasValue : the single-value assertion.

looseEquals

looseEquals: ((actual: unknown, expected: unknown, failureMessage?: string) => void)

Asserts that two values are loosely equal (using ==).

Type guards the first value.

Example

import {assert} from '@augment-vir/assert';

assert.looseEquals('a', 'a'); // passes

assert.looseEquals('1', 1); // passes

assert.looseEquals({a: 'a'}, {a: 'a'}); // fails

const objectExample = {a: 'a'};
assert.looseEquals(objectExample, objectExample); // passes

Throws

AssertionError If both inputs are not loosely equal.

See

assert.notLooseEquals : the opposite assertion.
assert.strictEquals : the strict equality assertion.

matches

matches: ((actual: string, expected: RegExp, failureMessage?: string) => void)

Asserts that a string (first input, actual) matches a RegExp (second input, expected).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.matches('hi', /^h/); // passes
assert.matches('hi', /^g/); // fails

Throws

AssertionError If the assertion fails.

See

assert.mismatches : the opposite assertion.

mismatches

mismatches: ((actual: string, expected: RegExp, failureMessage?: string) => void)

Asserts that a string (first input, actual) does not match a RegExp (second input, expected).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.mismatches('hi', /^h/); // fails
assert.mismatches('hi', /^g/); // passes

Throws

AssertionError If the assertion fails.

See

assert.matches : the opposite assertion.

notDeepEquals

notDeepEquals: ((actual: unknown, expected: unknown, failureMessage?: string) => void)

Asserts that two values are not deeply equal using the deep-eql package.

Note that this check may be expensive, depending on what values it is passed. Whenever possible, use simpler equality checks instead (see the see section below).

Type guards the first value.

Example

import {assert} from '@augment-vir/assert';

assert.deepEquals('a', 'a'); // false

assert.deepEquals('1', 1); // passes

assert.deepEquals({a: 'a'}, {a: 'a'}); // fails

const objectExample = {a: 'a'};
assert.deepEquals(objectExample, objectExample); // fails

Throws

AssertionError If both inputs are deeply equal.

See

assert.notDeepEquals : the opposite assertion.
assert.entriesEqual : a less expensive (but less thorough) deep equality assertion.
assert.jsonEquals : a less expensive (but less thorough) deep equality assertion.

notEntriesEqual

notEntriesEqual: ((actual: object, expected: object, failureMessage?: string) => void)

Asserts that two objects are not deeply equal by checking only their top-level values for strict (non-deep, reference, using ===) equality.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.notEntriesEqual({a: 'a'}, {a: 'a'}); // fails

assert.notEntriesEqual({a: {b: 'b'}}, {a: {b: 'b'}}); // passes

const bExample = {b: 'b'};
assert.notEntriesEqual({a: bExample}, {a: bExample}); // fails

Throws

AssertionError If both inputs are equal.

See

assert.entriesEqual : the opposite assertion.
assert.notJsonEquals : another not deep equality assertion.
assert.notDeepEquals : the most thorough (but also slow) not deep equality assertion.

notInstanceOf

notInstanceOf: (<const Actual, const Instance>(instance: Actual, constructor: Constructor<Instance>, failureMessage?: string) => asserts instance is Exclude<Actual, Instance>)

Asserts that a value is not an instance of the given class constructor.

Type guards the value.

Example

import {assert} from '@augment-vir/assert';

assert.notInstanceOf(/abc/, RegExp); // fails
assert.notInstanceOf('abc', RegExp); // passes

Throws

AssertionError If the value is an instance of the given class constructor.

See

assert.instanceOf : the opposite assertion.

notJsonEquals

notJsonEquals: ((actual: unknown, expected: unknown, failureMessage?: string) => void)

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

import {assert} from '@augment-vir/assert';

assert.notJsonEquals({a: 'a'}, {a: 'a'}); // fails

assert.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // passes

Throws

AssertionError If both inputs are not equal.

See

assert.jsonEquals : the opposite assertion.
assert.entriesEqual : another deep equality assertion.
assert.deepEquals : the most thorough (but also slow) deep equality assertion.

notLooseEquals

notLooseEquals: ((actual: unknown, expected: unknown, failureMessage?: string) => void)

Asserts that two values are not loosely equal (using ==).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.notLooseEquals('a', 'a'); // fails

assert.notLooseEquals('1', 1); // fails

assert.notLooseEquals({a: 'a'}, {a: 'a'}); // passes

const objectExample = {a: 'a'};
assert.notLooseEquals(objectExample, objectExample); // fails

Throws

AssertionError If both inputs are loosely equal.

See

assert.looseEquals : the opposite assertion.
assert.strictEquals : the strict equality assertion.

notStrictEquals

notStrictEquals: ((actual: unknown, expected: unknown, failureMessage?: string) => void)

Asserts that two values are not strictly equal (using ===).

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.notStrictEquals('a', 'a'); // fails

assert.notStrictEquals('1', 1); // passes

assert.notStrictEquals({a: 'a'}, {a: 'a'}); // passes

const objectExample = {a: 'a'};
assert.notStrictEquals(objectExample, objectExample); // fails

Throws

AssertionError If both inputs are strictly equal.

See

assert.strictEquals : the opposite assertion.
assert.notLooseEquals : the loose equality assertion.

output

output: {
<const FunctionToCall>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string): OutputReturn<NoInfer<FunctionToCall>, void>;
<const FunctionToCall>(asserter: CustomOutputAsserter<NoInfer<FunctionToCall>>, functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string): OutputReturn<NoInfer<FunctionToCall>, void>;
}

Asserts that the output of the given function deeply equals expectations. A custom asserter can optionally be provided as the first argument to change the expectation checking from "deeply equals" to whatever you want.

Performs no type guarding.

import {assert} from '@augment-vir/assert';

assert.output((input: number) => String(input), [5], '5'); // passes
assert.output((input: number) => String(input), [10], '5'); // fails

assert.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // fails
assert.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // passes

Throws

AssertionError If the assertion fails.

startsWith

startsWith: {
    <const ArrayElement>(parent: readonly ArrayElement[], child: ArrayElement, failureMessage?: string): void;
    (parent: string, child: string, failureMessage?: string): void;
    (parent: string | readonly string[], child: string, failureMessage?: string): void;
}

Asserts that a parent string or array starts with a specific child. This uses reference equality when the parent is an array.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.startsWith('ab', 'b'); // fails
assert.startsWith('ab', 'a'); // passes
assert.startsWith(
    [
        'a',
        'b',
    ],
    'b',
); // fails
assert.startsWith(
    [
        'a',
        'b',
    ],
    'a',
); // passes

Throws

AssertionError If the parent does not start with the child.

See

assert.startsWithout : the opposite assertion.
assert.endsWith : assertion on the other end.

startsWithout

startsWithout: {
    <const ArrayElement>(parent: readonly ArrayElement[], child: ArrayElement, failureMessage?: string): void;
    (parent: string, child: string, failureMessage?: string): void;
    (parent: string | readonly string[], child: string, failureMessage?: string): void;
}

Asserts that a parent string or array starts with a specific child. This uses reference equality when the parent is an array.

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.startsWith('ab', 'b'); // passes
assert.startsWith('ab', 'a'); // fails
assert.startsWith(
    [
        'a',
        'b',
    ],
    'b',
); // passes
assert.startsWith(
    [
        'a',
        'b',
    ],
    'a',
); // fails

Throws

AssertionError If the parent does start with the child.

See

assert.startsWithout : the opposite assertion.
assert.endsWith : assertion on the other end.

strictEquals

strictEquals: (<const Actual, const Expected>(actual: Actual, expected: Expected, failureMessage?: string) => asserts actual is Expected)

Asserts that two values are strictly equal (using ===).

Type guards the first value.

Example

import {assert} from '@augment-vir/assert';

assert.strictEquals('a', 'a'); // passes

assert.strictEquals('1', 1); // fails

assert.strictEquals({a: 'a'}, {a: 'a'}); // fails

const objectExample = {a: 'a'};
assert.strictEquals(objectExample, objectExample); // passes

Throws

AssertionError If both inputs are not strictly equal.

See

assert.notStrictEquals : the opposite assertion.
assert.looseEquals : the loose equality assertion.

throws

throws: {
    (callbackOrPromise: (() => never), matchOptions?: PartialWithNullable<{
        matchConstructor: ErrorConstructor | (new (...args: any[]) => Error);
        matchMessage: string | RegExp;
    }>, failureMessage?: string): void;
    (callbackOrPromise: Promise<any> | (() => Promise<any>), matchOptions?: PartialWithNullable<{
        matchConstructor: ErrorConstructor | (new (...args: any[]) => Error);
        matchMessage: string | RegExp;
    }>, failureMessage?: string): Promise<void>;
    (callback: (() => any), matchOptions?: PartialWithNullable<{
        matchConstructor: ErrorConstructor | (new (...args: any[]) => Error);
        matchMessage: string | RegExp;
    }>, failureMessage?: string): void;
    (callback: Promise<any> | (() => any), matchOptions?: PartialWithNullable<{
        matchConstructor: ErrorConstructor | (new (...args: any[]) => Error);
        matchMessage: string | RegExp;
    }>, failureMessage?: string): MaybePromise<void>;
}

If a function input is provided:

Calls that function and asserts that the function throw an error, comparing the error with the given ErrorMatchOptions, if provided.

If a promise is provided:

Awaits the promise and asserts that the promise rejected with an error, comparing the error with the given ErrorMatchOptions, if provided.

This assertion will automatically type itself as async vs async based on the input. (A promise or async function inputs results in async. Otherwise, sync.)

Performs no type guarding.

Example

import {assert} from '@augment-vir/assert';

assert.throws(() => {
    throw new Error();
}); // passes
assert.throws(
    () => {
        throw new Error();
    },
    {matchMessage: 'hi'},
); // fails
await assert.throws(Promise.reject()); // passes
assert.throws(() => {}); // fails

Throws

AssertionError If the assertion fails.

tsType

tsType: {
<Actual>(input: Actual): AssertTypeOf<Actual>;
<Actual>(): AssertTypeOf<Actual>;
}

Asserts within the TypeScript type system that a given type or value matches type expectations (using the expect-type package. Make sure to call a method on the first call to actually assert anything.

Use this to write type tests. Don't use this in production code. It won't cause issues, but it's a useless no-op at run-time (it's not even a type guard).

Performs no type guarding.

Type declaration

- <Actual>(input): AssertTypeOf<Actual>
- Type Parameters
  - Actual
  Parameters
  - input: Actual
    Run-time value to type check.
  Returns AssertTypeOf<Actual>
- <Actual>(): AssertTypeOf<Actual>
- Uses the expect-type package to assert type matching.
  Type Parameters
  - Actual
  Returns AssertTypeOf<Actual>

Example

import {assert} from '@augment-vir/assert';

assert.tsType('hello').equals<string>();
assert.tsType<'hello>().equals<'hello'>();
assert.tsType<'hello>().notEquals<string>();
assert.tsType('hello').notEquals<number>();

Returns

Never returns anything.

Throws

Never throws anything.

Function assert

Example

Throws

Package

Parameters

Returns void

Index

Properties

Properties

deepEquals

Example

Throws

See

endsWith

Example

Throws

See

endsWithout

Example

Throws

See

entriesEqual

Example

Throws

See

fail

Example

Throws

hasKey

Type declaration

Type Parameters

Parameters

Returns asserts parent is CombineTypeWithKey<Key, Parent>

Example

Throws

See

hasKeys

Type declaration

Type Parameters

Parameters

Returns asserts parent is CombineTypeWithKey<Keys, Parent>

Example

Throws

See

hasValue

Example

Throws

See

hasValues

Example

Throws

See

instanceOf

Type declaration

Type Parameters

Parameters

Returns asserts instance is Instance

Example

Throws

See

isAbove

Example

Throws

See

isApproximately

Example

Throws

See

isArray

Example

Throws

See

isAtLeast

Example

Throws

See

isAtMost

Example

Throws

See