livr-extra-rules
Version:
Extra rules for LIVR Validator
327 lines (224 loc) • 7.19 kB
Markdown
# livr-extra-rules
[](https://badge.fury.io/js/livr-extra-rules)
[](https://snyk.io/test/github/koorchik/js-livr-extra-rules?targetFile=package.json)
LIVR specification contains the most common rules that every implementation should support.
The module contains extra rules for [JavaScript LIVR](https://www.npmjs.com/package/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](https://www.npmjs.com/package/livr) itself and this module have **zero dependecies**. It means:
- Lighter builds
- Easier to maintain high level of security
## Usage
```sh
npm install --save livr livr-extra-rules
```
```js
import LIVR from livr;
import extraRules from 'livr-extra-rules';
LIVR.Validator.registerDefaultRules(extraRules);
```
You can use these rules with AsyncValidator as well
```js
import LIVR from livr/async;
import extraRules from 'livr-extra-rules';
LIVR.AsyncValidator.registerDefaultRules(extraRules);
```
## Documentation
- [LIVR for JavaScript](https://www.npmjs.com/package/livr)
- [Official LIVR documentation](http://livr-spec.org/)
## 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:
```js
{
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:
```js
{
field: 'boolean';
}
```
**Error code**: 'NOT_BOOLEAN'
### is
Сhecks the presence of the value and its correspondence to the specified value
Example:
```js
{
field: { 'is': 'some value' }
}
```
**Error codes**: 'REQUIRED', 'NOT_ALLOWED_VALUE
### credit_card
Checks that the value is a credit card number with [Lunh Algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm)
Example:
```js
{
field: 'credit_card';
}
```
**Error code**: 'WRONG_CREDIT_CARD_NUMBER'
### uuid
Example:
```js
{
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:
```js
{
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:
```js
{
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:
```js
{
list: 'list_items_unique';
}
```
**Error codes**: 'FORMAT_ERROR', 'NOT_UNIQUE_ITEMS', 'INCOMPARABLE_ITEMS'
### base64
Checks that the value is a base64 string
Example:
```js
{
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:
```js
{
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:
```js
{
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:
```js
{
sendMeEmails: { one_of: [0, 1] },
email: { 'required_if': { sendMeEmails: '1' } }
}
```
Example with JSON pointer:
```js
{
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:
```js
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:
```js
{
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
[](https://github.com/vira-khdr) [@vira-khdr](https://github.com/vira-khdr)