https://github.com/jomik/cerberus
https://github.com/jomik/cerberus
type-safety typescript-library validation-library
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jomik/cerberus
- Owner: Jomik
- License: mit
- Created: 2018-01-30T08:27:08.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-06-01T01:01:38.000Z (about 6 years ago)
- Last Synced: 2024-09-16T11:27:21.853Z (over 1 year ago)
- Topics: type-safety, typescript-library, validation-library
- Language: TypeScript
- Size: 2.08 MB
- Stars: 14
- Watchers: 5
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Cerberus
_The typescript object validator_ \
Experimental, work in progress.
[](https://travis-ci.org/Jomik/cerberus)
[](https://codecov.io/gh/jomik/cerberus)
[](https://david-dm.org/jomik/cerberus)
[](https://david-dm.org/jomik/cerberus?type=dev)
[](https://greenkeeper.io/)
Here is a basic example.
```ts
// We can import the schema `types` to match the types of Typescript.
import { object, any, string, number } from "cerberus";
// Create our schema
const schema = object({
a: string,
b: number,
c: any
});
// Get an object to test
const obj: any = { a: "foo", b: 42, c: "bar" };
// Validate the object against the schema
const result = schema.validate(obj);
if (result.valid) {
// A valid result gives us
// result.obj: { a: string, b: number, c: any }
}
```
## Features
- Validation against types and exact values
- Correctly typed result object
- Relevant constraints for each type, e.g. string.length
- Optional and default values
- Referencing values within objects
- Asynchronously validate values with mapAsync
## Installation
```
npm install cerberus
```
## Examples
```ts
import { object, array, string, integer } from "cerberus";
const person = object({ name: string, id: integer.positive() });
const schema = object({
...person.schema,
mother: person,
father: person,
children: array(person)
});
const result = schema.validate({
name: "foo jr bar",
id: 3,
mother: { name: "baz buz bar", id: 1 },
father: { name: "foo bar", id: 2 },
children: [{ name: "bum bar", id: 4 }, { name: "baz bar", id: 5 }]
});
```
## API Documentation
_Temporary_
### Types
The below functions are exposed to create a validator.
- `boolean: Validator`
- `number: Validator`
- `string: Validator`
- `any: Validator`
- `integer: Validator` - not a decimal
- `nil: Validator`
- `required: Validator` - not undefined and not null
- `forbidden: Validator`
- `array(Validator): Validator`
- `object(Schema): Validator`
A schema is an object where each property is a validator or a function from `A` to a validator.
### Runners
Below are the two methods of running a validator. Both of these also have an async version, called by appending `Async`.
#### `validate(Validator, value): Result`, `validateAsync(Validator, value): Result`
Result contains an `info` property, which is an object containing whether the result is valid or not, and if it is valid, it holds the validated value, else it holds an error.
`info: { valid: true; object: A } | { valid: false; error: ValidationError }`
#### `assert(Validator, value): A`, `assertAsync(Validator, value): A`
Returns the validated value, or throws an error if invalid.
### Logical operators
The below functions are exposed for logical operations on validators.
They are also methods on the class, if you prefer chaining.
#### `and(Validator, Validator): Validator`
Short circuits if the first is invalid.
#### `or(Validator, Validator): Validator`
Short circuits if the first is valid.
#### `xor(Validator, Validator): Validator`
Is valid if only one is valid, invalid in all other cases.
### Methods
#### `#default(a: A): Validator`
Allows the value to be undefined, and returns `a` in that case.
#### `#optional(): Validator`
Allows the value to be undefined.
#### `#not(a: A): Validator`
Ensures that the value is not strictly equal to `a`.
#### `#map(A -> B): Validator`, `mapAsync(A -> Promise): Validator`
Maps the result through the function if the validator returns valid.
## Contribute
Please submit an issue with outlining your idea. If small, a pull request can be submitted immediately.
- [Pull Requests](https://github.com/Jomik/cerberus/pulls)
- [Issues](https://github.com/Jomik/cerberus/issues)
## License
This project is licensed under the MIT license.