n4s v5.0.28

Enforce

Enforce is a validation assertions library. It allows you to run your data against rules and conditions and test whether it passes your validations. It is intended for validation logic that gets repeated over and over again and should not be written manually. It comes with a wide-variety of pre-built rules, but it can also be extended to support your own repeated custom logic.

The way Enforce operates is similar to most common assertion libraries - if the validation fails, it throws an Error, and if the validation succeeds, it returns the current instance of Enforce to allow chaining more rules.

import enforce from 'n4s'

enforce(4).isNumber();
// passes

enforce(4).lessThan(2);
// throws an error

Content

• Chaining enforce rules
• Custom Enforce Rules
  • Writing Custom Enforce Rules
• Enforce rules
  • equal
  • notEqual
  • isEmpty
  • isNotEmpty
  • isNumeric
  • isNotNumeric
  • greaterThan
  • greaterThanOrEquals
  • lengthEquals
  • lengthNotEquals
  • lessThan
  • lessThanOrEquals
  • longerThan
  • longerThanOrEquals
  • numberEquals
  • numberNotEquals
  • shorterThan
  • shorterThanOrEquals
  • matches
  • notMatches
  • inside
  • notInside
  • isTruthy
  • isFalsy
  • isArray
  • isNotArray
  • isNumber
  • isNotNumber
  • isString
  • isNotString
  • isOdd
  • isEven

Chaining enforce rules

All of enforce's rules are chainable and can be used more than once in the same chain. When chained, all blocks share an AND relationship, meaning that if one block fails, the whole test fails as well.

The following are valid uses of enforce.

enforce([1,2,3,4,5,6]).longerThan(5).isArray();

enforce('North Dakota, por favor').shorterThan(10).longerThan(6);

enforce('Toto, I\'ve a feeling we\'re not in Kansas anymore').notMatches(/0-9/);

Enforce exposes all predefined and custom rules. You may use chaining to make multiple enfocements for the same value.

Custom enforce rules

To make it easier to reuse logic across your application, sometimes you would want to encapsulate bits of logic in rules that you can use later on, for example, "what's considered a valid email".

Your custom rules are essentially a single javascript object containing your rules.

const myCustomRules = {
    isValidEmail: (value) => value.indexOf('@') > -1,
    hasKey: (value, {key}) => value.hasOwnProperty(key),
    passwordsMatch: (passConfirm, options) => passConfirm === options.passConfirm && options.passIsValid
}

Just like the predefined rules, your custom rules can accepts two parameters:

• value The actual value you are testing against.
• args (optional) the arguments which you pass on when running your tests.

You can extend enforce with your custom rules by creating a new instance of Enforce and adding the rules object as the argument.

import Enforce from 'n4s';

const myCustomRules = {
    isValidEmail: (value) => value.indexOf('@') > -1,
    hasKey: (value, key) => value.hasOwnProperty(key),
    passwordsMatch: (passConfirm, options) => passConfirm === options.passConfirm && options.passIsValid
}

const enforce = new Enforce(myCustomRules);

enforce(user.email).isValidEmail();

enforce rules

Enforce rules are functions that allow you to test your data against different criteria. The following rules are supported out-of-the-box

equals

Description

Checks if your enforced value strictly equals (===) another.

It is not recommended to use this rule to compare arrays or objects, as it does not perform any sort of deep comparison on the value.

For numeric value comparison, you should use numberEquals, which coerces numeric strings into numbers before comparing.

Arguments

• value: Any value you wish to check your enforced value against

Usage examples:

Passing

enforce(1).equals(1);

enforce('hello').equals('hello');

const a = [1, 2, 3];

enforce(a).equals(a);

failing

enforce('1').equals(1);

enforce([1, 2, 3]).equals([1, 2, 3]);

notEquals

Description

Checks if your enforced value does not strictly equal (===) another.

Reverse implementation of equals.

Usage examples:

Passing

enforce('1').notEquals(1);

enforce([1, 2, 3]).notEquals([1, 2, 3]);

failing

enforce(1).notEquals(1);

enforce('hello').notEquals('hello');

const a = [1, 2, 3];

enforce(a).notEquals(a);

isEmpty

Description

Checks if your enforced value is empty, false, zero, null or undefined.

Expected results are:

• object: checks against count of keys (0 is empty)
• array/string: checks against length. (0 is empty)
• number: checks the value of the number. (0 and NaN are empty)
• boolean: false is empty.
• undefined/null: are both empty.

