Travis CI

Args.js

Args.js lets you easily create functions with optional parameters, default parameters, parameter groups and named parameters. It checks types and will trigger exceptions if a function is called incorrectly.

More of this


var args = Args([
	{elements:  Args.ARRAY    | Args.Required},
	{qualifier: Args.FUNCTION | Args.Optional},
	{node:      Args.DOM_EL   | Args.Optional}
	{regex:     Args.STRING   | Args.Optional},
	{index:     Args.INT      | Args.Optional,
		_default: 0}
], arguments);

Less of this


// set a default value for qualifier
qualifier = qualifier || 0;

if ( jQuery.isFunction( qualifier ) ) {
	// treat qualifier as function
} else if ( qualifier.nodeType ) {
	// treat qualifier as a DOM node
} else if ( typeof qualifier === "string" ) {
	// treat qualifier as a regular expression
} else {
	// treat qualifier as an index
}
Based on actual code in jQuery

Example

Clearly and safely specify the arguments your function takes. Have flexibility without writing spaghetti code. 

function addBook() {
	var args = Args([
		{title:       Args.STRING | Args.Required},
		{description: Args.STRING | Args.Optional},
		{rating:      Args.INT    | Args.Optional}
	], arguments);

	args.title === "Frankenstein";
	args.description === undefined;
	args.rating === 5;
}

addBook("Frankenstein", 5);

Download

Full (12.0k) Minified (4.1k)

 

Or install with NPM: 


npm install args-js

Or Bower: 


bower install args-js

Source

The code is on GitHub and is MIT licensed. It works like <script src=...> in a browser or with AMD or Node.js's require(). There are over 50 tests (so far) which can be run using mocha.

Features

Optional & Required Arguments

Arguments can be specified as optional or required. If a required argument is absent an exception is thrown. 

var args = Args([
	{title:       Args.STRING | Args.Required},
	{description: Args.STRING | Args.Optional},
	{rating:      Args.INT    | Args.Optional}
], arguments);

Default Arguments

Optional arguments can have default values if no value is passed. 

var args = Args([
	{description: Args.STRING | Args.Optional,
		_default: "Description missing"},
	{rating:      Args.INT    | Args.Optional,
		_default: 3}
], arguments);

Custom Types

Args.js can work with your custom class hierarchy. 

var args = Args([
	{title: Args.STRING | Args.Required},
	{book:  Args.OBJECT | Args.Required,
		_type: MyBook}
], arguments);

Argument Groups

Specify an argument group when one of serveral types can be passed. 

function myFunc() {
	var args = Args([
		{title: Args.STRING | Args.Required},
		[
			{description: Args.STRING},
			{myBook:      Args.OBJECT, _type: MyBook}
		]
	], arguments);
}

myFunc("Wuthering Heights", wutherBookObject);
// or
myFunc("Wuthering Heights", "A book about love and rain.");
It is also possible to make an argument group optional by including an Args.Optional in the group, this means a positional argument will be taken if possible, but the group is skipped otherwise: 

	[ {description: Args.STRING}, {myBook: Args.OBJECT}, Args.Optional ]

Named Arguments

You can call your functions with named arguments too. 

function myFunc() {
	var args = Args([
		{title:       Args.STRING | Args.Required},
		{description: Args.STRING | Args.Optional},
		{rating:      Args.INT    | Args.Optional}
	], arguments);
}

myFunc("Frankenstein", "A book about monsters", 5);
// or
myFunc("Frankenstein", {
			description: "A book about monsters",
			rating: 5
	  });
// or
myFunc({
	title: "Frankenstein",
	description: "A book about monsters",
	rating: 5
});
Note: If the last argument you pass is a simple object which has a property with the same name and type of one of your other arguments Args.js will assume you are trying to use named arguments. So for example, this will cause problems: 

function myFunc() {
	var args = Args([
		{book:        Args.OBJECT | Args.Required},
		{description: Args.STRING | Args.Optional}
	], arguments);
}

var myBook = {title: "Frankenstein", description: "A book about a monster"};
// THIS WILL THROW AN ERROR!
myFunc(myBook);
To get around this you can make sure your book has a proper type, or it does not share property names with your arguments.

Mixed Order Arguments

Your first and third arguments are optional but the second and fourth aren't? No problem. 

function addBook() {
	var args = Args([
		{author:   Args.OBJECT   | Args.Optional, _type: MyAuthor},
		{title:    Args.STRING   | Args.Required},
		{rating:   Args.INT      | Args.Optional},
		{callback: Args.FUNCTION | Args.Required}
	], arguments);
}

// you can now call
addBook(new MyAuthor("Mary Shelley"), "Frankenstein", 5, function(book) { /* ... */ });
// or
addBook("Frankenstein", function(book) { /* ... */ });

Custom Checks

You can write custom check functions to guarantee the right arguments get through. 

var args = Args([
	{author:   Args.OBJECT   | Args.Required, _check:
		function(author) { return author.name === "Mary Shelley"; }
	},
	{title:    Args.STRING   | Args.Required}
], arguments);

Regex Checks

For arguments which have a sensible toString() representation you can pass a regular expression as a custom checker. This trys to match the regex to the string value of an argument. 

var args = Args([
	{author:   Args.OBJECT   | Args.Required, _check: /(Mary|Percy Bysshe) Shelley/ },
	{title:    Args.STRING   | Args.Required}
], arguments);

Argument Precedence

Args.js gives first precedence to named arguments, other arguments will be shifted to the right: 

function addBook() {
	var args = Args([
		{author:   Args.STRING   | Args.Required},
		{title:    Args.STRING   | Args.Required}
	], arguments);
}

addBook("Frankenstein", {author: "Mary Shelley"});

// args.author === "Mary Shelley" 
// args.title === "Frankenstein"
It also prefers Required arguments over Optional ones: 

function addBook() {
	var args = Args([
		{author:   Args.STRING   | Args.Optional},
		{title:    Args.STRING   | Args.Required}
	], arguments);
}

addBook("Frankenstein");

// args.author === undefined 
// args.title === "Frankenstein"

Types

Args.js includes the following type constants for you to use in function signatures: 

Args.ANY
Args.STRING       
Args.FUNCTION     
Args.INT          
Args.FLOAT        
Args.ARRAY_BUFFER 
Args.OBJECT       
Args.DATE         
Args.BOOL         
Args.DOM_EL       
Args.ARRAY

See Also

Credits

By Joe Bain