Introduction
Superstruct makes it easy to define interfaces and then validate JavaScript data against them. Its type annotation API was inspired by Typescript, Flow, Go, and GraphQL, giving it a familiar and easy to understand API.
But Superstruct is designed for validating data at runtime, so it throws (or returns) detailed runtime errors for you or your end users. This is especially useful in situations like accepting arbitrary input in a REST or GraphQL API. But it can even be used to validate internal data structures at runtime when needed.
Usage
Superstruct allows you to define the shape of data you want to validate:
1
import { assert, object, number, string, array } from 'superstruct'
2
3
const Article = object({
4
id: number(),
5
title: string(),
6
tags: array(string()),
7
author: object({
8
id: number(),
9
}),
10
})
11
12
const data = {
13
id: 34,
14
title: 'Hello World',
15
tags: ['news', 'features'],
16
author: {
17
id: 1,
18
},
19
}
20
21
assert(data, Article)
22
// This will throw an error when the data is invalid.
23
// If you'd rather not throw, you can use `is()` or `validate()`.
Copied!
Superstruct ships with validators for all the common JavaScript data types, and you can define custom ones too:
1
import { is, define, object, string } from 'superstruct'
2
import isUuid from 'is-uuid'
3
import isEmail from 'is-email'
4
5
const Email = define('Email', isEmail)
6
const Uuid = define('Uuid', isUuid.v4)
7
8
const User = object({
9
id: Uuid,
10
email: Email,
11
name: string(),
12
})
13
14
const data = {
15
id: 'c8d63140-a1f7-45e0-bfc6-df72973fea86',
16
email: '[email protected]',
17
name: 'Jane',
18
}
19
20
if (is(data, User)) {
21
// Your data is guaranteed to be valid in this block.
22
}
Copied!
Superstruct can also handle coercion of your data before validating it, for example to mix in default values:
1
import { create, object, number, string, defaulted } from 'superstruct'
2
3
const User = object({
4
id: defaulted(number(), () => 1),
5
name: string(),
6
})
7
8
const data = {
9
name: 'Jane',
10
}
11
12
// You can apply the defaults to your data while validating.
13
const user = create(data, User)
14
// {
15
// id: 1,
16
// name: 'Jane',
17
// }
Copied!
And if you use TypeScript, Superstruct automatically ensures that your data has proper typings whenever you validate it:
1
import { is, object, number, string } from 'superstruct'
2
3
const User = object({
4
id: number(),
5
name: string()
6
})
7
8
const data: unknown = { ... }
9
10
if (is(data, User)) {
11
// TypeScript knows the shape of `data` here, so it is safe to access
12
// properties like `data.id` and `data.name`.
13
}
Copied!
Superstruct supports more complex use cases too like defining arrays or nested objects, composing structs inside each other, returning errors instead of throwing them, and more!
Last modified 8mo ago
Copy link
Contents