Types

Superstruct exposes factory functions for a variety of common JavaScript (and TypeScript) types. You can also define your own custom validation functions using the struct factory.
any
1
any()
Copied!
1
'valid'
2
42
3
true
4
undefined
5
null
6
{
7
  also: 'valid'
8
}
Copied!
any structs accept any value as valid.
🤖 Note that if you're using TypeScript, the any struct will loosen the type to any, and you might want to use unknown instead.
array
1
array(number())
2
array(object({ id: number() }))
Copied!
1
[1, 2, 3]
2
[{ id: 1 }]
Copied!
array structs accept a list of values of a specific type.
bigint
1
bigint()
Copied!
1
0n
2
3n
3
4000030n
4
BigInt(10n^1000n)
Copied!
bigint structs validate that a value is a bigint.
boolean
1
boolean()
Copied!
1
true
2
false
Copied!
boolean structs accept the boolean values true and false.
date
1
date()
Copied!
1
new Date()
Copied!
date structs accept JavaScript Date instances.
🤖 To avoid unexpected runtime errors, date structs do not accept invalid Date objects, even though they are technically an instance of a Date. This meshes with the 99% use case where invalid dates create inconsistencies.
enums
1
enums(['Jane', 'John', 'Jack', 'Jill'])
Copied!
1
'Jane'
2
'John'
Copied!
enums structs validate that a value is one of a specific set of literals values.
func
1
func()
Copied!
1
function () {}
Copied!
func structs validate that a value is a function.
instance
1
instance(MyClass)
Copied!
1
new MyClass()
Copied!
instance structs validate that a value is an instance of a particular class, using JavaScript's built-in instanceof operator.
integer
1
integer()
Copied!
1
-7
2
0
3
42
Copied!
integer structs validate that a value is an integer.
intersection
1
intersection([string(), Email])
Copied!
1
'[email protected]'
Copied!
intersection structs validate that a value matches all of many structs. It takes existing struct objects as arguments.
literal
1
literal(42)
Copied!
1
42
Copied!
literal structs enforce that a value matches an exact value using the === operator.
map
1
map(string(), number())
Copied!
1
new Map([
2
  ['a', 1],
3
  ['b', 2],
4
])
Copied!
map structs validate that a value is a Map object with specific types for its keys and values.
🤖 When defining a key/value schemas with map it will traverse all the properties to ensure they are valid! If you don't care about validating the properties of the map, you can write map() instead.
never
1
never()
Copied!
1
​
Copied!
never structs will fail validation for every value.
number
1
number()
Copied!
1
0
2
3.14
3
42
4
Infinity
Copied!
number structs validate that a value is a number.
nullable
1
nullable(string())
Copied!
1
'a string of text'
2
null
Copied!
nullable structs validate that a value matches a specific struct, or that it is null.
object
1
struct({
2
  id: number(),
3
  name: string(),
4
})
Copied!
1
{
2
  id: 1,
3
  name: 'Jane Smith',
4
}
Copied!
object structs validate that a value is an object and that each of its properties match a specific type as well.
🤖 Note that object structs throw errors if they encounter extra properties on an object, unless mask is used! If you want to be less strict and ignore any extra properties, use type instead. For other more complex object use cases, check out the coercions and utilities too.
optional
1
optional(string())
Copied!
1
'a string of text'
2
undefined
Copied!
optional structs validate that a value matches a specific struct, or that it is undefined.
record
1
record(string(), number())
Copied!
1
{
2
  a: 1,
3
  b: 2,
4
}
Copied!
record structs validate an object with specific types for its keys and values. But, unlike object structs, they do not enforce a specific set of keys.
regexp
1
regexp()
Copied!
1
;/\d+/
2
new RegExp()
Copied!
regexp structs validate that a value is a RegExp object.
🤖 This does not test the value against the regular expression! For that you want the pattern refinement.
set
1
set(string())
Copied!
1
new Set(['a', 'b', 'c'])
Copied!
set structs validate that a value is a Set instance with elements of a specific type.
🤖 When defining a child schema with set it will traverse all the children to ensure they are valid! If you don't care about validating the elements of the set, you can write set() instead.
string
1
string()
Copied!
1
'a string of text'
Copied!
string structs validate that a value is a string.
tuple
1
tuple([string(), number(), boolean()])
Copied!
1
['a', 1, true]
Copied!
tuple structs validate that a value is an array of a specific length with values each of a specific type.
type
1
type({
2
  name: string(),
3
  walk: func(),
4
})
Copied!
1
{
2
  name: 'Jill',
3
  age: 37,
4
  race: 'human',
5
  walk: () => {},
6
}
Copied!
type structs validate that a value has a set of properties on it, but it does not assert anything about unspecified properties. This allows you to assert that a particular set of functionality exists without a strict equality check for properties.
When mask() is used with a value of type, its unknown properties are not removed. I.e. consider type as a signal to the core that the object may have arbitrary properties in addition to the known ones, in both masked and non-masked validation.
🤖 If you want to throw errors when encountering unknown properties, use object instead.
union
1
union([string(), number()])
Copied!
1
'a string'
2
42
Copied!
union structs validate that a value matches at least one of many types.
unknown
1
unknown()
Copied!
1
'valid'
2
42
3
true
4
undefined
5
null
6
{
7
  also: 'valid'
8
}
Copied!
unknown structs accept unknown value as valid without loosening its type to any.
Custom Types
You can also define your own custom structs that are specific to your application's requirements, like so:
1
import { define } from 'superstruct'
2
import isEmail from 'is-email'
3
import isUuid from 'is-uuid'
4
​
5
const Email = define('Email', isEmail)
6
const Uuid = define('Uuid', (value) => isUuid.v4(value))
7
​
8
const User = object({
9
  id: Uuid,
10
  name: string(),
11
  email: Email,
12
  age: number(),
13
})
Copied!
Custom types take validator functions that return either true/false or an array of StructFailure objects, in case you want to build more helpful error messages.
🤖 If you are using Typescript the value will be of type unknown by default. You can pass a more specific type for Typescript:
1
const Email = define<string>('Email', isEmail)
Copied!