@toolz/allow

allow

allow is a library that checks data types and allows the script to continue if they pass the check. If the check fails, the script can throw an Error, or emit a warning, or invoke a custom callback. The package was written to ensure that only the "right" kind of data is allowed into the body of a function / method / component / etc. The intention is to provide effective runtime validation of data before it reaches application logic.

Another goal is to eliminate the need for unit tests that only test a function's / method's operation when it receives the "wrong" kind of data. By validating that data at runtime, we are ensuring that the internal logic of the function / method is only invoked if it has been supplied with data of the expected type.

NOTE: This library is designed for "vanilla" JS. If you are working in a React project, it's recommended to consider using @toolz/allow-react, which offers special behavior for evaluating React elements.

Usage

After installation, import the package:

import { allow } from '@toolz/allow';

Once imported, the assumed usage is directly after the entry to any function / method / component / etc. The idea is to check the integrity of provided inputs before further computation proceeds. This would typically look like this:

const addSalesTax = originalPrice => {
   allow.aNumber(originalPrice, 0);
   /*
      ...proceed with the rest of the function
    */
}

In the above example, the assumption is that originalPrice should always be a number. If any other data type is provided for originalPrice, the allowcheck will fail. This means that a value of '32.99'will fail (because it's a string). nullwill fail. Boolean values will fail. Anything that is not a number will fail. In this example, the second argument (which is optional), indicates the minimum acceptable value of the number. In this case, we don't want negative values for originalPrice, so nothing below 0will pass the check.

Methods

.aBoolean()

const doSomething = someValue => {
   allow.aBoolean(someValue);
   /*
      This is NOT "truthy".  It fails if anything other than a Boolean is 
      provided. This means that it fails on 'TRUE'/'FALSE' (because they're 
      strings), on 1/0 (because they're numbers), or any other value that is 
      not a pure TRUE/FALSE
    */
}

.aFunction()

const doSomething = theCallback => {
   allow.aFunction(theCallback);
   /*
      This will fail unless a function is provided as the value for 
      theCallback. It doesn't care what's inside the function. It can even be
      blank, like:
      () => {}
      But it must be a function of some kind.
      Please note that, in JavaScript, a class is virtually indistinguishable
      from a function (since "class" is just syntactic sugar). For this reason,
      a class will also pass this check.
    */
}

.anArray()

const doSomething = theArray => {
   allow.anArray(theArray);
   /*
       This will fail unless an array is provided as the value for theArray.  
       The check doesn't examine the contents of the array. It can be an 
       empty array, like:
       [] 
       But it must be an array of some kind.
     */
}

const doSomething = theArray => {
   allow.anArray(theArray, 1);
   /*
       The second argument of anArray() is the minimum length of the array. 
       So, by setting this value to 1, it ensures that theArray is a 
       non-empty array.
     */
}

const doSomething = theArray => {
   allow.anArray(theArray, 2, 50);
   /*
       This ensures that theArray is an array, that has no fewer than 2 
       elements, and no more than 50 elements.
     */
}

.anArrayOfArrays()

const doSomething = theArrays => {
   allow.anArrayOfArrays(theArrays);
   /*
       This will fail unless an array is provided as the value for 
       theArrays. It will also fail if any of elements inside theArrays 
       are not also arrays. It does not inspect the contents of the arrays 
       inside theArrays. They can be empty arrays, like:
       [[], [], []]
       But they must be arrays of some kind.
     */
}

const doSomething = theArrays => {
   allow.anArrayOfArrays(theArrays, 1);
   /*
       The second argument of anArrayOfArrays() is the minimum length of the 
       array. So, by setting this value to 1, it ensures that theArrays is 
       a non-empty array-of-arrays.
     */
}

const doSomething = theArrays => {
   allow.anArrayOfArrays(theArrays, 2, 50);
   /*
       This ensures that theArrays is an array, that all of its elements 
       are arrays, that it has no fewer than 2 elements, and no more than 50 
       elements.
     */
}

.anArrayOfInstances()

const person = {
   firstName: '',
   lastName: '',
   middleInitial: '',
}

const doSomething = thePeople => {
   allow.anArrayOfInstances(thePeople, person);
   /*
       This will fail unless an array is provided as the value for 
       thePeople. It will also fail if any of the elements inside thePeople
       are not objects, and if those objects do not have all the keys present
       in the model object (in this case: person). It does not inspect the 
       types of data held in those keys, and it will allow additional keys 
       that do not exist in the model object. But it expects every object 
       in the array to have all of the keys present in the model.
     */
}

const person = {
   firstName: '',
   lastName: '',
   middleInitial: '',
}

const doSomething = thePeople => {
   allow.anArrayOfInstances(thePeople, person, 1);
   /*
       The third argument of anArrayOfInstances() is the minimum length of 
       the array. So, by setting this value to 1, it ensures that thePeople is 
       a non-empty array of "person" instances.
     */
}

const person = {
   firstName: '',
   lastName: '',
   middleInitial: '',
}

const doSomething = thePeople => {
   allow.anArrayOfInstances(thePeople, person, 2, 50);
   /*
       This ensures that thePeople is an array of "person" instances, that it
       has no fewer than 2 elements, and no more than 50 elements.
     */
}

.anArrayOfIntegers()

const doSomething = theNumbers => {
   allow.anArrayOfIntegers(theNumbers);
   /*
       This will fail unless an array is provided as the value for 
       theNumbers. It will also fail if any of elements inside theNumbers 
       are not also integers. This means that it will fail on any non-numeric
       value, and it will also fail on any number that is not a "whole" 
       number. It will accept decimal values, as long as those decimals 
       evaluate to a whole number. So this works:
       [1.0, 3.00, 42.0]
       But this does not:
       [1.0, 3.14, 42.0]
     */
}

const doSomething = theNumbers => {
   allow.anArrayOfIntegers(theNumbers, 1);
   /*
       The second argument of anArrayOfIntegers() is the minimum length of 
       the array. So, by setting this value to 1, it ensures that theNumbers
       is a non-empty array of integers.
     */
}

const doSomething = theNumbers => {
   allow.anArrayOfIntegers(theNumbers, 2, 50);
   /*
       This ensures that theNumbers is an array of integers, that it has no 
       fewer than 2 elements, and no more than 50 elements.
     */
}

.anArrayOfNumbers()

const doSomething = theNumbers => {
   allow.anArrayOfNumbers(theNumbers);
   /*
       This will fail unless an array is provided as the value for 
       theNumbers. It will also fail if any of elements inside theNumbers 
       are not also numbers.
     */
}

const doSomething = theNumbers => {
   allow.anArrayOfNumbers(theNumbers, 1);
   /*
       The third argument of anArrayOfNumbers() is the minimum length of 
       the array. So, by setting this value to 1, it ensures that theNumbers
       is a non-empty array of integers.
     */
}

const doSomething = theNumbers => {
   allow.anArrayOfNumbers(theNumbers, 2, 50);
   /*
       This ensures that theNumbers is an array of integers, that it has no 
       fewer than 2 elements, and no more than 50 elements.
     */
}

.anArrayOfObjects()

const doSomething = theObjects => {
   allow.anArrayOfObjects(theObjects);
   /*
       This will fail unless an array is provided as the value for 
       theObjects. It will also fail if any of the elements inside theObjects 
       are not also objects. It does not inspect the contents of the objects 
       inside theObjects. They can be empty objects, like:
       [{}, {}, {}]
       But they must be objects of some kind.
     */
}

const doSomething = theObjects => {
   allow.anArrayOfObjects(theObjects, 1);
   /*
       The second argument of anArrayOfObjects() is the minimum length of the 
       array. So, by setting this value to 1, it ensures that theObjects is 
       a non-empty array-of-objects.
     */
}

const doSomething = theObjects => {
   allow.anArrayOfObjects(theObjects, 2, 50);
   /*
       This ensures that theObjects is an array, that all of its elements 
       are objects, that it has no fewer than 2 elements, and no more than 50 
       elements.
     */
}

.anArrayOfStrings()

const doSomething = theStrings => {
   allow.anArrayOfStrings(theStrings);
   /*
       This will fail unless an array is provided as the value for 
       theStrings. It will also fail if any of the elements inside theStrings 
       are not also strings. It does not inspect the contents of the strings 
       inside theStrings. They can be empty strings, like:
       ['', '', '']
       But they must be strings of some kind.
     */
}

const doSomething = theStrings => {
   allow.anArrayOfStrings(theStrings, 1);
   /*
       The second argument of anArrayOfStrings() is the minimum length of the 
       array. So, by setting this value to 1, it ensures that theStrings is 
       a non-empty array-of-strings.
     */
}

const doSomething = theStrings => {
   allow.anArrayOfStrings(theStrings, 2, 50);
   /*
       This ensures that theStrings is an array, that all of its elements 
       are strings, that it has no fewer than 2 elements, and no more than 50 
       elements.
     */
}

.anInstanceOf()

const person = {
   firstName: '',
   lastName: '',
   middleInitial: '',
}

const doSomething = thePerson => {
   allow.anInstanceOf(thePerson, person);
   /*
       This is a (purposely forgiving) check to ensure that the provided object
       is of a similar type to a reference object. This only checks that the
       provided object has all of the same keys that are present in the
       reference object.  It does not look at the types of data held in those
       keys. It allows additional keys that don't exist in the reference
       object. These objects will pass the check against the person reference:
       
       {
          firstName: 'Bob',
          lastName: 'Doe',
          middleInitial: null, // this does not check to ensure that 
                               // middleInitial is a string
       }
       
       {
          firstName: 'Bob',
          lastName: 'Doe',
          middleInitial: 'K',
          favoriteIceCream: 'vanilla' // the check does not fail based upon any
                                      // "extra" keys
       }
       
       This object will fail the check against the person reference:
       
       {
          firstName: 'Bob',
          lastName: 'Doe',
          // the middleInitial key is missing
       }
     */
}

const person = {
   firstName: '',
   lastName: '',
   middleInitial: '',
   address: {},
   children: [],
}

const doSomething = thePerson => {
   allow.anInstanceOf(thePerson, person);
   /*
       Although anInstanceOf() does not check data types (string, number, 
       etc.), it does check to ensure that keys containing objects or 
       arrays in the model object also contain objects or arrays in the
       supplied object. This object will fails the check against the person
       reference:
       
       {
         firstName: 'Bob',
         lastName: 'Doe',
         middleInitial: 'I',
         address: '101 Main Street',
         children: 4,
       }
       
       This check is not recursive, meaning that anInstanceOf() only checks
       to ensure that address is an object and children is an array.  It makes
       no attempt to ensure that any objects/arrays below the first level of
       keys exist in the supplied object.
     */
}

.anInteger()

const doSomething = theNumber => {
   allow.anInteger(theNumber);
   /*
       This will fail unless an integer is provided as the value for
       theNumber. It will fail on any non-numeric value.  It will also
       fail on any numbers that are not "whole" numbers.  Values like
       1.00 or 42.0 are fine.  But 3.14 will fail, because it is not
       an integer.
     */
}

const doSomething = theNumber => {
   allow.anInteger(theNumber, 0);
   /*
       The second argument of anInteger() is the minimum value of theNumber. 
       So, by setting this value to 0, it ensures that theNumber is a 
       non-negative integer.
     */
}

const doSomething = theNumber => {
   allow.anInteger(theNumber, 2, 50);
   /*
       This ensures that theNumber is an integer, that the value is no less
       than 2, and no greater than 50.
     */
}

.anObject()

const doSomething = theObject => {
   allow.anObject(theObject);
   /*
       This ensures that theObject is an object. In JavaScript, an array is
       seen as having typeof 'object', but an array will fail this check.
       Similarly, NULL is seen as having typeof 'object', but it will also
       fail this check. 
     */
}

const doSomething = theObject => {
   allow.anObject(theObject, 1);
   /*
       The second argument of anObject() is the minimum number of keys that
       must be present in theObject. So, by setting this value to 1, it ensures
       that theObject is a non-empty object.
     */
}

const doSomething = theObject => {
   allow.anObject(theObject, 2, 50);
   /*
       This ensures that theObject is an object, with no fewer than two keys,
       and no more than 50 keys.
     */
}

.aString()

const doSomething = theString => {
   allow.aString(theString);
   /*
       This will fail unless a string is provided as the value for theString.  
       The check doesn't examine the contents of the string. It can be an 
       empty string, like:
       ''
       But it must be a string of some kind.
     */
}

const doSomething = theString => {
   allow.aString(theString, 1);
   /*
       The second argument of aString() is the minimum length of the string. 
       So, by setting this value to 1, it ensures that theString is a 
       non-empty string.
     */
}

const doSomething = theString => {
   allow.aString(theString, 2, 50);
   /*
       This ensures that theString is a string, that has no fewer than 2 
       characters, and no more than 50 characters.
     */
}

.getAllowNull()

console.log(allow.getAllowNull()); // false
/*
   allowNull is Boolean. The default value is FALSE. When set to
   TRUE, all of the checks will pass if the provided value is NULL. 
 */

.getFailureBehavior()

console.log(allow.getFailureBehavior()); // 'throw'
/*
   The behavior has three possible values:
      throw
      warn
      ignore
   'throw' is the default value.
 */

.getOnFailure()

allow.getOnFailure();
/*
   returns whatever function has been set to be called onFailure
 */

.oneOf()

This can be called two different ways - by passing in a reference array or a reference object.

const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thur', 'Fri', 'Sat'];

const doSomething = theDay => {
   allow.oneOf(theDay, days);
   /*
      This ensures that theDay matches one of the values in the days array.
    */
}

const days = {
   0: 'Sun',
   1: 'Mon',
   2: 'Tue',
   3: 'Wed',
   4: 'Thur',
   5: 'Fri',
   6: 'Sat',
}

const doSomething = theDay => {
   allow.oneOf(theDay, days);
   /*
      This ensures that theDay matches one of the values in the days object.
      It does not try to check against any of the keys in the key/value pairs.
      It only checks against the values.
    */
}

The first value passed into oneOf() must be a primitive. It cannot be an object, an array, or a function.

.setAllowNull()

const thisIsNull = null;
allow.anArray(thisIsNull); // this throws an Error
allow.setAllowNull(true);
allow.anArray(thisIsNull); // this does NOT throw an Error
/*
   setAllowNull() requires a Boolean as its only argument. By default, the
   values checked in by the allow methods are not nullable. But this behavior
   can be toggled with setAllowNull(). 
   If sessionStorage is available, the allowNull value will be set there.
   This allows the setting to be saved once in the lifecycle of the app.
 */

.setFailureBehavior()

allow.setFailureBehavior(allow.failureBehavior.WARN);
/*
   setFailureBehavior() requires one of the following three values:
      'throw'
      'warn'
      'ignore'
   'throw' is the default value.  Throwing an Error will halt JavaScript
   execution.  
   'warn' will spawn warnings to be displayed in the console.
   'ignore' will turn off all warnings and cease the throwing of all Errors.
   If sessionStorage is available, the failureBehavior value will be set there.
   This allows the setting to be saved once in the lifecycle of the app.
 */

.setOnFailure()

const myCustomErrorHandler = (value, message) => {
   // do the custom error handling...
}

allow.setFailureBehavior(allow.failureBehavior.IGNORE);
allow.setOnFailure(myCustomErrorHandler);
/*
   The onFailure handler is called before any warning is displayed and before
   any Error is thrown.  Setting an onFailure callback does not halt the
   further error handling provide by allow.  If you want to turn off
   those features, you must use setFailureBehavior().
   
   When the onFailure method is invoked, it will be called with two arguments:
      The original value that failed validation
      The message spawned by that failed validation
 */

Chaining

A successful call to any of the allow validation methods always returns allow. This enables the chaining of multiple checks on a single line of code. That would look something like this:

const doSomething = (patient, isAlive, age) => {
   allow.anObject(patient, 1).aBoolean(isAlive).aNumber(age, 0, 130);
   /*
      This ensures that patient is a non-empty object
      AND that isAlive is a Boolean
      AND that age is a non-negative number no greater than 130
    */
}