Function assertWrap

A group of guard methods that do the following:

  1. Run the method's assertion on the given inputs.
  2. If the assertion fails, throws an error.
  3. If the assertion succeeds, the first input is returned and (when possible) type guarded.

This can also be called as a standalone assertion function which asserts that its input is truthy and returns it if so.

Example

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

// `result1` will be `['a']`
const result1 = assertWrap.deepEquals(['a'], ['a']);

const value: unknown = 'some value' as unknown;
// `result2` will be `'some value'` and it will have the type of `string`
const result2 = assertWrap.isString(value);

const value2: unknown = 'some value' as unknown;
// this will throw an error
const result3 = assertWrap.isNumber(value2);

Throws

AssertionError When the assertion fails.

Package

@augment-vir/assert

Properties

deepEquals endsWith endsWithout entriesEqual 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

Properties

deepEquals

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

Asserts that two values are deeply equal using the deep-eql package. Returns the first value if the assertion passes.

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 {assertWrap} from '@augment-vir/assert';

assertWrap.deepEquals('a', 'a'); // returns `'a'`

assertWrap.deepEquals('1', 1); // throws an error

assertWrap.deepEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`

const objectExample = {a: 'a'};
assertWrap.deepEquals(objectExample, objectExample); // returns `{a: 'a'}`

Throws

AssertionError If both inputs are not deeply equal.

See

endsWith

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

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

Performs no type guarding.

Example

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

assertWrap.endsWith('ab', 'b'); // returns `'ab'`
assertWrap.endsWith('ab', 'a'); // throws an error
assertWrap.endsWith(
    [
        'a',
        'b',
    ],
    'b',
); // returns `['a', 'b']`
assertWrap.endsWith(
    [
        'a',
        'b',
    ],
    'a',
); // throws an error

Returns

The parent value if it does end with the child.

Throws

AssertionError If the parent does not end with the child.

See

endsWithout

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

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

Performs no type guarding.

Example

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

assertWrap.endsWithout('ab', 'b'); // throws an error
assertWrap.endsWithout('ab', 'a'); // returns `'ab'`
assertWrap.endsWithout(
    [
        'a',
        'b',
    ],
    'b',
); // throws an error
assertWrap.endsWithout(
    [
        'a',
        'b',
    ],
    'a',
); // returns `['a', 'b']`

Returns

The parent value if it does not end with the child.

Throws

AssertionError If the parent ends with the child.

See

entriesEqual

entriesEqual: (<Actual, Expected>(actual: Actual, expected: Expected, failureMessage?: string) => NarrowToExpected<Actual, Expected>) = ...

Asserts that two objects are deeply equal by checking only their top-level values for strict (non-deep, reference, using ===) equality and, if so, returns the first object.

Type guards the first value.

Type declaration

Example

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

assertWrap.entriesEqual({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`

assertWrap.entriesEqual({a: {b: 'b'}}, {a: {b: 'b'}}); // throws an error

const bExample = {b: 'b'};
assertWrap.entriesEqual({a: bExample}, {a: bExample}); // returns `{a: {b: 'b'}}`

Throws

AssertionError If both inputs are not equal.

See

hasKey

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

Asserts that a parent value has the key. Returns the parent if the assertion passes.

Type guards the parent value.

Type declaration

    • <const Parent, const Key>(parent, key, failureMessage?): CombineTypeWithKey<Key, Parent>

    • Type Parameters

      • const Parent
      • const Key extends PropertyKey

      Parameters

      • parent: Parent
      • key: Key
      • OptionalfailureMessage: string

      Returns CombineTypeWithKey<Key, Parent>

      The parent if it has the key.

Example

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

assertWrap.hasKey({a: 0, b: 1}, 'a'); // returns `{a: 0, b: 1}`
assertWrap.hasKey({a: 0, b: 1}, 'c'); // throws an error

Throws

AssertionError If the parent does not have the key.

See

hasKeys

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

Asserts that a parent value has all the keys. Returns the parent if the assertion passes.

Type guards the parent value.

Type declaration

    • <const Keys, const Parent>(parent, keys, failureMessage?): CombineTypeWithKey<Keys, Parent>

    • Type Parameters

      • const Keys extends PropertyKey
      • const Parent

      Parameters

      • parent: Parent
      • keys: readonly Keys[]
      • OptionalfailureMessage: string

      Returns CombineTypeWithKey<Keys, Parent>

      The parent if it has all the keys.

Example

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

assertWrap.hasKeys({a: 0, b: 1}, [
    'a',
    'b',
]); // returns `{a: 0, b: 1}`
assertWrap.hasKeys({a: 0, b: 1}, [
    'b',
    'c',
]); // throws an error

Throws

AssertionError If the parent does not have all the keys.

See

hasValue

hasValue: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that an object/array parent includes a child value through reference equality. Returns the parent value if the assertion passes.

Performs no type guarding.

Example

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

const child = {a: 'a'};

assertWrap.hasValue({child}, child); // returns `{child}`;
assertWrap.hasValue({child: {a: 'a'}}, child); // throws an error
assertWrap.hasValue([child], child); // returns `[child]`;

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

hasValues

hasValues: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that an object/array parent includes all child values through reference equality. Returns the parent value if the assertion passes.

