# Superstruct — Composable Validation for TypeScript and JavaScript

> Lightweight library for validating data against structs with coercion, defaults, and detailed error paths.

## Install

Save as a script file and run:

# Superstruct — Composable Validation for TypeScript and JavaScript

## Quick Use
```bash
npm install superstruct
```
```ts
import { object, string, number, enums, assert } from 'superstruct';

const User = object({
  name: string(),
  age: number(),
  role: enums(['admin', 'user', 'guest'])
});

const data = { name: 'Alice', age: 30, role: 'admin' };
assert(data, User);
// data is now typed as { name: string; age: number; role: 'admin' | 'user' | 'guest' }
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-dd4760a9
Author: Script Depot