JSON schema validator with excellent type inference for JavaScript and TypeScript.
npm install tiny-schema-validatorJSON schema validator with excellent type inference for JavaScript and TypeScript.
 !Minzipped size
``sh`
npm install tiny-schema-validatoror
yarn add tiny-schema-validator
`js
import { createSchema, _ } from 'tiny-schema-validator';
export const User = createSchema({
metadata: _.record({
date_created: _.number(),
id: _.string(),
}),
profile: _.record({
name: _.string({
maxLength: [100, 'too-long'],
minLength: [2, 'too-short'],
}),
age: _.number({
max: [150, 'too-old'],
min: [13, 'too-young'],
}),
email: _.string({
pattern: [/^[^@]+@[^@]+\.[^@]+$/, 'invalid-email'],
}),
}),
payment_status: _.union(
_.constant('pending'),
_.constant('failed'),
_.constant('success'),
_.constant('canceled')
),
});
`
and in TypeScript, everything is the same, but to get the data type inferred from the schema, you can do this:
`ts`
/*
UserType {
metadata: {
date_created: number;
id: string;
};
profile: {
name: string;
age: number;
email: string;
};
payment_status: 'pending' | 'failed' | 'success' | 'canceled';
}
*/
export type UserType = ReturnType
When you create a schema, you will get a nice API to handle multiple use-cases in the client and the server.
- is(data: any): boolean check if the data is valid (eager evaluation)validate(data: any): Errors
- errors returned has the same shape as the schema you defined (does not throw)produce(data: any): data
- throws an error when the data is invalid. otherwise, it returns dataembed(config?: { optional: boolean })
- embeds the schema in other schemassource
- the schema itself in a parsable format
example usage:
`js
const Person = createSchema({
name: _.string(),
age: _.number(),
email: _.string(),
});
const john = { name: 'john', age: 42, email: 'john@gmail.com' };
Person.is({}); // false
Person.is(john); // true
Person.validate({}); // { name: 'invalid-type', age: 'invalid-type', email: 'invalid-type' }
Person.validate(john); // null
try {
Person.produce(undefined);
} catch (e) {
console.log(e instanceof TypeError); // true
console.log(e.message); // "invalid-data"
}
// embedding the person schema
const GroupOfPeople = createSchema({
// ...
people: _.listof(Person.embed()),
// ...
});
`
All validators are required by default.
All validators are accessible with the _ (underscore) namespace; The reason for using _ instead of a good name like validators is developer experience, and you can alias it to whatever you want.
`js`
import { _ as validators } from 'tiny-schema-validator';
Example of all validators and corresponding Typescript types:
`js
import { _ } from 'tiny-schema-validator';
// NOTE: when you call a validator you just create an object
// containing { type: '
// this is just a shorthand for that.
// simple validators.
_.string(); // string
_.number(); // number
_.boolean(); // boolean
_.constant(42); // 42
// complex validators (types that accepts other types as paramater)
_.union(
_.record({ id: _.string() }),
_.constant(1),
_.constant(2),
_.constant(3)
); // { id: string; } | 1 | 2 | 3
_.list([
_.number(),
_.string(),
]); // [number, number]
_.record({
timestamp: _.number(),
id: _.string(),
}); // { timestamp: number; id: string; }
_.listof(validators.string()); // string[]
_.recordof(validators.string()); // Record
`
Check out the full validators API below:
| validator | signature | props |
| :-------- | ------------------------------- | :------------------------------------------------------------- |
| | | |
| constant | constant(value) | value: string \| number \| boolean |string(options?)
| | | |
| string | | options (optional): Object |optional : boolean
| | | - defaults to false |maxLength: [length: number, error: string]
| | | - |minLength: [length: number, error: string]
| | | - |pattern : [pattern: RegExp, error: string]
| | | - |number(options?)
| | | |
| number | | options(optional): Object |optional: boolean
| | | - default to false |min: [number, error: string]
| | | - |max: [number, error: string]
| | | - |is : ['integer' \| 'float', error: string]
| | | - default is both |boolean(options?)
| | | |
| boolean | | options(optional): Object |optional: boolean
| | | - default to false |union(...validators)
| | | |
| union | | validators: Array of validators as paramaters |list(validators[], options?)
| | | |
| list | | validators: Array of validators |optional: boolean
| | | options(optional): Object |
| | | - default to false |listof(validator, options?)
| | | |
| listof | | validator: Validator |optional: boolean
| | | options(optional): Object |
| | | - default to false |record(shape, options?)
| | | |
| record | | shape: Object { [key: string]: Validator } |optional: boolean
| | | options(optional): Object |
| | | - default to false |recordof(validator, options?)
| | | |
| recordof | | validator: Validator |optional: boolean
| | | options(optional): Object |
| | | - default to false |
To create custom validators that do not break type inference:
- use validators from _ as building blocks for your custom validator.optional
- your custom validator should define and required functions.
Example of creating custom validators:
`js
const alphaNumeric = (() => {
const config = {
pattern: [/^[a-zA-Z0-9]*$/, 'only-letters-and-number'],
};
return {
required: additional => _.string({ ...additional, ...config, optional: false }), // inferred as Required
optional: additional => _.string({ ...additional, ...config, optional: true }), // inferred as Optional
};
})();
const Person = createSchema({
// ...
username: alphaNumeric.required({ maxLength: [20, 'username-too-long'] }),
// ...
});
`
`js
// when typeof value does not match the validator infered type
const TYPEERR = 'invalid-type';
// when "schema" in createSchema(schema) is not plain object
const SCHEMAERR = 'invalid-schema';
// when produce(data) and "data" failed to match the schema
// always accompanied be TypeError, so make sure to catch it
const DATAERR = 'invalid-data';
// when an unknown key is found in data while using record | list
// and any keys that exists on data and not present in the schema
const UNKOWN_KEY_ERR = 'unknown-key';
`
- When using the recordof | listof | list validators, the optional property of the validator is ignored, example:
`js`
_.recordof(_.string({ optional: true / THIS IS IGNORED / }));
_.list([_.number({ optional: true / THIS IS IGNORED / }), _.number()]);
- You might expect errors returned from a list | listof validators to be an array but it is actually an object, example:
`js`
const list = createSchema({ list: _.listof(_.string()) });
list.validate({ list: ['string', 42, 'string'] }); // { list: { 1: 'invalid-type' } }
Currently, there's no easy way to create recursive types. if you think you could help, PRs are welcome
if you try to wrap your schema, you will encounter this error (Type instantiation is excessively deep and possibly infinite)
to fix it, you should unwrap your schema and re-create it inside your abstraction.
let's take the following example:
`ts
const User = createSchema({
name: _.string(),
age: _.number(),
});
// your abstraction
function schemaWrapper
//...
}
const wrappedUser = schemaWrapper(User); // ERROR: Type instantiation is excessively deep and possibly infinite
`
The fix:
`ts
import { Schema, R, RecordOptions } from 'tiny-schema-validator';
/*
optionally, to infer data from the embedded schema, you do DataFrom
import { DataFrom } from 'tiny-schema-validator/dist/type-utils';
*/
// extract schema with Schema.embed()
function schemaWrapper
const newSchema = createSchema(schema.shape); // you can add/remove/modify passed schema here
// ...
}
const wrappedUser = schemaWrapper(User.embed()); // all good no errors
``