Performs no type guarding.

Example

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

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

assertWrap.hasValues({child, child2}, [
    child,
    child2,
]); // returns `{child, child2}`;
assertWrap.hasValues({child: {a: 'a'}, child2}, [
    child,
    child2,
]); // throws an error
assertWrap.hasValues(
    [child],
    [
        child,
        child2,
    ],
); // returns `[child]`;

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

instanceOf

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

Asserts that a value is an instance of the given class constructor. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.instanceOf(/abc/, RegExp); // returns `/abc/`
assertWrap.instanceOf('abc', RegExp); // throws an error

Throws

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

See

isAbove

isAbove: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is above the expectation (actual > expected). Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isAbove(10, 5); // returns `10`
assertWrap.isAbove(5, 5); // throws an error
assertWrap.isAbove(5, 10); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isApproximately

isApproximately: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is within ±delta of the expectation. Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isApproximately(10, 8, 4); // returns `10`
assertWrap.isApproximately(10, 12, 4); // returns `10`
assertWrap.isApproximately(10, 8, 1); // throws an error
assertWrap.isApproximately(10, 12, 1); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isArray

isArray: (<Actual>(actual: Actual) => ArrayNarrow<Actual>) = ...

Asserts that a value is an array. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <Actual>(actual): ArrayNarrow<Actual>

    • Type Parameters

      • Actual

      Parameters

      Returns ArrayNarrow<Actual>

      The value if the assertion passes.

Example

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

assertWrap.isArray([]); // returns `[]`
assertWrap.isArray({length: 4}); // throws an error

Throws

AssertionError If the assertion failed.

See

isAtLeast

isAtLeast: AssertWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

assertWrap.isAtLeast(10, 5); // returns `10`
assertWrap.isAtLeast(5, 5); // returns `5`
assertWrap.isAtLeast(5, 10); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isAtMost

isAtMost: AssertWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

assertWrap.isAtMost(10, 5); // throws an error
assertWrap.isAtMost(5, 5); // returns `5`
assertWrap.isAtMost(5, 10); // returns `5`

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isBelow

isBelow: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is below the expectation (actual < expected). Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isBelow(10, 5); // throws an error
assertWrap.isBelow(5, 5); // throws an error
assertWrap.isBelow(5, 10); // returns `5`

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isBigInt

isBigInt: AssertWrapFunction<bigint> = autoGuardSymbol

Asserts that a value is a BigInt. Returns the value if the assertion passes.

Type guards the value.

Example

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

AssertionError If the assertion failed.

See

isBoolean

isBoolean: AssertWrapFunction<boolean> = autoGuardSymbol

Asserts that a value is a boolean. Returns the value if the assertion passes.

Type guards the value.

Example

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

AssertionError If the assertion failed.

See

isDefined

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

Asserts that a value is defined (not null and not undefined). Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <Actual>(input, failureMessage?): Exclude<Actual, undefined | null>

    • Type Parameters

      • Actual

      Parameters

      • input: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, undefined | null>

      The value if the assertion passes.

Example

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

assertWrap.isDefined(0); // returns `0`
assertWrap.isDefined(''); // returns `''`
assertWrap.isDefined(null); // fails
assertWrap.isDefined(undefined); // fails

Throws

AssertionError If the assertion fails.

See

isEmpty

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

Asserts that a value is empty. Supports strings, Maps, Sets, objects, and arrays. Returns the value if the assertion passes.

Type guards the value.

Type declaration

Example

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

assertWrap.isEmpty({}); // returns `{}`;
assertWrap.isEmpty(''); // returns `''`;
assertWrap.isEmpty([]); // returns `[]`;

assertWrap.isEmpty('a'); // throws an error
assertWrap.isEmpty({a: 'a'}); // throws an error

Throws

AssertionError If the assertion fails.

See

isEnumValue

isEnumValue: (<const Actual, const Expected>(child: Actual, checkEnum: Expected, failureMessage?: string) => NarrowToExpected<Actual, Expected[keyof Expected]>) = ...

Asserts that a child value is an enum member. Returns the child value if the assertion passes.

Type guards the child value.

Type declaration

Example

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

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

assertWrap.isEnumValue('a', MyEnum); // returns `'a'`
assertWrap.isEnumValue('A', MyEnum); // throws an error

Throws

AssertionError If the child is not an enum member.

See

isError

isError: AssertWrapFunction<Error> = autoGuardSymbol

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 {assertWrap} from '@augment-vir/assert';

assertWrap.isError(new Error()); // returns the error instance
assertWrap.isError(new Error(), {matchMessage: 'hi'}); // throws an error
assertWrap.isError({message: 'not an error'}); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

isFalse

isFalse: AssertWrapFunction<false> = autoGuardSymbol

Asserts that a value is exactly false. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isFalse(true); // throws an error
assertWrap.isFalse(false); // returns `false`
assertWrap.isFalse(1); // throws an error
assertWrap.isFalse(0); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the value is not false.

See

isFalsy

isFalsy: (<T>(input: T, failureMessage?: string) => NarrowToExpected<T, FalsyValue>) = ...

Asserts that a value is falsy. Returns the value if the assertion passes.

Type guards the value when possible.

Type declaration

Example

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

