Function checkWrap

A group of guard methods that do the following:

Run the method's assertion on the given inputs.
If the assertion fails, return undefined.
If the assertion succeeds, the first input is returned and (when possible) type guarded.

This can also be called as a standalone check function which checks that its input is truthy and returns it if so, else undefined.

Example

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

// `result1` will be `['a']`
const result1 = checkWrap.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 = checkWrap.isString(value);

const value2: unknown = 'some value' as unknown;
// `result` will be `undefined`
const result3 = checkWrap.isNumber(value2);

Package

@augment-vir/assert

checkWrap<T>(input): undefined | T
Type Parameters
- T
Parameters
- input: T
Returns undefined | T
The original given value (type guarded when possible) or, if the expectation fails, undefined.
- Defined in packages/assert/src/augments/guards/check-wrap.ts:44

Index

Properties

deepEquals endsWith endsWithout entriesEqual hasKey hasKeys hasValue hasValues instanceOf isAbove isApproximately isArray isAtLeast isAtMost isBelow isBigInt isBoolean 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 isNotUuid isNull isNumber isObject isOutBounds isPrimitive isPromise isPromiseLike isPropertyKey isString isSymbol isTrue isTruthy 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) => undefined | NarrowToExpected<Actual, Expected>) = ...

Checks that two values are deeply equal using the deep-eql package. Returns the first value if the check 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.

Type declaration

- <Actual, Expected>(actual, expected): undefined | NarrowToExpected<Actual, Expected>
- Type Parameters
  - Actual
  - Expected
  Parameters
  - actual: Actual
  - expected: Expected
  Returns undefined | NarrowToExpected<Actual, Expected>
  The first value if the check passes, otherwise undefined.

Example

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

checkWrap.deepEquals('a', 'a'); // true

checkWrap.deepEquals('1', 1); // false

checkWrap.deepEquals({a: 'a'}, {a: 'a'}); // true

const objectExample = {a: 'a'};
checkWrap.deepEquals(objectExample, objectExample); // true

See

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

endsWith

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

Checks that a parent string or array ends with a specific child. This uses reference equality when the parent is an array. Returns the value if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.endsWith('ab', 'b'); // returns `'ab'`
checkWrap.endsWith('ab', 'a'); // returns `undefined`
checkWrap.endsWith(
    [
        'a',
        'b',
    ],
    'b',
); // returns `['a', 'b']`
checkWrap.endsWith(
    [
        'a',
        'b',
    ],
    'a',
); // returns `undefined`

Returns

The first value if the check passes, otherwise undefined.

See

checkWrap.endsWithout : the opposite check.
checkWrap.startsWith : check on the other end.

endsWithout

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

Checks 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 value if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.endsWithout('ab', 'b'); // returns `undefined`
checkWrap.endsWithout('ab', 'a'); // returns `'ab'`
checkWrap.endsWithout(
    [
        'a',
        'b',
    ],
    'b',
); // returns `undefined`
checkWrap.endsWithout(
    [
        'a',
        'b',
    ],
    'a',
); // returns `['a', 'b']`

Returns

The first value if the check passes, otherwise undefined.

See

checkWrap.endsWith : the opposite check.
checkWrap.startsWithout : check on the other end.

entriesEqual

entriesEqual: (<Actual, Expected>(actual: Actual, expected: Expected) => undefined | NarrowToExpected<Actual, Expected>) = ...

Checks that two objects are deeply equal by checking only their top-level values for strict (non-deep, reference, using ===) equality. If the check passes the first object is returned. If not, undefined is returned.

Type guards the first value.

Type declaration

- <Actual, Expected>(actual, expected): undefined | NarrowToExpected<Actual, Expected>
- Type Parameters
  - Actual
  - Expected
  Parameters
  - actual: Actual
  - expected: Expected
  Returns undefined | NarrowToExpected<Actual, Expected>
  The first input if the assertion passes, otherwise undefined.

Example

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

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

checkWrap.entriesEqual({a: {b: 'b'}}, {a: {b: 'b'}}); // returns `undefined`

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

See

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

hasKey

hasKey: (<const Parent, const Key>(parent: Parent, key: Key) => undefined | CombineTypeWithKey<Key, Parent>) = ...

Checks that a parent value has the key. Returns the parent value if the check passes, otherwise undefined.

Type guards the parent value.

Type declaration

- <const Parent, const Key>(parent, key): undefined | CombineTypeWithKey<Key, Parent>
- Type Parameters
  - const Parent
  - const Key extends PropertyKey
  Parameters
  - parent: Parent
  - key: Key
  Returns undefined | CombineTypeWithKey<Key, Parent>
  The parent value if the check passes, otherwise undefined.

Example

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

checkWrap.hasKey({a: 0, b: 1}, 'a'); // returns `{a: 0, b: 1}`
checkWrap.hasKey({a: 0, b: 1}, 'c'); // returns `undefined`

See

checkWrap.lacksKey : the opposite check.
checkWrap.hasKeys : the multi-key check.

hasKeys

hasKeys: (<const Keys, const Parent>(parent: Parent, keys: readonly Keys[]) => undefined | CombineTypeWithKey<Keys, Parent>) = ...

Checks that a parent value has all the keys. Returns the parent value if the check passes, otherwise undefined.

Type guards the parent value.

Type declaration

