shapeit is an object validation tools for Javascript and, specially, Typescript. With it, you can ensure any javascript object has a provided shape corresponding to a typescript type. You can also do asynchronous data validation of any nested object and get decent error messages.
assertfunction from validate now throws an error instead of returning the original contition.- Fix: If you have any rule that uses
asserttwo or more times sequentially, convert it to an array of rules.
- Fix: If you have any rule that uses
Example (expand)
sp.validate(myObj, {
myProperty: (value, assert) => {
assert(testCondition1(value), 'error message 1');
assert(testCondition2(value), 'error message 2');
}
});would be replaced by
sp.validate(myObj, {
myProperty: [
(value, assert) => assert(testCondition1(value), 'error message 1'),
(value, assert) => assert(testCondition2(value), 'error message 2'),
]
});or simply
sp.validate(myObj, {
myProperty: [
value => sp.assert(testCondition1(value), 'error message 1'),
value => sp.assert(testCondition2(value), 'error message 2'),
]
});- Importing
shapeit's subfolders won't work anymore.- Fix: If you had any import like
import { ... } from 'shapeit/...';, import it directly from'shapeit'.
- Fix: If you had any import like
shapeit consists of two different parts.
The first one is called guards and is dedicated to typecheking, so, its synchronous all the way down since typescript demands.
The second one is called validation and is dedicated to apply rules to a typechecked input. Since validation can be asynchronous, all the rules are applied asynchronously.
A basic example of guards usage would be like this
const sp = require('shapeit');
// First we create a guard
const personShape = sp.shape({
name: 'string',
age: 'number',
});
// Then we create some objects (consider they as unknown types)
const p1 = {
name: 'John',
age: 26
};
const p2 = {
name: 'Mary',
age: '27'
};
// Then we test then against the created shape
if (personShape(p1)) {
p1; // p1 is now typed as { name: string; age: number }
}
personShape.errors; // null
if (personShape(p2)) {
p2; // This line is not executed since p2 doesn't fit the shape
}
personShape.errors; // { '$.age': [ "Invalid type provided. Expected: 'number'" ] }
// Or, for a list of all errors
personShape.errors.all // [{ path: '$.age', message: "Invalid type provided. Expected: 'number'" }]And a more complex one (expand)
import * as sp from 'shapeit';
const personShape = sp.shape({
name: 'string',
age: 'number',
emails: sp.arrayOf('string')
});
const person = {
name: 'John Doe',
age: 25,
emails: [
'john.doe@example.com',
'john_doe@email.com',
null
]
};
if (personShape(person)) {
person; // Unexecuted line
}
personShape.errors; // { '$.emails.2': [ "Invalid type provided. Expected: 'string'" ] }Validation consists of matching an object against a set of rules.
A set of rules can be either
- A validation function that receives the original object and the assert function
- A validation object containing some of the input's keys, each one matching a set of rules for the corresponding key on the input
- An array containing multiple sets of rules
Any failing assertion will throw an AssertionError
A simple example looks like this
const sp = require('shapeit');
// First, we get a valid typed object
const person = {
name: 'Not John Doe',
age: 25
};
// Then we can validate it
sp.validate(person, {
name: (name, assert) => {
assert(name === 'John Doe', 'You must be John Doe');
},
age: age => {
// assert can be imported directly from shapeit.
// The second argument is optional
sp.assert(age >= 18, 'You must be at least 18 years old');
}
}).then(result => {
result.valid; // false
result.errors; // { '$.name': ['You must be John Doe'] }
});And a more complex one (expand)
import * as sp from 'shapeit';
// Typescript interface (you can obtain that with guards too)
interface Person {
name: string;
age: number;
emails: string[];
// Notice "job" is an optional parameter
job?: {
id: number;
bossId: number;
}
}
const person: Person = {
name: 'John Doe',
age: 25,
emails: [
'john.doe@example.com',
'john_doe@email.com'
],
job: {
id: 13,
bossId: 10
}
};
sp.validate(person, {
name: name => {
sp.assert(name === 'John Doe', 'You must be John Doe');
},
age: age => {
sp.assert(age >= 18, 'You must be at least 18 years old');
},
// An object validator can be an object with its keys
job: {
// Those rules will be evaluated only if key "job"
// exists in the person object. So, don't need to
// worry about that
id: async jobId => {
sp.assert(
await existsOnDb(jobId),
'This job doesnt exist on database'
)
},
// Rules can be asynchronous functions 🥳
// and all of them will be executed in parallel
bossId: async bossId => {
sp.assert(
await existsOnDb(bossId),
'This employee doesnt exist on database'
)
}
},
// When you need to validate the entire object and its keys,
// you can pass an array containing
// its rule and the rules for its members
emails: [
emails => {
sp.assert(emails.length > 0, 'Provide at least one email');
},
{
// $each is a way to apply the same rule
// to all the array elements
$each: email => {
sp.assert(isValidEmail(email), 'Invalid email');
}
}
]
}).then(result => {
// Do something with validation result
});This way, you can set schemas to validate all your incoming data with typesafety and get error messages matching the fields of your object.
shapeit allows you to configure the error messages generated by the type guards like below.
const { config } = require('shapeit');
config.set('errorMessage', typename => {
return `I was expecting for a ${typename}`;
});
config.set('sizeErrorMessage', size => {
return `Give me an array of size ${size} the next time`;
});Or, if you just want to return to the default values,
config.set('errorMessage', 'default');
config.set('sizeErrorMessage', 'default');You can also get the current configuration like below
const genErrorMessage = config.get('errorMessage');
Primitive
String representing a JS basic type.
type Primitive =
| 'number' | 'string' | 'boolean'
| 'bigint' | 'object' | 'symbol'
| 'null' | 'undefined';
ValidationErrors
Representation of the errors found on a validation process. It's a map of property paths to an array of error messages.
type ValidationErrors = Record<string, string[]>;
Guard
Basic guard type. Can be called to verify a type synchronously. Validation errors will be present on Guard.errors after validation is complete.
type Guard<T> = {
(input: unknown): input is T;
errors: ValidationErrors;
}
GuardSchema
Schema for defining a shape guard. Represents the keys of an object mapped to their respective types.
type GuardSchema = Record<string, Primitive | Guard>;
is(type: Primitive)
Creates a basic guard for a primitive type
const isString = is('string');
if (isString(value)) {
value; // string
}
else {
console.error(isString.errors); // Errors found
}
instanceOf(constructor: GenericClass)
Creates a native instanceof guard. Can be useful when used in conjunction with other guards.
class MyClass {
// My class code...
}
const isMyClass = instanceOf(MyClass);
if (isMyClass(value)) {
doSomethingWith(value); // value is typed as MyClass
}
else {
console.error(isMyClass.errors); // Errors found
}
oneOf(...types: (Primitive | Guard)[])
Creates a guard for a union type from primitive names or other guards
const isValid = oneOf('string', is('number'));
if (isValid(input)) {
doSomethingWith(input); // input is typed as string | number
}
else {
console.error(isValid.errors); // Errors found
}
allOf(...types: (Primitive | Guard)[])
Creates a guard for a intersection type from primitive names or other guards
const isValid = allOf(
looseShape({ a: 'string' }),
looseShape({ b: 'number' })
);
if (isValid(input)) {
doSomethingWith(input); // input is typed as { a: string; b: number; }
}
else {
console.error(isValid.errors); // Errors found
}
shape(schema: GuardSchema, strict = true)
Makes a guard for an object. Types can be specified with other guards or primitive names.
const isValidData = shape({
name: 'string',
emails: arrayOf('string')
});
if (isValidData(input)) {
doSomethingWith(input); // input is typed as { name: string, emails: string[] }
}
else {
console.error(isValidData.errors); // Errors found
}The strict parameter can be passed to specify if the validation must ensure there are no extraneous keys on the object or not (defaults to true).
const isValidData = shape({
name: 'string',
emails: arrayOf('string')
}, false);
// This will be valid
isValidData({
name: 'John Doe',
emails: ['john@doe.com', 'john.doe@example.com'],
age: 34
});
arrayOf(type: Primitive | Guard)
Creates an array shape where all elements must have the same type
const emailsShape = sp.arrayOf('string');
const peopleShape = sp.arrayOf(
sp.shape({
name: 'string',
age: 'number'
})
);
tuple(...types: (Primitive | Guard)[])
Creates a guard for a tuple type. The order of the arguments is the same as the type order of the tuple
const entryShape = sp.tuple('string', 'number');
if (entryShape(input)) {
input; // Typed as [string, number]
}
literal(...template: Template)
Creates a guard for a template literal type. It's used alongside with $, $$ and $$$.
$ is used for generating a tempate type derived from a primitive or a list of primitives or literals
const idTemplate = sp.literal('id-', sp.$('bigint'));
if (idTemplate(input)) {
input; // input is typed as `id-${bigint}`
}$$ is used for generating sets of allowed values.
const versionTemplate = sp.literal(
sp.$('bigint'), '.', sp.$('bigint'), '.', sp.$('bigint'),
sp.$$('', '-alpha', '-beta')
);
if (versionTemplate(input)) {
input; // input is typed as `${bigint}.${bigint}.${bigint}${'' | '-alpha' | '-beta'}`
}$$$ is used for generating recursive template types
const testTemplate = sp.literal(
'a-', sp.$('number', sp.$$$('b', $('number')))
);
if (testTemplate(input)) {
input; // input is typed as `a-${number | `b-${number}`}`;
}
narrow(...targets: any[])
Creates a guard that perfectly narrows a type.
const is10 = sp.narrow(10);
if (is10(input)) {
input; // typed as 10
}
const isAorB = sp.narrow('a', 'b');
if (isAorB(input)) {
input; // typed as 'a' | 'b'
}
const isLikeMyVerySpecificObject = sp.narrow({
my: {
specific: {
property: 'my-specific-value'
}
},
another: {
specific: {
property: 'another-specific-value'
}
}
});
if (isLikeMyVerySpecificObject(input)) {
input; // typed exactly as the (very specific) object provided
}
unknown()
Creates a guard that always validates
Equivalent to unknown type in TS.
never()
Creates a guard that never validates
Equivalent to never type in TS.
any()
Creates a guard that always validates
Equivalent to any type in TS.
For improved type safety, use unknown instead
custom(name: string, validator: (input: unknown) => input is any)
Creates a custom guard from a typeguard function
const myCustomType = sp.custom(
'myCustomType',
(input): input is MyCustomType => {
let result : boolean;
// test if input is MyCustomType
return result;
}
);custom also allows you to define your own error messages by simply seting the errors property of the generated guard.
const myCustomType = sp.custom(
'myCustomType',
(input): input is MyCustomType => {
let result : boolean;
// test if input is MyCustomType
if (!result) {
myCustomType.errors = {
'$.my.property': ['This value is invalid']
}
}
return result;
}
);
looseShape(schema: GuardSchema)
Equivalent of shape(schema, false)
strictShape(schema: GuardSchema)
Equivalent of shape(schema, true)
pick(guard: Guard, keys: string[])
Creates a shape guard from an original shape by picking a set of its keys.
omit(guard: Guard, keys: string[])
Creates a shape guard from an original shape by omiting a set of its keys.
partial(guard: Guard)
Creates a shape where all object keys are optional.
This is NOT valid for nested keys inside objects. If you really need it, use deepPartial instead
deepPartial(guard: Guard)
Creates a shape where all object keys and nested keys are optional
maybe(guard: Primitive | Guard)
Shorthand for oneOf(guard, 'undefined');
nullable(guard: Primitive | Guard)
Shorthand for oneOf(guard, 'null');
Add ESM support🎉Improve the validation API🎉Add validation mechanism to the guards API directly🎉- Improve docs
- Release v1.0