assertWrap.isFalsy(true); // throws an error
assertWrap.isFalsy(false); // returns `false`
assertWrap.isFalsy(1); // throws an error
assertWrap.isFalsy(0); // returns `0`

Throws

AssertionError If the value is not falsy.

See

isFinite

isFinite: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is finite: meaning, not NaN and not Infinity or -Infinity. Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isFinite(10); // returns `10`
assertWrap.isFinite(parseInt('invalid')); // throws an error
assertWrap.isFinite(Infinity); // throws an error
assertWrap.isFinite(-Infinity); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isFunction

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

Asserts that a value is a function. Returns the value if the assertion passes.

Type guards the value.

Type declaration

Example

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

assertWrap.isFunction(() => {}); // returns `() => {}`
assertWrap.isFunction({}); // throws an error

Throws

AssertionError If the assertion failed.

See

isHttpStatus

isHttpStatus: AssertWrapFunction<HttpStatus> = autoGuardSymbol

Asserts that a value is an HttpStatus. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isHttpStatus(400); // returns `400`
assertWrap.isHttpStatus(500); // returns `500`
assertWrap.isHttpStatus(99); // throws an error

Throws

AssertionError If the value is not an HttpStatus.

See

isHttpStatusCategory

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

Checks that a value is an HttpStatus within a specific HttpStatusCategory. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `400`
assertWrap.isHttpStatusCategory(500, HttpStatusCategory.Success); // throws an error
assertWrap.isHttpStatusCategory(99, HttpStatusCategory.Information); // throws an error

See

isIn

isIn: (<const Child, const Parent>(child: Child, parent: Parent, failureMessage?: string) => NarrowToExpected<Child, Values<Parent>>) = ...

Asserts that child value is contained within a parent object, array, or string through reference equality. Returns the child value if the assertion passes.

Type guards the child when possible.

Type declaration

Example

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

const child = {a: 'a'};

assertWrap.isIn(child, {child}); // returns `child`;
assertWrap.isIn('a', 'ab'); // returns `'a'`;
assertWrap.isIn(child, [child]); // returns `child`;

assertWrap.isIn(child, {child: {a: 'a'}}); // throws an error
assertWrap.isIn('a', 'bc'); // throws an error

Throws

AssertionError If the assertion fails.

See

isInBounds

isInBounds: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is inside the provided min and max bounds, inclusive. Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isInBounds(5, {min: 1, max: 10}); // returns `5`
assertWrap.isInBounds(10, {min: 1, max: 10}); // returns `10`
assertWrap.isInBounds(11, {min: 1, max: 10}); // fails
assertWrap.isInBounds(0, {min: 1, max: 10}); // fails

Throws

AssertionError If the assertion fails.

See

isInfinite

isInfinite: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is either Infinity or -Infinity. Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isInfinite(10); // throws an error
assertWrap.isInfinite(parseInt('invalid')); // throws an error
assertWrap.isInfinite(Infinity); // returns `Infinity`
assertWrap.isInfinite(-Infinity); // returns `-Infinity`

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isInteger

isInteger: AssertWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

assertWrap.isInteger(5); // returns `5`
assertWrap.isInteger(5.0000000000000001); // returns `5`
assertWrap.isInteger(5.1); // fails
assertWrap.isInteger(NaN); // fails

Throws

AssertionError If the assertion fails.

See

isKeyOf

isKeyOf: (<const Key, const Parent>(key: Key, parent: Parent, failureMessage?: string) => NarrowToExpected<Key, keyof Parent>) = ...

Asserts that a key is contained within a parent value. Returns the key if the assertion passes.

Type guards the key.

Type declaration

Example

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

assertWrap.isKeyof('a', {a: 0, b: 1}); // returns `'a'`
assertWrap.isKeyof('c', {a: 0, b: 1}); // throws an error

Throws

AssertionError If the key is not in the parent.

See

isLengthAtLeast

isLengthAtLeast: {
    <Element, Length>(actual: readonly (undefined | Element)[], length: Length): AtLeastTuple<Element, Length>;
    <Actual>(actual: Actual, length: number): Actual;
} = ...

Asserts that an array or string has at least the given length. Returns the value if the assertion passes.

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

Example

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

assertWrap.isLengthAtLeast(
    [
        'a',
        'b',
        'c',
    ],
    2,
); // returns `['a', 'b', 'c']`
assertWrap.isLengthAtLeast(
    [
        'a',
        'b',
        'c',
    ],
    3,
); // returns `['a', 'b', 'c']`
assertWrap.isLengthAtLeast(
    [
        'a',
        'b',
    ],
    3,
); // throws an error

Returns

The value if it has at least the given length.

Throws

AssertionError If the value is less than the given length.

See

isLengthExactly

isLengthExactly: {
    <Element, Length>(actual: readonly (undefined | Element)[], length: Length): Tuple<Element, Length>;
    <Actual>(actual: Actual, length: number): Actual;
} = ...

Asserts that an array or string has exactly the given length. Returns the value if the assertion passes.

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

Example

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

assertWrap.isLengthExactly(
    [
        'a',
        'b',
        'c',
    ],
    2,
); // throws an error
assertWrap.isLengthExactly(
    [
        'a',
        'b',
        'c',
    ],
    3,
); // returns `['a', 'b', 'c']`
assertWrap.isLengthExactly(
    [
        'a',
        'b',
    ],
    3,
); // throws an error

