Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Superstruct

Superstruct factories create different kinds of Struct validators, and encapsulate the user-defined data types.

The struct export is a factory that ships with Superstruct by default, pre-configured with all of the built-in JavaScript data types. It's the easiest way to quickly define structs:

import { struct } from 'superstruct'

const User = struct({
  id: 'number',
  name: 'string',
})

If you need to define custom data types, you can define your own by using the superstruct export:

import { superstruct } from 'superstruct'
import isEmail from 'is-email'
import isUrl from 'is-url'

const struct = superstruct({
  types: {
    email: value => isEmail(value) && value.length < 256,
    url: value => isUrl(value) && value.length < 2048,
  }
})

const User = struct({
  id: 'number',
  name: 'string',
  email: 'email',
  website: 'url?',
})

This way you can easily define structs that contain types like 'email', 'url', or whatever else your application may need.

Hierarchy

  • Superstruct

Callable

  • __call(schema: any, defaults?: any): Struct
  • Structs are defined by passing a schema definition to the struct factory. The schema definition can be a string, array, object or function. They can also be composed by nesting structs inside each other.

    The default struct factory allows you to write structs using a shorthand syntax for the most common cases—arrays, objects, scalars, tuples, etc.

    struct('string') // Scalars
    struct(['number']) // Arrays
    struct({ name: 'string' }) // Objects
    struct(['error', 'string']) // Tuples
    struct('number?') // Optional
    struct('string & email') // Intersection
    struct('number | string') // Union
    struct(value => true || false) // Function
    struct(Struct) // Pass-through

    Each shorthand is equivalent to a method on the Superstruct factory:

    // These are equivalent...
    struct(['number'])
    struct.array(['number'])
    
    struct('string & email')
    struct.union(['string', 'email'])

    And each one can use your custom types, or even other structs:

    struct('email')
    struct(User)

    The second argument to struct factories is always a defaults value. It can either be the default itself or a function that returns the default.

    struct('id', uuid.v4)
    
    struct({
      id: 'number',
      name: 'string',
      is_admin: 'boolean?',
    }, {
      is_admin: false,
    })

    Parameters

    • schema: any
    • Optional defaults: any

    Returns Struct

Index

Properties

Error

Error: object

The class for errors thrown by Structs, defaults to StructError.

Type declaration

  • constructor: function
    • new __type(failures: Failure[]): Error
    • Parameters

      Returns Error

Types

Types: Record<string, Validator>

The set of data types that the factory knows.

Methods

array

  • array(schema: [any], defaults?: any): Struct
  • Array structs validate that their input is an array with elements that match a specific struct. You can also pass the max or min options to validate the length of the array.

    const Struct = struct.array(['number'])
    
    Struct([1, 2, 3])

    They are similar to the Array type in TypeScript.

    Parameters

    • schema: [any]
    • Optional defaults: any

    Returns Struct

dynamic

  • dynamic(schema: function, defaults?: any): Struct
  • Dynamic structs are defined by a function that is passed the value being validated, and they determine which struct to use at runtime.

    const Struct = struct.dynamic(value => StructA || StructB)

    They are inhernetly less performant that compile-time structs, but they unlock a set of possibilities that aren't possible at compile time alone.

    Parameters

    Returns Struct

enum

  • enum(schema: any[], defaults?: any): Struct
  • Enum structs validate that their input is one of a set of values.

    const Struct = struct.enum(['fruit', 'vegetable', 'meat'])
    
    Struct('fruit')

    They are similar to the enum type in TypeScript.

    Parameters

    • schema: any[]
    • Optional defaults: any

    Returns Struct

function

  • Function structs validate their input against a one-off validator function.

    const Struct = struct.function(value => typeof value === 'string')
    
    Struct('a simple string')

    They can't provide as detailed of errors as other struct types, but they do allow for customization for easy one-off cases.

    Parameters

    Returns Struct

instance

  • instance(schema: any, defaults?: any): Struct
  • Instance structs validate that their input is an instance of a class.

    const Struct = struct.instance(MyClass)
    
    Struct(new MyClass())

    Parameters

    • schema: any
    • Optional defaults: any

    Returns Struct

interface

  • interface(schema: any, defaults?: any): Struct
  • Interface structs validate that their input matches an interface defined as a set of properties with associated types.

    const Struct = struct.interface({
      length: 'number',
      indexOf: 'function',
    })
    
    Struct([1, 2, 3])
    Struct('abc')

    They are similar to the structural-typing granted by TypeScript.

    Parameters

    • schema: any
    • Optional defaults: any

    Returns Struct

