A functional assertion library for ECMAScript.

Created by Kris Walker 2017 - 2023.

AMD and Browserify are supported. Or include in your HTML:

<script src="./kixx-assert.js" type="text/javascript"></script>

Then use in your JavaScript:

var KixxAssert = window.KixxAssert;

Install with NPM on the command line:

$ npm install --save kixx-assert

Then use in your project:

const KixxAssert = require('kixx-assert');

Errors

• AssertionError

Assertions

• isOk(subject, reason)
• isNotOk(subject, reason)
• isEqual(expected, actual, reason)
• isNotEqual(expected, actual, reason)
• isMatch(pattern, actual, reason)
• isNotMatch(pattern, actual, reason)
• isUndefined(subject, reason)
• isDefined(subject, reason)
• isEmpty(subject, reason)
• isNotEmpty(subject, reason)
• includes(item, subject, reason)
• doesNotInclude(item, subject, reason)
• has(key, subject, reason)
• doesNotHave(key, subject, reason)
• isGreaterThan(a, b, reason)
• isLessThan(a, b, reason)
• isNonEmptyString(subject, reason)
• isNumberNotNaN(subject, reason)

helpers

• identity(x)
• complement(f)
• type(v)
• keys(x)
• has(prop, x)
• equal(a, b)
• greaterThan(a, b)
• lessThan(a, b)
• match(matcher, x)
• isPrimitive(x)
• isString(x)
• isNumber(x)
• isBoolean(x)
• isArray(x)
• isObject(x)
• isFunction(x)
• isNull(x)
• isUndefined(x)
• isDefined(x)
• isNumberNotNaN(x)
• isNonEmptyString(x)
• isEmpty(x)
• isNotEmpty(x)
• includes(item, list)
• doesNotInclude(item, list)
• toString(item, list)
• printf(pattern, ..rest)
• assertion1(guard, reason)
• assertion2(guard, reason)

An Error constructor used to identify assertion errors. Passing in a caller can help isolate stack traces to make them more usable.

Access in browsers: window.KixxAssert.AssertionError;

Access in Node.js: require('kixx-assert').AssertionError;

// Example:
function myFunction() {
    throw new KixxAssert.AssertionError('test error', null, myFunction);
}

// Implementation:
function AssertionError (message, props, caller) {
    this.message = message || 'Unspecified AssertionError';
    caller = caller || AssertionError;
    Error.captureStackTrace(this, caller);
}

AssertionError.prototype = Object.create(Error.prototype);

AssertionError.prototype.name = 'AssertionError';

AssertionError.prototype.constructor = AssertionError;

Access in browsers: window.KixxAssert.assert;

Access in Node.js: require('kixx-assert').assert;

KixxAssert.assert.isOk(subject, reason)

Passes if the subject is truthy.

KixxAssert.assert.isNotOk(subject, reason)

Passes if the subject is falsy.

KixxAssert.assert.isEqual(expected, actual, reason)

Passes if expected strictly equals === actual.

KixxAssert.assert.isNotEqual(expected, actual, reason)

Passes if expected does not strictly equal === actual.

KixxAssert.assert.isMatch(pattern, actual, reason)

Passes if actual matches the pattern String or RegExp.

KixxAssert.assert.isNotMatch(pattern, actual, reason)

Passes if actual does not match the pattern String or RegExp.

KixxAssert.assert.isUndefined(subject, reason)

Passes if the subject is undefined. Fails if the subject is null or false.

KixxAssert.assert.isDefined(subject, reason)

Passes if the subject is anything other than undefined.

KixxAssert.assert.isEmpty(subject, reason)

Passes if the subject is an empty Array, String, or Object with no enumerable properties. Also passes for all primitives which are falsy.

KixxAssert.assert.isNotEmpty(subject, reason)

Passes if the subject is a non empty Array, String, or Object with enumerable properties. Also passes for all primitives which are truthy.

KixxAssert.assert.includes(item, subject, reason)

Passes if the subject contains the item. In the case of a String, the item must be a character contained in the subject. In the case of an Array, any primitive or object which strictly equals an item in the Array will pass. In the case of an Object, any primitive or object strictly equals an enumerable property of the Object will pass.

