README
validateargs
Validates parameters passed to a Javascript function against an expected order of data types, allowing for any or all parameters to be optional, and provides an alternative method to passing a single object or using the ES6 spread operator.
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, at the expected positions specified in the array, regardless of how many parameters were passed to a function.
ES6's deconstructor capabilities can then be leveraged to quickly assign them to variables, without doing a lot of arduous and ugly code to sort out what parameters are what.
This allows for all parameters to be optional, as order matters.
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
In fact, 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 be friendly to 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.
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.
Turning off strict mode tells validateargs to stop processing at the first invalid parameter it finds and ignore the rest.
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.
Default values
Deconstruction in ES6 supports setting default values, so using them replaces any undefined values, in the result, to their defaults instead.
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, and fellow Herzegovinan, 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"