Superstruct — Composable Validation for TypeScript and JavaScript

Introduction

Superstruct is a validation library that defines data structures using composable struct definitions. Unlike schema-heavy validators, Superstruct treats validation as composition of simple building blocks. It produces clear error messages with exact paths to invalid fields and supports coercion for transforming data during validation.

What Superstruct Does

• Validates JavaScript values against declarative struct definitions
• Infers TypeScript types from struct schemas automatically
• Coerces data by applying transforms like defaults, trimming, and type casting
• Reports detailed errors with the exact path to each invalid field
• Composes complex schemas from simple primitives using union, intersection, and refinement

Architecture Overview

Superstruct defines a struct as a function that takes unknown input and returns either the validated value or a detailed error. Structs compose through combinators like object(), array(), union(), and intersection(). The coercion system applies transforms in a pre-validation pass, and refinements add custom constraints on top of base types. All structs expose an Infer utility type for extracting static TypeScript types.

Self-Hosting & Configuration

• Install via npm with zero dependencies
• Define structs inline and export them for reuse across modules
• Works with any JavaScript runtime and TypeScript version 4.0 or later
• No build plugins or code generation required
• Ships both ESM and CommonJS module formats

Key Features

• Composable struct primitives that combine like building blocks
• Automatic TypeScript type inference from struct definitions
• Coercion layer for defaults, trimming, and data transformation
• Detailed error messages with field paths for debugging
• Lightweight with zero dependencies

Comparison with Similar Tools

• Zod — richer API with method chaining; larger community and plugin ecosystem
• ArkType — string-based TypeScript syntax; faster editor inference for complex types
• Valibot — modular tree-shakeable design; similar composable approach
• io-ts — fp-ts integration with codec-based encode/decode; more FP-oriented

FAQ

Q: When should I use Superstruct over Zod? A: Superstruct is a good fit when you prefer a minimal composable API and want built-in coercion. Zod is better when you need a larger ecosystem of plugins and integrations.

Q: Does Superstruct support async validation? A: Superstruct is synchronous by design. For async validation, run async checks separately after struct validation passes.

Q: Can I use Superstruct for API request validation? A: Yes. Use assert() or create() in your request handlers to validate and optionally coerce incoming payloads.

Q: How does coercion work? A: Define a coercion with coerce(struct, transform). During create(), the transform runs before validation, allowing defaults, trimming, or type conversion.

Sources

• https://github.com/ianstormtaylor/superstruct
• https://docs.superstructjs.org/