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.");

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
});

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);

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

Credits

By Joe Bain at