validateargs v1.0.4-b
validateargs
Provides a means to use strict validation of explicit parameters passed to a Javascript function against an expected order of data types.
It allows for any or all parameters to be optional and accounting for all possible user permutations of user input.
Usage
validateargs( [ DataTypes ], arguments )
// => returns an array of values found in arguments.
The order of the values represented in the result preserves the order of data types, as specified in the DataTypes array.
In a nutshell
validateargs
takes an array of data types, in an expected order they should be in, and the arguments
object. It returns an array of values, assigned sequentially based on the order of data types provided.
If validateargs
only expects to find a String
, then an Integer
, and then finally an Object
, in that order, it doesn't care if it doesn't find all three.
It does care, however, if it finds something other than an Object
immediately following an Integer
. It also cares if it finds something other than an Integer
or an Object
, immediately following a String
.
Likewise, in this example, it expects an Object
to be the last thing it finds, regardless of how many parameters were passed.
Therefore, any extra parameters passed, that were not expected, will cause it to simply return an empty array []
.
This is how validateargs
reports that the validation has failed, as all the deconstructed variable assignments will be undefined
.
This is how validateargs
works by default and is referred to as running in strict mode. It is possible to tell validateargs
to just assign values
as it discovers them, ignoring any unexpected or extra parameters it finds (see Disabling Strict Mode below).
Examples:
const validateargs = require ('validateargs');
function foo(name, age, options) {
const types = [ "String", "Integer", "Object" ];
[ name, age, options ] = validateargs(types, arguments);
console.log("Name: " + name);
console.log("Age: " + age);
console.log("Options: " + JSON.stringify(options));
console.log();
}
foo( "Jason" );
foo( 23 );
foo( { city: "Atlanta" } );
foo( "Jason", 23 );
foo( "Jason", { city: "Atlanta" } );
foo( 23, { city: "Atlanta" } );
foo(true);
foo();
Yields:
Name: Jason
Age: undefined
Options: undefined
Name: undefined
Age: 23
Options: undefined
Name: undefined
Age: undefined
Options: {"city":"Atlanta"}
Name: Jason
Age: 23
Options: undefined
Name: Jason
Age: undefined
Options: {"city":"Atlanta"}
Name: undefined
Age: 23
Options: {"city":"Atlanta"}
Name: undefined
Age: undefined
Options: undefined
Name: undefined
Age: undefined
Options: undefined
Technically, since validateargs
handles the argument parsing and allows leveraging of deconstruction, regardless of the number of parameters passed, the parameters to the function can really be omitted, altogether.
So this will work, just as well, and return the same results:
const validateargs = require ('validateargs');
function foo() {
const types = [ "String", "Integer", "Object" ];
[ name, age, options ] = validateargs(types, arguments);
console.log("Name: " + name);
console.log("Age: " + age);
console.log("Options: " + JSON.stringify(options));
console.log();
}
foo( "Jason" );
foo( 23 );
foo( { city: "Atlanta" } );
foo( "Jason", 23 );
foo( "Jason", { city: "Atlanta" } );
foo( 23, { city: "Atlanta" } );
foo(true);
foo();
However, since validateargs
is an alternative designed to encourage the use of named parameters, I would recommend including them, anyway. I think it's easier for someone else to understand your code that way, especially if they don't have to look inside the function to know what parameters it takes.
Note that validateargs
uses js.typeof as a type checker, so the data types are Capitalized to differentiate them from the native Javascript typeof
and include some not supported by it.
Data types passed to validateargs can be any of the following:
Arguments
Array
Boolean
Date
Error
Float
Infinity
Integer
JSON
Math
NaN
Object
RegExp
String
Strict mode
There is a strict mode in validateargs
that is on by default, but can be turned off by passing an additional false
parameter.
validateargs
will process all of the arguments
object, unless told not to. This is essentially what strict mode means.
Turning off strict mode tells validateargs
to process parameters in order, as best it can, ignoring any unexpected parameters it finds.
For example:
With strict mode turned on (by default):
const validateargs = require ('validateargs');
function foo(name, age, options) {
const types = [ "String", "Integer", "Object" ];
[ name, age, options ] = validateargs(types, arguments);
console.log("Name: " + name);
console.log("Age: " + age);
console.log("Options: " + JSON.stringify(options));
console.log();
}
foo( { city: "Atlanta" }, 23 );
foo( "Jason", "Gwyn", 47 );
foo( 53, 21, 19 );
Yields:
Name: undefined
Age: undefined
Options: undefined
Name: undefined
Age: undefined
Options: undefined
Name: undefined
Age: undefined
Options: undefined
Now, with strict mode turned off (by adding a false
to the end of the validateargs
call), this:
const validateargs = require ('validateargs');
function foo(name, age, options) {
const types = [ "String", "Integer", "Object" ];
[ name, age, options ] = validateargs(types, arguments, false);
console.log("Name: " + name);
console.log("Age: " + age);
console.log("Options: " + JSON.stringify(options));
console.log();
}
foo( { city: "Atlanta" }, 23 );
foo( "Jason", "Gwyn", 47 );
foo( 53, 21, 19 );
Yields:
Name: undefined
Age: undefined
Options: {"city":"Atlanta"}
Name: Jason
Age: undefined
Options: undefined
Name: undefined
Age: 53
Options: undefined
So, in summary:
With strict mode turned on, unexpected parameter types will cause []
to be returned.
With strict mode turned off, validateargs
will simply ignore unexpected parameter types, that deviate from the expected order.
When setting default values for parameters, they will only be assigned if validateargs
would normally have left that variable undefined.
Examples:
With strict mode turned on:
const validateargs = require ('validateargs');
function foo(name, age, options) {
const types = [ "String", "Integer", "Object" ];
[ name = "Gwyn", age = 38, options = { "fun": "yes!" } ] = validateargs(types, arguments);
console.log("Name: " + name);
console.log("Age: " + age);
console.log("Options: " + JSON.stringify(options));
console.log();
}
foo( { city: "Atlanta" }, 23 );
foo( "Jason", "Gwyn", 47 );
foo( 53, 21, 19 );
Yields:
Name: Gwyn
Age: 38
Options: {"fun":"yes!"}
Name: Gwyn
Age: 38
Options: {"fun":"yes!"}
Name: Gwyn
Age: 38
Options: {"fun":"yes!"}
With strict mode turned off:
const validateargs = require ('validateargs');
function foo(name, age, options) {
const types = [ "String", "Integer", "Object" ];
[ name = "Gwyn", age = 38, options = { "fun": "yes!" } ] = validateargs(types, arguments, false);
console.log("Name: " + name);
console.log("Age: " + age);
console.log("Options: " + JSON.stringify(options));
console.log();
}
foo( { city: "Atlanta" }, 23 );
foo( "Jason", "Gwyn", 47 );
foo( 53, 21, 19 );
Yields:
Name: Gwyn
Age: 38
Options: {"city":"Atlanta"}
Name: Jason
Age: 38
Options: {"fun":"yes!"}
Name: Gwyn
Age: 53
Options: {"fun":"yes!"}
TO-DOs
I don't know. You tell me.
Credit
validateargs wouldn't be possible without my good friend, Oibaf.
Also, I don't always like hiding my function parameters inside an object or using the spread operator. For me, it makes for easier to understand and better documented code.
License
Licensed under MIT (Mother Insured Task) - a.k.a. contribute please, but no criticizing Oibaf's mother's cooking or she will beat you senseless with an old wooden soup ladel.
Copyleft (c) 2019 by Nosaj and Oibaf - "we code, you like, that how work"