Blork! Mini runtime type checking in Javascript


Keywords
javascript, validation
License
0BSD
Install
npm install blork@9.3.0

Documentation

Blork! Mini runtime type checking in Javascript

Semantic Release Conventional Commits Prettier GitHub Actions npm

A mini type checker for locking down the external edges of your code. Mainly for use in modules when you don"t know who'll be using the code. Minimal boilerplate code keeps your functions hyper readable and lets them be their beautiful minimal best selves (...or something?)

Blork is fully unit tested and 100% covered (if you're into that!). Heaps of love has been put into the niceness and consistency of error messages, so hopefully you'll enjoy that too.

Contents

Installation

npm install blork

Basic usage

check(): Check individual values

The check() function allows you to test that individual values correspond to a type, and throw a TypeError if not. This is primarily designed for checking function arguments but can be used for any purpose.

check() accepts three arguments:

  1. value The value to check
  2. type The type to check the value against (full reference list of types is available below)
  3. error An optional custom error type to throw if the check fails
import { check } from "blork";

// Checks that pass.
check("Sally", "string"); // No error.
check("Sally", String); // No error.

// Checks that fail.
check("Sally", "number"); // Throws ValueError 'Must be number (received "Sally")'
check("Sally", Boolean); // Throws ValueError 'Must be true or false (received "Sally")'

// Checks that fail (with a custom error thrown).
check(123, "str", ReferenceError); // Throws ReferenceError "Must be string (received 123)"

type will mostly be specified with a type string (a full list of string types is available below) made up of a type identifier (e.g. integer) and one or more modifiers (e.g. str? which will allow string or undefined, !num will allow anything except number, and bool[] will allow an array of booleans).

// Optional types.
check(undefined, "number"); // Throws ValueError 'Must be finite number (received undefined)'
check(undefined, "number?"); // No error.

// Note that null does not count as optional.
check(null, "number?"); // Throws ValueError 'Must be finite number (received null)'

// Inverted types.
check(123, "!str"); // No error.
check(123, "!int"); // Throws ValueError 'Must be anything except integer (received 123)'

// Combined OR types.
check(1234, "int | str"); // No error.
check(null, "int | str"); // Throws ValueError 'Must be integer or string (received null)'

// Combined AND types.
check("abc", "string & !falsy"); // No error.
check("", "string & !falsy"); // Throws ValueError 'Must be string and not falsy (received "")'

// Non-empty types.
check("abc", "str+"); // No error.
check("", "str+"); // Throws ValueError 'Must be non-empty string (received "")'

// Size types.
check([1, 2, 3], "arr{2,4}"); // No error.
check([1], "arr{2,3}"); // Throws ValueError 'Must be plain array (minimum 2) (maximum 3) (received [1])'
check([1, 3, 3, 4], "arr{,3}"); // Throws ValueError 'Must be plain array (maximum 3) (received [1])'
check([1, 2], "arr{3,}"); // Throws ValueError 'Must be plain array (minimum 2) (received [1])'

// Array types.
check([1, 2, 3], "num[]"); // No error.
check(["a", "b"], "num[]"); // Throws ValueError 'Must be plain array containing finite number (received ["a", "b"])'

// Tuple types.
check([1, "a"], "[int, str]"); // No error.
check([1, false], "[int, str]"); // Throws ValueError 'Must be plain array tuple like [integer, string] (received [1, false])'

// Object types.
check({ a: 1 }, "{ camel: integer }"); // No error.
check({ "$": 1 }, "{ camel: integer }"); // Throws ValueError 'Must be plain object like { camelCase string: integer } (received { "$": 1 })'

// String literal types.
check("abc", "'abc'"); // No error.
check("def", "'abc'"); // Throws ValueError 'Must be "abc" (received "def")'

// Number literal types.
check(1234, "1234"); // No error.
check(5678, "1234"); // Throws ValueError 'Must be 1234 (received 5678)'

// Return type.
function get123() { return 123; }
check(get123(), "return string"); // Throws ValueError 'Must return string (received 123)'

// Prefix type.
const name = 123;
check(name, "name: string"); // Throws ValueError 'name: Must be string (received 123)'

add(): Add a custom checker type

Register your own checker using the add() function. This is great if 1) you're going to be applying the same check over and over, or 2) want to integrate your own checks with Blork's built-in types so your code looks clean.

