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()
'valid'
42
true
undefined
null
{
also: 'valid'
}
any structs accept any value as valid.🤖 Note that if you're using TypeScript, theanystruct will loosen the type toany, and you might want to useunknowninstead.
array(number())
array(object({ id: number() }))
[1, 2, 3]
[{ id: 1 }]
array structs accept a list of values of a specific type.bigint()
0n
3n
4000030n
BigInt(10n^1000n)
bigint structs validate that a value is a bigint.boolean()
true
false
boolean structs accept the boolean values true and false.date()
new Date()
date structs accept JavaScript Date instances.🤖 To avoid unexpected runtime errors,datestructs do not accept invalidDateobjects, even though they are technically an instance of aDate. This meshes with the 99% use case where invalid dates create inconsistencies.
enums(['Jane', 'John', 'Jack', 'Jill'])
'Jane'
'John'
enums structs validate that a value is one of a specific set of literals values.func()
function () {}
func structs validate that a value is a function.instance(MyClass)
new MyClass()
instance structs validate that a value is an instance of a particular class, using JavaScript's built-in instanceof operator.integer()
-7
0
42
integer structs validate that a value is an integer.intersection([string(), Email])
intersection structs validate that a value matches all of many structs. It takes existing struct objects as arguments.literal(42)
42
literal structs enforce that a value matches an exact value using the === operator.map(string(), number())
new Map([
['a', 1],
['b', 2],
])
map structs validate that a value is a Map object with specific types for its keys and values.🤖 When defining a key/value schemas withmapit will traverse all the properties to ensure they are valid! If you don't care about validating the properties of the map, you can writemap()instead.
never()
never structs will fail validation for every value.number()
0
3.14
42
Infinity
number structs validate that a value is a number.nullable(string())
'a string of text'
null
nullable structs validate that a value matches a specific struct, or that it is null.object({
id: number(),
name: string(),
})
{
id: 1,
name: 'Jane Smith',
}
object structs validate that a value is an object and that each of its properties match a specific type as well.optional(string())
'a string of text'
undefined
optional structs validate that a value matches a specific struct, or that it is undefined.🤖 Warning: If you are using TypeScript, you must enable TypeScript'sstrictNullChecksoption in yourtsconfig.jsonfor Superstruct to work properly with "optional" types. Note thatstrictNullChecksis disabled by default. If you enablestrict,strictNullCheckswill automatically be enabled.
record(string(), number())
{
a: 1,
b: 2,
}
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()
;/\d+/
new RegExp()
regexp structs validate that a value is a RegExp object.🤖 This does not test the value against the regular expression! For that you want thepatternrefinement.
set(string())
new Set(['a', 'b', 'c'])
set structs validate that a value is a Set instance with elements of a specific type.🤖 When defining a child schema withsetit will traverse all the children to ensure they are valid! If you don't care about validating the elements of the set, you can writeset()instead.
string()
'a string of text'
string structs validate that a value is a string.tuple([string(), number(), boolean()])
['a', 1, true]
tuple structs validate that a value is an array of a specific length with values each of a specific type.type({
name: string(),
walk: func(),
})
{
name: 'Jill',
age: 37,
race: 'human',
walk: () => {},
}
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.union([string(), number()])
'a string'
42
union structs validate that a value matches at least one of many types.unknown()
'valid'
42
true
undefined
null
{
also: 'valid'
}
unknown structs accept unknown value as valid without loosening its type to any.You can also define your own custom structs that are specific to your application's requirements, like so:
import { define } from 'superstruct'
import isEmail from 'is-email'
import isUuid from 'is-uuid'
const Email = define('Email', isEmail)
const Uuid = define('Uuid', (value) => isUuid.v4(value))
const User = object({
id: Uuid,
name: string(),
email: Email,
age: number(),
})
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 typeunknownby default. You can pass a more specific type for Typescript:const Email = define<string>('Email', isEmail)
Last modified 8mo ago