livr-extra-rules

    1.3.0 • Public • Published

    livr-extra-rules

    Build Status npm version Known Vulnerabilities

    LIVR specification contains the most common rules that every implementation should support.

    The module contains extra rules for JavaScript LIVR. It is absolutely ok for LIVR to have your own custom rules in your project. But there are some rules that are useful cross projects.

    Moreover, LIVR itself and this module have zero dependecies. It means:

    • Lighter builds
    • Easier to maintain high level of security

    Usage

    npm install --save livr livr-extra-rules
    import LIVR from livr;
    import extraRules from 'livr-extra-rules';
    LIVR.Validator.registerDefaultRules(extraRules);

    Documentation

    Rules

    • ipv4
    • boolean
    • credit_card
    • uuid
    • mongo_id
    • list_length
    • list_items_unique
    • base64
    • md5
    • iso_date (extended version)
    • required_if
    • is
    • instance_of
    • has_methods

    ipv4

    Example:

    {
        field: 'ipv4';
    }

    Error code: 'NOT_IP'

    boolean

    Checks that the value is true or false

    • True values: true, 1, '1'
    • False values: false, 0, '0'

    String values (except empty string) will force error "NOT_BOOLEAN".

    Return value will converted to JavaScript boolean values - true or false

    Example:

    {
        field: 'boolean';
    }

    Error code: 'NOT_BOOLEAN'

    is

    Сhecks the presence of the value and its correspondence to the specified value

    Example:

    {
        field: { 'is': 'some value' }
    }

    Error codes: 'REQUIRED', 'NOT_ALLOWED_VALUE

    credit_card

    Checks that the value is a credit card number with Lunh Algorithm

    Example:

    {
        field: 'credit_card';
    }

    Error code: 'WRONG_CREDIT_CARD_NUMBER'

    uuid

    Example:

    {
        field1: 'uuid', // default v4
        field2: {uuid: 'v1'},
        field3: {uuid: 'v2'},
        field4: {uuid: 'v3'},
        field5: {uuid: 'v4'},
        field6: {uuid: 'v5'}
    }

    Error code: 'NOT_UUID'

    mongo_id

    Checks that the value looks like mongo object id

    Example:

    {
        field: 'mongo_id',
    }

    Error code: 'NOT_ID'

    list_length

    Checks that the value is a list and it contains required number of elements. You can pass exact number of elements required or a range.

    Do not forget about "required" rule if you want the field to be required.

    Example:

    {
        list1: ['required', { list_length: 10 }]; // List is required and should contain exactly 10 items,
        list2: {
            list_length: 10;
        } // List is not required but if it is present, it should contain exactly 10 items
        list3: {
            list_length: [3, 10];
        } // List is not required but if it is present, it should has from 3 to 10 items
    }

    Error codes: 'FORMAT_ERROR', 'TOO_FEW_ITEMS', 'TOO_MANY_\ITEMS'

    list_items_unique

    Checks that items in list are unique. if the value is not an array, the rule will return "FORMAT_ERROR". The rule will check string representations of the values and supports only primitive values. if the value is not primitive (array, object) then the rule will return 'INCOMPARABLE_ITEMS'

    Example:

    {
        list: 'list_items_unique';
    }

    Error codes: 'FORMAT_ERROR', 'NOT_UNIQUE_ITEMS', 'INCOMPARABLE_ITEMS'

    base64

    Checks that the value is a base64 string

    Example:

    {
        field1: 'base64'; // by default, padding is required
        field2: {
            base64: 'relaxed';
        } // padding is optional
    }

    Error code: 'MALFORMED_BASE64'

    md5

    Checks the value is a md5 hash string

    Example:

    {
        field: 'md5';
    }

    Error code: 'NOT_MD5'

    iso_date

    This rule is compatible with the standard "iso_date" rule (and will redefine it) but allows you to pass extra params - "min" and "max" dates.

    There are special dates: "current", "yesterday", "tomorrow". You can use them if you want to check that passed date is in the future or in the past.

    Example:

    {
        date1: "iso_date",
        date2: { "iso_date": {min: "2017-10-15"} },
        date3: { "iso_date": {max: "2017-10-30"} },
        date4: { "iso_date": {min: "2017-10-15T15:30Z", max: "2017-10-30", format: "datetime"} },
        date5: { "iso_date": {min: "current", max: "tomorrow"} },
        date6: { "iso_date": {format: "datetime"} },
    }

    Supported options:

    • "min" - can be iso8601 date, iso 8601 datetime, "current", "tomorrow", "yesterday".
    • "max" - can be iso8601 date, iso 8601 datetime, "current", "tomorrow", "yesterday".
    • "format" - can be "date", "datetime". (default "date")

    If you pass only date (without time) to "min" or "max" and expected format of user's input is "datetime" then:

    • "min" starts from the beginning of min date.
    • "max" ends at the end of the max date.

    If you pass the time along with the date, then you need to specify the time zone.

    Error codes: 'WRONG_DATE', 'DATE_TOO_LOW', 'DATE_TOO_HIGH'

    required_if

    Checks that the value is present if another field is present and has value.

    Simple example:

    {
        sendMeEmails: { one_of: [0, 1] },
        email: { 'required_if': { sendMeEmails: '1' } }
    }

    Example with JSON pointer:

    {
        address: {nested_object: {
            city: 'required',
            street: 'required'
        }},
    
        email: { 'required_if': { 'address/city': 'Kyiv' } }
    }

    You cannot access parent fields with JSON pointers here, only siblings and nested values.

    Error code: 'REQUIRED'

    instance_of

    Checks that the value is a instaceof a class. This rule is JS specific and not serializable but can be useful for runtime validations

    Example:

    class Dog {}
    
    {
        dog1: {'instance_of': Dog};
    }

    Error code: 'WRONG_INSTANCE'

    has_methods

    Checks that the value is an object which has all of required methods. This rule is JS specific and not serializable but can be useful for runtime validations

    Example:

    {
        dog1: {'has_methods': 'bark'};
        dog2: {'has_methods': ['bark', 'getName']};
    }

    Error code: 'NOT_HAVING_METHOD [${method}]' like 'NOT_HAVING_METHOD [bark]'

    How to add own rule?

    if you want to add own rule, you will need:

    1. Create a new file for the rule in src/rules (see existing rules)
    2. Add rule to src/index.js
    3. Add positive tests to tests/test_suite/positive/your_rule_name/ (see existing tests)
    4. Add negative tests to tests/test_suite/negative/your_rule_name/ (see existing tests)
    5. Update this README!

    Contributors

    @ViraRodionova @ViraRodionova

    Install

    npm i livr-extra-rules

    DownloadsWeekly Downloads

    2,792

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    48.2 kB

    Total Files

    113

    Last publish

    Collaborators

    • koorchik