Returns

The value if it has exactly the given length.

Throws

AssertionError If the value is not exactly the given length.

See

isNaN

isNaN: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is NaN. Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isNaN(10); // throws an error
assertWrap.isNaN(parseInt('invalid')); // returns `NaN`
assertWrap.isNaN(Infinity); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isNotApproximately

isNotApproximately: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is outside ±delta of the expectation. Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isNotApproximately(10, 8, 4); // throws an error
assertWrap.isNotApproximately(10, 12, 4); // throws an error
assertWrap.isNotApproximately(10, 8, 1); // returns `10`
assertWrap.isNotApproximately(10, 12, 1); // returns `10`

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isNotArray

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

Asserts that a value is not an array. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(actual, failureMessage?): Exclude<Actual, readonly unknown[]>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, readonly unknown[]>

      The value if the assertion passes.

Example

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

assertWrap.isNotArray([]); // throws an error
assertWrap.isNotArray({length: 4}); // returns `{length: 4}`

Throws

AssertionError If the assertion failed.

See

isNotBigInt

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

Asserts that a value is not a BigInt. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(actual, failureMessage?): Exclude<Actual, bigint>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, bigint>

      The value if the assertion passes.

Example

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

assertWrap.isNotBigInt(123n); // throws an error
assertWrap.isNotBigInt(123); // returns `123`

Throws

AssertionError If the assertion failed.

See

isNotBoolean

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

Asserts that a value is not a boolean. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(actual, failureMessage?): Exclude<Actual, boolean>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, boolean>

      The value if the assertion passes.

Example

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

assertWrap.isNotBoolean(true); // throws an error
assertWrap.isNotBoolean('true'); // returns `'true'`

Throws

AssertionError If the assertion failed.

See

isNotEmpty

isNotEmpty: (<const Actual>(actual: Actual) => Exclude<Actual, Empty>) = ...

Asserts that a value is not empty. Supports strings, Maps, Sets, objects, and arrays. Returns the value if the assertion passes.

Type guards the value.

Type declaration

Example

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

assertWrap.isNotEmpty({}); // throws an error
assertWrap.isNotEmpty(''); // throws an error
assertWrap.isNotEmpty([]); // throws an error

assertWrap.isNotEmpty('a'); // returns `'a'`;
assertWrap.isNotEmpty({a: 'a'}); // returns `{a: 'a'}`;

Throws

AssertionError If the assertion fails.

See

isNotEnumValue

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

Asserts that a child value is not an enum member. Returns the child value if the assertion passes.

Type guards the child value.

Type declaration

Example

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

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

assertWrap.isNotEnumValue('a', MyEnum); // throws an error
assertWrap.isNotEnumValue('A', MyEnum); // returns `'A'`

Throws

AssertionError If the child is an enum member.

See

isNotFunction

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

Asserts that a value is not a function. Returns the value if the assertion passes.

Type guards the value.

Type declaration

Example

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

assertWrap.isNotFunction(() => {}); // throws an error
assertWrap.isNotFunction({}); // returns `{}`

Throws

AssertionError If the assertion failed.

See

isNotIn

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

Asserts that child value is not contained within a parent object, array, or string through reference equality. Returns the child value if the assertion passes.

Type guards the child when possible.

Type declaration

Example

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

const child = {a: 'a'};

assertWrap.isNotIn(child, {child}); // throws an error
assertWrap.isNotIn('a', 'ab'); // throws an error
assertWrap.isNotIn(child, [child]); // throws an error

assertWrap.isNotIn(child, {child: {a: 'a'}}); // returns `child`;
assertWrap.isNotIn('a', 'bc'); // returns `'a'`;

Throws

AssertionError If the assertion fails.

See

isNotInteger

isNotInteger: AssertWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

assertWrap.isNotInteger(5); // fails
assertWrap.isNotInteger(5.0000000000000001); // fails
assertWrap.isNotInteger(5.1); // returns `5.1`
assertWrap.isNotInteger(NaN); // returns `NaN`

Throws

AssertionError If the assertion fails.

See

isNotKeyOf

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

Asserts that a key is not contained within a parent value. Returns the key if the assertion passes.

Type guards the key.

Type declaration

Example

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

assertWrap.isNotKeyOf('a', {a: 0, b: 1}); // throws an error
assertWrap.isNotKeyOf('c', {a: 0, b: 1}); // returns `'c'`

Throws

AssertionError If the key is in the parent.

See

isNotNull

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

Asserts that a value is not exactly `null. Returns the value if the assertion passes.

Type guards the value.

@example

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.

isNotNumber

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

Asserts that a value is not a number. This includes `NaN. Returns the value if the assertion passes.

Type guards the value.

@example

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.isNotFunction} : the opposite assertion.

isNotObject

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

Asserts that a value is not an object. This includes arrays. Returns the value if the assertion passes.

Type guards the value.

Type declaration

Example

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

assertWrap.isNotObject({}); // throws an error
assertWrap.isNotObject([]); // returns `[]`

Throws

AssertionError If the assertion failed.

See

isNotPrimitive

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

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.

