Incrowd Model Validator

A tool for validating objects against a schema

Motivation

To provide a highly portable validator that can be applied to validate data in frontend projects.

getting started

npm i @incrowd/model-validator

usage

in es6

import ModelValidator from '@incrowd/model-validator'

ModelValidator.setConfig({defaultRequire: false}) /*optional*/

const myModel = new ModelValidator(schema, data)

in vue

in main.js

import ModelValidator from '@incrowd/model-validator'

Vue.use(ModelValidator)

in vue module

<template>
	<div>
		{{name}}
	</div>
</template>

<script>
import ModelValidator from '@incrowd/model-validator'

const schema = {
	name: 'string'
}
const data = {
	name: 'this is a string'
}

export default {
	name: 'component',
	data: () => new ModelValidator(schema, data)
}

</script>

Creating a schema

Schemas can be given as either a string containing just the schema type (setting all other values to their default) or as an object in the following structure:

schema = {
	fieldName: {
		type:     'number',
		required: true, /*optional*/
		arrayOf:  true, /*optional*/
	}
}

Schema types:

| Type | Extra Fields | Description | Example Schema | Example Data | |---------|--------------|---------------------------------------------------|--------------------------------------------------------------------------|---------------------------------------------| |Any | None | Allows any data to be entered. | "any" | 23 | |string | None | Accepts string literals. | "string" | "Example" | |number | None | Accepts number literals. | "number" | 12 | |boolean| None | Accepts boolean values. | "boolean" | true | |date | None | Accepts date strings and Date objects. | "date" | "2021-02-16T15:15:19+00:00" | |color | None | Accepts hex color strings | "color" | "#FFFFFF" | |enum | enum | Accepts values in given enum string. | {type: "enum", enum: [12, 'value', 'something else]} | "value" | |object | schema | Accepts an object that adheres to a child schema. | {type: "object", schema: {childField: "any", booleanChild: "boolean"}} | {childField: 42, booleanChild: false} | |url | None | Accepts a valid url. | "url" | "http://www.example.com/path/to/resource" |

Generic Fields:

these can be applied to any of the above types.

| Field | Description | Example value | |------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------| | required | Makes the field required. the model validator will throw an error if field is not present. | 'true' | | arrayOf | The field expects an array of values that conform to the schema. If required, length must be at least 1 | 'true' | | default | Default value for the field to be used if no value is given. Value does not have to match required type. for example, a string field could have a default of false | "default value" | | alias | An alternate path to find the given data. allows dot notation to be used to fetch data from deeper in the given structure. | "childobject.anotherfield.value" |

Example Schema with valid data

schema = {
	label:       {type: 'string', required: true},
	publishDate: 'date',
	listOfLinks: {
		type:    'url',
		arrayOf: true,
	},
	theme:       {
		type:   'object',
		schema: {
			color1: 'color',
			color2: 'color'
		}
	},
	people:      {
		type:    'object',
		arrayOf: true,
		schema:  {
			name:           {type: 'string', required: true},
			age:            'number',
			favouriteColor: {
				type: 'enum',
				enum: ["Red", "Green", "Blue", "Purple", "Orange", "Pink", "Turquoise"]
			}
		}
	}
}

data = {
	label:       'valid data!',
	publishDate: "Tuesday, 16-Feb-21 16:07:56 UTC",
	listOfLinks: [
		'http://www.example.com',
		"https://www.google.com",
		"http://www.thisisalink.co.uk/path/to/page",
	],
	theme:       {
		color1: '#F00',
		color2: '#3c5afe',
	},
	people:      [
		{
			name:           'John Doe',
			age:            42,
			favouriteColor: "Green"
		},
		{
			name:           'Jane Doe',
			age:            36,
			favouriteColor: "Orange"
		}
	]
}

validatedData = new ModelValidator(schema, data)

Accessing and Updating Data

Data Retrieval

There are two primary ways of retrieving data. by exporting the fields you want (recommended), or by directly accessing the model.

Exporting a model's data

Assuming the schema and data are the same as in the previous example:

let data = new ModelValidator(schema, originalData);

filteredData = data.toObject({
	label:  true,
	people: {
		name: true
	}
})

this will return filtered data to include only the label and each person's name:

filteredData == {
	label:  'valid data!',
	people: [
		{name: 'John Doe'},
		{name: 'Jane Doe'},
	]
}

If you wish to simplify the data returned for a child object, you can use the flatten option in toObject:

let data = new ModelValidator(schema, originalData);

filteredData = data.toObject({
	label:  true,
	people: {
		name: 'flatten'
	}
})

Please note, however, that doing this will prevent the exported data from being re-imported, as it no longer conforms to the expected structure.

filteredData == {
	label:  'valid data!',
	people: [
		'John Doe',
		'Jane Doe',
	]
}

Re-importing exported data

ModelValidator.prototype.update allows updating of an entire structure at once. this means that you can do the following to mutate data:

let data = new ModelValidator(schema, originalData);

filteredData = data.toObject({
	label: true,
	theme: {
		color1: true
	}
})

filteredData.label = 'this is a new label';
filteredData.theme.color1 = '#fe5a3c'

data.update = filteredData;

you can then expect the modelValidator to hold the following:

data == {
	label:       'this is a new label',
	publishDate: "Tuesday, 16-Feb-21 16:07:56 UTC",
	listOfLinks: [
		'http://www.example.com',
		"https://www.google.com",
		"http://www.thisisalink.co.uk/path/to/page",
	],
	theme:       {
		color1: '#fe5a3c',
		color2: '#3c5afe',
	},
	people:      [
		{
			name:           'John Doe',
			age:            42,
			favouriteColor: "Green"
		},
		{
			name:           'Jane Doe',
			age:            36,
			favouriteColor: "Orange"
		}
	]
}