Arguments

Usage examples:

enforce([]).isEmpty();
enforce('').isEmpty();
enforce({}).isEmpty();
enforce(0).isEmpty();
enforce(NaN).isEmpty();
enforce(undefined).isEmpty();
enforce(null).isEmpty();
enforce(false).isEmpty();
// passes

enforce([1]).isEmpty();
enforce('1').isEmpty();
enforce({1:1}).isEmpty();
enforce(1).isEmpty();
enforce(true).isEmpty();
// throws

isNotEmpty

Description

Checks that your enforced value is not empty, false, or zero. Reverse implementation of isEmpty.

Usage examples:

enforce([1]).isNotEmpty();
// passes

enforce('1').isNotEmpty();
// passes

enforce({1:1}).isNotEmpty();
// passes

enforce([]).isNotEmpty();
// throws

enforce('').isNotEmpty();
// throws

enforce({}).isNotEmpty();
// throws

enforce(0).isNotEmpty();
// throws

isNumeric

Description

Checks if a value is a representation of a real number

Arguments

Usage examples:

enforce(143).isNumeric();
enforce('143').isNumeric();
// passes

enforce(NaN).isNumeric();
enforce('1hello').isNumeric();
enforce('hi').isNumeric();
// throws

isNotNumeric

Description

Checks if a value is not a representation of a real number. Reverse implementation of isNumeric.

Usage examples:

enforce(NaN).isNotNumeric();
enforce('Hello World!').isNotNumeric();
// passes

enforce(731).isNotNumeric();
enforce('42').isNotNumeric();
// throws

greaterThan

• alias: gt

Description

Checks that your numeric enforced value is larger than a given numeric value.

Arguments

• value: number | string | A numeric value against which you want to check your enforced value.

Strings are parsed using Number(), values which are non fully numeric always return false;

Usage

Passing examples:

enforce(1).greaterThan(0);
enforce('10').greaterThan(0);
enforce(900).gt('100');

Failing examples:

enforce(100).greaterThan(100);
enforce('100').greaterThan(110);
enforce([100]).gt(1);

greaterThanOrEquals

• alias: gte()

Description

Checks that your numeric enforced value is larger than or equals to a given numeric value.

Arguments

• value: number | string | A numeric value against which you want to check your enforced value.

Strings are parsed using Number(), values which are non fully numeric always return false;

Usage

Passing examples:

enforce(1).greaterThanOrEquals(0);
enforce('10').greaterThanOrEquals(0);
enforce(900).greaterThanOrEquals('100');
enforce(100).greaterThanOrEquals('100');
enforce(900).gte('900');
enforce('1337').gte(1337);

Failing examples:

enforce(100).greaterThanOrEquals('120');
enforce('100').greaterThanOrEquals(110);
enforce([100]).gte(1);

lengthEquals

Description

Checks that your enforced value is equal to the given number.

Arguments

• size: number | the number which you would like your initial value to be tested against.

The value argument can be of the following types:

• array: checks against length.
• string: checks against length.

Usage examples:

Passing examples:

enforce([1]).lengthEquals(1);
// passes

enforce('a').lengthEquals(1);
// passes

Failing examples:

enforce([1, 2]).lengthEquals(1);
// throws

enforce('').lengthEquals(1);
// throws

lengthNotEquals

Description

Checks that your enforced value is not equal to the given number. Reverse implementation of lengthEquals.

Arguments

• size: number | the number which you would like your initial value to be tested against.

The value argument can be of the following types:

• array: checks against length.
• string: checks against length.

Usage examples:

Passing examples:

enforce([1]).lengthNotEquals(0);
// passes

enforce('a').lengthNotEquals(3);
// passes

Failing examples:

enforce([1]).lengthNotEquals(1);
// throws

enforce('').lengthNotEquals(0);
// throws

lessThan

• alias: lt()

Description

Checks that your numeric enforced value is smaller than a given numeric value.

Arguments

• value: number | string | A numeric value against which you want to check your enforced value.

Strings are parsed using Number(), values which are non fully numeric always return false;

Usage

Passing examples:

enforce(0).lessThan(1);
enforce(2).lessThan('10');
enforce('90').lt(100);

Failing examples:

enforce(100).lessThan(100);
enforce('110').lessThan(100);
enforce([0]).lt(1);