- <const Keys, const Parent>(parent, keys): undefined | CombineTypeWithKey<Keys, Parent>
- Type Parameters
  - const Keys extends PropertyKey
  - const Parent
  Parameters
  - parent: Parent
  - keys: readonly Keys[]
  Returns undefined | CombineTypeWithKey<Keys, Parent>
  The parent value if the check passes, otherwise undefined.

Example

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

checkWrap.hasKeys({a: 0, b: 1}, [
    'a',
    'b',
]); // returns `{a: 0, b: 1}`
checkWrap.hasKeys({a: 0, b: 1}, [
    'b',
    'c',
]); // returns `undefined`

See

checkWrap.lacksKeys : the opposite check.
checkWrap.hasKey : the single-key check.

hasValue

hasValue: CheckWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

const child = {a: 'a'};

checkWrap.hasValue({child}, child); // returns `{child}`
checkWrap.hasValue({child: {a: 'a'}}, child); // returns `undefined`
checkWrap.hasValue([child], child); // returns `[child]`

See

checkWrap.lacksValue : the opposite check.
checkWrap.hasValues : the multi-value check.

hasValues

hasValues: CheckWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

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

checkWrap.hasValues({child, child2}, [
    child,
    child2,
]); // returns `{child, child2}`
checkWrap.hasValues({child: {a: 'a'}, child2}, [
    child,
    child2,
]); // returns `undefined`
checkWrap.hasValues(
    [child],
    [
        child,
        child2,
    ],
); // returns `[child]`

See

checkWrap.lacksValues : the opposite check.
checkWrap.hasValue : the single-value check.

instanceOf

instanceOf: (<const Instance>(instance: unknown, constructor: Constructor<Instance>) => undefined | Instance) = ...

Checks that a value is an instance of the given class constructor. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Instance>(instance, constructor): undefined | Instance
- Type Parameters
  - const Instance
  Parameters
  - instance: unknown
  - constructor: Constructor<Instance>
  Returns undefined | Instance
  The value if the check passes, otherwise undefined.

Example

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

checkWrap.instanceOf(/abc/, RegExp); // returns `/abc/`
checkWrap.instanceOf('abc', RegExp); // returns `undefined`

See

checkWrap.notInstanceOf : the opposite check.

isAbove

isAbove: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is above the expectation (actual > expected). Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isAbove(10, 5); // returns `10`
checkWrap.isAbove(5, 5); // returns `undefined`
checkWrap.isAbove(5, 10); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isBelow : the opposite check.
checkWrap.isAtLeast : the more lenient check.

isApproximately

isApproximately: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is within ±delta of the expectation. Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isApproximately(10, 8, 4); // returns `10`
checkWrap.isApproximately(10, 12, 4); // returns `10`
checkWrap.isApproximately(10, 8, 1); // returns `undefined`
checkWrap.isApproximately(10, 12, 1); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isNotApproximately : the opposite check.

isArray

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

Checks that a value is an array. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <Actual>(actual): undefined | ArrayNarrow<Actual>
- Type Parameters
  - Actual
  Parameters
  - actual: Actual
  Returns undefined | ArrayNarrow<Actual>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isArray([]); // returns `[]`
checkWrap.isArray({length: 4}); // returns `undefined`

See

checkWrap.isNotArray : the opposite check.

isAtLeast

isAtLeast: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is at least the expectation (actual >= expected). Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isAtLeast(10, 5); // returns `10`
checkWrap.isAtLeast(5, 5); // returns `5`
checkWrap.isAtLeast(5, 10); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isAtMost : the opposite check.
checkWrap.isAbove : the more restrictive check.

isAtMost

isAtMost: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is at most the expectation (actual <= expected). Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isAtMost(10, 5); // returns `undefined`
checkWrap.isAtMost(5, 5); // returns `5`
checkWrap.isAtMost(5, 10); // returns `5`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isAtLeast : the opposite check.
checkWrap.isBelow : the more restrictive check.

isBelow

isBelow: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is below the expectation (actual < expected). Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isBelow(10, 5); // returns `undefined`
checkWrap.isBelow(5, 5); // returns `undefined`
checkWrap.isBelow(5, 10); // returns `5`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isAbove : the opposite check.
checkWrap.isAtMost : the more lenient check.

isBigInt

isBigInt: CheckWrapFunction<bigint> = autoGuardSymbol

Checks that a value is a BigInt. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isBigInt(123n); // returns `123n`
checkWrap.isBigInt(123); // returns `undefined`

Returns

The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotBigInt : the opposite check.

isBoolean

isBoolean: CheckWrapFunction<boolean> = autoGuardSymbol

Checks that a value is a boolean. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isBoolean(true); // returns `true`
checkWrap.isBoolean('true'); // returns `undefined`

Returns

The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotBoolean : the opposite check.

isEmpty

isEmpty: (<const Actual>(actual: Actual) => undefined | NarrowToActual<Actual, Empty>) = ...

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

Type guards the value.

Example

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

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

checkWrap.isEmpty('a'); // returns `undefined`
checkWrap.isEmpty({a: 'a'}); // returns `undefined`

See

checkWrap.isNotEmpty : the opposite check.

isEnumValue

isEnumValue: (<const Actual, const Expected>(child: Actual, checkEnum: Expected) => undefined | NarrowToExpected<Actual, Expected[keyof Expected]>) = ...

Checks that a child value is an enum member. Returns the child value if the check passes, otherwise undefined.

Type guards the child value.

Type declaration

