README.md



check-types.js


A tiny JavaScript library
for checking arguments
and throwing exceptions.


Why would I want that?
How tiny is it?
How do I install it?

How do I use it?


Loading the library

Calling the exported functions


String functions
Number functions
Function functions
Array functions
Date functions
Object functions
Modifiers
Batch operations
Some examples


What changed from 0.x to 1.x?
How do I set up the build environment?
What license is it released under?


Why would I want that?

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,
abstracted by a simple API.


How tiny is it?

14.4 kb unminified with comments, 3.2 kb minified, 1.2 kb minified + gzipped.


How do I install it?

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


How do I use it?


Loading the library

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.


Calling the exported functions

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 four types.


check.xxx(thing):
These functions are predicates,
returning true or false
depending on the type and value of thing.
check.maybe.xxx(thing):
The maybe modifier
returns true if thing is null or undefined,
otherwise it returns the result
of the equivalent predicate.
check.not.xxx(thing):
The not modifier
negates a predicate,
returning true if the predicate returns false
and false if the predicate returns true.
check.verify.xxx(thing, message):
The verify modifier
calls the equivalent predicate
and throws an Error
if the result is false.
It can also be applied
to maybe and not modifiers
using the form
check.verify.maybe.xxx(thing, message)
or
check.verify.not.xxx(thing, message)
respectively.


Additionally, there are 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.


String functions


check.string(thing):
Returns true
if thing is a string,
false otherwise.
check.unemptyString(thing):
Returns true
if thing is a non-empty string,
false otherwise.
check.webUrl(thing):
Returns true
if thing is an HTTP or HTTPS URL,
false otherwise.
check.gitUrl(thing):
Returns true
if thing is a git+ssh, git+http or git+https URL,
false otherwise.
check.email(thing):
Returns true
if thing seems like a valid email address,
false otherwise.
check.length(thing, value):
Returns true
if thing has a length property
that equals value,
false otherwise.


Number functions


check.number(thing):
Returns true
if thing is a real number,
false otherwise.
Note that
NaN,
Number.POSITIVE_INFINITY and
Number.NEGATIVE_INFINITY
are not real numbers.
check.positiveNumber(thing):
Returns true if thing is a number
greater than zero,
false otherwise.
check.negativeNumber(thing):
Returns true
if thing is a number
less than zero,
false otherwise.
check.oddNumber(thing):
Returns true
if thing is an odd number,
false otherwise.
check.evenNumber(thing):
Returns true
if thing is an even number,
false otherwise.
check.intNumber(thing):
Returns true
if thing is an integer,
false otherwise.
check.floatNumber(thing):
Returns true
if thing is a floating-point number,
false otherwise.


Function functions


check.fn(thing):
Returns true
if thing is a function,
false otherwise.


Array functions


check.array(thing):
Returns true
if thing is an array,
false otherwise.
check.length(thing, value):
Returns true
if thing has a length property
that equals value,
false otherwise.


Date functions


check.date(thing):
Returns true
if thing is a date,
false otherwise.


Object functions


check.object(thing):
Returns true
if thing is a non-null, non-array, non-date object,
false otherwise.
check.nulled(thing):
Returns true
if thing is null,
false otherwise.
check.defined(thing):
Returns true
if thing is not undefined,
false otherwise.
check.emptyObject(thing):
Returns true
if thing is an empty object,
false otherwise.
check.instance(thing, prototype):
Returns true
if thing is an instance of prototype,
false otherwise.
check.like(thing, duck):
Duck-typing checker.
Returns true
if thing has all of the properties of duck,
false otherwise.
If either argument is not an object,
an exception is thrown.


Modifiers


check.maybe.xxx(...):
Returns true
if thing is null or undefined,
otherwise it propagates
the return value
from its predicate.
check.verify.xxx(...) / check.verify.maybe.xxx(...):
Throws an Error
if the predicate returns false.
The last argument
is an optional message
to be set on the Error instance.


Batch operations


check.map(things, functions):
Maps each predicate from the functions object
to the corresponding value from things,
returning the hash of results.
Similar to like
but using functions instead of values.
Supports nested objects.
check.every(predicateResults):
Returns true
if all properties of the predicateResults object are true,
false otherwise.
check.any(predicateResults):
Returns true
is any property of the predicateResults object is true,
false otherwise.


Some examples

check.object(0);
// Returns false


check.maybe.object(null);
// Returns true


check.not.object(0);
// Returns true


check.verify.like({}, { foo: 'bar' }, 'Invalid object');
// Throws new Error('Invalid object')


check.verify.maybe.like(undefined, { foo: 'bar' }, 'Invalid object');
// Doesn't throw


check.verify.not.like({}, { foo: 'bar' }, 'Invalid object');
// Doesn't throw


check.map({
    foo: 2,
    bar: {
        baz: 'qux'
    }
}, {
    foo: check.oddNumber,
    bar: {
        baz: check.unemptyString
    }
});
// Returns { foo: false, bar: { baz: true } }


check.every(
    check.map({
        foo: 0,
        bar: ''
    }, {
        foo: check.number,
        bar: check.unemptyString
    })
);
// Returns false


check.any(
    check.map({
        foo: 0,
        bar: ''
    }, {
        foo: check.number,
        bar: check.unemptyString
    })
);
// Returns true


What changed from 0.x to 1.x?

Breaking changes
were made to the API
in version 1.0.0.

Specifically,
all of the predicates
were renamed
from check.isXxxx
to check.xxx and
all of the verifiers
were renamed
from check.verifyXxxx
to check.verify.xxx.

See the history
for more details.


How do I set up the build environment?

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.


What license is it released under?

MIT