lessThanOrEquals

• alias: lte()

Description

Checks that your numeric enforced value is smaller than or equals to a given numeric value.

Arguments

• value: number | string | A numeric value against which you want to check your enforced value.

Strings are parsed using Number(), values which are non fully numeric always return false;

Usage

Passing examples:

enforce(0).lessThanOrEquals(1);
enforce(2).lessThanOrEquals('10');
enforce('90').lte(100);
enforce(100).lte('100');

Failing examples:

enforce(100).lessThanOrEquals(90);
enforce('110').lessThanOrEquals(100);
enforce([0]).lte(1);

longerThan

Description

Checks that your enforced value is longer than a given number.

Arguments

• size: number | the number which you would like your initial value to be tested against.

The value argument can be of the following types:

• array: checks against length.
• string: checks against length.

Usage examples:

Passing examples:

enforce([1]).longerThan(0);
// passes

enforce('ab').longerThan(1);
// passes

Failing examples:

enforce([1]).longerThan(2);
// throws

enforce('').longerThan(0);
// throws

longerThanOrEquals

Description

Checks that your enforced value is longer than or equals to a given number.

Arguments

• size: number | the number which you would like your initial value to be tested against.

The value argument can be of the following types:

• array: checks against length.
• string: checks against length.

Usage examples:

Passing examples:

enforce([1]).longerThanOrEquals(0);
// passes

enforce('ab').longerThanOrEquals(1);
// passes

enforce([1]).longerThanOrEquals(1);
// passes

enforce('a').longerThanOrEquals(1);
// passes

Failing examples:

enforce([1]).longerThanOrEquals(2);
// throws

enforce('').longerThanOrEquals(1);
// throws

numberEquals

Description

Checks that your numeric enforced value is equals another value.

Arguments

• value: number | string | A numeric value against which you want to check your enforced value.

Strings are parsed using Number(), values which are non fully numeric always return false;

Usage

Passing examples:

enforce(0).numberEquals(0);
enforce(2).numberEquals('2');

Failing examples:

enforce(100).numberEquals(10);
enforce('110').numberEquals(100);
enforce([0]).numberEquals(1);

numberNotEquals

Description

Checks that your numeric enforced value does not equal another value. Reverse implementation of numberEquals.

Arguments

• value: number | string | A numeric value against which you want to check your enforced value.

Strings are parsed using Number(), values which are non fully numeric always return false;

Usage

Passing examples:

enforce(2).numberNotEquals(0);
enforce('11').numberNotEquals('10');

Failing examples:

enforce(100).numberNotEquals(100);
enforce('110').numberNotEquals(100);

shorterThan

Description

Checks that your enforced value is shorter than a given number.

Arguments

• size: number | the number which you would like your initial value to be tested against.

The value argument can be of the following types:

• array: checks against length.
• string: checks against length.

Usage examples:

Passing examples:

enforce([]).shorterThan(1);
// passes

enforce('a').shorterThan(2);
// passes

Failing examples:

enforce([1]).shorterThan(0);
// throws

enforce('').shorterThan(0);
// throws

shorterThanOrEquals

Description

Checks that your enforced value is shorter than or equals to a given number.

Arguments

• size: number | the number which you would like your initial value to be tested against.

The value argument can be of the following types:

• array: checks against length.
• string: checks against length.

Usage examples:

Passing examples:

enforce([]).shorterThanOrEquals(1);
// passes

enforce('a').shorterThanOrEquals(2);
// passes

enforce([]).shorterThanOrEquals(0);
// passes

enforce('a').shorterThanOrEquals(1);
// passes

Failing examples:

enforce([1]).shorterThanOrEquals(0);
// throws

enforce('ab').shorterThanOrEquals(1);
// throws

matches

Description

Checks if a value contains a regex match.

Arguments

• regexp: either a RegExp object, or a RegExp valid string

Usage examples:

enforce(1984).matches(/[0-9]/);
// passes

enforce(1984).matches('[0-9]');
// passes

enforce('1984').matches(/[0-9]/);
// passes

enforce('1984').matches('[0-9]');
// passes

enforce('198four').matches(/[0-9]/);
// passes

enforce('198four').matches('[0-9]');
// passes

enforce('ninety eighty four').matches(/[0-9]/);
// throws

enforce('ninety eighty four').matches('[0-9]');
// throws

notMatches

Description