- <const Actual, const Expected>(child, checkEnum): undefined | NarrowToExpected<Actual, Expected[keyof Expected]>
- Type Parameters
  - const Actual
  - const Expected extends EnumBaseType
  Parameters
  - child: Actual
  - checkEnum: Expected
  Returns undefined | NarrowToExpected<Actual, Expected[keyof Expected]>
  The child value if the check passes, otherwise undefined.

Example

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

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

checkWrap.isEnumValue('a', MyEnum); // returns `'a'`
checkWrap.isEnumValue('A', MyEnum); // returns `undefined`

See

checkWrap.isNotEnumValue : the opposite check.

isError

isError: CheckWrapFunction<Error> = autoGuardSymbol

Checks that a value is an instance of the built-in Error class and compares it to the given ErrorMatchOptions, if provided. Returns the error if the check passes, otherwise undefined.

Type guards the input.

Example

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

checkWrap.isError(new Error()); // returns the Error
checkWrap.isError(new Error(), {matchMessage: 'hi'}); // returns `undefined`
checkWrap.isError({message: 'not an error'}); // returns `undefined`

Returns

The Error if the check passes, otherwise undefined.

isFalse

isFalse: CheckWrapFunction<false> = autoGuardSymbol

Checks that a value is exactly false. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isFalse(true); // returns `false`
checkWrap.isFalse(false); // returns `true`
checkWrap.isFalse(1); // returns `false`
checkWrap.isFalse(0); // returns `false`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isTrue : the opposite check.
checkWrap.isFalsy : a less exact check.

isFalsy

isFalsy: (<T>(input: T) => undefined | NarrowToExpected<T, FalsyValue>) = ...

Checks that a value is falsy. Returns the value if the check passes, otherwise undefined.

Type guards the value when possible.

Type declaration

- <T>(input): undefined | NarrowToExpected<T, FalsyValue>
- Type Parameters
  - T
  Parameters
  - input: T
  Returns undefined | NarrowToExpected<T, FalsyValue>
  The value if the check passes, otherwise undefined.

Example

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

checkWrap.isFalsy(true); // returns `false`
checkWrap.isFalsy(false); // returns `true`
checkWrap.isFalsy(1); // returns `false`
checkWrap.isFalsy(0); // returns `true`

See

checkWrap.isTruthy : the opposite check.
checkWrap.isFalse : a more exact check.

isFinite

isFinite: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is finite: meaning, not NaN and not Infinity or -Infinity. Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isFinite(10); // returns `10`
checkWrap.isFinite(parseInt('invalid')); // returns `undefined`
checkWrap.isFinite(Infinity); // returns `undefined`
checkWrap.isFinite(-Infinity); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isNaN : an opposite check.
checkWrap.isInfinite : an opposite check.

isFunction

isFunction: (<const Actual>(actual: Actual) => undefined | NarrowToActual<Actual, AnyFunction>) = ...

Checks that a value is a function. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual): undefined | NarrowToActual<Actual, AnyFunction>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  Returns undefined | NarrowToActual<Actual, AnyFunction>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isFunction(() => {}); // returns `() => {}`
checkWrap.isFunction({}); // returns `undefined`

See

checkWrap.isNotFunction : the opposite check.

isHttpStatus

isHttpStatus: CheckWrapFunction<HttpStatus> = autoGuardSymbol

Checks that a value is an HttpStatus. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isHttpStatus(400); // returns `400`
checkWrap.isHttpStatus(500); // returns `500`
checkWrap.isHttpStatus(99); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isHttpStatusCategory : the category check.
HttpStatus : all included statuses.
HttpStatusCategory : all status categories.

isHttpStatusCategory

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

Checks that a value is an HttpStatus within a specific HttpStatusCategory. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isHttpStatusCategory(400, HttpStatusCategory.ClientError); // returns `400`
checkWrap.isHttpStatusCategory(500, HttpStatusCategory.Success); // returns `undefined`
checkWrap.isHttpStatusCategory(99, HttpStatusCategory.Information); // returns `undefined`

See

checkWrap.isHttpStatus : the status check.
HttpStatus : all included statuses.
HttpStatusCategory : all status categories.

isIn

isIn: (<const Child, const Parent>(child: Child, parent: Parent) => undefined | NarrowToExpected<Child, Values<Parent>>) = ...

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

Type guards the child when possible.

Example

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

const child = {a: 'a'};

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

checkWrap.isIn(child, {child: {a: 'a'}}); // returns `undefined`
checkWrap.isIn('a', 'bc'); // returns `undefined`

See

checkWrap.isNotIn : the opposite check.

isInBounds

isInBounds: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is inside the provided min and max bounds, inclusive. Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

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

See

checkWrap.isOutBounds : the opposite check.

isInfinite

isInfinite: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is either Infinity or -Infinity. Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isInfinite(10); // returns `undefined`
checkWrap.isInfinite(parseInt('invalid')); // returns `undefined`
checkWrap.isInfinite(Infinity); // returns `Infinity`
checkWrap.isInfinite(-Infinity); // returns `-Infinity`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isNaN : an opposite check.
checkWrap.isInfinite : an opposite check.

isInteger

isInteger: CheckWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

checkWrap.isInteger(5); // returns `5`
checkWrap.isInteger(5.0000000000000001); // returns `5`
checkWrap.isInteger(5.1); // returns `undefined`
checkWrap.isInteger(NaN); // returns `undefined`

See

checkWrap.isNotInteger : the opposite check.

isKeyOf

