A tiny JavaScript library for checking types and throwing exceptions.
- Why would I want that?
- How tiny is it?
- How do I install it?
- How do I use it?
- How do I set up the build environment?
- What license is it released under?
Writing explicit conditions in your functions for checking arguments and throwing exceptions is a task that swiftly becomes tiresome and adds complexity to your codebase.
The purpose of check-types.js is to remove this burden from JavaScript application developers in an efficient and robust manner.
17.7 kb unminified with comments, 2.9 kb minified, 1 kb minified + gzipped.
Any of the following will do:
npm install check-types
jam install check-types
bower install check-types
component install philbooth/check-types.js
git clone git@github.com:philbooth/check-types.js.git
If you are running in
Node.js,
Browserify
or another CommonJS-style
environment,
you can require
check-types.js like so:
var check = require('check-types');
It also the supports the AMD-style format preferred by Require.js:
require.config({
paths: {
check: 'check-types.js/src/check-types'
}
});
require([ 'check' ], function (check) {
});
If you are
including check-types.js
with an HTML <script>
tag,
or neither of the above environments
are detected,
check-types.js will just export its interface globally
as check
.
Once you have loaded the library in your application, a whole bunch of functions are available to call.
For the most part, the exported functions are broadly split into two types.
-
check.isXxxx(thing)
: These functions are predicates, returning true or false depending on the type and value ofthing
. -
check.verifyXxxx(thing, message)
: These functions call their equivalentisXxxx
predicate and throw anError
if the result isfalse
.
Additionally, every exported function
is available with a maybe
modifier
that simply returns true
if the value is null
or undefined
,
otherwise it delegates to the original, unmodified function.
Calls to these functions look like
check.maybe.isXxxx(thing)
and
check.maybe.verifyXxxx(thing)
.
Finally, there are also some batch operations
that allow you to test maps
of many predicates at once.
These are implemented by
check.map
,
check.any
and
check.every
.
-
check.isString(thing)
: Returnstrue
ifthing
is a string,false
otherwise. -
check.verifyString(thing, message)
: Throws an exception unlessthing
is a string. -
check.isUnemptyString(thing)
: Returnstrue
ifthing
is a non-empty string,false
otherwise. -
check.verifyUnemptyString(thing, message)
: Throws an exception unlessthing
is a non-empty string. -
check.isLength(thing, length)
: Returnstrue
ifthing
has a length property that matches the specified length,false
otherwise. -
check.verifyLength(thing, length, message)
: Throws an exception unlessthing
has a length property that matches the specified length.
-
check.isNumber(thing)
: Returnstrue
ifthing
is a number,false
otherwise. In this case,NaN
is not considered to be a number. -
check.verifyNumber(thing, message)
: Throws an exception unlessthing
is a number. In this case,NaN
is not considered to be a number. -
check.isPositiveNumber(thing)
: Returnstrue
ifthing
is a number greater than zero,false
otherwise. -
check.verifyPositiveNumber(thing, message)
: Throws an exception unlessthing
is a number greater than zero. -
check.isNegativeNumber(thing)
: Returnstrue
ifthing
is a number less than zero,false
otherwise. -
check.verifyNegativeNumber(thing, message)
: Throws an exception unlessthing
is a number less than zero. -
check.isEvenNumber(thing)
: Returnstrue
ifthing
is an even number,false
otherwise. -
check.verifyEvenNumber(thing, message)
: Throws an exception unlessthing
is an even number. -
check.isOddNumber(thing)
: Returnstrue
ifthing
is an odd number,false
otherwise. -
check.verifyOddNumber(thing, message)
: Throws an exception unlessthing
is an odd number.
-
check.isFunction(thing)
: Returnstrue
ifthing
is function,false
otherwise. -
check.verifyFunction(thing, message)
: Throws an exception unlessthing
is function.
-
check.isArray(thing)
: Returnstrue
ifthing
is an array,false
otherwise. -
check.verifyArray(thing, message)
: Throws an exception unlessthing
is an array. -
check.isLength(thing, length)
: Returnstrue
ifthing
has a length property that matches the specified length,false
otherwise. -
check.verifyLength(thing, length, message)
: Throws an exception unlessthing
has a length property that matches the specified length.
-
check.isDate(thing)
: Returnstrue
ifthing
is a date,false
otherwise. -
check.verifyDate(thing, message)
: Throws an exception unlessthing
is a date.
-
check.isObject(thing)
: Returnstrue
ifthing
is a non-null, non-array, non-date object,false
otherwise. -
check.verifyObject(thing, message)
: Throws an exception unlessthing
is a non-null, non-array, non-date object. -
check.isEmptyObject(thing)
: Returnstrue
ifthing
is an empty object,false
otherwise. -
check.verifyEmptyObject(thing, message)
: Throws an exception unlessthing
is an empty object. -
check.isInstance(thing, prototype)
: Returnstrue
ifthing
is an instance ofprototype
,false
otherwise. -
check.verifyInstance(thing, prototype, message)
: Throws an exception unlessthing
is an instance ofprototype
. -
check.quacksLike(thing, duck)
: Tests whether an object 'quacks like a duck'. Returnstrue
ifthing
has all of the properties ofduck
,false
otherwise. If either argument is not an object, an exception is thrown. -
check.verifyQuack(thing, duck, message)
: Throws an exception unlessthing
has all of the properties ofduck
.
check.maybe.isXxxx(...)
/check.maybe.verifyXxxx(...)
: Returnstrue
ifthing
isnull
orundefined
, otherwise it delegates to the original, unmodified function.
-
check.map(things, functions)
: Maps each predicate from thefunctions
object to the corresponding value fromthings
, returning the hash of results. Similar toquacksLike
but using functions instead of values. Supports nested objects. -
check.every(predicateResults)
: Returnstrue
if all properties of thepredicateResults
object aretrue
,false
otherwise. -
check.any(predicateResults)
: Returnstrue
is any property of thepredicateResults
object istrue
,false
otherwise.
check.isObject(null);
// Returns false
check.maybe.isObject(null);
// Returns true
check.verifyQuack({}, { foo: 'bar' }, 'Invalid object');
// Throws new Error('Invalid object')
check.maybe.verifyQuack(undefined, { foo: 'bar' }, 'Invalid object');
// Doesn't throw
check.map({
foo: 2,
bar: {
baz: 'qux'
}
}, {
foo: check.isOddNumber,
bar: {
baz: check.isUnemptyString
}
});
// Returns { foo: false, bar: { baz: true } }
check.every(
check.map({
foo: 0,
bar: ''
}, {
foo: check.isNumber,
bar: check.isUnemptyString
})
);
// Returns false
check.any(
check.map({
foo: 0,
bar: ''
}, {
foo: check.isNumber,
bar: check.isUnemptyString
})
);
// Returns true
The build environment relies on
Node.js,
NPM,
JSHint,
Mocha,
Chai and
UglifyJS.
Assuming that you already have Node.js and NPM set up,
you just need to run npm install
to
install all of the dependencies as listed in package.json
.
The unit tests are in test/check-types.js
.
You can run them with the command npm test
.
To run the tests in a web browser,
open test/check-types.html
.