eskema

Description:

eskema

Eskema is a tool to help you validate dynamic data with a simple yet powerful API.
It as initially intended to validate dynamic JSON returned from an API, passed in by a user or any other scenario where you might need to validate dynamic data. But it's not limited to JSON data, you can validate any type of dinamic data.
Features #

Simple API
Composable / Extensible
Safe
Fully tested

Getting started #
To use the package there's not much to do apart from installing the package or adding it to pubspec.yml. For a guide on how to do it, check the install instructions
Concepts #
Validator #
Mostly everything in Eskema are [Validators], which are functions that take in a value and return a [IResult].
The following are all validators:
isType<String>();
listOfLength(2);
listEach(isType<String>());
all([isType<List>(), isListOfLength(2)]);
copied to clipboard
IResult #
This is a class that represents the result of a validation
Usage #
An example explains more than 100 words, so here are a couple of simple examples.
For more detailed examples check the /examples folder.
Simple example #

NOTE: that if you only want to validate a single value, you probably don't need Eskema.

Otherwise let's check how to validate a single value. You can use validators individually:
final isString = isType<String>();
const result1 = isString('valid string');
const result2 = isString(123);

result1.isValid; // true
result2.isValid; // false
result2.expected; // String
copied to clipboard
Or you can combine validators:
all([isType<String>(), isDate()]); // all validators must be valid
or(isType<String>(), isType<int>()); // either validator must be valid
and(isType<String>(), isType<int>()); // both validator must be valid


// This validator checks that, the value is a list of strings, with length 2, and contains item "test"
all([
isOfLength(2), // checks that the list is of length 2
listEach(isTypeOrNull<String>()), // checks that each item is either string or null
listContains('test'), // list must contain value "test"
]);

// This validator checks a map against a eskema. Map must contain property 'books',
// which is a list of maps that matches a sub-eskema. Subeskema validates that the map has a name which is a string
final matchesEskema = eskema({
'books': listEach(
eskema({
'name': isType<String>(),
}),
),
});
matchesEskema({'books': [{'name': 'book name'}]});
copied to clipboard
Validators #
isType
This validator checks that a value is of a certain type
isType<String>();
isType<int>();
isType<double>();
isType<List>();
isType<Map>();
copied to clipboard
isTypeOrNull
This validator checks that a value is of a certain type or is null
isTypeOrNull<String>();
isTypeOrNull<int>();
copied to clipboard
nullable #
This validator allows to make validators allow null values
nullable(eskema({...}));
copied to clipboard

The validator above, allows a map or null

eskema #
The most common use case will probably be validating JSON or dynamic maps. For this, you can use the eskema validator.
In this example we validate a Map with optional fields and with nested fields.
final validateMap = eskema({
'name': isTypeString(),
'address': nullable(
eskema({
'city': isTypeString(),
'street': isTypeString(),
'number': all([
isTypeInt(),
isMin(0),
]),
'additional': nullable(
eskema({
'doorbel_number': Field([isTypeInt()])
})
),
})
)
});

final invalidResult = validateMap.call({});
invalidResult.isValid; // false
invalidResult.isNotValid; // true
invalidResult.expected; // name -> String
invalidResult.message; // Expected name -> String

final validResult = validateMap.call({ 'name': 'bobby' });
validResult.isValid; // true
validResult.isNotValid; // false
validResult.expected; // Valid
copied to clipboard
listEach #
The other common use case is validating dynamic Lists. For this, you can use the listEach class.
This example validates that the provided value is a List of length 2, and each item must be of type int:
final isValidList = all([
listOfLength(2),
listEach(isTypeInt()),
]);

isValidList.validate(null).isValid; // true
isValidList.validate([]).isValid; // true
isValidList.validate([1, 2]).isValid; // true
isValidList.validate([1, "2"]).isValid; // false
isValidList.validate([1, "2"]).expected; // [1] -> int
copied to clipboard
Additional Validators #
For a complete list of validators, check the docs
Custom Validators #
Eskema offers a set of common Validators located in lib/src/validators.dart. You are not limited to only using these validators, custom ones can be created very easily.
Let's see how to create a validator to check if a string matches a pattern:
Validator validateRegexp(RegExp regexp) {
return (value) {
return Result(
isValid: regexp.hasMatch(value),
expected: 'match pattern $regexp', // the message explaining what this validator expected
);
};
}
copied to clipboard

If you want a validator you built to be part of the package, please send in a PR and I will consider adding it!!

More examples #
For more examples check out the /examples folder. Or check out the docs
Package Name #
Eskema is the Vasque word for "Schema". I did not know what to call the package, and after looking for a bit I found the Vasque word for schema and decided to use it!
Additional information #

For more information check the docs
out.
If you find a bug please file an issue or send a PR my way.
Contributions are welcomed, feel free to send in fixes, new features, custom validators, etc...