Type declaration

    • <const Actual>(input, failureMessage?): Exclude<Actual, Primitive>

    • Type Parameters

      • const Actual

      Parameters

      • input: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, Primitive>

      The value if the assertion passes.

Example

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

assertWrap.isPropertyKey('key'); // returns `'key'`
assertWrap.isPropertyKey(true); // throws an error
assertWrap.isPropertyKey({}); // throws an error

Throws

AssertionError If the assertion fails.

See

isNotPromise

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

Asserts that a value is a not Promise instance. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(actual, failureMessage?): Exclude<Actual, Promise<any>>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, Promise<any>>

      The value if the assertion passes.

Example

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

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

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

assertWrap.isNotPromise(Promise.resolve(5)); // throws an error
assertWrap.isNotPromise(new CustomThenable(5)); // returns the `CustomThenable` promise
assertWrap.isNotPromise(5); // returns `5`

Throws

AssertionError If the assertion fails.

See

isNotPromiseLike

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

Asserts that a value is not a PromiseLike. Returns the value if the assertion passes.

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.

Type declaration

    • <const Actual>(actual, failureMessage?): Exclude<Actual, PromiseLike<any>>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, PromiseLike<any>>

      The value if the assertion passes.

Example

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

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

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

assertWrap.isNotPromiseLike(Promise.resolve(5)); // throws an error
assertWrap.isNotPromiseLike(new CustomThenable(5)); // throws an error
assertWrap.isNotPromiseLike(5); // returns `5`

Throws

AssertionError If the assertion fails.

See

isNotPropertyKey

isNotPropertyKey: (<const Actual>(input: Actual, failureMessage?: string) => 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. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(input, failureMessage?): Exclude<Actual, PropertyKey>

    • Type Parameters

      • const Actual

      Parameters

      • input: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, PropertyKey>

      The value if the assertion passes.

Example

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

assertWrap.isNotPropertyKey('key'); // throws an error
assertWrap.isNotPropertyKey(true); // returns `true`
assertWrap.isNotPropertyKey({}); // returns `{}`

Throws

AssertionError If the assertion fails.

See

isNotString

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

Asserts that a value is not a string. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(actual, failureMessage?): Exclude<Actual, string>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, string>

      The value if the assertion passes.

Example

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

assertWrap.isNotString(''); // throws an error
assertWrap.isNotString(5); // returns `5`

Throws

AssertionError If the assertion failed.

See

isNotSymbol

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

Asserts that a value is not a symbol. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(actual, failureMessage?): Exclude<Actual, symbol>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Exclude<Actual, symbol>

      The value if the assertion passes.

Example

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

assertWrap.isNotSymbol(Symbol('my-symbol')); // throws an error
assertWrap.isNotSymbol('my-symbol'); // returns `'my-symbol'`

Throws

AssertionError If the assertion failed.

See

isNotUndefined

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

Asserts that a value is not exactly `undefined. Returns the value if the assertion passes.

Type guards the value.

@example

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

assertWrap.isNotUndefined(undefined); // throws an error
assertWrap.isNotUndefined(null); // returns `null`

@returns The value if the assertion passes. @throws {@link AssertionError} If the assertion failed. @see

  • {@link assertWrap.isFunction} : the opposite assertion.

isNotUuid

isNotUuid: (<const Actual>(actual: Actual, failureMessage?: string) => 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. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isNotUuid(createUuidV4()); // throws an error
assertWrap.isNotUuid('29e0f18e-6115-4982-8342-0afcadf5d611'); // throws an error
assertWrap.isNotUuid('00000000-0000-0000-0000-000000000000'); // returns `'00000000-0000-0000-0000-000000000000'`
assertWrap.isNotUuid('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // returns `'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'`
assertWrap.isNotUuid('not-a-uuid'); // returns `'not-a-uuid'`

Throws

AssertionError If the assertion fails.

See

isNull

isNull: AssertWrapFunction<null> = autoGuardSymbol

Asserts that a value is exactly `null. Returns the value if the assertion passes.

Type guards the value.

@example

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.isNotFunction} : the opposite assertion.

isNullish

isNullish: AssertWrapFunction<undefined | null> = autoGuardSymbol

Asserts that a value is nullish (null or undefined). Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isNullish(0); // fails
assertWrap.isNullish(''); // fails
assertWrap.isNullish(null); // returns `null`
assertWrap.isNullish(undefined); // returns `undefined`

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

isNumber

isNumber: AssertWrapFunction<number> = autoGuardSymbol

