mikrovalid v1.0.17

mikrovalid

MikroValid is the minimalist, smart, and easy way to validate objects on both the client and server-side.

MikroValid is the JSON validator that cuts out all the bullshit:

• Dead easy, no proprietary stuff — uses simple JSON objects for schemas and input
• Doesn't pollute your code with "convenient" APIs
• Minimalist approach that will work for the majority of conventional-type objects
• Meant to work effortlessly in both client- and server-side environments
• Tiny (~2.2 KB gzipped), which is ~7-80x smaller than common, popular options
• Zero dependencies
• Has 100% test coverage

Usage

Basic importing and usage

// ES5 format
const { MikroValid } = require('mikrovalid');
// ES6 format
import { MikroValid } from 'mikrovalid';

const mikrovalid = new MikroValid();

const schema = {
  properties: {
    personal: {
      name: {
        type: 'string'
      },
      required: ['name']
    },
    work: {
      office: {
        type: 'string'
      },
      currency: {
        type: 'string'
      },
      salary: {
        type: 'number'
      },
      required: ['office']
    },
    required: ['personal', 'work']
  },
};

const input = {
  personal: {
    name: 'Sam Person'
  },
  work: {
    office: 'London',
    currency: 'GBP',
    salary: 10000
  }
};

const generatedSchema = mikrovalid.schemaFrom(input); // <-- OPTIONAL: You can also generate a schema directly from your input!

const { success, errors } = mikrovalid.test(schema, input);

console.log('Was the test successful?', success);

Warnings and silent mode

By default you will get warnings and non-critical message output. If you want to silence these message, you can instantiate MikroValid by passing true for the isSilent option, like so:

const mikrovalid = new MikroValid(true);

Errors

The errors object includes an aggregation of any errors, both those relating to field-level validation and for inline failures emitted when not having required keys or having excess keys.

Since version 1.0.3 both error formats have the same shape:

[{ "key": "blip", "value": 123, "success": false, "error": "Invalid type" }]

Using schemas

The format is inspired by (but is not the same as, nor compliant with) JSON Schema.

The general shape it uses is:

{
  "properties": {
    "username": {
      "type": "string"
    },
    "required": ["username"]
  }
}

A valid input for this particular schema is:

{
  "username": "Sam Person"
}

Using the schemaFrom() method, you can easily generate schemas for your input. This is especially useful in a programmatic environment in which you can't decide or know before-hand what schema to create. Note that the generated schemas should work for the majority of cases, but you should try this functionality out before relying fully on it.

Properties

properties is the only required root-level object. Each key describes a property of the expected input. In the example, name is of the type string. Note that you never repeat the properties keyword—it's used only in the root.

Allowing or disallowing additional properties

By default, unknown properties will be allowed and valid. Setting additionalProperties to false enables you to disallow any unlisted properties.

Since version 1.0.10 it only works in the direct scope of its location, as per below:

{
  "properties": {
    "first": {
      "type": "string"
    },
    "second": {
      "type": "string"
    },
    "third": {
      "type": "string"
    },
    "additionalProperties": false
  }
}

A payload like this...

{
  "first": "the first",
  "second": "the second",
  "third": "the third",
  "fourth": "the fourth"
}

...would therefore break the validation.

The same can be done with nested objects, by setting additionalProperties in the scope of the object:

{
  "properties": {
    "blip": {
      "type": "string"
    },
    "inside": {
      "type": "object",
      "thing": {
        "type": "string"
      },
      "additionalProperties": false
    }
  }
}

So this would not work:

{
  "blip": "beep bloop",
  "inside": {
    "thing": "scary monster",
    "somethingThatIsNotAllowed": "...?"
  }
}

Required

For each level of nesting, including within objects, a required key with an array of strings may be used to describe properties that must exist at that location.

Even the lowest-level required will be within the properties key after version 1.0.10.

This example requires both the personal_data object, as well as the inner name string:

{
  "properties": {
    "personal_data": {
      "type": "object",
      "name": { "type": "string" },
      "required": ["name"]
    },
    "required": ["personal_data"]
  }
}

Types

The type is the only required item-level object. Allowed types are:

• string
• number
• boolean
• object
• array

You can require basic validation of array items by setting the expected type in items.type:

{
  "properties": {
    "books": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}

For this schema, a valid input could for example be something like:

{
  "books": [{ "author": "Cormac McCarthy" }, { "author": "William Blake" }]
}

Note that this will not work for mixed arrays or for any deeper inspection of object properties.

Formats

You can use a number of special keywords to specify expectations on the input. These are:

• alphanumeric
• date (YYYY-MM-DD)
• email
• hexColor
• numeric
• url

Usage is as simple as:

{
  "properties": {
    "username": {
      "type": "string",
      "format": "email"
    }
  }
}

Deeply nested objects

This example shows 3 levels of nesting with objects.

{
  "properties": {
    "things": {
      "type": "object",
      "required": ["nestedThings"],
      "nestedThings": {
        "type": "object",
        "required": ["deeperThings"],
        "deeperThings": {
          "type": "object",
          "required": ["something"],
          "something": "number"
        }
      }
    },
    "required": ["things"]
  },
}

Minimum length

{
  "properties": {
    "username": {
      "type": "string",
      "minLength": 20
    }
  }
}

Maximum length

{
  "properties": {
    "username": {
      "type": "string",
      "maxLength": 2
    }
  }
}

Minimum value

{
  "properties": {
    "phone": {
      "type": "number",
      "minValue": 1000
    }
  }
}

Maximum value

{
  "properties": {
    "phone": {
      "type": "number",
      "minValue": 1000
    }
  }
}

Matches regular expression pattern

You can provide your own regular expressions to match for.

{
  "properties": {
    "runtime": {
      "type": "string",
      "matchesPattern": /^(nodejs20|python3.7)$/
    }
  }
}

License

MIT. See LICENSE file.