add() accepts three arguments:

  1. name The name of the custom checker (only kebab-case strings allowed and usually prefixed with a unique identifier).
  2. checker A Blork type string, or a custom function that accepts a single argument (the value) and returns true or false.
  3. description A description of the type of value that's valid. Must fit the phrase Must be ${description}, e.g. "positive number" or "unique string". Defaults to the value of the name parameter.
import { add, check } from "blork";

// Register a new checker.
add("myapp-dog-name", "str{1,20}", "valid name for a dog");

// Pass.
check("Fido", "myapp-dog-name"); // No error

// Fail.
check("", "myapp-dog-name"); // Throws ValueError 'Must be valid name for a dog (received "")'

This example shows using a custom function as a Blork checker:

import { add, check } from "blork";

// Register your new fussy checker.
add(
	// Name of checker.
	"myapp-catty",
	// Checker to validate a string containing "cat".
	(v) => typeof v === "string" && v.strToLower().indexOf("cat") >= 0,
	// Description of what the variable _should_ contain.
	// Gets shown in the error message.
	"string containing 'cat'"
);

// Pass.
check("That cat is having fun", "myapp-catty"); // No error.
check("That CAT is having fun", "myapp-catty"); // No error.

// Fail.
check("A dog sits on the chair", "myapp-catty"); // Throws ValueError 'Must be string containing "cat" (received "A dog sits on the chair")'

// Combine a custom checkers with a built-in checker using `&` syntax.
// The value must pass both checks or an error will be thrown.
// This saves you replicating existing logic in your checker.
check("A CAT SAT ON THE MAT", "upper+ & catty"); // No error.
check("A DOG SAT ON THE MAT", "upper+ & catty"); // Throws ValueError 'Must be non-empty uppercase string and string containing 'cat''

checker(): Return a checker function

Retrieve any Blork checker that can be used elsewhere to check the boolean truthyness of a value.

checker() accepts one argument: the type string for the checker function you want to return.

import { checker } from "blork";

// Get a checker function
const isNonEmptyString = checker("str+");

// Use the checker.
isNonEmptyString("abc"); // true
isNonEmptyString(""); // false
isNonEmptyString(84); // false

debug(): Debug any value as a string

Blork exposes its debugger helper function debug(), which it uses to format error messages correctly. debug() accepts any argument and will return a clear string interpretation of the value.

debug() deals well with large and nested objects/arrays by inserting linebreaks and tabs if line length would be unreasonable. Output is also kept cleanish by only debugging 3 levels deep, truncating long strings, and not recursing into circular references.

debug() accepts one argument: the value to be debugged as a string.

import { debug } from "blork";

// Debug primitives.
debug(undefined); // Returns `undefined`
debug(null); // Returns `null`
debug(true); // Returns `true`
debug(false); // Returns `false`
debug(123); // Returns `123`
debug("abc"); // Returns `"abc"`
debug(Symbol("abc")); // Returns `Symbol("abc")`

// Debug functions.
debug(function dog() {}); // Returns `dog()`
debug(function() {}); // Returns `anonymous function()`

// Debug objects.
debug({}); // Returns `{}`
debug({ a: 123 }); // Returns `{ "a": 123 }`
debug(new Promise()); // Returns `Promise {}`
debug(new MyClass()); // Returns `MyClass {}`
debug(new class {}()); // Returns `anonymous class {}`

ValueError: extensible TypeError for debugging

Internally, when there's a problem with a value, Blork will throw a ValueError. This value extends TypeError and standardises error message formats, so errors are consistent and provide the detail a developer should need to debug the issue error quickly and easily.

new ValueError() accepts two arguments:

  1. message The error describing what is wrong with the value, e.g. "Must be string"
  2. value The invalid value so it can appear in the error message, e.g. (received 123)
