@toolz/allow

    1.1.5 • Public • Published

    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
        */
    }

    Install

    npm i @toolz/allow

    DownloadsWeekly Downloads

    148

    Version

    1.1.5

    License

    MIT

    Unpacked Size

    84 kB

    Total Files

    6

    Last publish

    Collaborators

    • bytebodger