livr-extra-rules
Version:
Extra rules for LIVR Validator
366 lines (256 loc) • 9.03 kB
Markdown
# livr-extra-rules
> Extra validation rules for LIVR with zero dependencies
[](https://badge.fury.io/js/livr-extra-rules)
[](https://www.npmjs.com/package/livr-extra-rules)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://snyk.io/test/github/koorchik/js-livr-extra-rules?targetFile=package.json)
---
## Table of Contents
- [Highlights](#highlights)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Rules Overview](#rules-overview)
- [Rule Documentation](#rule-documentation)
- [`ipv4`](#ipv4)
- [`boolean`](#boolean)
- [`is`](#is)
- [`credit_card`](#credit_card)
- [`uuid`](#uuid)
- [`mongo_id`](#mongo_id)
- [`list_length`](#list_length)
- [`list_items_unique`](#list_items_unique)
- [`base64`](#base64)
- [`md5`](#md5)
- [`iso_date`](#iso_date)
- [`required_if`](#required_if)
- [`instance_of`](#instance_of)
- [`has_methods`](#has_methods)
- [Contributing](#contributing)
- [Documentation](#documentation)
- [Contributors](#contributors)
- [License](#license)
---
## Highlights
- **Zero Dependencies** — Lighter builds, easier to maintain high level of security
- **TypeScript Support** — Full type definitions included
- **14 Extra Rules** — Credit cards, UUIDs, dates, IP addresses, and more
## Installation
```sh
npm install livr livr-extra-rules
```
## Quick Start
```js
import LIVR from 'livr';
import extraRules from 'livr-extra-rules';
LIVR.Validator.registerDefaultRules(extraRules);
```
Works with AsyncValidator too:
```js
import LIVR from 'livr/async';
import extraRules from 'livr-extra-rules';
LIVR.AsyncValidator.registerDefaultRules(extraRules);
```
---
## Rules Overview
| Rule | Description | Error Code(s) |
|------|-------------|---------------|
| [`ipv4`](#ipv4) | Validates IPv4 addresses | `NOT_IP` |
| [`boolean`](#boolean) | Checks for true/false values | `NOT_BOOLEAN` |
| [`is`](#is) | Exact value match | `REQUIRED`, `NOT_ALLOWED_VALUE` |
| [`credit_card`](#credit_card) | Validates credit card numbers (Luhn) | `WRONG_CREDIT_CARD_NUMBER` |
| [`uuid`](#uuid) | Validates UUID (v1-v5) | `NOT_UUID` |
| [`mongo_id`](#mongo_id) | Validates MongoDB ObjectId | `NOT_ID` |
| [`list_length`](#list_length) | Validates array length | `FORMAT_ERROR`, `TOO_FEW_ITEMS`, `TOO_MANY_ITEMS` |
| [`list_items_unique`](#list_items_unique) | Checks array uniqueness | `FORMAT_ERROR`, `NOT_UNIQUE_ITEMS`, `INCOMPARABLE_ITEMS` |
| [`base64`](#base64) | Validates base64 strings | `MALFORMED_BASE64` |
| [`md5`](#md5) | Validates MD5 hash strings | `NOT_MD5` |
| [`iso_date`](#iso_date) | Extended ISO date validation | `WRONG_DATE`, `DATE_TOO_LOW`, `DATE_TOO_HIGH` |
| [`required_if`](#required_if) | Conditional required field | `REQUIRED` |
| [`instance_of`](#instance_of) | Class instance check | `WRONG_INSTANCE` |
| [`has_methods`](#has_methods) | Object method check | `NOT_HAVING_METHOD [method]` |
---
## Rule Documentation
### `ipv4`
Validates IPv4 addresses.
```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 return error `NOT_BOOLEAN`.
Return value will be converted to JavaScript boolean values — `true` or `false`.
```js
{
field: 'boolean'
}
```
**Error code:** `NOT_BOOLEAN`
### `is`
Checks the presence of the value and its correspondence to the specified value.
```js
{
field: { 'is': 'some value' }
}
```
**Error codes:** `REQUIRED`, `NOT_ALLOWED_VALUE`
### `credit_card`
Checks that the value is a credit card number with [Luhn Algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm).
```js
{
field: 'credit_card'
}
```
**Error code:** `WRONG_CREDIT_CARD_NUMBER`
### `uuid`
Validates UUID strings (versions 1-5).
```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 a MongoDB ObjectId.
```js
{
field: 'mongo_id'
}
```
**Error code:** `NOT_ID`
### `list_length`
Checks that the value is a list and contains the required number of elements. You can pass an exact number or a range.
> **Note:** Don't forget about the `required` rule if you want the field to be required.
```js
{
// List is required and should contain exactly 10 items
list1: ['required', { list_length: 10 }],
// List is not required but if present, should contain exactly 10 items
list2: { list_length: 10 },
// List is not required but if present, should have from 3 to 10 items
list3: { list_length: [3, 10] }
}
```
**Error codes:** `FORMAT_ERROR`, `TOO_FEW_ITEMS`, `TOO_MANY_ITEMS`
### `list_items_unique`
Checks that items in a list are unique. The rule checks string representations of values and supports only primitive values.
- If the value is not an array → `FORMAT_ERROR`
- If the value is not primitive (array, object) → `INCOMPARABLE_ITEMS`
```js
{
list: 'list_items_unique'
}
```
**Error codes:** `FORMAT_ERROR`, `NOT_UNIQUE_ITEMS`, `INCOMPARABLE_ITEMS`
### `base64`
Validates base64 encoded strings.
```js
{
field1: 'base64', // padding is required (default)
field2: { base64: 'relaxed' } // padding is optional
}
```
**Error code:** `MALFORMED_BASE64`
### `md5`
Validates MD5 hash strings.
```js
{
field: 'md5'
}
```
**Error code:** `NOT_MD5`
### `iso_date`
Compatible with the standard `iso_date` rule (and will redefine it) but allows extra params — `min` and `max` dates.
Special date values: `current`, `yesterday`, `tomorrow` — useful for checking if a date is in the future or past.
```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' } }
}
```
**Options:**
| Option | Description | Default |
|--------|-------------|---------|
| `min` | ISO 8601 date/datetime, `current`, `tomorrow`, `yesterday` | — |
| `max` | ISO 8601 date/datetime, `current`, `tomorrow`, `yesterday` | — |
| `format` | `date` or `datetime` | `date` |
**Date boundary behavior:**
If you pass only a date (without time) to `min` or `max` and the expected format is `datetime`:
- `min` starts from the beginning of the min date
- `max` ends at the end of the max date
If you pass the time along with the date, 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 a specific value.
**Simple example:**
```js
{
sendMeEmails: { one_of: [0, 1] },
email: { required_if: { sendMeEmails: '1' } }
}
```
**With JSON pointer:**
```js
{
address: {
nested_object: {
city: 'required',
street: 'required'
}
},
email: { required_if: { 'address/city': 'Kyiv' } }
}
```
> **Note:** You cannot access parent fields with JSON pointers here, only siblings and nested values.
**Error code:** `REQUIRED`
### `instance_of`
Checks that the value is an instanceof a class.
> **Note:** This rule is JS-specific and not serializable but can be useful for runtime validations.
```js
class Dog {}
{
dog1: { instance_of: Dog }
}
```
**Error code:** `WRONG_INSTANCE`
### `has_methods`
Checks that the value is an object which has all required methods.
> **Note:** This rule is JS-specific and not serializable but can be useful for runtime validations.
```js
{
dog1: { has_methods: 'bark' },
dog2: { has_methods: ['bark', 'getName'] }
}
```
**Error code:** `NOT_HAVING_METHOD [${method}]` (e.g., `NOT_HAVING_METHOD [bark]`)
---
## Contributing
To add a new rule:
1. Create a new file in `src/rules/` (see existing rules for reference)
2. Export the rule in `src/index.js`
3. Add positive tests in `tests/test_suite/positive/your_rule_name/`
4. Add negative tests in `tests/test_suite/negative/your_rule_name/`
5. Update this README
## Documentation
- [LIVR for JavaScript](https://www.npmjs.com/package/livr)
- [Official LIVR documentation](http://livr-spec.org/)
---
## Contributors
[](https://github.com/vira-khdr) [@vira-khdr](https://github.com/vira-khdr)
---
## License
MIT