ever-mandate
v0.0.5
Published
The ever-mandate module eases defensive development annoyance.
Downloads
6
Maintainers
Readme
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);
}
Unit Tests
Unit tests can be done with the following commands.
Run this command to execute the unit tests.
npm run-script test
Run this command to execute the unit tests and output a code-coverage report.
npm run-script test-cov
Contributors
Author: Michael Hayes
License
MIT