Using TypeScript

Superstruct is built with TypeScript, and is designed to integrate seamlessly with its guards and assertions. Which means that if you're using TypeScript too you'll get compile-time typings for your data.
🤖 Warning: If you are not using TypeScript's strictNullChecks option, Superstruct will be unable to infer your "optional" types correctly and will mark all types as optional.
Narrowing Types
Whenever you use the is or assert helpers in Superstruct, TypeScript will infer information about your data and give you type safety. For example:
1
const User = object({
2
  id: number(),
3
  email: email(),
4
  name: string(),
5
})
6
​
7
if (is(data, User)) {
8
  // In this block TypeScript knows the shape of `data` is guaranteed to match
9
  // the `User` struct, so you can access properties like `data.name`.
10
}
Copied!
Inside that if block you can safely access the User properties id, name and email because TypeScript knows that the data already passed validation.
The same for goes assertions:
1
assert(data, User)
2
// After this point TypeScript knows that data is valid too!
Copied!
This makes it a lot easier to deal with inputs because you don't need to manually guard and refine their types.
Describing Types
You can ensure that you're properly describing your existing TypeScript types with Superstruct by using the Describe utility. For example:
1
type User = {
2
  id: number
3
  name: string
4
}
5
​
6
const User: Describe<User> = object({
7
  id: string(), // This mistake will fail to pass type checking!
8
  name: string(),
9
})
Copied!
In this case, the incorrectly defined id property will cause TypeScript's compilation checks to throw an error. This way your compile-time and run-time validations are never out of sync.
Inferring Types
You can also do the reverse and infer a TypeScript type using an existing Superstruct struct with the Infer utility. For example:
1
import { Infer } from 'superstruct'
2
​
3
const User = object({
4
  id: number(),
5
  email: email(),
6
  name: string(),
7
})
8
​
9
type User = Infer<typeof User>
Copied!
The User type above is the same as if you'd defined it by hand:
1
type User = {
2
  id: number
3
  email: string
4
  name: string
5
}
Copied!
This saves you from having to duplicate definitions.
🤖 Notice that in each of the cases above, the User type and the User struct have the same name! This is handy for importing them elsewhere in the codebase at the same time.

Guides - Previous

Handling Errors

Next - API Reference

Core

Last modified 3mo ago

Copy link

Contents

Narrowing Types

Describing Types

Inferring Types