Superstruct

Why?

There are lots of existing validation libraries—joi, express-validator, validator.js, yup, ajv, is-my-json-valid… But they exhibit many issues that lead to your codebase becoming hard to maintain…

• They don’t expose detailed errors. Many validators simply return string-only errors or booleans without any details as to why, making it difficult to customize the errors to be helpful for end-users.

• They make custom types hard. Many validators ship with built-in types like emails, URLs, UUIDs, etc. with no way to know what they check for, and complicated APIs for defining new types.

• They don’t encourage single sources of truth. Many existing APIs encourage re-defining custom data types over and over, with the source of truth being spread out across your entire code base.

• They don’t throw errors. Many don’t actually throw the errors, forcing you to wrap everywhere. Although helpful in the days of callbacks, not using throw in modern JavaScript makes code much more complex.

• They’re tightly coupled to other concerns. Many validators are tightly coupled to Express or other frameworks, which results in one-off, confusing code that isn’t reusable across your code base.

• They use JSON Schema. Don’t get me wrong, JSON Schema can be useful. But it’s kind of like HATEOAS—it’s usually way more complexity than you need and you aren’t using any of its benefits. (Sorry, I said it.)

Of course, not every validation library suffers from all of these issues, but most of them exhibit at least one. If you’ve run into this problem before, you might like Superstruct.

Which brings me to how Superstruct solves these issues…

Principles

1. Customizable types. Superstruct’s power is in making it easy to define an entire set of custom data types that are specific to your application, and defined in a single place, so you have full control over your requirements.

2. Unopinionated defaults. Superstruct ships with native JavaScript types, and everything else is customizable, so you never have to fight to override decisions made by “core” that differ from your application’s needs.

3. Composable interfaces. Superstruct interfaces are composable, so you can break down commonly-repeated pieces of data into components, and compose them to build up the more complex objects.

4. Useful errors. The errors that Superstruct throws contain all the information you need to convert them into your own application-specific errors easy, which means more helpful errors for your end users!

5. Familiar API. The Superstruct API was heavily inspired by Typescript, Flow, Go, and GraphQL. If you’re familiar with any of those, then its schema definition API will feel very natural to use, so you can get started quickly.

Demo

Try out the live demo on CodeSandbox to get an idea for how the API works, or to quickly verify your use case:

Examples

Superstruct’s API is very flexible, allowing it to be used for a variety of use cases on your servers and in the browser. Here are a few examples of common patterns…

• Basic Validation
• Custom Types
• Default Values
• Optional Values
• Composing Structs
• Throwing Errors
• Returning Errors
• Testing Values
• Custom Errors

Documentation

Read the getting started guide to familiarize yourself with how Superstruct works. After that, check out the full API reference for more detailed information about structs, types and errors…

• Guide
  • Getting Started
  • Validating Data
  • Coercing Data
  • Refining Validation
  • Handling Errors
  • Using TypeScript
• Reference
  • Core
  • Types
  • Refinements
  • Coercions
  • Utilities
  • Errors
  • TypeScript
• FAQ
• Resources