OSS TanbouOn this page
Overview
io-ts defines runtime types as codecs that decode and validate unknown input while also exposing matching TypeScript types. Decode results use fp-ts Either, separating successful values from validation failures in the type system.
Features and best fit
Based on official documentation; not hands-on tested · Content checked:
Key features
Build runtime types with t.type and other combinators
Combinators such as t.type, t.array, t.union, and t.intersection define runtime representations of objects and collections that can validate actual input values.
Sources: [2]
Handle decode results with Either and report validation paths
decode() returns Either<Errors, A>, conventionally using Left for failure and Right for success. PathReporter can turn failures into messages that identify invalid property paths.
Sources: [2]
Extract static types with TypeOf
t.TypeOf<typeof Codec> derives a TypeScript type from the runtime codec, reducing duplication between validation schemas and interfaces. Custom codecs can also model different encoded and decoded representations.
Sources: [2]
Best fit
Fits TypeScript projects that want functional runtime validation of external values
It is useful for network responses, configuration, and message payloads when validation failures should flow through typed Either values instead of relying only on exceptions.
Sources: [2]
Before adoption
fp-ts is a peer dependency and Either is part of the programming model
io-ts 2.2.22 requires fp-ts ^2.5.0 as a peer dependency. Teams should be comfortable with Either and related functional patterns because they appear directly in decode results and composition.
The 2.2+ experimental modules are separate from the stable API
The README labels Decoder, Encoder, Codec, Eq, and Schema as experimental modules that are independent and backward-incompatible with the stable modules. Production adoption should keep stable and experimental APIs clearly separated.
Sources: [1]
Official sources
- [1]io-ts 2.2.22 README(2026-10-05)
- [2]io-ts 2.2.22 stable API guide(2026-10-05)
- [3]io-ts 2.2.22 package metadata(2026-10-05)
- [4]io-ts 2.2.22 release(2026-10-05)
- [5]io-ts MIT license(2026-10-05)
Supplemental curator note
The stable API is the index.ts module. The README explicitly marks the 2.2+ Decoder, Encoder, Codec, Eq, and Schema modules as experimental, independent, and backward-incompatible with the stable modules, so keep their adoption scope separate.
Try it in 3 steps
- 1
Install io-ts 2.2.22 with fp-ts 2.16.9
Install the stable io-ts release together with its required fp-ts peer dependency.
demo=$(mktemp -d "${TMPDIR:-/tmp}/io-ts.XXXXXX") && cd "$demo" && npm init -y >/dev/null && npm install --save-exact io-ts@2.2.22 fp-ts@2.16.9 - 2
Create a runtime codec and decode unknown values
Use the stable
t.typeanddecode()APIs and require valid input to return Right while invalid input returns Left.printf "%s\n" "const t = require('io-ts');" "const {isRight, isLeft} = require('fp-ts/Either');" "const User = t.type({userId: t.number, name: t.string});" "const ok = User.decode({userId: 1, name: 'Ada'});" "const ng = User.decode({userId: '1', name: 'Ada'});" "if (!isRight(ok) || !isLeft(ng)) process.exit(1);" "console.log(ok.right);" > demo.cjs - 3
Run the decoder with Node.js
Confirm that the correct object decodes successfully and the wrong field type is rejected.
node demo.cjs
Growth
Growth trends · Last 30 days
6,814 Stars
Trend data is still being collected.
Development activity
Last 90 days · weekly
- Commits (last 30 days)
- 0
- Open PRs
- 21
Development activity is still being collected.
Built with
Categories and tags
Categories
GitHub data
GitHub dataView detailed GitHub data
GitHub Topics
- typescript
- validation
- inference
- types
- runtime
- Stars
- 6,814
- Forks
- 318
- Watchers
- 49
- Open issues
- 140
- Contributors
- 33
- Owner type
- User
- Primary language
- TypeScript
- License
- MIT
- Repository last updated
- Dec 10, 2024
Related information
Write a related articleShare a guide or use case for this OSS in Markdown. Articles are published after administrator approval.
Explore next
- Faker15,509 Stars
3 shared tag(s) · 1 shared category(s) · Same language
generate realistic-looking people, locations, products, and other fake data for testing and development
TypeScript - Linaria12,350 Stars
3 shared tag(s) · 1 shared category(s) · Same language
keep CSS-in-JS authoring while extracting styles to static CSS at build time
TypeScript - PurgeCSS8,050 Stars
3 shared tag(s) · 1 shared category(s) · Same language
scan content files and keep only selectors that are actually referenced
TypeScript - Superstruct7,127 Stars
5 shared tag(s) · 2 shared category(s) · Same language
compose small structs to validate JavaScript and TypeScript data at runtime
TypeScript - Runtypes2,699 Stars
5 shared tag(s) · 2 shared category(s) · Same language
validate unknown values with composable runtime types and infer TypeScript types from the same definitions
TypeScript - Ky17,104 Stars
5 shared tag(s) · 1 shared category(s) · Same language
extend Fetch API with concise retries, timeouts, hooks, and JSON handling
TypeScript
Report incorrect information
Tell us if any listing information is incorrect or outdated.