Checks if a value does not contain a regex match. Reverse implementation of matches.

Usage examples:

enforce(1984).notMatches(/[0-9]/);
// throws

enforce('ninety eighty four').notMatches('[0-9]');
// passes

inside

Description

Checks if your enforced value is contained in another array or string. Your enforced value can be of the following types:

• string
• number
• boolean

Arguments

• container: a string or an array which may contain the value specified.

Usage examples:

inside: array

Checks for membership in an array.

• string: checks if a string is an element in an array

enforce('hello').inside(['hello', 'world']);
// passes

enforce('hello!').inside(['hello', 'world']);
// throws

• number: checks if a number is an element in an array

enforce(1).inside([1, 2]);
// passes

enforce(3).inside([1, 2]);
// throws

• boolean: checks if a number is an element in an array

enforce(false).inside([true, false]);
// passes

enforce(true).inside([1,2,3]);
// throws

inside: string

• string: checks if a string is inside another string

enforce('da').inside('tru dat.');
// passes

enforce('ad').inside('tru dat.');
// throws

notInside

Description

Checks if a given value is not contained in another array or string. Reverse implementation of inside.

Usage examples:

enforce('ad').notInside('tru dat.');
enforce('hello!').notInside(['hello', 'world']);
// passes

enforce('hello').notInside(['hello', 'world']);
enforce('da').notInside('tru dat.');
// throws

isTruthy

Description

Checks if a value is truthy; Meaning: if it can be coerced into boolean true. Anything not in the following list is considered to be truthy.

• undefined
• null
• false
• 0
• NaN
• empty string ("")

Arguments

Usage examples:

enforce("hello").isTruthy();
enforce(true).isTruthy();
enforce(1).isTruthy();
// passes

enforce(false).isTruthy();
enforce(null).isTruthy();
enforce(undefined).isTruthy();
enforce(0).isTruthy();
enforce(NaN).isTruthy();
enforce("").isTruthy();
// throws

isFalsy

Description

Checks if a value is falsy; Meaning: if it can be coerced into boolean false. Reverse implementation of isTruthy.

Anything not in the following list is considered to be truthy:

• undefined
• null
• false
• 0
• NaN
• empty string ("")

Usage examples:

enforce(1).isFalsy();
// throws

enforce(true).isFalsy();
// throws

enforce('hi').isFalsy();
// throws

enforce(false).isFalsy();
// passes

enforce(0).isFalsy();
// passes

enforce(undefined).isFalsy();
// passes

isArray

Description

Checks if a value is of type Array.

Arguments

Usage examples:

enforce(['hello']).isArray();
// passes

enforce('hello').isArray();
// throws

isNotArray

Description

Checks if a value is of any type other than Array. Reverse implementation of isArray.

Usage examples:

enforce(['hello']).isNotArray();
// throws

enforce('hello').isNotArray();
// passes

isNumber

Description

Checks if a value is of type number.

Arguments

Usage examples:

enforce(143).isNumber();
enforce(NaN).isNumber(); // (NaN is of type 'number!')
// passes

enforce([]).isNumber();
enforce("143").isNumber();
// throws

isNotNumber

Description

Checks if a value is of any type other than number. Reverse implementation of isNumber.

Usage examples:

enforce(143).isNotNumber();
// throws

enforce(NaN).isNotNumber();
// throws (NaN is of type 'number!')

enforce('143').isNotNumber();
// passes

enforce(143).isNotNumber();
// passes

isString

Description

Checks if a value is of type String.

Arguments

Usage examples:

enforce('hello').isString();
// passes

enforce(['hello']).isString();
enforce(1984).isString();
// throws

isNotString

Description

Checks if a value is of any type other than String. Reverse implementation of isString.

Usage examples:

enforce('hello').isNotString();
// throws

enforce(['hello']).isNotString();
// passes

isOdd

Description

Checks if a value is an odd numeric value.

Usage examples:

enforce('1').isOdd();
enforce(9).isOdd();
// passes

enforce(2).isOdd();
enforce('4').isOdd();
enforce('1withNumber').isOdd();
enforce([1]).isOdd();
// throws

isEven

Description

Checks if a value is an even numeric value.

Usage examples:

enforce(0).isEven();
enforce('2').isEven();
// passes

enforce(1).isEven();
enforce('3').isEven();
enforce('2withNumber').isEven();
enforce([0]).isEven();
// throws