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 value is undefined.
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.
Asserts that a value is a string with at least one non-whitespace character.
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 value is undefined.
import assert from "@jsdevtools/assert";assert.string.nonWhitespace("John") // ✔assert.string.nonWhitespace(" a ") // ✔assert.string.nonWhitespace(""); // ❌ Invalid value: "". It cannot be empty.assert.string.nonWhitespace(" "); // ❌ Invalid value: " ". It cannot be all whitespace.assert.string.nonWhitespace("\n") // ❌ Invalid value: "\n". It cannot be all whitespace.assert.string.nonWhitespace("\t") // ❌ Invalid value: "\t". It cannot be all whitespace.assert.string.nonWhitespace(new String()); // ❌ Invalid value: String. Expected a string.
Asserts that a value is a string with at least the specified number of characters (including whitespace).
value - The value to check
minLength - The minimum allowed length
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 value is undefined.
import assert from "@jsdevtools/assert";assert.string.minLength("John", 1) // ✔assert.string.minLength(" a ", 5) // ✔assert.string.minLength("", 0) // ✔assert.string.minLength("", 1); // ❌ Invalid value: "". It cannot be empty.assert.string.minLength("John", 10); // ❌ Invalid value: "John". It should be at least 10 characters.
Asserts that a value is a string with no more than the specified number of characters (including whitespace).
value - The value to check
maxLength - The maximum allowed length
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 value is undefined.
import assert from "@jsdevtools/assert";assert.string.maxLength("John", 10) // ✔assert.string.maxLength(" a ", 5) // ✔assert.string.maxLength("", 50) // ✔assert.string.maxLength("John Doe", 5); // ❌ Invalid value: "John Doe". It cannot be more than 5 characters.
Asserts that a value is a string with the specified number of characters (including whitespace)
value - The value to check
minLength - The minimum allowed length
maxLength - (optional) The maximum allowed length. If not specified, it defaults to the same as minLength.
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 value is undefined.
import assert from "@jsdevtools/assert";assert.string.length("John", 1, 10) // ✔assert.string.length(" a ", 5, 25) // ✔assert.string.length("", 0, 100) // ✔assert.string.length("John Doe", 1, 5); // ❌ Invalid value: "John Doe". It cannot be more than 5 characters.assert.string.length("John Doe", 20, 50); // ❌ Invalid value: "John Doe". It should be at least 20 characters.assert.string.length("John Doe", 5); // ❌ Invalid value: "John Doe". It must be exactly 5 characters.
Asserts that a value is a string that matches the specified Regular Expression pattern.
value - The value to check
regex - The regular expression to test
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 value is undefined.
import assert from "@jsdevtools/assert";assert.string.pattern("Foo", /^fo+$/i); // ✔assert.string.pattern("image.jpg", /\.(jpg|jpeg)/); // ✔assert.string.pattern("", /^\w*$/); // ✔assert.string.pattern("foobar", /^fo+$/i); // ❌ Invalid value: "foobar". It must match /^fo+$/i.assert.string.pattern("jpeg.gif", /\.(jpg|jpeg)/); // ❌ Invalid value: "jpeg.gif". It must match /\\.(jpg|jpeg)/.
You can customize the assertion error message by adding an example or examples property to the RegExp object.
import assert from "@jsdevtools/assert";let pattern = /\.(jpg|jpeg)/;pattern.example = "image.jpg";assert.string.pattern("jpeg.gif", pattern); // ❌ Invalid value: "jpeg.gif". It should look like "image.jpg".let pattern = /\.(jpg|jpeg)/;pattern.examples = ["image.jpg", "image.jpeg"];assert.string.pattern("jpeg.gif", pattern); // ❌ Invalid value: "jpeg.gif". It should look like "image.jpg" or "image.jpeg".
Asserts that a value is an array with at least the specified number of items.
value - The value to check
minLength - The minimum allowed length
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 value is undefined.
import assert from "@jsdevtools/assert";assert.array.minLength([], 0); // ✔assert.array.minLength(["a", "b", "c"], 1); // ✔assert.array.minLength([], 1); // ❌ Invalid value: Array. It cannot be empty.assert.array.minLength(["a", "b", "c"], 10); // ❌ Invalid value: [a,b,c]. It should have at least 10 items.
Asserts that a value is an array with no more than the specified number of items.
value - The value to check
maxLength - The maximum allowed length
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 value is undefined.
import assert from "@jsdevtools/assert";assert.array.maxLength([], 5); // ✔assert.array.maxLength(["a", "b", "c"], 3); // ✔assert.array.maxLength([1, 2, 3], 1); // ❌ Invalid value: [1,2,3]. It cannot have more than 1 item.assert.array.maxLength(["a", "b", "c"], 2); // ❌ Invalid value: [a,b,c]. It cannot have more than 2 items.
Clone this repo git clone https://github.com/JS-DevTools/assert.git
Install dependencies npm install
Build the code npm run build
Run the tests npm test
License
@jsdevtools/assert is 100% free and open-source, under the MIT license. Use it however you want.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Big Thanks To
Thanks to these awesome companies for their support of Open Source developers ❤