JavaScript object parsing and validation
Get started
The package is available via npm. It has to be installed as a local dependency:
npm install validolum
It's a DSL for parsing and validation of JavaScript objects. It some sense, it is an attempt to create a typesafe replacement for JSONSchema.
Usage
The most straightforward approach for verification is presented in the following listening. verify function is called with two arguments:
- A first argument is an object replicates the structure of expected data, but instead of real values, properties contain function responsible for parsing of the values. There are several predefined validation and parsing functions, but it is also possible to define a custom one. It should satisfy following signature (value: I) => Result<O, string>, where I is input type, O is output type and Result is a container for monadic error handling from a package called amonad.
- A second argument is an object which has to follow provided parsing schema.
The function is also provided with an optional type argument, which describes a type of expected output. It is optional since, in most cases, it can be inferred automatically.
A presented example will be successfully verified and will return { value: 2 } as a result.
// verificationResult is { value: 2 }
In the following case, the value provided for verification does not satisfy expectations. Therefore the function will throw an exception with a detailed description of the detected issue.
// Should throw an Error with an explanation of problem like:// "Key value is not validated due to: Value is not number"
The function is also capable of parsing, so it can attempt to transform data according to our expectations. float is capable of turning a string into a floating number. Since the output type of parsing does not match the type of input anymore, it might be required to provide a second type of argument. It describes a type of input value.
The execution will be successful with { value: 3.1415 } as a result.
// verificationResult is { value: 3.1415 }
The API also contains a special version of verification function, which is capable of handling errors in monadic style. It is possible to learn more about the approach to deal with mistakes in documentation to amonad. Briefly, it returns output wrapped inside Result object, which in some sense similar to Promise. Correctly, validated value is going to be wrapped by Success, while an error is going to return Failure. This technique allows the library to avoid throwing exceptions.
// verificationResult Success({ value: 2 })
maybeVerify has another remarkable ability, it can be partially applied. In this case, it caches provided schema inside of new function, which can be passed around and used for verification of multiple objects.
// verificationResult is Success({ value: 2 })
The function produced as a result of maybeVerify's partial application can also be used as a part of the schema. It allows parsing of nested objects.
// verificationResult is { valueNested: { value: true } }
The last example presents the most real-life scenario, which utilizes all of the previously explained techniques. Firstly, it is a sizeable multi-property schema with a nested object. It was already mentioned that it is possible to create a custom function compatible with the schema. There is a custom type for the representation of City, verification of the type is done by the creation of city function, which can recognize if provided string might be considered as valid City. The function is used as part of address schema, which is after that is used as the nested value inside of the main schema.
// verificationResult is {// name: "Sherlock",// address: {// street: "Baker",// houseNumber: 221,// city: "London"// },// customField: {},// }
API
The package consists of two parts: verification functions and functions, which can be used as part of the schema.
verify()
Basic verify function expects two arguments:
- The first argument is an object which describes the structure of expected values. The object has similar properties, but actual values are replaced with functions responsible for their validation or even parsing.
- The second value is an object which expects to be verified or parsed.
It also accepts two type arguments, the first one represents an output type, while input is meant for input type. By default, an input type is defined based on an output type as an object with the properties of the same kind by with the possibility to be nullable. Input and output types are also reflected in types of parsing functions accepted by the schema. Schema, as well as the output value, contain only properties that appear to be in both of the provided type arguments.
The expected result of the execution is a parsed, and correctly types object. Otherwise, the function will throw an exception with a detailed explanation of the mistake.
maybeVerify()
It is a special version of verify function modified for handling errors in a monadic way. The function is similar in all other ways.
Curred version of maybeVerify can be used for cached of the schema or the creation of custom parsing function for a schema with nested objects.
Parsing and verification functions
The following function can be used as part of the parsing schema.
numeric
There are three functions for the parsing of numeric values. num function is mainly used for verification of values, which expected to be numeric. It is meant for verification that numeric property is defined and that it is indeed number.
float function is more targeted on the extraction of floating numbers out of strings.
int does the same thing, but only for integer.
strings
Strings are the most common type of raw data. str function can verify that the value is really string and that it is defined.
boolean
There is no build-in way to parse boolean. Therefore function is capable of validating if the provided value is boolean or string with correspondent value. Strings are going to be converted accordingly.
object
An object can be detected by obj function. Unfortunately, the function can not provide any other additional information except the fact that the value is an object of unknown shape.
Contribution guidelines
The project is based on npm eco-system. Therefore, development process is organized via npm scripts.
For installation of dependencies run
npm install
To build application once
npm run build
To build an application and watch for changes of files
npm run build:w
To run tslint one time for CI
npm run lint
To unit tests in a watching mode are performed by
npm run test
To execute a test suit single time
npm run test:once
To execute a test suit single time with coverage report
npm run test:c
To execute a test suit single time with coverage report submitted to coveralls
npm run test:ci
Everybody is welcome to contribute and submit pull requests. Please communicate your ideas and suggestions via issues.