KixxAssert.assert.doesNotInclude(item, subject, reason)

Passes if the subject does not contain the item. In the case of a String, the item must be a character not in the subject. In the case of an Array, any primitive or object which strictly equals an item in the Array will fail. In the case of an Object, any primitive or object strictly equals an enumerable property of the Object will fail.

KixxAssert.assert.has(key, subject, reason)

Passes if subject has own property key.

KixxAssert.assert.doesNotHave(key, subject, reason)

Passes if subject does not have own property key.

KixxAssert.assert.isGreaterThan(a, b, reason)

Assertion will pass if b is greater than a.

KixxAssert.assert.isLessThan(a, b, reason)

Assertion will pass if b is less than a.

KixxAssert.assert.isNonEmptyString(subject, reason)

Passes if subject is a String with length greater than 0.

KixxAssert.assert.isNumberNotNaN(subject, reason)

Passes if subject is a Number but not NaN.

Access in browsers: window.KixxAssert.helpers;

Access in Node.js: require('kixx-assert').helpers;

KixxAssert.helpers.identity(x)

Returns the input value x.

A function that does nothing but return the parameter supplied to it. Good as a default or placeholder function.

KixxAssert.helpers.complement(f)

Returns a new Function which will call f.

Takes a function f and returns a function g such that if called with the same arguments when f returns a "truthy" value, g returns false and when f returns a "falsy" value g returns true.

KixxAssert.helpers.type(v)

Returns a String representing the type of the value.

Gives a single-word string description of the (native) type of a value, returning such answers as 'Object', 'Number', 'Array', or 'Null'. Does not attempt to distinguish user Object types any further, reporting them all as 'Object'.

KixxAssert.helpers.keys(x)

Returns an Array of the object's own enumerable property names.

Returns a list containing the names of all the enumerable own properties of the supplied object. Note that the order of the output array is not guaranteed to be consistent across different JS platforms.

KixxAssert.helpers.has(prop, x)

Returns a Boolean indicating if the property exists.

Returns whether or not an object has an own property with the specified name.

KixxAssert.helpers.equal(a, b)

Returns a Boolean indicating if a and b are strict equal.

Determine if both arguments are strict equal (===).

KixxAssert.helpers.greaterThan(a, b)

Returns a Boolean indicating if b is greater than (>) a.

Deterimine if the second argument is greater than the first.

KixxAssert.helpers.lessThan(a, b)

Returns a Boolean indicating if b is less than (<) a.

Deterimine if the second argument is less than the first.

KixxAssert.helpers.match(matcher, x)

Returns a Boolean indicating if x matches matcher.

Determine if the second argument matches the first using a RegExp or String match. If the first argument is a String the second argument will be matched against it using ===. Otherwise the first argument is assumed to be a RegExp and will be matched using .test().

KixxAssert.helpers.isPrimitive(x)

Returns a Boolean indicating if x is not an Object or is null.

Indicate if the argument is not an object, or is null.

KixxAssert.helpers.isString(x)

Returns a Boolean indicating if x is a String.

Indicate if the argument is a String.

KixxAssert.helpers.isNumber(x)

Returns a Boolean indicating if x is a number.

Indicate if the argument is a number or NaN.

KixxAssert.helpers.isBoolean(x)

Returns a Boolean indicating if x is a Boolean.

Indicate if the argument is a Boolean.

KixxAssert.helpers.isArray(x)

Returns a Boolean indicating if x is an Array.

Indicate if the argument is an Array.

KixxAssert.helpers.isObject(x)

Returns a Boolean indicating if x is a plain Object.

Indicate if the argument is a plain Object. It will return false for Dates, RegExp, Arrays, etc.

KixxAssert.helpers.isFunction(x)

Returns a Boolean indicating if x is a Function.

Indicate if the argument is a Function.

KixxAssert.helpers.isNull(x)

Returns a Boolean indicating if x is null.

Indicate if the argument is null. It will return false for undefined.

KixxAssert.helpers.isUndefined(x)

