ts-valid
v1.0.0ts-valid
DEPRECATED: Use https://www.npmjs.com/package/type-safe-validator instead which has nicer syntax.
A validation library designed to take full advantage of the TypeScript type system. All return types are inferred directly from the schema.
Motivation
I wanted a library that would guarantee that my validation schema will always fully comply with my TypeScript interfaces. As far I as know, such a library did not exist.
This library aims to completely stop runtime errors by ensuring that a compiled TypeScript program can never mistakenly receive an invalid object from sources such a REST API.
Benefits
- Less bugs. No disparity between the schema and the interface your code compiles.
- If an object successfully makes its way into your domain, it is guaranteed to be in the correct shape.
- Explicit checks for
null
andundefined
. - Infinitely nestable schemas for Objects, Tuples, Arrays, Records and Union types.
- Supports literal types.
- Direct support custom parsers and "Opaque" types (see
ts-essentials
module). - All excess properties are trimmed and a deep copy is returned. The original object is untouched.
Usage modes
Two primary usages depending on preference:
Use assertValid
to get a validated object, or throw if there is an error:
const answer = assertValid(input, schema);
Use getValid
to get a tuple which contains a validation object, or detailed failure information:
const [answer, validation, messages] = getValid(input, schema);
if (answer !== ValidationFail) {
// Use answer
}
The validation
object will mirror the object shape, but for each of the property values, a string
will be present if there is an error, or null
is there is no error.
The messages
array will contain a flattened list of all error messages, each with a path
property (i.e. 'a.b.c'), and a human readable err
string.
Example
Here is how to validate a simple object. See tests for many more examples and to see how error results are returned.
import { assertValid } from 'ts-valid';
interface Schema {
one: number;
two: string | null;
three?: number;
}
const schema = [{
one: ['number', []],
two: ['string', ['Null']],
three: ['number', ['Opt']],
}, []] as const;
// Type error will show here if the schema and interface 'mis-align'.
// Will throw if input doesn't comply with schema.
const answer: Schema = assertValid(
{
one: 1,
two: 'two',
three: 3,
extra: 'disappear', // This prop will disappear as not in the schema
},
schema,
);
Alternative usage...
import { getValid, ValidationFail } from 'ts-valid';
const [answer, validation, messages] = getValid(
{
one: 'one', // Deliberate mistake
two: 'two',
three: true, // Deliberate mistake
},
schema,
);
if (answer !== ValidationFail) {
// Use answer
} else {
// Read from either `validation` or `messages`
// validation = {
// one: '"one" is not a number.',
// two: null,
// three: '"true" is not a number.',
// }
// messages = [
// { path: 'root.one', err: '"one" is not a number.' },
// { path: 'root.three', err: '"true" is not a number.' },
// ]
}
Notes
This library is a work in progress however I am already using it in two major projects. Feedback is welcome.