isKeyOf: (<const Key, const Parent>(key: Key, parent: Parent) => undefined | NarrowToExpected<Key, keyof Parent>) = ...

Checks that a key is contained within a parent value. Returns the key if the check passes, otherwise undefined.

Type guards the key.

Type declaration

- <const Key, const Parent>(key, parent): undefined | NarrowToExpected<Key, keyof Parent>
- Type Parameters
  - const Key extends PropertyKey
  - const Parent
  Parameters
  - key: Key
  - parent: Parent
  Returns undefined | NarrowToExpected<Key, keyof Parent>
  The key if the check passes, otherwise undefined.

Example

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

checkWrap.isKeyof('a', {a: 0, b: 1}); // returns `'a'`
checkWrap.isKeyof('c', {a: 0, b: 1}); // returns `undefined`

See

checkWrap.isNotKeyOf : the opposite check.

isLengthAtLeast

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

Checks that an array or string has at least the given length. Returns the value if the check passes, otherwise undefined.

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

Example

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

checkWrap.isLengthAtLeast(
    [
        'a',
        'b',
        'c',
    ],
    2,
); // returns `['a', 'b', 'c']`
checkWrap.isLengthAtLeast(
    [
        'a',
        'b',
        'c',
    ],
    3,
); // returns `['a', 'b', 'c']`
checkWrap.isLengthAtLeast(
    [
        'a',
        'b',
    ],
    3,
); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isLengthExactly : the more exact check.

isLengthExactly

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

Checks that an array or string has exactly the given length. Returns the value if the check passes, otherwise undefined.

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

Example

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

checkWrap.isLengthExactly(
    [
        'a',
        'b',
        'c',
    ],
    2,
); // returns `undefined`
checkWrap.isLengthExactly(
    [
        'a',
        'b',
        'c',
    ],
    3,
); // returns `['a', 'b', 'c']`
checkWrap.isLengthExactly(
    [
        'a',
        'b',
    ],
    3,
); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isLengthAtLeast : the more flexible check.

isNaN

isNaN: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is NaN. Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isNaN(10); // returns `undefined`
checkWrap.isNaN(parseInt('invalid')); // returns `NaN`
checkWrap.isNaN(Infinity); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isNumber : can be used as the opposite check.

isNotApproximately

isNotApproximately: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is outside ±delta of the expectation. Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.isNotApproximately(10, 8, 4); // returns `undefined`
checkWrap.isNotApproximately(10, 12, 4); // returns `undefined`
checkWrap.isNotApproximately(10, 8, 1); // returns `10`
checkWrap.isNotApproximately(10, 12, 1); // returns `10`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isApproximately : the opposite check.

isNotArray

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

Checks that a value is not an array. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, readonly unknown[]>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, readonly unknown[]>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isNotArray([]); // returns `undefined`
checkWrap.isNotArray({length: 4}); // returns `{length: 4}`

See

checkWrap.isArray : the opposite check.

isNotBigInt

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

Checks that a value is not a BigInt. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, bigint>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, bigint>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isNotBigInt(123n); // returns `undefined`
checkWrap.isNotBigInt(123); // returns `123`

See

checkWrap.isBigInt : the opposite check.

isNotBoolean

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

Checks that a value is not a boolean. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, boolean>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, boolean>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isNotBoolean(true); // returns `undefined`
checkWrap.isNotBoolean('true'); // returns `'true'`

See

checkWrap.isBoolean : the opposite check.

isNotEmpty

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

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

Type guards the value.

Example

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

checkWrap.isNotEmpty({}); // returns `undefined`
checkWrap.isNotEmpty(''); // returns `undefined`
checkWrap.isNotEmpty([]); // returns `undefined`

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

See

checkWrap.isEmpty : the opposite check.

isNotEnumValue

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

Checks that a child value is not an enum member. Returns the child value if the check passes, otherwise undefined.

Type guards the child value.

Type declaration

- <const Actual, const Expected>(child, checkEnum): undefined | Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>
- Type Parameters
  - const Actual
  - const Expected extends EnumBaseType
  Parameters
  - child: Actual
  - checkEnum: Expected
  Returns undefined | Exclude<Actual, Expected[keyof Expected] | `${Expected[keyof Expected]}`>
  The child value if the check passes, otherwise undefined.

Example

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

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

checkWrap.isNotEnumValue('a', MyEnum); // returns `undefined`
checkWrap.isNotEnumValue('A', MyEnum); // returns `'A'`

See

checkWrap.isEnumValue : the opposite check.

isNotFunction

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

Checks that a value is not a function. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, AnyFunction>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, AnyFunction>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isNotFunction(() => {}); // returns `undefined`
checkWrap.isNotFunction({}); // returns `{}`

See

checkWrap.isFunction : the opposite check.

isNotIn

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

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

Type guards the child when possible.

Example

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

const child = {a: 'a'};

checkWrap.isNotIn(child, {child}); // returns `undefined`
checkWrap.isNotIn('a', 'ab'); // returns `undefined`
checkWrap.isNotIn(child, [child]); // returns `undefined`

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

See

checkWrap.isIn : the opposite check.

isNotInteger

isNotInteger: CheckWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

checkWrap.isNotInteger(5); // returns `undefined`
checkWrap.isNotInteger(5.0000000000000001); // returns `undefined`
checkWrap.isNotInteger(5.1); // returns `5.1`
checkWrap.isNotInteger(NaN); // returns `NaN`

See

checkWrap.isInteger : the opposite check.

isNotKeyOf

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

