typed-args

A utility for managing optional typed arguments.

Usage no npm install needed!

<script type="module">
  import typedArgs from 'https://cdn.skypack.dev/typed-args';
</script>

README

typed-args

A utility for managing optional typed arguments.

Installation

npm install typed-args --save

Usage

Pass the utility method the arguments object or any array, and it will return an array with an additional .get() method attached.

args = typedArgs(arguments[, start[, end]])

arguments Array or Arguments object that needs help. This array/object and the values in it will not be modified.

start An optional starting index at which to begin the arguments slice.

end An optional ending index at which to end the arguments slice.

Returns an Array with an additional .get() method.

args.get(typeCheck1[, typeCheck2[, ...]]);

Pass the get method type checking functions which will be passed the first value in the args array. If any return true, the value will be shifted off of the args array and returned.

Null values are always shifted off the args array without being passed to any of the type checking functions. It's assumed that null is valid for any type. You'll need to do your own null/undefined value checking after using this utility.

Examples

Lets say you have the following method with three optional arguments.

function foo(string, number, array)

All of the arguments are expected to be different types and can be differentiated that way. The 2nd argument could actually be in the first position if the first argument is omitted. The 3rd argument could be in any position if one or more of the preceding arguments are omitted. Sorting out which argument is which can be a rather long chunk of code with nested conditionals.

Lets try it with this utility (and lodash for type checking utility methods):

var _ = require('lodash');
var typedArgs = require('typed-args');

function foo(stringOrRegex, number, array) {
    var args = typedArgs(arguments);

    string = args.get(_.isString, _.isRegExp);
    number = args.get(_.isNumber);
    array = args.get(_.isArray);
}

Now if we call it with just an array:

foo([1, 2, 3]);

The arguments will have these values:

stringOrRegex = undefined;
number = undefined;
array = [1, 2, 3];
args = [];

If nulls are passed, they are always consumed by the next get method:

foo(null, [1, 2, 3]);

Gives you:

stringOrRegex = null;
number = undefined;
array = [1, 2, 3];
args = [];

With a regular expression:

foo(/test/);

Gives you:

stringOrRegex = /test/;
number = undefined;
array = undefined;
args = [];

What if the typed argument is in the wrong position?

foo(2, "test", [1, 2, 3]);

The first type (String/RegExp) isn't matched so it's considered omitted. Then the number check matches and consumes the argument. The array check encounters the string and the array is considered omitted. The actual array is never checked. So, only one of the optional arguments was present, but there are two extra arguments and you end up with this:

stringOrRegex = undefined;
number = 2;
array = undefined;
args = ["test", [1, 2, 3]];