mylesmegyesi /
hamcrest.js
An extensible assertion library for JavaScript, based on Hamcrest
Active repository
TypeScriptMIT#assert#assertion#assertion-checking#assertion-framework
⑂ 0 forks◯ 0 issuesUpdated Jul 6, 2018
Loading repository data…
JS-DevTools / repository
assert
An assertion library with user-friendly error messages
#assert#assertion-library#assertions#input-validation#javascript#nodejs
Live repository statistics
★ 1Stars
⑂ 1Forks
◯ 0Open issues
◉ 1Watchers
README preview
Assert
An assertion library with user-friendly error messages
Features
-
When an assertion succeeds, the value is returned. Useful for assertion + assignment.
-
Throws appropriate error types for each assertion (e.g.
TypeError,RangeError, etc.) -
Error messages include the invalid value, humanized and sanitized
-
You can customize the field name used in error messages
Installation
You can install this library via npm.
npm install @jsdevtools/assert
Usage
The exported assert function supports fluent-like chaining with various assertion functions. Each of the assertion functions returns the value if valid, or throws an error if invalid.
assert.value(value, [fieldName], [defaultValue])
Asserts that a value that is not undefined. Any other value will pass, even null and NaN.
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.value(0); // ✔
assert.value(false); // ✔
assert.value(null); // ✔
assert.value(NaN); // ✔
assert.value(undefined); // ❌ Invalid value: undefined. A value is required.
assert.value.oneOf(value, values, [fieldName], [defaultValue])
Assets that a value that is one of the specified values.
- value - The value to check
- values - The allowed values
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.value.oneOf("a", ["a", "b", "c"]); // ✔
assert.value.oneOf(4, [1, 2, 3, 4, 5]); // ✔
assert.value.oneOf(true, [1, true, "yes"]); // ✔
assert.value.oneOf("b", ["x", "y", "z"]); // ❌ Invalid value: "b". Expected "x", "y", or "z".
assert.type(value, type, [fieldName], [defaultValue])
Asserts that a value is the specified type.
- value - The value to check
- type - The expected type. This can be a class, a primitive wrapper (e.g.
String),null, orundefined - fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type("John", String); // ✔
assert.type(42, Number); // ✔
assert.type(false, Boolean); // ✔
assert.type(null, null); // ✔
assert.type({ x: 1 }, Object); // ✔
assert.type(/^regex$/, RegExp); // ✔
assert.type(new Date(), Date); // ✔
assert.type("Fred", Object); // ❌ Invalid value: "Fred". Expected an Object.
assert.type(100, BigInt); // ❌ Invalid value: 100. Expected a bigint.
assert.type(undefined, null); // ❌ Invalid value: undefined. Expected null.
assert.type(null, Object); // ❌ Invalid value: null. Expected an Object.
assert.type(new Date(), RangeError); // ❌ Invalid value: Date. Expected a RangeError.
assert.type.oneOf(value, types, [fieldName], [defaultValue])
Asserts that a value is one of the specified types.
- value - The value to check
- types - An array of the allowed types.
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type.oneOf("John", [Number, String, Boolean]); // ✔
assert.type.oneOf(42, [Number, BigInt, Date]); // ✔
assert.type.oneOf(null, [null, undefined]); // ✔
assert.type.oneOf(new RangeError(), [TypeError, RangeError]); // ✔
assert.type.oneOf("Fred", [Number, Boolean, Object]); // ❌ Invalid value: "Fred". Expected a number, boolean, or Object.
assert.type.oneOf(undefined, [Boolean, Number, null]); // ❌ Invalid value: undefined. Expected a boolean, number, or null.
assert.type.oneOf(new SyntaxError(), [TypeError, RangeError]); // ❌ Invalid value: SyntaxError. Expected a TypeError or RangeError.
assert.type.string(value, [fieldName], [defaultValue])
Asserts that a value is a primitive string (including empty strings).
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type.string("John"); // ✔
assert.type.string(""); // ✔
assert.type.string(" "); // ✔
assert.type.string("\n"); // ✔
assert.type.string("\t"); // ✔
assert.type.string(123); // ❌ Invalid value: 123. Expected a string.
assert.type.string(null); // ❌ Invalid value: null. Expected a string.
assert.type.string(new String()); // ❌ Invalid value: String. Expected a string.
assert.type.number(value, [fieldName], [defaultValue])
Asserts that a value is a primitive number. NaN is not considered a number.
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type.number(0) // ✔
assert.type.number(123) // ✔
assert.type.number(-42.1245) // ✔
assert.type.number(Math.PI) // ✔
assert.type.number(Infinity) // ✔
assert.type.number("123"); // ❌ Invalid value: "123". Expected a number.
assert.type.number(NaN); // ❌ Invalid value: NaN. Expected a number.
assert.type.number(new Number()); // ❌ Invalid value: Number. Expected a number.
assert.type.boolean(value, [fieldName], [defaultValue])
Asserts that a value is a primitive boolean value.
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type.boolean(false) // ✔
assert.type.boolean(true) // ✔
assert.type.boolean("true"); // ❌ Invalid value: "true". Expected a boolean.
assert.type.boolean(0); // ❌ Invalid value: 0. Expected a boolean.
assert.type.boolean(1); // ❌ Invalid value: 1. Expected a boolean.
assert.type.boolean(new Boolean()); // ❌ Invalid value: Boolean. Expected a boolean.
assert.type.object(value, [fieldName], [defaultValue])
Asserts that a value is an object. null is not considered an object.
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type.object({}) // ✔
assert.type.object(/^regex$/) // ✔
assert.type.object(new Date()) // ✔
assert.type.object(new Object()) // ✔
assert.type.object(Object.prototype) // ✔
assert.type.object(null); // ❌ Invalid value: null. Expected an object.
assert.type.object(undefined); // ❌ Invalid value: undefined. A value is required.
assert.type.object(Object); // ❌ Invalid value: function. Expected an object.
assert.type.array(value, [fieldName], [defaultValue])
Asserts that a value is an array.
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type.array([]) // ✔
assert.type.array([1, 2, 3]) // ✔
assert.type.array(new Array()) // ✔
assert.type.array(Array.prototype) // ✔
assert.type.array("hello"); // ❌ Invalid value: "hello". Expected an array.
assert.type.array(Array); // ❌ Invalid value: function. Expected an array.
assert.type.function(value, [fieldName], [defaultValue])
Asserts any type of function, including async, generators, arrow functions, classes, etc.
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.type.function(Object) // ✔
assert.type.function(Object.toString) // ✔
assert.type.function(function foo() {}) // ✔
assert.type.function(() => null) // ✔
assert.type.function(class Foo {}) // ✔
assert.type.function(null); // ❌ Invalid value: null. Expected a function.
assert.type.function(new Object()); // ❌ Invalid value: {}. Expected a function.
assert.type.function("function"); // ❌ Invalid value: "function". Expected a function.
assert.string(value, [fieldName], [defaultValue])
This is an alias for assert.type.string()
assert.string.nonEmpty(value, [fieldName], [defaultValue])
Asserts that a value is a string with at least one character (including whitespace).
- value - The value to check
- fieldName - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
- defaultValue - (optional) The default value to use if
valueisundefined.
import assert from "@jsdevtools/assert";
assert.string.nonEmpty("John") // ✔
assert.string.nonEmpty(" ") // ✔
assert.string.nonEmpty("\n") // ✔
assert.string.nonEmpty("\t") // ✔
assert.string.nonEmpty(""); // ❌ Invalid value: "". It cannot be empty.
assert.string.nonEmpty(null); // ❌ Invalid value: null. Expected a string.
assert.string.nonEm
ALGORITHMICALLY RELATED
Similar Open-Source Projects
Selected from shared topics, language and repository description—not editorial ratings.
★ 2