Checks that a key is not contained within a parent value. Returns the key if the check passes, otherwise undefined.

Type guards the key.

Type declaration

- <const Key, const Parent>(key, parent, failureMessage?): undefined | Exclude<Key, RequiredKeysOf<Parent>>
- Type Parameters
  - const Key extends PropertyKey
  - const Parent
  Parameters
  - key: Key
  - parent: Parent
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Key, RequiredKeysOf<Parent>>
  The key if the check passes, otherwise undefined.

Example

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

checkWrap.isNotKeyOf('a', {a: 0, b: 1}); // returns `undefined`
checkWrap.isNotKeyOf('c', {a: 0, b: 1}); // returns `'c'`

See

checkWrap.isKeyOf : the opposite check.

isNotNull

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

Checks that a value is not exactly null. Returns the value if the check passes, otherwise undefined`.

Type guards the value.

@example

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

checkWrap.isNotNull(null); // returns `undefined`
checkWrap.isNotNull(undefined); // returns `undefined`

@returns The value if the check passes. Otherwise, undefined.

See

checkWrap.isFunction : the opposite check.

isNotNumber

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

Checks that a value is not a number. This includes NaN. Returns the value if the check passes, otherwise undefined`.

Type guards the value.

@example

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

checkWrap.isNotNumber(123); // returns `undefined`
checkWrap.isNotNumber(123n); // returns `123n`

@returns The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotFunction : the opposite check.

isNotObject

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

Checks that a value is not an object. This includes arrays. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, UnknownObject>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, UnknownObject>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isNotObject({}); // returns `undefined`
checkWrap.isNotObject([]); // returns `[]`

See

checkWrap.isFunction : the opposite check.

isNotPrimitive

isNotPrimitive: (<const Actual>(input: Actual) => undefined | Exclude<Actual, Primitive>) = ...

Checks that a value is a valid PropertyKey. PropertyKey is a built-in TypeScript type which refers to all possible key types for a JavaScript object. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(input): undefined | Exclude<Actual, Primitive>
- Type Parameters
  - const Actual
  Parameters
  - input: Actual
  Returns undefined | Exclude<Actual, Primitive>
  The value if the check passes, otherwise undefined.

Example

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

checkWrap.isPropertyKey('key'); // returns `'key'`
checkWrap.isPropertyKey(true); // returns `undefined`
checkWrap.isPropertyKey({}); // returns `undefined`

See

checkWrap.isNotPropertyKey : the opposite check.

isNotPromise

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

Checks that a value is a PromiseLike. Returns the value if the check passes, otherwise undefined.

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

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

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

checkWrap.isPromiseLike(Promise.resolve(5)); // returns `true`
checkWrap.isPromiseLike(new CustomThenable(5)); // returns `true`
checkWrap.isPromiseLike(5); // returns `false`

See

checkWrap.isNotPromiseLike : the opposite check.
checkWrap.isPromise : the more precise check.

isNotPromiseLike

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

Checks that a value is not a PromiseLike. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

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

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

checkWrap.isNotPromiseLike(Promise.resolve(5)); // returns `false`
checkWrap.isNotPromiseLike(new CustomThenable(5)); // returns `false`
checkWrap.isNotPromiseLike(5); // returns `true`

See

checkWrap.isPromiseLike : the opposite check.
checkWrap.isNotPromise : the more precise check.

isNotPropertyKey

isNotPropertyKey: (<const Actual>(input: Actual) => undefined | Exclude<Actual, PropertyKey>) = ...

Checks that a value is not a valid PropertyKey. PropertyKey is a built-in TypeScript type which refers to all possible key types for a JavaScript object. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(input): undefined | Exclude<Actual, PropertyKey>
- Type Parameters
  - const Actual
  Parameters
  - input: Actual
  Returns undefined | Exclude<Actual, PropertyKey>
  The value if the check passes, otherwise undefined.

Example

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

checkWrap.isNotPropertyKey('key'); // returns `undefined`
checkWrap.isNotPropertyKey(true); // returns `true`
checkWrap.isNotPropertyKey({}); // returns `{}`

See

checkWrap.isPropertyKey : the opposite check.

isNotString

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

Checks that a value is not a string. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, string>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, string>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isNotString(''); // returns `undefined`
checkWrap.isNotString(5); // returns `5`

See

checkWrap.isFunction : the opposite check.

isNotSymbol

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

Checks that a value is not a symbol. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, symbol>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, symbol>
  The value if the check passes. Otherwise, undefined.

Example

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

checkWrap.isNotSymbol(Symbol('my-symbol')); // returns `undefined`
checkWrap.checkWrap('my-symbol'); // returns `'my-symbol'`

See

checkWrap.isFunction : the opposite check.

isNotUuid

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

Checks that a value is not a valid UUID. The nil or max UUIDs are included as not valid. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual>(actual, failureMessage?): undefined | Exclude<Actual, `${string}-${string}-${string}-${string}-${string}`>
- Type Parameters
  - const Actual
  Parameters
  - actual: Actual
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Actual, `${string}-${string}-${string}-${string}-${string}`>
  The value if the check passes, otherwise undefined.

Example

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

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

See

checkWrap.isUuid : the opposite check.

isNull

isNull: CheckWrapFunction<null> = autoGuardSymbol