Asserts that a value is a number. This excludes `NaN. Returns the value if the assertion passes.

Type guards the value.

@example

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.isNotFunction} : the opposite assertion.

isObject

isObject: AssertWrapFunction<UnknownObject> = autoGuardSymbol

Asserts that a value is an object. This excludes arrays. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isObject({}); // returns `{}`
assertWrap.isObject([]); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion failed.

See

isOutBounds

isOutBounds: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a number is outside the provided min and max bounds, exclusive. Returns the number if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.isOutBounds(5, {min: 1, max: 10}); // fails
assertWrap.isOutBounds(10, {min: 1, max: 10}); // fails
assertWrap.isOutBounds(11, {min: 1, max: 10}); // returns `11`
assertWrap.isOutBounds(0, {min: 1, max: 10}); // returns `0`

Throws

AssertionError If the assertion fails.

See

isPrimitive

isPrimitive: AssertWrapFunction<Primitive> = autoGuardSymbol

Asserts that a value is a JavaScript primitive. Returns the value if the assertion passes.

Type guards the value.

Example

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

AssertionError If the assertion fails.

See

isPromise

isPromise: (<const Actual>(actual: Actual, failureMessage?: string) => Extract<Actual, Promise<any>>) = ...

Asserts that a value is a Promise instance. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <const Actual>(actual, failureMessage?): Extract<Actual, Promise<any>>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Extract<Actual, Promise<any>>

      The value if the assertion passes.

Example

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

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

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

assertWrap.isPromise(Promise.resolve(5)); // returns the `Promise` instance
assertWrap.isPromise(new CustomThenable(5)); // throws an error
assertWrap.isPromise(5); // throws an error

Throws

AssertionError If the assertion fails.

See

isPromiseLike

isPromiseLike: (<const Actual>(actual: Actual, failureMessage?: string) => Extract<Actual, PromiseLike<any>>) = ...

Asserts that a value is a PromiseLike. Returns the value if the assertion passes.

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.

Type declaration

    • <const Actual>(actual, failureMessage?): Extract<Actual, PromiseLike<any>>

    • Type Parameters

      • const Actual

      Parameters

      • actual: Actual
      • OptionalfailureMessage: string

      Returns Extract<Actual, PromiseLike<any>>

      The value if the assertion passes.

Example

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

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

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

assertWrap.isPromiseLike(Promise.resolve(5)); // returns the `Promise` instance
assertWrap.isPromiseLike(new CustomThenable(5)); // returns the `CustomThenable` instance
assertWrap.isPromiseLike(5); // throws an error

Throws

AssertionError If the assertion fails.

See

isPropertyKey

isPropertyKey: AssertWrapFunction<PropertyKey> = autoGuardSymbol

Asserts that a value is not a JavaScript primitive. Returns the value if the assertion passes.

Type guards the value.

Example

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

AssertionError If the assertion fails.

See

isString

isString: AssertWrapFunction<string> = autoGuardSymbol

Asserts that a value is a string. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isString(''); // returns `''`
assertWrap.isString(5); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion failed.

See

isSymbol

isSymbol: (<const Actual>(actual: Actual, failureMessage?: string) => NarrowToExpected<Actual, symbol>) = ...

Asserts that a value is a symbol. Returns the value if the assertion passes.

Type guards the value.

Type declaration

Example

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

assertWrap.isSymbol(Symbol('my-symbol')); // returns the created symbol
assertWrap.isSymbol('my-symbol'); // throws an error

Throws

AssertionError If the assertion failed.

See

isTrue

isTrue: AssertWrapFunction<true> = autoGuardSymbol

Asserts that a value is exactly true. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.isTrue(true); // returns `true`
assertWrap.isTrue(false); // throws an error
assertWrap.isTrue(1); // throws an error
assertWrap.isTrue(0); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the value is not true.

See

isTruthy

isTruthy: (<T>(input: T, failureMessage?: string) => Exclude<T, FalsyValue>) = ...

Asserts that a value is truthy. Returns the value if the assertion passes.

Type guards the value.

Type declaration

    • <T>(input, failureMessage?): Exclude<T, FalsyValue>

    • Type Parameters

      • T

      Parameters

      • input: T
      • OptionalfailureMessage: string

      Returns Exclude<T, FalsyValue>

      The value if the assertion passes.

Example

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

assertWrap.isTruthy(true); // returns `true`
assertWrap.isTruthy(false); // throws an error
assertWrap.isTruthy(1); // returns `1`
assertWrap.isTruthy(0); // throws an error

Throws

AssertionError If the value is not truthy.

See

isUndefined

isUndefined: AssertWrapFunction<undefined> = autoGuardSymbol

Asserts that a value is exactly `undefined. Returns the value if the assertion passes.

Type guards the value.

@example

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.isNotFunction} : the opposite assertion.

isUuid

isUuid: AssertWrapFunction<`${string}-${string}-${string}-${string}-${string}`> = autoGuardSymbol

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

Type guards the value.

Example

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

assertWrap.isUuid(createUuidV4()); // returns the generated UUID
assertWrap.isUuid('29e0f18e-6115-4982-8342-0afcadf5d611'); // returns `'29e0f18e-6115-4982-8342-0afcadf5d611'`
assertWrap.isUuid('00000000-0000-0000-0000-000000000000'); // throws an error
assertWrap.isUuid('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'); // throws an error
assertWrap.isUuid('not-a-uuid'); // throws an error

Throws

AssertionError If the assertion fails.

See

jsonEquals