Returns a Boolean indicating if x is not defined.

Indicate if the argument is not defined using typeof x === 'undefined'.

KixxAssert.helpers.isDefined(x)

Returns a Boolean indicating if x is defined.

Indicate if the argument is anything other than undefined, even null.

KixxAssert.helpers.isNumberNotNaN(x)

Returns a Boolean indicating that x is a Number but not NaN.

Indicate if the first argument is a Number, but not NaN.

KixxAssert.helpers.isNonEmptyString(x)

Returns a Boolean indicating that x is a String with length greater than 0.

Indicate if the first argument is a String with length greater than zero.

KixxAssert.helpers.isEmpty(x)

Returns a Boolean indicating that x has its type's empty value.

Returns Boolean true if the first argument is an empty Array, String, or Object with no enumerable properties. Returns Boolean true for all primitives which are falsy and Boolean false for all primitives which are truthy.

KixxAssert.helpers.isNotEmpty(x)

Returns a Boolean indicating that x does not have its type's empty value.

Returns Boolean true if the first argument is an empty Array, String, or Object with more than zero enumerable properties. Returns Boolean true for all primitives which are truthy and Boolean false for all primitives which are falsy.

KixxAssert.helpers.includes(item, list)

Returns a Boolean indicating that item was found in list using the === comparator.

Returns Boolean true if the second argument is an Array, String, or Object which contains the first argument. In the case of a String, the first argument must be a character contained in the second argument to return true. In the case of an Array, any primitive or object which compares with === will return true. In the case of an Object, any primitive or object which is an enumerable property of the Object and compares wth === will return true.

KixxAssert.helpers.doesNotInclude(item, list)

Returns a Boolean indicating that item was not found in list using the === comparator.

Returns Boolean true if the second argument is an Array, String, or Object which does not contain the first argument. In the case of a String, the first argument must be a character which is not contained in the second argument to return true. In the case of an Array, any primitive or object which compares with === will return false. In the case of an Object, any primitive or object which is an enumerable property of the Object and compares wth === will return false.

KixxAssert.helpers.toString(x)

Returns a String representation of x.

console.log(helpers.toString('foo')); // String("foo")
console.log(helpers.toString(true)); // Boolean(true)
console.log(helpers.toString(99)); // Number(99)
console.log(helpers.toString()); // undefined
console.log(helpers.toString(null)); // null
console.log({}); // Object({})
console.log(Object.create(null)); // [object Object]
console.log(new Cat()); // Cat({})

KixxAssert.helpers.printf(pattern, ...rest)

Returns a String.

If the first argument is a string with replacement patterns (starting with "%") then the following arguments are stringified and replaced. If the first argument is a string with no replacement patterns it will be returned alone. If the first argument is not a string, then all arguments will simply be stringified, separated by spaces.

console.log(heleprs.printf('foo')); // foo
console.log(helpers.printf('foo %d %x'), 1, null); // foo Number(1) null
console.log(helpers.printf({foo: 'bar'}, 1, null)); // Object({}) Number(1) null

KixxAssert.helpers.assertion1(guard, reason)

Returns a composed assertion Function.

The returned assertion Function will through an AssertionError if the call to the guard() returns false.

const isEmpty = assertion1(isEmpty, function (actual) {
    return printf('expected %x to be empty', actual);
});

isEmpty([1], 'Is it empty?'); // Will throw AssertionError

KixxAssert.helpers.assertion1(guard, reason)

Returns a composed assertion Function.

The returned assertion Function will throw an AssertionError if the call to the guard() returns false. If the returned assertion function is called with only 1 argument, it will automatically curry, returning a function which will accept the remaining 2 arguments.

const isEqual = assertion2(helpers.equal, function (expected, actual) {
    return printf('expected %x to equal %x', actual, expected);
});

const isEqualToFoo = isEqual('foo');

isEqualToFoo('bar', 'is it equal to "foo"?'); // Will throw AssertionError

Copyright: (c) 2017 - 2023 by Kris Walker (www.kriswalker.me)

Unless otherwise indicated, all source code is licensed under the MIT license. See MIT-LICENSE for details.