Checks that a value is exactly null. Returns the value if the check passes, otherwise undefined`.

Type guards the value.

@example

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

checkWrap.isNull(null); // returns `null`
checkWrap.isNull(undefined); // returns `undefined`

@returns The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotFunction : the opposite check.

isNumber

isNumber: CheckWrapFunction<number> = autoGuardSymbol

Checks that a value is a number. This excludes NaN. Returns the value if the check passes, otherwise undefined`.

Type guards the value.

@example

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

checkWrap.isNumber(123); // returns `123`
checkWrap.isNumber(123n); // returns `undefined`

@returns The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotFunction : the opposite check.

isObject

isObject: CheckWrapFunction<UnknownObject> = autoGuardSymbol

Checks that a value is an object. This excludes arrays. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isObject({}); // returns `{}`
checkWrap.isObject([]); // returns `undefined`

Returns

The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotFunction : the opposite check.

isOutBounds

isOutBounds: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a number is outside the provided min and max bounds, exclusive. Returns the number if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

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

See

checkWrap.isInBounds : the opposite check.

isPrimitive

isPrimitive: CheckWrapFunction<Primitive> = autoGuardSymbol

Checks that a value is a JavaScript primitive. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isPrimitive('key'); // returns `'key'`
checkWrap.isPrimitive(true); // returns `true`
checkWrap.isPrimitive({}); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isNotPrimitive : the opposite check.

isPromise

isPromise: CheckWrapFunction<Promise<any>> = autoGuardSymbol

Checks that a value is a Promise instance. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

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

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

checkWrap.isPromise(Promise.resolve(5)); // returns `true`
checkWrap.isPromise(new CustomThenable(5)); // returns `false`
checkWrap.isPromise(5); // returns `false`

See

checkWrap.isNotPromise : the opposite check.
checkWrap.isPromiseLike : the more lenient check.

isPromiseLike

isPromiseLike: CheckWrapFunction<PromiseLike<any>> = autoGuardSymbol

Checks that a value is a not Promise instance. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

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

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

checkWrap.isNotPromise(Promise.resolve(5)); // returns `false`
checkWrap.isNotPromise(new CustomThenable(5)); // returns `true`
checkWrap.isNotPromise(5); // returns `true`

See

checkWrap.isPromise : the opposite check.
checkWrap.isNotPromiseLike : the more lenient check.

isPropertyKey

isPropertyKey: CheckWrapFunction<PropertyKey> = autoGuardSymbol

Checks that a value is not a JavaScript primitive. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isPrimitive('key'); // returns `undefined`
checkWrap.isPrimitive(true); // returns `undefined`
checkWrap.isPrimitive({}); // returns `{}`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isPrimitive : the opposite check.

isString

isString: CheckWrapFunction<string> = autoGuardSymbol

Checks that a value is a string. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isString(''); // returns `''`
checkWrap.isString(5); // returns `undefined`

Returns

The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotFunction : the opposite check.

isSymbol

isSymbol: CheckWrapFunction<symbol> = autoGuardSymbol

Checks that a value is a symbol. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isSymbol(Symbol('my-symbol')); // returns the created symbol
checkWrap.isSymbol('my-symbol'); // returns `undefined`

Returns

The value if the check passes. Otherwise, undefined.

See

checkWrap.isNotFunction : the opposite check.

isTrue

isTrue: CheckWrapFunction<true> = autoGuardSymbol

Checks that a value is exactly true. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

checkWrap.isTrue(true); // returns `true`
checkWrap.isTrue(false); // returns `false`
checkWrap.isTrue(1); // returns `false`
checkWrap.isTrue(0); // returns `false`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isFalse : the opposite check.
checkWrap.isTruthy : a less exact check.

isTruthy

isTruthy: (<T>(input: T) => undefined | Exclude<T, FalsyValue>) = ...

Checks that a value is truthy. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <T>(input): undefined | Exclude<T, FalsyValue>
- Type Parameters
  - T
  Parameters
  - input: T
  Returns undefined | Exclude<T, FalsyValue>
  The value if the check passes, otherwise undefined.

Example

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

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

See

checkWrap.isFalsy : the opposite check.
checkWrap.isTrue : a more exact check.

isUuid

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

Checks that a value is a valid UUID. Does not accept the nil or max UUIDs. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Example

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

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

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.isNotUuid : the opposite check.

jsonEquals

jsonEquals: (<Actual, Expected>(actual: Actual, expected: Expected) => undefined | NarrowToExpected<Actual, Expected>) = ...

Checks 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 check passes.

Type guards the first value.

Example

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

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

checkWrap.jsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // returns `undefined`

See

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

lacksKey

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

Checks that a parent value does not have the key. Returns the parent value if the check passes, otherwise undefined.

Type guards the parent value.

Type declaration

- <const Parent, const Key>(parent, key, failureMessage?): undefined | Exclude<Parent, Record<Key, any>>
- Type Parameters
  - const Parent
  - const Key extends PropertyKey
  Parameters
  - parent: Parent
  - key: Key
  - OptionalfailureMessage: string
  Returns undefined | Exclude<Parent, Record<Key, any>>
  The parent value if the check passes, otherwise undefined.

Example

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

checkWrap.lacksKey({a: 0, b: 1}, 'a'); // returns `undefined`
checkWrap.lacksKey({a: 0, b: 1}, 'c'); // returns `{a: 0, b: 1}`

See

checkWrap.hasKey : the opposite check.
checkWrap.lacksKeys : the multi-key check.

lacksKeys

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

Checks that a parent value none of the keys. Returns the parent value if the check passes, otherwise undefined.

