Introduced in 4.0.0

Stability: 2 - Stable

Assert extends Validate and provides a test-friendly interface which returns true or throws. It also provides an expected-error interface for anti-testing, which will return true for specified error message(s), but throw for any others.

The Assert library should be used for building tests, or to protect code from execution when input sanity is not achieved.

The Validate parent library should be used for boolean evaluations, eg: if statements or other logic.

const { Assert, expect } = require('kado/lib/Assert')

Class: AssertionError


This constructor takes a string for easier setup. It extends the standard AssertionError and is the same other than the simplified allowance of string input on the constructor. It is available via alias Assert.Error which should be used instead to ensure it not be assumed to be the standard method.

Class: Assert

Extends Validate class. Evaluates data, types, or other conditions to either return boolean true or throw.

static Assert.getInstance(data)


Stateful functions

These are used upon an instance, with the data provided in the constructor








Static (stateless) functions

These are the base functions which wire back to Validate methods. All these methods have common return and throw behavior (except where specified):

static Assert.assert(val1, val2)

Loosely asserts data types to okay and has logic to improve matching types:

If none of the above types are passed, the assertion will be tested against Assert.eq(val1, val2)

static, val2, options)

With no options, valid when val1 is the exact same date as val2

When granularity is used, time is subdivided by the provided milliseconds and val1 should be in the same subdivision as val2 to be considered valid.

When distance is used, val1 difference from val2 should be equal to or less than provided milliseconds to be considered valid.

static Assert.ensure(type, val)

This method will coerce input of various types into an acceptable version of that input, even when the type does not match. WARNING, will coerce data into different types. It is important to understand the mechanics of data coercion and why user input must be sanitized before using a method like this.


const someString = 'foo'
const arr = Assert.ensure('Array', someString) // ['foo']
const obj = Assert.ensure('Object', someString) // { a: 'foo' }
const i = Assert.ensure('Number', someString) // Assert.Error

Types can be referenced by their short version see below.


const someNum = '0'
const num = Assert.ensure('num', somNum) // 0

static Assert.eq(val1, val2)

Valid when val1 equal to val2

static Assert.eqDeep(val1, val2)

Valid when val1 deeply matches val2 Note: Uses Node.js->assert->deepStrictEqual for evaluations

static Assert.neq(val1, val2)

Valid when val1 not equal to val2

static Assert.getType(val)

Utility method to obtain type or class, internally used by the next method:

static Assert.isType(type, value)

Valid when type or class of value matches

static Assert.isAbove(base, test)

Valid when test is greater than base

static Assert.isBelow(base, test)

Valid when test is less than base

static Assert.minimum(base, test)

Valid when test is greater than or equal to base

static Assert.maximum(base, test)

Valid when test is less than or equal to base

static Assert.isOk(value, message)

static Assert.catch(v1, v2, msg, method)

Comparison modes supported for msg:

Also, msg can be an Array of any of the above supported types to allow for "any" style multi-matching. At least one must match or the catch falls through.

Catch Wrappers

These methods allow for expected/approved throw(s) to occur within the target method call. These methods return true, otherwise they throw again in a pass through fashion. These are generally used for anti-testing to ensure the bounds and type checks are working.

The msg argument is the same as documented in the parent method.

Assert.assert.catch(val1, val2, msg)

Assert.eq.catch(val1, val2, msg)

Assert.eqDeep.catch(val1, val2, msg)

Assert.isType.catch(type, value, msg)

Assert.isAbove.catch(base, test, msg)

Assert.isBelow.catch(base, test, msg)

Assert.minimum.catch(base, test, msg)

Assert.maximum.catch(base, test, msg)

Assert.neq.catch(val1, val2, msg)

Assert.isOk.catch(value, message, msg)