jsonEquals: (<Actual, Expected>(actual: Actual, expected: Expected, failureMessage?: string) => NarrowToExpected<Actual, 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. Returns the first value if the assertion passes.

Type guards the first value.

Example

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

assertWrap.jsonEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`

assertWrap.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // throws an error

Throws

AssertionError If both inputs are not equal.

See

lacksKey

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

Asserts that a parent value does not have the key. Returns the parent if the assertion passes.

Type guards the parent value.

Type declaration

    • <const Parent, const Key>(parent, key, failureMessage?): Exclude<Parent, Record<Key, any>>

    • Type Parameters

      • const Parent
      • const Key extends PropertyKey

      Parameters

      • parent: Parent
      • key: Key
      • OptionalfailureMessage: string

      Returns Exclude<Parent, Record<Key, any>>

      The parent if it does not have the key.

Example

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

assertWrap.lacksKey({a: 0, b: 1}, 'a'); // throws an error
assertWrap.lacksKey({a: 0, b: 1}, 'c'); // returns `{a: 0, b: 1}`

Throws

AssertionError If the parent has the key.

See

lacksKeys

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

Asserts that a parent value none of the keys. Returns the parent if the assertion passes.

Type guards the parent value.

Type declaration

    • <const Parent, const Key>(parent, key, failureMessage?): Exclude<Parent, Partial<Record<Key, any>>>

    • Type Parameters

      • const Parent
      • const Key extends PropertyKey

      Parameters

      • parent: Parent
      • key: readonly Key[]
      • OptionalfailureMessage: string

      Returns Exclude<Parent, Partial<Record<Key, any>>>

      The parent if it does not have any of the keys.

Example

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

assertWrap.lacksKeys({a: 0, b: 1}, [
    'b',
    'c',
]); // throws an error
assertWrap.lacksKeys({a: 0, b: 1}, [
    'c',
    'd',
]); // returns `{a: 0, b: 1}`

Throws

AssertionError If the parent has any of the keys.

See

lacksValue

lacksValue: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that an object/array parent does not include a child value through reference equality. Returns the parent value if the assertion passes.

Performs no type guarding.

Example

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

const child = {a: 'a'};

assertWrap.lacksValue({child}, child); // throws an error
assertWrap.lacksValue({child: {a: 'a'}}, child); // returns `{child: {a: 'a'}}`;
assertWrap.lacksValue([child], child); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

lacksValues

lacksValues: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that an object/array parent includes none of the provided child values through reference equality. Returns the parent value if the assertion passes.

Performs no type guarding.

Example

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

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

assertWrap.lacksValues({}, [
    child,
    child2,
]); // returns `{}`;
assertWrap.lacksValues({child, child2}, [
    child,
    child2,
]); // throws an error
assertWrap.lacksValues({child: {a: 'a'}, child2}, [
    child,
    child2,
]); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

looseEquals

looseEquals: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that two values are loosely equal (using ==). Returns the first value if the assertion passes.

Type guards the first value.

Example

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

assertWrap.looseEquals('a', 'a'); // returns `'a'`

assertWrap.looseEquals('1', 1); // returns `'1'`

assertWrap.looseEquals({a: 'a'}, {a: 'a'}); // throws an error

const objectExample = {a: 'a'};
assertWrap.looseEquals(objectExample, objectExample); // returns `{a: 'a'}`

Throws

AssertionError If both inputs are not loosely equal.

See

matches

matches: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a string (first input, actual) matches a RegExp (second input, expected). Returns the string if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.matches('hi', /^h/); // returns `'hi'`
assertWrap.matches('hi', /^g/); // throws an error

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

mismatches

mismatches: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that a string (first input, actual) does not match a RegExp (second input, expected). Returns the string if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.mismatches('hi', /^h/); // throws an error
assertWrap.mismatches('hi', /^g/); // returns `'hi'`

Returns

The value if the assertion passes.

Throws

AssertionError If the assertion fails.

See

notDeepEquals

notDeepEquals: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that two values are not deeply equal using the deep-eql package. Returns the first value if the assertion passes.

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 {assertWrap} from '@augment-vir/assert';

assertWrap.deepEquals('a', 'a'); // returns `'a'`

assertWrap.deepEquals('1', 1); // throws an error

assertWrap.deepEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`

const objectExample = {a: 'a'};
assertWrap.deepEquals(objectExample, objectExample); // returns `{a: 'a'}`

Throws

AssertionError If both inputs are deeply equal.

See

notEntriesEqual

notEntriesEqual: AssertWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

assertWrap.notEntriesEqual({a: 'a'}, {a: 'a'}); // throws an error

assertWrap.notEntriesEqual({a: {b: 'b'}}, {a: {b: 'b'}}); // returns `{a: {b: 'b'}}`

const bExample = {b: 'b'};
assertWrap.notEntriesEqual({a: bExample}, {a: bExample}); // throws an error

Returns

The first input if the assertion passes.

Throws

AssertionError If both inputs are equal.

See

notInstanceOf

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

Asserts that a value is not an instance of the given class constructor. Returns the value if the assertion passes.

Type guards the value.

Example

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

assertWrap.notInstanceOf(/abc/, RegExp); // throws an error
assertWrap.notInstanceOf('abc', RegExp); // returns `'abc'`

Throws

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

See

notJsonEquals

notJsonEquals: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that two values are not deeply equal when stringified into JSON. This may not make any sense if the values are not valid JSON. This internally sorts all given object keys so it is insensitive to object key order. Returns the first value if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.notJsonEquals({a: 'a'}, {a: 'a'}); // throws an error

assertWrap.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // returns `{a: {b: 'b'}}`

Throws

AssertionError If both inputs are not equal.

See

notLooseEquals

notLooseEquals: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that two values are not loosely equal (using ==). Returns the first value if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.notLooseEquals('a', 'a'); // throws an error

assertWrap.notLooseEquals('1', 1); // throws an error

assertWrap.notLooseEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`

const objectExample = {a: 'a'};
assertWrap.notLooseEquals(objectExample, objectExample); // throws an error

Throws

AssertionError If both inputs are loosely equal.

See

notStrictEquals

notStrictEquals: AssertWrapFunction<unknown> = autoGuardSymbol

Asserts that two values are not strictly equal (using ===). Returns the first value if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.notStrictEquals('a', 'a'); // throws an error

assertWrap.notStrictEquals('1', 1); // returns `'1'`

assertWrap.notStrictEquals({a: 'a'}, {a: 'a'}); // returns `{a: 'a'}`

const objectExample = {a: 'a'};
assertWrap.notStrictEquals(objectExample, objectExample); // throws an error

Throws

AssertionError If both inputs are strictly equal.

See

output

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

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 the default "deeply equals" to whatever you want. Returns the output if the assertion passes.

Performs no type guarding.

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

assertWrap.output((input: number) => String(input), [5], '5'); // returns `'5'`
assertWrap.output((input: number) => String(input), [10], '5'); // throws an error

assertWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // throws an error
assertWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `10`

Returns

The output if the assertion passes.

Throws

AssertionError If the assertion fails.

startsWith

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

Checks that a parent string or array starts with a specific child. This uses reference equality when the parent is an array. Returns the parent if the assertion passes.

Performs no type guarding.

Example

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

assertWrap.startsWith('ab', 'b'); // throws an error
assertWrap.startsWith('ab', 'a'); // returns `'ab'`
assertWrap.startsWith(
    [
        'a',
        'b',
    ],
    'b',
); // throws an error
assertWrap.startsWith(
    [
        'a',
        'b',
    ],
    'a',
); // returns `['a', 'b']`

Returns

The parent value if it starts with the child.

Throws

AssertionError If the parent does not start with the child.

See

startsWithout

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

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

Performs no type guarding.

Example

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

assertWrap.startsWith('ab', 'b'); // returns `'ab'`
assertWrap.startsWith('ab', 'a'); // throws an error
assertWrap.startsWith(
    [
        'a',
        'b',
    ],
    'b',
); // returns `['a', 'b']`
assertWrap.startsWith(
    [
        'a',
        'b',
    ],
    'a',
); // throws an error

Returns

The parent value if it does not start with the child.

Throws

AssertionError If the parent does start with the child.

See

strictEquals

strictEquals: (<Actual, Expected>(actual: Actual, expected: Expected, failureMessage?: string) => NarrowToExpected<Actual, Expected>) = ...

Asserts that two values are strictly equal (using ===). Returns the first value if the assertion passes.

Type guards the first value.

Example

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

assertWrap.strictEquals('a', 'a'); // returns `'a'`

assertWrap.strictEquals('1', 1); // throws an error

assertWrap.strictEquals({a: 'a'}, {a: 'a'}); // throws an error

const objectExample = {a: 'a'};
assertWrap.strictEquals(objectExample, objectExample); // returns `{a: 'a'}`

Throws

AssertionError If both inputs are not strictly equal.

See

throws

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

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. Returns the Error if the assertion passes.

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. Returns the Error if the assertion passes.

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 {assertWrap} from '@augment-vir/assert';

assertWrap.throws(() => {
    throw new Error();
}); // returns the thrown error
assertWrap.throws(
    () => {
        throw new Error();
    },
    {matchMessage: 'hi'},
); // throws an error
await assertWrap.throws(Promise.reject()); // returns the rejection
assertWrap.throws(() => {}); // throws an error

Returns

The Error if the assertion passes.

Throws

AssertionError If the assertion fails.

Settings

Member Visibility

On This Page

Properties
deepEqualsendsWithendsWithoutentriesEqualhasKeyhasKeyshasValuehasValuesinstanceOfisAboveisApproximatelyisArrayisAtLeastisAtMostisBelowisBigIntisBooleanisDefinedisEmptyisEnumValueisErrorisFalseisFalsyisFiniteisFunctionisHttpStatusisHttpStatusCategoryisInisInBoundsisInfiniteisIntegerisKeyOfisLengthAtLeastisLengthExactlyisNaNisNotApproximatelyisNotArrayisNotBigIntisNotBooleanisNotEmptyisNotEnumValueisNotFunctionisNotInisNotIntegerisNotKeyOfisNotNullisNotNumberisNotObjectisNotPrimitiveisNotPromiseisNotPromiseLikeisNotPropertyKeyisNotStringisNotSymbolisNotUndefinedisNotUuidisNullisNullishisNumberisObjectisOutBoundsisPrimitiveisPromiseisPromiseLikeisPropertyKeyisStringisSymbolisTrueisTruthyisUndefinedisUuidjsonEqualslacksKeylacksKeyslacksValuelacksValueslooseEqualsmatchesmismatchesnotDeepEqualsnotEntriesEqualnotInstanceOfnotJsonEqualsnotLooseEqualsnotStrictEqualsoutputstartsWithstartsWithoutstrictEqualsthrows