Type guards the parent value.

Type declaration

- <const Parent, const Key>(parent, key): undefined | Exclude<Parent, Partial<Record<Key, any>>>
- Type Parameters
  - const Parent
  - const Key extends PropertyKey
  Parameters
  - parent: Parent
  - key: readonly Key[]
  Returns undefined | Exclude<Parent, Partial<Record<Key, any>>>
  The parent value if the check passes, otherwise undefined.

Example

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

checkWrap.lacksKeys({a: 0, b: 1}, [
    'b',
    'c',
]); // returns `undefined`
checkWrap.lacksKeys({a: 0, b: 1}, [
    'c',
    'd',
]); // returns `{a: 0, b: 1}`

See

checkWrap.hasKeys : the opposite check.
checkWrap.lacksKey : the single-key check.

lacksValue

lacksValue: CheckWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

const child = {a: 'a'};

checkWrap.lacksValue({child}, child); // returns `undefined`
checkWrap.lacksValue({child: {a: 'a'}}, child); // returns `{child: {a: 'a'}}`
checkWrap.lacksValue([child], child); // returns `undefined`

See

checkWrap.hasValue : the opposite check.
checkWrap.lacksValues : the multi-value check.

lacksValues

lacksValues: CheckWrapFunction<unknown> = autoGuardSymbol

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

Performs no type guarding.

Example

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

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

checkWrap.lacksValues({}, [
    child,
    child2,
]); // returns `{}`
checkWrap.lacksValues({child, child2}, [
    child,
    child2,
]); // returns `undefined`
checkWrap.lacksValues({child: {a: 'a'}, child2}, [
    child,
    child2,
]); // returns `undefined`

See

checkWrap.lacksValues : the opposite check.
checkWrap.hasValue : the single-value check.

looseEquals

looseEquals: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that two values are loosely equal (using ==). Returns the first value if the check passes, otherwise undefined.

Type guards the first value.

Example

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

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

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

checkWrap.looseEquals({a: 'a'}, {a: 'a'}); // returns `undefined`

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

Returns

The first value if the check passes, otherwise undefined.

See

checkWrap.notLooseEquals : the opposite check.
checkWrap.strictEquals : the strict equality check.

matches

matches: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a string (first input, actual) matches a RegExp (second input, expected). Returns the string if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.matches('hi', /^h/); // returns `'hi'`
checkWrap.matches('hi', /^g/); // returns `undefined`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.mismatches : the opposite check.

mismatches

mismatches: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that a string (first input, actual) does not match a RegExp (second input, expected). Returns the string if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.mismatches('hi', /^h/); // returns `undefined`
checkWrap.mismatches('hi', /^g/); // returns `'hi'`

Returns

The value if the check passes, otherwise undefined.

See

checkWrap.matches : the opposite check.

notDeepEquals

notDeepEquals: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that two values are not deeply equal using the deep-eql package. Returns the first value if the check 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 {checkWrap} from '@augment-vir/assert';

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

checkWrap.deepEquals('1', 1); // true

checkWrap.deepEquals({a: 'a'}, {a: 'a'}); // false

const objectExample = {a: 'a'};
checkWrap.deepEquals(objectExample, objectExample); // false

Returns

The first value if the check passes, otherwise undefined.

See

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

notEntriesEqual

notEntriesEqual: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that two objects are not deeply equal by checking only their top-level values for strict (non-deep, reference, using ===) equality. If the check passes the first object is returned. If not, undefined is returned.

Performs no type guarding.

Example

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

checkWrap.notEntriesEqual({a: 'a'}, {a: 'a'}); // returns `undefined`

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

const bExample = {b: 'b'};
checkWrap.notEntriesEqual({a: bExample}, {a: bExample}); // returns `undefined`

Returns

The first input if the assertion passes, otherwise undefined.

See

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

notInstanceOf

notInstanceOf: (<const Actual, const Instance>(instance: Actual, constructor: Constructor<Instance>) => undefined | Exclude<Actual, Instance>) = ...

Checks that a value is not an instance of the given class constructor. Returns the value if the check passes, otherwise undefined.

Type guards the value.

Type declaration

- <const Actual, const Instance>(instance, constructor): undefined | Exclude<Actual, Instance>
- Type Parameters
  - const Actual
  - const Instance
  Parameters
  - instance: Actual
  - constructor: Constructor<Instance>
  Returns undefined | Exclude<Actual, Instance>
  The value if the check passes, otherwise undefined.

Example

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

checkWrap.notInstanceOf(/abc/, RegExp); // returns `undefined`
checkWrap.notInstanceOf('abc', RegExp); // returns `'abc'`

See

checkWrap.instanceOf : the opposite check.

notJsonEquals

notJsonEquals: CheckWrapFunction<unknown> = autoGuardSymbol

Checks 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 check passes.

Performs no type guarding.

Example

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

checkWrap.notJsonEquals({a: 'a'}, {a: 'a'}); // false

checkWrap.notJsonEquals({a: {b: 'b'}}, {a: {b: 'c'}}); // true

See

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

notLooseEquals

notLooseEquals: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that two values are not loosely equal (using ==). Returns the first value if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.notLooseEquals('a', 'a'); // returns `undefined`

checkWrap.notLooseEquals('1', 1); // returns `undefined`

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

const objectExample = {a: 'a'};
checkWrap.notLooseEquals(objectExample, objectExample); // returns `undefined`

Returns

The first value if the check passes, otherwise undefined.

