OSS探訪GitHubでログイン

codecで未知の値をdecode・encodeし、同じ定義からTypeScript型を推論する

スコアの見方

OSS規模スコアはStars・Watchers・Forks・Contributorsを対数圧縮して重み付けした現在の規模指標(上限なし)です。発掘スコアは現在のOSS規模スコアから発掘時点のOSS規模スコアを引いた値、更新ペースは直近30日Commit数、成長モメンタムは直近の観測期間におけるOSS規模スコア差、OSS健全度は取得できた更新状況・Community Health・Releaseの0〜100評価です。

Stars
6,814
主要言語
TypeScript
ライセンス
MIT
リポジトリ最終更新
2024/12/10
ページ内ナビ

概要

io-tsは、実行時の型をcodecとして定義し、未知の入力をdecodeして検証しながら同じ定義からTypeScript型を取り出すlibraryです。decode結果はfp-tsのEitherとして返り、成功と失敗を型で分けて扱えます。

特徴と向いている用途

公式資料に基づく紹介・実機未検証 · 内容確認日:

主な特徴

t.typeなどのcombinatorでruntime typeを組み立てる

t.type、t.array、t.union、t.intersectionなどのcombinatorを使い、objectやcollectionのruntime typeを組み立てます。定義したcodecは入力値を実際に検証できます。

出典:[2]

decode結果をEitherで扱い、失敗理由をreportする

decode()はEither<Errors, A>を返し、Leftを失敗、Rightを成功として処理します。PathReporterを使うと不正なproperty pathを含むerror messageを生成できます。

出典:[2]

TypeOfでcodecから静的TypeScript型を取り出す

t.TypeOf<typeof Codec>から静的な型を取得できるため、runtime validation用schemaとTypeScript interfaceを二重に定義せずに済みます。encode/decodeの型が異なるcustom codecも作れます。

出典:[2]

向いている用途

API responseや外部inputをfunctionally扱いたいTypeScript projectに向く

unknownなnetwork response、設定値、message payloadなどをcodecで検証し、失敗をexceptionではなくEitherとしてpipelineへ組み込みたいapplicationに適します。

出典:[2]

導入前の確認

fp-tsがpeer dependencyで、Either等の考え方を理解する必要がある

io-ts 2.2.22はfp-ts ^2.5.0をpeer dependencyとして要求します。decode結果やcombinatorの使い方にfunctional programmingの型が現れるため、team内でEither等の扱いを揃える必要があります。

出典:[3][1]

2.2+のExperimental moduleはstable APIと別物として扱う

READMEはDecoder、Encoder、Codec、Eq、Schema moduleをExperimentalとし、stable moduleから独立し後方互換ではないと説明しています。production採用ではstable APIとExperimental APIを混在させる範囲を明確にしてください。

出典:[1]

参考にした公式資料

  1. [1]io-ts 2.2.22 README(2026-10-05)
  2. [2]io-ts 2.2.22 stable API guide(2026-10-05)
  3. [3]io-ts 2.2.22 package metadata(2026-10-05)
  4. [4]io-ts 2.2.22 release(2026-10-05)
  5. [5]io-ts MIT license(2026-10-05)
編集部からの補足

stable APIはindex.ts moduleです。Decoder、Encoder、Codec、Eq、Schemaなど2.2+のExperimental moduleは独立しており、stable APIとの後方互換も保証されないとREADMEに明記されています。採用範囲を分けてください。

3ステップで試す

  1. 1

    io-ts 2.2.22とfp-ts 2.16.9を導入する

    READMEが必須としているfp-ts peer dependencyとともにstable io-tsを固定して導入します。

    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. 2

    runtime codecでunknown値をdecodeするscriptを作る

    stable APIのt.typeとdecode()を使い、成功がRight、不正入力が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. 3

    Node.jsでdecode結果を確認する

    正しいobjectがdecodeされ、不正な型のobjectが拒否されることを確認します。

    node demo.cjs
公式READMEで確認

成長

成長の推移 · 直近30日

6,814 Stars

推移データを蓄積中です。

開発アクティビティ

直近90日・週次

Commit(直近30日)
0
Open PR
21

開発アクティビティを蓄積中です。

Built with

カテゴリとタグ

GitHubデータ

GitHubのデータGitHubの詳細データを見る

GitHub Topics

  • typescript
  • validation
  • inference
  • types
  • runtime
Stars
6,814
Forks
318
Watchers
49
Open Issues
140
Contributors
33
所有者種別
User
主要言語
TypeScript
ライセンス
MIT
リポジトリ最終更新
2024/12/10

このOSSの使い方や活用事例をMarkdownで投稿できます。管理者が承認した後に公開されます。

情報の誤りを報告

掲載内容に誤りや古い情報があればお知らせください。

このページを読んで、次に何をすればよいか分かりましたか?