argument-spec

A library to ease argument checking, especially complex arguments like options objects.

Usage

Node, Browserify

At command prompt

npm install argument-spec

In code

argumentSpec = require('argument-spec');

RequireJS

Download argument-spec.js from the most recent release at https://github.com/jrootham/argument-spec/releases and put it in your lib directory.

var argumentSpec = require('argument-spec');

Script tag

<script type="text/javascript"
        src="https://cdn.rawgit.com/jrootham/argument-spec/v3.1.0/argument-spec.js">
</script>

Example of Use

var write = function(file, data, fetch) {
    var fileSpec = {
        name:argumentSpec.every([argumentSpec.length(10), '[a-z]+']) ,
        extension: "jpg|gif"
    };

    var dataSpec = {
        width: argumentSpec.range(20, 500),
        height: argumentSpec.range(20, 500),
        buffer: argumentSpec.instance(Buffer)
    };

    var errorArray = argumentSpec.validate('file', fileSpec, file);
    errorArray = errorArray.concat(argumentSpec.validate('data', dataSpec, data));
    errorArray = errorArray.concat(argumentSpec.validate('fetch', function(){}, fetch));

    if (errorArray.length > 0) {
        throw new Error(errorArray.join('\n'));
    }
}

Specification meanings

Specification	Valid argument
undefined	anything
''	string
'regex'	string argument matching regex
0 (or any number)	number
true (or false)	boolean
[]	any Array
[spec]	Array all of whose elements match spec
[spec1, spec2, ...]	Exact match for the array argument
function(a1,a2, ...)	Argument is function with matching number of arguments
{}	Any Object
{key1:spec, key2:spec2,...}	Object containing key1, key2,... where each property matches the corresponding spec. Keys are included in the name part of any error message.
argumentSpec.Base->{validate:function, spec:{key1:spec, key2:spec2,...}}	A function that validates an argument using a spec object (see below).

Array and object specs nest.

Validation Functions

Functions and related specifications are defined as properties of objects created by the function argumentSpec.Base.

Function	definition
some([spec1, spec2,...])	some spec is true for argument
every([spec1, spec2,...])	every spec is true for argument (useful for composing specs)
range(low, high)	numeric argument in low..high range (inclusive)
integer()	integer (fractional part is 0)
length(maxLength)	argument.length <= maxLength (argument.length must exist)
instance(object)	instanceof object
exact(object)	exact match for object properties, useful for options without defaults
optional(object)	permit missing properties in the argument, useful for options with defaults
isFalse()	argument is exactly false
You can write your own validation functions.
Here is an example:

/*
 *      Validation function that tests if the argument is an instance of another object
 */

var instance = function (thing) {
    var instance = new Base();

    instance.validate = function(name, argument) {
        if (! (argument instanceof thing)) {
            return [name + " is not an instance"]
        }

        return [];
    }

    return instance;
}