Superstruct
GitHubDocs
  • Introduction
  • Guides
    • Getting Started
    • Validating Data
    • Coercing Data
    • Refining Validation
    • Handling Errors
    • Using TypeScript
  • API Reference
    • Core
    • Types
    • Refinements
    • Coercions
    • Utilities
    • Errors
    • TypeScript
  • Resources
    • FAQ
    • Links
Powered by GitBook
On this page
  • Installing Superstruct
  • Defining Structs
  1. Guides

Getting Started

Installing Superstruct

To install Superstruct run:

npm install --save superstruct

And then you can import it:

import { object, string, number } from 'superstruct'

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

If you'd like, you can use a wildcard import:

import * as s from 'superstruct'

const User = s.object({
  id: s.number(),
  name: s.string(),
})

If you'd rather use a <script> tag, you can use the UMD build:

<script src="https://unpkg.com/superstruct/lib/index.cjs"></script>

This will expose the Superstruct global.

Defining Structs

Once you've got Superstruct installed, the next step is to create a "struct" for some data you want validate. Each struct corresponds to a specific type of data. In our case, lets start with data describing a user:

const data = {
  id: 42,
  name: 'Jane Smith',
  email: 'jane@example.com',
}

We'll import Superstruct and create an object-shaped struct with it:

import { object, number, string } from 'superstruct'

const User = object({
  id: number(),
  name: string(),
  email: string(),
})

This User struct will expect an object with an id property that is a number, and name and email properties that are strings.

import { assert } from 'superstruct'

assert(data, User)

This will throw an error if the data is invalid. In this case, the data is valid, so no error is thrown.

But if we pass it invalid data, it will throw an error:

const data = {
  id: 43,
  name: false,
  email: 'jane@example.com',
}

assert(data, User)
// StructError: 'Expected a value of type "string" for `name` but received `false`.' {
//   type: 'string',
//   value: false,
//   branch: [{ ... }, false],
//   path: ['name'],
//   failures: [...],
// }
PreviousIntroductionNextValidating Data

Last updated 2 years ago

Now we can use our User struct to validate the data. The easiest way to do this is to use the helper, like so:

If you'd rather have the error returned instead of thrown, you can use the helper. Or, if you'd just like receive a boolean of whether the data is valid or not, use the helper.

assert
validate
is