# io-ts — Runtime Type Validation with Static TypeScript Inference

> Codec-based validation library that encodes and decodes data at runtime while inferring TypeScript types from schemas.

## Install

Save in your project root:

# io-ts — Runtime Type Validation with Static TypeScript Inference

## Quick Use
```bash
npm install io-ts fp-ts
```
```ts
import * as t from 'io-ts';
import { isRight } from 'fp-ts/Either';

const User = t.type({
  name: t.string,
  age: t.number,
  email: t.string
});
type User = t.TypeOf<typeof User>;

const result = User.decode({ name: 'Alice', age: 30, email: 'a@b.com' });
if (isRight(result)) {
  console.log(result.right); // typed as User
}
```

## Introduction
io-ts is a runtime type validation library for TypeScript built on top of fp-ts. It uses codecs that both decode unknown data into typed values and encode typed values back into serializable formats. Every codec automatically derives a static TypeScript type, ensuring compile-time and runtime type safety stay in sync without duplication.

## What io-ts Does
- Decodes unknown input into typed TypeScript values with error reporting
- Encodes typed values back to serializable output formats
- Infers static TypeScript types from codec definitions via TypeOf
- Composes complex codecs from primitives using intersection, union, and partial
- Integrates with fp-ts Either for functional error handling

## Architecture Overview
io-ts defines codecs as objects with decode and encode methods. Decode takes unknown input and returns an Either: Left for errors with detailed path information, or Right for the validated value. Codecs compose through combinators like t.type, t.array, t.union, and t.intersection. The library uses fp-ts conventions throughout, making it natural to pipe validation results into functional pipelines.

## Self-Hosting & Configuration
- Install io-ts and fp-ts as peer dependencies
- Define codecs in shared modules and export both the codec and its inferred type
- Requires TypeScript 3.5 or later for proper type inference
- Works in Node.js, browsers, and any JavaScript runtime
- No build-time code generation or CLI tools needed

## Key Features
- Bidirectional codecs that both validate input and serialize output
- Automatic TypeScript type inference from codec definitions
- Detailed error reporting with paths to invalid fields
- Composable codec combinators for unions, intersections, and recursive types
- Tight integration with fp-ts for functional error handling

## Comparison with Similar Tools
- **Zod** — standalone with method-chaining API; no fp-ts dependency needed
- **ArkType** — string-based TypeScript syntax; faster editor inference
- **Superstruct** — lighter weight with coercion support; no encode/decode duality
- **fp-ts Schema** — newer fp-ts companion that may eventually supersede io-ts

## FAQ
**Q: Do I need fp-ts to use io-ts?**
A: Yes. io-ts returns fp-ts Either values from decode and uses fp-ts conventions. If you prefer a standalone library, consider Zod or ArkType instead.

**Q: What is the difference between decode and encode?**
A: Decode validates unknown input and produces a typed value. Encode converts a typed value back to a serializable format, useful for API responses or storage.

**Q: Can io-ts handle recursive types?**
A: Yes. Use t.recursion to define self-referencing codecs like tree structures or linked lists.

**Q: Is io-ts actively maintained?**
A: The library is stable and widely used. Development has slowed as the author explores fp-ts Schema as a successor, but io-ts remains reliable for production use.

## Sources
- https://github.com/gcanti/io-ts
- https://gcanti.github.io/io-ts/

---
Source: https://tokrepo.com/en/workflows/asset-f1ad4d1a
Author: AI Open Source