io-ts — Runtime Type Validation with Static TypeScript Inference

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/