Ever-mandate NPM

ever-mandate

The ever-mandate module provides a utility for defensive development. Tiresome are the if/then/throw statements written to protect our processes from poor inputs and outputs. Mandate replaces those if/then/throw statements with easy-to-use functions.

Installation

	npm install ever-mandate

Argument Functions

Argument Type Functions

There are seven functions designed to validate function arguments; argIsArray, argIsBoolean, argIsDate, argIsFunction, argIsNumber, argIsObject, and argIsString. Each one of these functions accepts the input value to check and the name of the argument to use in the error message should the condition fail.

	mandate.argIsArray(someArg, 'someArg'); // Throws error if null/undefined/!array.
	mandate.argIsBoolean(someArg, 'someArg'); // Throws error if null/undefined/!boolean.
	mandate.argIsDate(someArg, 'someArg'); // Throws error if null/undefined/!date.
	mandate.argIsFunction(someArg, 'someArg'); // Throws error if null/undefined/!function.
	mandate.argIsNumber(someArg, 'someArg'); // Throws error if null/undefined/!number.
	mandate.argIsObject(someArg, 'someArg'); // Throws error if null/undefined/!object.
	mandate.argIsString(someArg, 'someArg'); // Throws error if null/undefined/!string.

Argument Array Functions

There are five functions designed to validate an array argument contains only elements of a specific type.

	// All of these functions throw an error if the argument is null, undefined, not an array, or any of the
	// elements are not of the appropriate type.
	mandate.argArrayIsBoolean(someArg, 'someArg'); // All elements must be a boolean.
	mandate.argArrayIsDate(someArg, 'someArg'); // All elements must be a date.
	mandate.argArrayIsNumber(someArg, 'someArg'); // All elements must be numeric.
	mandate.argArrayIsObject(someArg, 'someArg'); // All elements must be an object.
	mandate.argArrayIsString(someArg, 'someArg'); // All elements must be a string.

argIsNotUndefined Function

The argIsNotUndefined function verifies that a specified argument is not undefined.

	var someArg = undefined;

	// Throws the error:
	// Argument [someArg] is undefined.
	mandate.argIsNotUndefined(someArg, 'someArg');

General Functions

is* Functions

There are seven functions designed to provide general variable checks; isArray, isBoolean, isDate, isFunction, isNumber, isObject, and isString. Each of these functions accept an input value, optional message, and optional message format values. The message formatting takes advantage of lodash's template method.

	var someVariable = 'asdf';

	// Throws the error: "someVariable was not an array, instead received: asdf"
	mandate.isArray(someVariable, 'someVariable was not an array, instead received: ${value}', { value: someVariable });
	
	// Throws the error: "someVariable was not a boolean, instead received: asdf"
	mandate.isBoolean(someVariable, 'someVariable was not a boolean, instead received: ${value}', { value: someVariable });

	// Throws the error: "someVariable was not a date, instead received: asdf"
	mandate.isDate(someVariable, 'someVariable was not a date, instead received: ${value}', { value: someVariable });

	// Throws the error: "someVariable was not a function, instead received: asdf"
	mandate.isFunction(someVariable, 'someVariable was not a function, instead received: ${value}', { value: someVariable });
	
	// Throws the error: "someVariable was not a number, instead received: asdf"
	mandate.isNumber(someVariable, 'someVariable was not a number, instead received: ${value}', { value: someVariable });

	// Throws the error: "someVariable was not an object, instead received: asdf"
	mandate.isObject(someVariable, 'someVariable was not an object, instead received: ${value}', { value: someVariable });

	// Change the value for the isString test.
	someVariable = false;

	// Throws the error: "someVariable was not a string, instead received: false"
	mandate.isString(someVariable, 'someVariable was not a string, instead received: ${value}', { value: someVariable });

isNotUndefined Function

The isNotUndefined function verifies that a given value is not undefined.

	var someVariable = 'asdf';

	// Throws the error: "someVariable is undefined."
	mandate.isNotUndefined(someVariable, 'someVariable is undefined.');

that Function

that is the catch-all function for non-argument related state checks. that can be passed a boolean or function to evaluate. Should the evaluation or condition be false, an exception is thrown with the specified message.

Simple that example:

	var someObj = { name: 'object2' };

	// Throw an exception with the custom message only if the condition is false.
	mandate.that(someObj.name === 'object1', 'someObj does not have a valid name property.');

Example using a function:

	var someObj = { name: 'object2' };

	var objectTest = function(item) { return item.name === 'object1'; };

	// Throws an exception as the function returns false.
	mandate.that(objectTest, 'someObj does not have a valid name property.');

The that method accepts a trailing object that can be used to format the message. This message formatting takes advantage of lodash's template method.

	var someObj = { name: 'object2' };

	// Throws an exception with the message:
	// "someObj does not have a valid name property. Expected object1, received object2"
	mandate.that(someObj.name === 'object1', 'someObj does not have a valid name property. Expected ${expectedVal}, received ${actualVal}',
		{ expectedVal: 'object1', actualVal: someObj.name });

Array Functions

There are five functions designed to validate array elements. Should the array in question not contain the appropriate element type an error will be thrown with the message specified. Similar to other methods, lodash's template method is used for message formatting. A default property index is available for identifying the first invalid element found.

	var booleans = [true, 5];

	// Throws an exception with the message:
	// "Array does not contain a boolean at index: 1."
	mandate.arrayIsBoolean(booleans, 'Array does not contain a boolean at index: ${index}.');
	

	var dates = [new Date(), 'not a date'];

	// Throws an exception with the message:
	// "Array does not contain a date at index: 1."
	mandate.arrayIsDate(dates, 'Array does not contain a date at index: ${index}.');
	

	var numbers = [4, 5, 6, '7'];

	// Throws an exception with the message:
	// "Array does not contain a number at index: 3."
	mandate.arrayIsNumber(numbers, 'Array does not contain a number at index: ${index}.');
	

	var objects = ['not an object', { key: '123' }];

	// Throws an exception with the message:
	// "Array does not contain an object at index: 0."
	mandate.arrayIsObject(objects, 'Array does not contain an object at index: ${index}.');
	

	var strings = ['one', 'two', 3];

	// Throws an exception with the message:
	// "Array does not contain a string at index: 2."
	mandate.arrayIsString(strings, 'Array does not contain a string at index: ${index}.');

arrayCondition Function

The arrayCondition function allows for custom array element validation.

	var numbers = [1, 2, 3, 4, 5];

	var lessThan4 = function(value, index) { return value < 4; };

	// Throws an exception with the message:
	// "Number at index, 3, is not less than four."
	mandate.arrayCondition(numbers, lessThan4, 'Number at index, ${index}, is not less than four.');

Fluent Functions

Each of the functions in mandate provide a fluent interface to chain together function calls.

	function login(username, password) {

		// Throws an error if either username or password is not a string.
		mandate
			.argIsString(username, 'username')
			.argIsString(password, 'password');

		// ...

		var user = { name: username };

		// Throws an error if user is not an object or user.name is not a string.
		mandate.isObject(user).isString(user.name);
	}