See

checkWrap.looseEquals : the opposite check.
checkWrap.strictEquals : the strict equality check.

notStrictEquals

notStrictEquals: CheckWrapFunction<unknown> = autoGuardSymbol

Checks that two values are not strictly equal (using ===). Returns the first value if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.notStrictEquals('a', 'a'); // returns `undefined`

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

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

const objectExample = {a: 'a'};
checkWrap.notStrictEquals(objectExample, objectExample); // returns `undefined`

Returns

The first value if the check passes, otherwise undefined.

See

checkWrap.strictEquals : the opposite check.
checkWrap.notLooseEquals : the loose equality check.

output

output: {
<const FunctionToCall>(functionToCall: FunctionToCall, inputs: Parameters<NoInfer<FunctionToCall>>, expectedOutput: Awaited<ReturnType<NoInfer<FunctionToCall>>>, failureMessage?: string): OutputReturn<FunctionToCall, Awaited<ReturnType<NoInfer<FunctionToCall>>> | undefined>;
<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>>> | undefined>;
} = checkWrapOutput

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 check passes, otherwise undefined.

Performs no type guarding.

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

checkWrap.output((input: number) => String(input), [5], '5'); // returns `'5'`
checkWrap.output((input: number) => String(input), [10], '5'); // returns `undefined`

checkWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [5], 2); // returns `undefined`
checkWrap.output(assert.isLengthAtLeast, (input: number) => String(input), [10], 2); // returns `10`

Returns

The output if the assertion passes, otherwise undefined.

startsWith

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

Checks that a parent string or array starts with a specific child. This uses reference equality when the parent is an array. Returns the value if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.startsWith('ab', 'b'); // returns `undefined`
checkWrap.startsWith('ab', 'a'); // returns `'ab'`
checkWrap.startsWith(
    [
        'a',
        'b',
    ],
    'b',
); // returns `undefined`
checkWrap.startsWith(
    [
        'a',
        'b',
    ],
    'a',
); // returns `['a', 'b']`

Returns

The first value if the check passes, otherwise undefined.

See

checkWrap.startsWithout : the opposite check.
checkWrap.endsWith : check on the other end.

startsWithout

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

Checks that a parent string or array starts with a specific child. This uses reference equality when the parent is an array. Returns the value if the check passes, otherwise undefined.

Performs no type guarding.

Example

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

checkWrap.startsWith('ab', 'b'); // returns `undefined`
checkWrap.startsWith('ab', 'a'); // returns `'ab'`
checkWrap.startsWith(
    [
        'a',
        'b',
    ],
    'b',
); // returns `undefined`
checkWrap.startsWith(
    [
        'a',
        'b',
    ],
    'a',
); // returns `['a', 'b']`

Returns

The first value if the check passes, otherwise undefined.

See

checkWrap.startsWithout : the opposite check.
checkWrap.endsWith : check on the other end.

strictEquals

strictEquals: (<Actual, Expected>(actual: Actual, expected: Expected) => undefined | Expected) = ...

Checks that two values are strictly equal (using ===). Returns the first value if the check passes, otherwise undefined.

Type guards the first value.

Type declaration

- <Actual, Expected>(actual, expected): undefined | Expected
- Type Parameters
  - Actual
  - Expected
  Parameters
  - actual: Actual
  - expected: Expected
  Returns undefined | Expected
  The first value if the check passes, otherwise undefined.

Example

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

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

checkWrap.strictEquals('1', 1); // returns `undefined`

checkWrap.strictEquals({a: 'a'}, {a: 'a'}); // returns `undefined`

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

See

checkWrap.notStrictEquals : the opposite check.
checkWrap.looseEquals : the loose equality check.

throws

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

If a function input is provided:

Calls that function and checks that the function throw an error, comparing the error with the given ErrorMatchOptions, if provided. Returns the error if the check passes, otherwise undefined.

If a promise is provided:

Awaits the promise and checks that the promise rejected with an error, comparing the error with the given ErrorMatchOptions, if provided. Returns the error if the check passes, otherwise undefined.

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

checkWrap.throws(() => {
    throw new Error();
}); // returns the thrown error
await checkWrap.throws(Promise.reject()); // returns the rejection
checkWrap.throws(() => {}); // returns `undefined`

Returns

The Error if the check passes, otherwise undefined.

Function checkWrap

Example

Package

Type Parameters

Parameters

Returns undefined | T

Index

Properties

Properties

deepEquals

Type declaration

Type Parameters

Parameters

Returns undefined | NarrowToExpected<Actual, Expected>

Example

See

endsWith

Example

Returns

See

endsWithout

Example

Returns

See

entriesEqual

Type declaration

Type Parameters

Parameters

Returns undefined | NarrowToExpected<Actual, Expected>

Example

See

hasKey

Type declaration

Type Parameters

Parameters

Returns undefined | CombineTypeWithKey<Key, Parent>

Example

See

hasKeys

Type declaration

Type Parameters

Parameters

Returns undefined | CombineTypeWithKey<Keys, Parent>

Example

See

hasValue

Example

See

hasValues

Example

See

instanceOf

Type declaration

Type Parameters

Parameters

Returns undefined | Instance

Example

See

isAbove

Example

Returns

See

isApproximately

Example

Returns

See

isArray

Type declaration

Type Parameters

Parameters

Returns undefined | ArrayNarrow<Actual>

Example

See

isAtLeast

Example

Returns

See

isAtMost

Example

Returns