intersection

  • intersection(schema: any[], defaults?: any): Struct
  • Intersection structs validate that their input matches all of a set of different structs.

    const Struct = struct.intersection('string & email')
    
    Struct('jane@example.com')

    Note: The structs will be validated in order, so validators on the right can rely on the validators before them having passed.

    They are similar to the & operator in TypeScript.

    Parameters

    • schema: any[]
    • Optional defaults: any

    Returns Struct

lazy

  • lazy(schema: function, defaults?: any): Struct
  • Lazy structs allow you to initialize a struct lazily, only initializing it once on the first time it attempts to be validated.

    const Struct = struct({
      nodes: struct.lazy(() => Struct)
    })
    
    Struct({
      nodes: {
        nodes: { ... }
      }
    })

    They are helpful for defining recursive structs.

    Parameters

    • schema: function
    • Optional defaults: any

    Returns Struct

literal

  • literal(schema: any, defaults?: any): Struct
  • Literal structs validate their input against a literal value.

    const Struct = struct.literal(42)
    
    Struct(42)

    Parameters

    • schema: any
    • Optional defaults: any

    Returns Struct

object

  • object(schema: __type, defaults?: any): Struct
  • Object structs validate that their input exactly matches an object defined as a set of properties with associated types.

    const Struct = struct.object({
      id: 'number',
      name: 'string',
    })
    
    Struct({
      id: 1,
      name: 'Jane Smith',
    })

    They are similar to the ? qualifier in TypeScript.

    Parameters

    • schema: __type
    • Optional defaults: any

    Returns Struct

optional

  • optional(schema: any, defaults?: any): Struct
  • Optional structs validate that their input passes a specific struct, or undefined.

    const Struct = struct.optional('string?')
    
    Struct('a string of text')
    Struct(undefined)

    This is a shorthand for using struct.union with undefined.

    Parameters

    • schema: any
    • Optional defaults: any

    Returns Struct

partial

  • partial(schema: __type, defaults?: any): Struct
  • Partial structs validate that their input partially matches an object defined as a set of properties with associated types. All of the properties of the object are optional.

    const Struct = struct.partial({
      id: 'number'
      name: 'string',
    })
    
    Struct({
      name: 'Jane Smith',
    })

    They are similar to the Partial utility in TypeScript.

    Parameters

    • schema: __type
    • Optional defaults: any

    Returns Struct

pick

  • pick(schema: __type, defaults?: any): Struct
  • Pick structs validate that their input exactly matches a subset of an object defined as a set of properties with associated types. All of the properties of its schema are required, but the object can have more that it does not concern itself with.

    const Struct = struct.pick({
      id: 'string',
      name: 'string',
    })
    
    Struct({
      id: 1,
      name: 'James Smith',
      email: 'james@example.com',
    })

    They are similar to the Pick utility in TypeScript.

    Parameters

    • schema: __type
    • Optional defaults: any

    Returns Struct

record

  • record(schema: [any, any], defaults?: any): Struct
  • Record structs validate that their input is an object with keys that match one struct and values that match another. The object can have zero or many properties set on it.

    const Struct = struct.record('string', 'number')
    
    Struct({
      a: 1,
      b: 2,
    })

    They are similar to the Record utility in TypeScript.

    Parameters

    • schema: [any, any]
    • Optional defaults: any

    Returns Struct

scalar

  • scalar(schema: string, defaults?: any): Struct
  • Scalar structs validate that their input passes the Validator function defined for a specific type by name. By default Superstruct ships with a set of built-in scalars. But you can configure it with custom scalars that match your domain.

    const Struct = struct.scalar('string')
    
    Struct('a string of text')

    Parameters

    • schema: string
    • Optional defaults: any

    Returns Struct

size

  • size(schema: [number, number], defaults?: any): Struct
  • Size structs validate their input has a certain length, by checking its length property. This works strings or arrays.

    const Struct = struct.size([0, 7])
    
    Struct([1, 2, 3])
    Struct('abcdefg')

    They are helpful for defining unions with array structs.

    Parameters

    • schema: [number, number]
    • Optional defaults: any

    Returns Struct

tuple

  • tuple(schema: any[], defaults?: any): Struct
  • Tuple structs validate that their input exactly matches a tuple of values, in length and in type.

    const Struct = struct.tuple(['string', 'boolean'])
    
    Struct(['one', true])

    Parameters

    • schema: any[]
    • Optional defaults: any

    Returns Struct

union

  • union(schema: any[], defaults?: any): Struct
  • Union structs validate that their input matches at least one of a set of different structs.

    const Struct = struct.union(['string', 'number'])
    
    Struct('a string')
    Struct(42)

    They are similar to the | operator in TypeScript.

    Parameters

    • schema: any[]
    • Optional defaults: any

    Returns Struct