legitjs
Version:
Lightweight objects and strings validation for Node.js
244 lines (177 loc) • 6.61 kB
Markdown
# legit.js 0.1.1
Lightweight objects and strings validation for Node.js.
## Usage
Create a schema and use it to validate data.
There are two equivalent usages:
- `schema.test(data)`
- `legit.mize(schema, data)`
These functions return `null` if there was no error validating the data.
If the data didn't fit the schema, they return a description of the error (either a String, an Array, or a Map/Object).
```js
var schema = legit.Number().min(5).max(10);
var err1 = schema.test(30); // err1 = 'Greater than max'
var err2 = schema.test(6); // err2 = null
// alternative usage:
err1 = legit.mize(schema, 30); // err1 = 'Greater than max'
err2 = legit.mize(schema, 6); // err2 = null
```
Note: The keyword "new" should not be used when creating an instance of a schema.
### Real world example
Suppose you have some incoming network data and you want to validate it before using/processing it.
```js
// Create the schema
var userSchema = legit.Map().strict()
.key("user", legit.String().min(3).max(20))
.key("age", legit.Number().min(21));
// Validate incoming data
var err = userSchema.test(data);
if (err) {
// Data did not fit the schema.
// Check 'err' to learn what went wrong.
console.log(err);
}
else {
// Data successfully validated!
// Now you can use/process it with confidence.
...
}
```
## Installing and Importing
Using [NPM](https://npmjs.org/), run the following command in your project's root directory.
```
$ npm install legitjs
```
In your Node.js program:
```js
var legit = require("legitjs");
```
## Types Of Schemas
- [legit.Any()](#legitany)
- [legit.Null()](#legitnull)
- [legit.Boolean()](#legitboolean)
- [legit.Number()](#legitnumber)
- [legit.String()](#legitstring)
- [legit.Array()](#legitarray)
- [legit.Map()](#legitmap)
### legit.Any()
Accepts anything.
Example:
```js
var schema = legit.Any();
schema.test("POTATO") // null
schema.test([1, 2, 3]) // null
```
### legit.Null()
Accepts only `null`.
Example:
```js
var schema = legit.Null();
schema.test("Hello") // 'Not null'
schema.test(null) // null
```
### legit.Boolean()
Accepts only Booleans.
Modifiers:
- `none()`: Accepts `null` and `undefined`.
Example:
```js
var schema = legit.Bool();
schema.test(123) // 'Not a boolean'
schema.test(null) // 'Boolean is null or undefined'
schema.test(true) // null
var schema2 = legit.Bool().none()
schema2.test(null) // null
```
### legit.Number()
Accepts only Numbers.
Modifiers:
- `none()`: Accepts `null` and `undefined`.
- `min(a)`: Sets minimum allowed value (`a`).
- `max(b)`: Sets maximum allowed value (`b`).
Example:
```js
var schema = legit.Number().min(-5).max(30);
schema.test(-5); // null
schema.test(31); // 'Greater than maximum'
schema.test(true); // 'Not a number'
schema.test(null); // 'Number is null or undefined'
```
### legit.String()
Accepts only Strings.
Modifiers:
- `none()`: Accepts `null` and `undefined`.
- `min(a)`: Sets minimum allowed length (`a`).
- `max(b)`: Sets maximum allowed length (`b`).
- `regex(e)`: Sets a regular expression to use (`e`).
Example:
```js
var schema = legit.String().max(12).regex(/(\w+)\s(\w+)/);
schema.test("JohnSmith");
// 'Regular expression didn't match'
schema.test("John Smith");
// null
schema.test("John R. Smith");
// 'Greater than maxmimum'
```
### legit.Array()
Accepts only Arrays. Can be used recursively with all other schemas.
You have two options when using legit.Array():
- Set a schema to validate all objects of the array by using `.type(schema)` once.
- Set a different schema for each item by using `.item(schema)` once for each item, in the expected order.
Modifiers:
- `none()`: Accepts `null` and `undefined`.
- `min(a)`: Sets minimum allowed length (`a`). Only affects same-type arrays.
- `max(b)`: Sets maximum allowed length (`b`). Only affects same-type arrays.
- `type(s)`: Sets a schema (`s`) to test all array items. Establishes array as same-type.
- `item(s)`: Sets a schema (`s`) to test a single item of the array. Establishes array as different-type.
- `strict()`: Rejects arrays with length greater than expected. Only affects different-type arrays.
Example:
```js
// Same-type array
var schema = legit.Array().max(4)
.type(legit.Number().min(0).max(10));
schema.test([1, 2, 3, 4]);
// null
schema.test([1, 2, 3, 4, 5]);
// 'Greater than maxmimum'
schema.test([5, 11]);
// [null, 'Greater than maximum']
// Different-type array
var schema = legit.Array().strict()
.item(legit.String().min(3).max(12))
.item(legit.Number().min(21));
schema.test(["John Smith", 25]);
// null
schema.test(["John", 25, true]);
// [ null, null,
// 'More items than expected (Array in strict mode)' ]
schema.test(["John Smith Jr.", 20]);
// [ 'Greater than maximum', 'Less than minimum' ]
```
### legit.Map()
Accepts only Maps/Objects. Can be used recursively with all other schemas.
Modifiers:
- `none()`: Accepts `null` and `undefined`.
- `strict()`: Rejects maps with unexpected keys.
- `key(n, s)`: Sets an expected key-value pair. `n` is the expected key and `s` is the schema that will be used to validate the value.
Example:
```js
var schema = legit.Map().strict()
.key("user", legit.String().min(3).max(12))
.key("age", legit.Number().min(21));
schema.test({
"user": "John Smith",
"age": 25
})
// null
schema.test({
"user": "John Smith Junior",
"age": 16
})
// { user: 'Greater than maximum',
// age: 'Less than minimum' }
```
## Support/Contact
Feel free to [contact me](https://github.com/danaugrs) with questions, suggestions, or comments.
I hope you enjoy using legit.js as much as I enjoyed writing it.
If you come across any issues, please [report them](https://github.com/danaugrs/legitjs/issues).