import { ValueError } from "blork";

// Function that checks its argument.
function myFunc(name) {
	// If name isn't a string, throw a ValueError.
	// (This is essentially what check() does behind the scenes.)
	if (typeof name !== "string") throw new ValueError("Must be string", name, "myFunc(): name");
}

// Call with incorrect name.
myFunc(123); // Throws ValueError 'myFunc(): name: Must be a string (received 123)'

Reference

Types are strings made up of a type identifier (e.g. "promise" or "integer") possibly combined with a modifier (e.g. "?" or "!").

Type identifiers

This section lists all types identifiers that are built into Blork.

Type string Description
primitive Value is any primitive value (undefined, null, booleans, strings, finite numbers)
null Value is null
undefined, undef, void Value is undefined
defined, def Value is not undefined
boolean, bool Value is true or false
true Value is true
false Value is false
truthy Any truthy values (i.e. == true)
falsy Any falsy values (i.e. == false)
zero Value is 0
one Value is 1
nan Value is NaN
number, num Any numbers except NaN/Infinity (using Number.isFinite())
+number, +num, Numbers more than or equal to zero
-number, -num Numbers less than or equal to zero
integer, int Integers (using Number.isInteger())
+integer, +int Positive integers including zero
-integer, -int Negative integers including zero
int8, byte 8-bit integer (-128 to 127)
uint8, octet unsigned 8-bit integer (0 to 255)
int16, short 16-bit integer (-32768 to 32767)
uint16, ushort unsigned 16-bit integer (0 to 65535)
int32, long 32-bit integer (-2147483648 to 2147483647)
uint32, ulong unsigned 32-bit integer (0 to 4294967295)
string, str Any strings (using typeof)
alphabetic alphabetic string (non-empty and alphabetic only)
numeric numeric strings (non-empty and numerals 0-9 only)
alphanumeric alphanumeric strings (non-empty and alphanumeric only)
lower lowercase strings (non-empty and lowercase alphabetic only)
upper UPPERCASE strings (non-empty and UPPERCASE alphabetic only)
camel camelCase strings e.g. variable/function names (non-empty alphanumeric with lowercase first letter)
pascal PascalCase strings e.g. class names (non-empty alphanumeric with uppercase first letter)
snake snake_case strings (non-empty alphanumeric lowercase)
screaming SCREAMING_SNAKE_CASE strings e.g. environment vars (non-empty uppercase alphanumeric)
kebab, slug kebab-case strings e.g. URL slugs (non-empty alphanumeric lowercase)
train Train-Case strings e.g. HTTP-Headers (non-empty with uppercase first letters)
identifier JavaScript identifier names (string starting with _, $, or letter)
path Valid filesystem path (e.g. "abc/def")
absolute, abs Valid absolute path (e.g. "/abc/def" or "C:\abd\def")
relative, rel Valid relative path (e.g. "../abc/def" or "..\abd\def")
function, func Functions (using instanceof Function)
object, obj Plain objects (using typeof && !null and constructor check)
objectlike Any object (using typeof && !null)
iterable Objects with a Symbol.iterator method (that can be used with for..of loops)
circular Objects with one or more circular references (use !circular to disallow circular references)
array, arr Plain arrays (using instanceof Array and constructor check)
arraylike, arguments, args Array-like objects (any object with numeric .length property, e.g. the arguments object)
map Instances of Map
weakmap Instances of WeakMap
set Instances of Set
weakset Instances of WeakSet
promise Instances of Promise
date Instances of Date
future Instances of Date with a value in the future
past Instances of Date with a value in the past
regex, regexp Instances of RegExp (regular expressions)
error, err Instances of Error
evalerror Instances of EvalError
rangeerror Instances of RangeError
referenceerror Instances of ReferenceError
syntaxerror Instances of SyntaxError
typeerror Instances of TypeError
urierror Instances of URIError
symbol Value is Symbol (using typeof)
empty Value is empty (e.g. v.length === 0 (string/array), v.size === 0 (Map/Set), Object.keys(v) === 0 (objects), or !v (anything else)
any, mixed Allow any value (transparently passes through with no error)
json, jsonable Values that can be successfully converted to JSON and back again! (null, true, false, finite numbers, strings, plain objects, plain arrays)

Literal types

If you want to validate a value against a literal string or number etc, you can use that string or number to make a type string:

e.g. 9|10|11 for a value matching either number 9, 10, or 11; or 0|false|'no' for a value matching either the number 0, literal false, or the string "no".

Format Description
"abc", 'abc' Literal strings, e.g. "Dave" or 'Lucy'
1234 Literal numbers, e.g. 1234 or 123.456 or -12
true, false Literal boolean (note you can use truthy and falsy for soft equal
undefined, null Literal undefined and null

Type modifiers

Modifiers can be applied to any string identifier from the list above to modify that type's behaviour, e.g. num? for an optional number (also accepts undefined), str[] for an array of strings, or ["abc", 12|13] for an array tuple containing the string "abc" and the number 12 or 13.

Format Description
(type) Grouped type, e.g. `(num
type1 & type2 AND combined type, e.g. str & upper
`type1 type2`
type[] Array type (all array entries must match type)
[type1, type2] Tuple type (must match tuple exactly)
{ type } Object value type (all own props must match type
{ keyType: type } Object key:value type (keys and own props must match types)
!type Inverted type (opposite is allowed), e.g. !str
type? Optional type (allows type or undefined), e.g. str?
type+ Non-empty type, e.g. str+ or num[]+
type{1,2} Size type, e.g. str{5} or arr{1,6} or map{12,} or set{,6}
return type Changes error message from e.g. Must be true to Must return true
prefix: type Prepend prefix to error message, e.g. name: Must be string or age: Must be integer

Array type modifier

Any string type can be made into an array of that type by appending [] brackets to the type reference. This means the check looks for a plain array whose contents only include the specified type.

// Pass.
check(["a", "b"], "str[]"); // No error.
check([1, 2, 3], "int[]"); // No error.
check([], "int[]"); // No error (empty is fine).
check([1], "int[]+"); // No error (non-empty).

// Fail.
check([1, 2], "str[]"); // Throws ValueError 'Must be plain array containing string (received [1, 2])'
check(["a"], "int[]"); // Throws ValueError 'Must be plain array containing integer (received ["a"])'
check([], "int[]+"); // Throws ValueError 'Must be non-empty plain array containing integer (received [])'

Tuple type modifier

Array tuples can be specified by surrounding types in [] brackets.

// Pass.
check([true, false], "[bool, bool]") // No error.
check(["a", "b"], "[str, str]") // No error.
check([1, 2, 3], "[num, num, num]"); // No error.

// Fail.
check([true, true], "[str, str]") // Throws ValueError 'Must be plain array tuple like [string, string] (received [true, true])'
check([true], "[bool, bool]") // Throws ValueError 'Must be plain array tuple like [boolean, boolean] (received [true])'
check(["a", "b", "c"], "[str, str]") // Throws ValueError 'Must be plain array tuple like [string, string] (received ["a", "b", "c"])'

Object type modifier

Check for objects only containing strings of a specified type by surrounding the type in {} braces. This means the check looks for a plain object whose contents only include the specified type (whitespace is optional). If you specify multiple props (separated by commas) they are treated like OR conditions.

// Pass.
check({ a: "a", b: "b" }, "{str}"); // No error.
check({ a: 1, b: 2 }, "{ int }"); // No error.
check({}, "{int}"); // No error (empty is fine).
check({ a: 1 }, "{int}+"); // No error (non-empty).
check({ a: 1, b: "B" }, "{ int, str }"); // No error (integers or strings are fine).

// Fail.
check({ a: 1, b: 2 }, "{str}"); // Throws ValueError 'Must be plain object like { string: string } (received { a: 1, b: 2 })'
check({ a: "a" }, "{ int }"); // Throws ValueError 'Must be plain object like { string: integer } (received { a: "a" })'
check({}, "{int}+"); // Throws ValueError 'Must be non-empty plain object like { string: integer } (received {})'

A type for the keys can also be specified by using { key: value } format. Again multiple props can be specified separated by commas.

// Pass.
check({ myVar: 123 }, "{ camel: int }"); // No error (key is camelCase).
check({ "my-var": 123 }, "{ kebab: int }"); // No error (key is kebab-case).
check({ "YAS": 123 }, "{ upper: bool }"); // No error (key is UPPERCASE).
check({ a: 1, B: true }, "{ lower: int, upper: bool }"); // No error (a is lowercase and integer, B is UPPERCASE and boolean).

// Fail.
check({ "myVar": 123 }, "{ kebab: int }"); // Throws ValueError 'Must be plain object like { kebab-case string: integer } (received { "myVar": 123 })'
check({ "nope": true }, "{ upper: bool }"); // Throws ValueError 'Must be plain object like { UPPERCASE string: boolean } (received { "nope": true })'

Exact props can be specified by wrapping the key string in quotes (single or double).

// Pass.
check({ name: "Dave" }, '{ "name": str }');
check({ name: "Dave", age: 48 }, '{ "name": str, "age": int }');

// Fail.
check({ name: 123 }, '{ "name": str }'); // Throws ValueError 'Must be plain object like { "name": string } (received etc)"..'
check({ name: "Dave", age: "123" }, '{ "name": str, "age": int }'); // Throws ValueError 'Must be plain object like { "name": string, "age": integer }'(received etc)"

Exact prop checkers and normal checkers can be mixed in the same string type. If an exact key is specified it will be favoured.

// Pass.
check({ name: "Dave", a: 1, b: 2 }, '{ "name": str, lower: int }');

// Fail.
check({ name: "Dave", a: 1, b: false }, '{ "name": str, lower: int }'); // Throws ValueError 'Must be plain object like { "name": string, lowercase string:'integer } (received etc)"

Optional type modifier

Any string type can be made optional by appending a ? question mark to the type reference. This means the check will also accept undefined in addition to the specified type.

// Pass.
check(undefined, "str?"); // No error.
check(undefined, "lower?"); // No error.
check(undefined, "int?"); // No error.
check([undefined, undefined, 123], ["number?"]); // No error.

// Fail.
check(123, "str?"); // Throws ValueError 'Must be string (received 123)'
check(null, "str?"); // Throws ValueError 'Must be string (received null)'

Non-empty type modifier

Any type can be made non-empty by appending a + plus sign to the type reference. This means the check will only pass if the value is non-empty. Specifically this works as follows:

  • Strings: .length is more than 0
  • Map and Set objects: .size is more than 0
  • Objects and arrays: If it has a .length property Number of own properties is not zero (using typeof === "object" && Object.keys())
  • Booleans and numbers: Use truthyness (e.g. true is non-empty, false and 0 is empty)

This is equivalent to the inverse of the empty type.

// Pass.
check("abc", "str+"); // No error.
check([1], "arr+"); // No error.
check({ a: 1 }, "obj+"); // No error.

// Fail.
check(123, "str+"); // Throws ValueError 'Must be non-empty string (received "")'
check([], "arr+"); // Throws ValueError 'Must be non-empty plain array (received [])'
check({}, "obj+"); // Throws ValueError 'Must be non-empty plain object (received {})'

Size type modifier

To specify a size for the type, you can prepend minimum/maximum with e.g. {12}, {4,8}, {4,} or {,8} (e.g. RegExp style quantifiers). This allows you to specify e.g. a string with 12 characters, an array with between 10 and 20 items, or an integer with a minimum value of 4.

// Pass.
check("abc", "str{3}"); // No error (string with exact length 3 characters).
check(4, "num{,4}"); // No error (number with maximum value 4).
check(["a", "b"], "arr{1,}"); // No error (array with more than 1 item).
check([1, 2, 3], "num[]{2,4}"); // No error (array of numbers with between 2 and 4 items).

// Fail.
check("ab", "str{3}"); // Throws ValueError 'Must be string with size 3'
check(4, "num{,4}"); // Throws ValueError 'Must be finite number with maximum size 4'
check(["a", "b"], "arr{1,}"); // Throws ValueError 'Must be array with minimum size 1'
check([1, 2, 3], "num[]{2,4}"); // Throws ValueError 'Must be plain array containing finite number with size between 2 and 4'

Inverted type modifier

Any string type can inverted by prepending a ! exclamation mark to the type reference. This means the check will only pass if the inverse of its type is true.

// Pass.
check(undefined, "!str"); // No error.
check("Abc", "!lower"); // No error.
check(123.456, "!integer"); // No error.
check([undefined, "abc", true, false], ["!number"]); // No error.

// Fail.
check(123, "!str"); // Throws ValueError 'Must be not string (received "abc")'
check(true, "!bool"); // Throws ValueError 'Must be not true or false (received true)'
check([undefined, "abc", true, 123], ["!number"]); // Throws ValueError 'array[3]: Must be not number (received 123)'

Prefix and return type modifiers

Both of these modifiers modify the message of the error message that is thrown if the check doesn't pass. This allows you to ensure that your error messages are consistent and helpful.

Prefix types like name: X are used when you need to indicate the name of an argument or parameter in the thrown error if the value doesn't pass the check. Prefix types will modify the error message from Must be X to name: Must be X allowing the developer to understand which argument caused an error.

The return X return type will change the error message from Must be X to Must return X. It's designed to be when you're using check() to check a value returned from a callback function, or similar.

// Create a function that uses both prefix and return type modifiers to check the return type of a callback.
function myFunc(callback) {
	// Check initial args.
	check(callback, "callback: func");

	// Call the callback and check the returned value.
	const result = callback();
	check(result, "callback: return false");
}

// Pass.
myFunc(() => false); // No error.

// Fail.
myFunc(123); // Throws ValueError 'myFunc(): callback: Must be function (received 123)'
myFunc(() => true); // Throws ValueError 'myFunc(): callback: Must return false (received true)'

OR and AND type modifiers

You can use & and | to join string types together, to form AND and OR chains of allowed types. This allows you to compose together more complex types like number | string or date | number | null or string && custom-checker

| is used to create an OR type, meaning any of the values is valid, e.g. number|string or string | null

// Pass.
check(123, "str|num"); // No error.
check("a", "str|num"); // No error.

// Fail.
check(null, "str|num"); // Throws ValueError 'Must be string or number (received null)'
check(null, "str|num|bool|func|obj"); // Throws ValueError 'Must be string or number or boolean or function or object (received null)'

& is used to create an AND type, meaning the value must pass all of the checks to be valid. This is primarily useful for custom checkers e.g. lower & username-unique.

// Add a checker that confirms a string contains the word "cat"
add("myapp-catty", v => v.toLowerCase().indexOf("cat") >= 0);

// Pass.
check("this cat is crazy!", "lower & myapp-catty"); // No error.
check("THIS CAT IS CRAZY", "upper & myapp-catty"); // No error.

// Fail.
check("THIS CAT IS CRAZY", "lower & myapp-catty"); // Throws ValueError 'Must be lowercase string and catty'
check("THIS DOG IS CRAZY", "string & myapp-catty"); // Throws ValueError 'Must be string and catty'

Note: Built in checkers like lower or int+ already check the basic type of a value (e.g. string and number), so there's no need to use string & lower or number & int+ — internally the value will be checked twice. Spaces around the & or | are optional.

() parentheses can be used to create a 'grouped type' which is useful to specify an array that allows several types, to make an invert/optional type of several types, or to state an explicit precence order for & and |.

// Pass.
check([123, "abc"], "(str|num)[]"); // No error.
check({ a: 123, b: "abc" }, "!(str|num)"); // No error.
check("", "(int & truthy) | (str & falsy)"); // No error.
check(12, "(int & truthy) | (str & falsy)"); // No error.

Roadmap and ideas

  • Support @decorator syntax for class methods

Contributing

See (CONTRIBUTING.md)

Changelog

See Releases