kixx-assert v1.1.1

Kixx Assert

A functional assertion library for ECMAScript.

Install in the browser:

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 in a Node.js project:

Install with NPM on the command line:

$ npm install --save kixx-assert

Then use in your project:

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

API

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)

AssertionError

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;

Assertions

Access in browsers: window.KixxAssert.assert;

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

assert.isOk

KixxAssert.assert.isOk(subject, reason)

Passes if the subject is truthy.

assert.isNotOk

KixxAssert.assert.isNotOk(subject, reason)

Passes if the subject is falsy.

assert.isEqual

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

Passes if expected strictly equals === actual.

assert.isNotEqual

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

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

assert.isMatch

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

Passes if actual matches the pattern String or RegExp.

assert.isNotMatch

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

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

assert.isUndefined

KixxAssert.assert.isUndefined(subject, reason)

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

assert.isDefined

KixxAssert.assert.isDefined(subject, reason)

Passes if the subject is anything other than undefined.

assert.isEmpty

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.

assert.isNotEmpty

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.

assert.includes

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.

assert.doesNotInclude

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.

assert.has

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

Passes if subject has own property key.

assert.doesNotHave

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

Passes if subject does not have own property key.

assert.isGreaterThan

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

Assertion will pass if b is greater than a.

assert.isLessThan

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

Assertion will pass if b is less than a.

assert.isNonEmptyString

KixxAssert.assert.isNonEmptyString(subject, reason)

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

assert.isNumberNotNaN

KixxAssert.assert.isNumberNotNaN(subject, reason)

Passes if subject is a Number but not NaN.

Helpers

Access in browsers: window.KixxAssert.helpers;

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

helpers.identity

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.

helpers.complement

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.

helpers.type

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'.

helpers.keys

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.

helpers.has

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.

helpers.equal

KixxAssert.helpers.equal(a, b)

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

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

helpers.greaterThan

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.

helpers.lessThan

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.

helpers.match

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().

helpers.isPrimitive

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.

helpers.isString

KixxAssert.helpers.isString(x)

Returns a Boolean indicating if x is a String.

Indicate if the argument is a String.

helpers.isNumber

KixxAssert.helpers.isNumber(x)

Returns a Boolean indicating if x is a number.

Indicate if the argument is a number or NaN.

helpers.isBoolean

KixxAssert.helpers.isBoolean(x)

Returns a Boolean indicating if x is a Boolean.

Indicate if the argument is a Boolean.

helpers.isArray

KixxAssert.helpers.isArray(x)

Returns a Boolean indicating if x is an Array.

Indicate if the argument is an Array.

helpers.isObject

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.

helpers.isFunction

KixxAssert.helpers.isFunction(x)

Returns a Boolean indicating if x is a Function.

Indicate if the argument is a Function.

helpers.isNull

KixxAssert.helpers.isNull(x)

Returns a Boolean indicating if x is null.

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

helpers.isUndefined

KixxAssert.helpers.isUndefined(x)

Returns a Boolean indicating if x is not defined.

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

helpers.isDefined

KixxAssert.helpers.isDefined(x)

Returns a Boolean indicating if x is defined.

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

helpers.isNumberNotNaN

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.

helpers.isNonEmptyString

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.

helpers.isEmpty

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.

helpers.isNotEmpty

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.

helpers.includes

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.

helpers.doesNotInclude

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.

helpers.toString

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({})

helpers.printf

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

helpers.assertion1

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

helpers.assertion2

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 and License

Copyright: (c) 2017 - 2022 by Kris Walker (www.kixx.name)

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