Handling Errors

By default Superstruct throws errors that are easy to understand for developers. This means that out of the box you'll get nice errors messages that help you track down why a piece of data is invalid.
For example, consider a simple User struct:
1
const User = object({
2
  id: number(),
3
  name: string(),
4
  email: email(),
5
})
Copied!
If you pass in an invalid email, an error will be thrown:
1
const data = {
2
  id: 1,
3
  name: 'Alex',
4
  email: false,
5
}
6
​
7
assert(data, User)
8
// StructError: At path: email -- Expected a string, but received: false
Copied!
In addition to the error message, the error object will have a bunch of useful properties on it:
1
StructError {
2
  value: false,
3
  key: 'email',
4
  type: 'string',
5
  refinement: undefined,
6
  path: ['email'],
7
  branch: [{ id: 1, name: 'Alex', email: false }, false],
8
  failures: [Function]
9
}
Copied!
You can use those properties to perform whatever logic is necessary to recover from errors in your application.
To see all of the information embedded in StructError objects, check out the StructError reference.
Customizing Errors
But there are cases where you want more control over the errors, especially when displaying error messages to end users. For example, if you're building a REST or GraphQL API, you probably want to customize your errors to be specific to your application, and to follow a spec.
To make this possible, you can catch the errors, and use their built-in properties to build up your own custom error codes or messages.
For example, consider a REST API for creating users:
1
router.post('/users', ({ request, response }) => {
2
  const data = request.body
3
​
4
  try {
5
    assert(data, User)
6
  } catch (e) {
7
    const { key, value, type } = e
8
​
9
    if (value === undefined) {
10
      const error = new Error(`user_${key}_required`)
11
      error.attribute = key
12
      throw error
13
    } else if (type === 'never') {
14
      const error = new Error(`user_attribute_unknown`)
15
      error.attribute = key
16
      throw error
17
    } else {
18
      const error = new Error(`user_${key}_invalid`)
19
      error.attribute = key
20
      error.value = value
21
      throw error
22
    }
23
  }
24
})
Copied!
When a developer tries to create a user with invalid properties, the error responses given by the API are standardized. You end up with errors with codes like:
1
user_email_invalid
2
user_email_required
3
user_email_unknown
4
​
5
user_name_invalid
6
user_name_required
7
...
Copied!
Although this example is simplified, the struct errors expose all of the possible information about why the validation failed, so you can use them to construct extremely detailed errors for your end users.
Multiple Failures
By default Superstruct throws an error for the very first failure encountered during validation. This greatly simplifies logic for most cases, and results in the best performance.
However, there are situations where you need to check for all of the potential errors in a single piece of data. To do that, you can use the error.failures generator, like so:
1
try {
2
  assert(data, Struct)
3
} catch (error) {
4
  for (const failure of error.failures()) {
5
    // ...
6
  }
7
}
Copied!
Each failure object will give you information about a specific failure of the data.
🤖 Note: Superstruct actually doesn't know what the failures are beyond the first one until you iterate through them. This happens "on-demand", which can signficantly improve performance in failure cases.

Guides - Previous

Refining Validation

Next - Guides

Using TypeScript

Last modified 3mo ago

Copy link

Contents

Customizing Errors

Multiple Failures