io-ts vs Joi vs Superstruct vs Yup：フロントエンド開発におけるバリデーションと型安全の設計比較

JavaScript は動的型付け言語であり、API やユーザー入力から受け取るデータの形状が予期せず変化することがよくあります。このため、多くのプロジェクトでは「実行時バリデーション（runtime validation）」と「静的型安全性（static type safety）」を組み合わせたアプローチが必要です。io-ts、joi、superstruct、yup はいずれもその目的に使われますが、設計思想やユースケース、TypeScript との連携方法に大きな違いがあります。

🧪 基本的な使い方：スキーマ定義とバリデーション

io-ts

io-ts は TypeScript の型システムと完全に統合することを目的としており、実行時チェック用の「コーデック（codec）」を定義すると、そこから TypeScript の型が自動生成されます。これは「1つの定義で両方を満たす」という設計哲学に基づいています。

import * as t from 'io-ts';

const User = t.type({
  id: t.number,
  name: t.string,
});

// 実行時バリデーション
type UserType = t.TypeOf<typeof User>;

const result = User.decode({ id: 1, name: 'Alice' });
if (result._tag === 'Right') {
  const user: UserType = result.right; // 型安全！
}

joi

joi は元々 Hapi.js のバリデーションライブラリとして生まれ、柔軟かつ高機能なルール定義が特徴です。ただし、TypeScript との統合は公式サポートされておらず、型情報は手動で書く必要があります。

const Joi = require('joi');

const userSchema = Joi.object({
  id: Joi.number().required(),
  name: Joi.string().required(),
});

const { error, value } = userSchema.validate({ id: 1, name: 'Alice' });
if (!error) {
  // value を使う（TypeScript では any または独自型が必要）
}

superstruct

superstruct は シンプルで高速な実行時バリデーションを目指しており、スキーマ定義が非常に簡潔です。TypeScript との連携は可能ですが、io-ts のような自動型推論は提供していません。

import { object, number, string, assert } from 'superstruct';

const User = object({
  id: number(),
  name: string(),
});

try {
  assert({ id: 1, name: 'Alice' }, User);
  // バリデーション成功 → 以降のコードで安全に使用可能
} catch (e) {
  // エラー処理
}

yup

yup は 直感的でチェーン可能な API を持ち、フォームバリデーションなどインタラクティブな UI での利用に適しています。TypeScript との連携は部分的に可能ですが、完全な型推論には限界があります。

import * as yup from 'yup';

const userSchema = yup.object({
  id: yup.number().required(),
  name: yup.string().required(),
});

try {
  const user = await userSchema.validate({ id: 1, name: 'Alice' });
  // user を使う（型は infer で取得可能だが、完全ではない）
} catch (err) {
  // エラー処理
}

🔗 TypeScript との統合度：型安全の確保方法

io-ts：型とバリデーションの完全同期

io-ts は、スキーマ定義から TypeScript の型を自動生成する仕組みを持ちます。これにより、「実行時にもコンパイル時にも正しい型」を保証できます。

const Post = t.type({
  title: t.string,
  published: t.boolean,
});

type PostType = t.TypeOf<typeof Post>; // { title: string; published: boolean }

このアプローチは、API レスポンスや外部データソースの型を厳密に管理したい場合に非常に強力です。

joi：型は別途定義が必要

joi 自体は TypeScript の型情報を生成しません。そのため、以下のように手動で型を定義する必要があります。

type User = {
  id: number;
  name: string;
};

const schema = Joi.object({
  id: Joi.number().required(),
  name: Joi.string().required(),
});

型とスキーマの乖離リスクがあるため、保守コストが増える可能性があります。

superstruct：型付きだが自動推論なし

superstruct は TypeScript で書かれており、型安全に使えるようになっていますが、スキーマから型を自動生成する機能はありません。

interface User {
  id: number;
  name: string;
}

const UserStruct = object({
  id: number(),
  name: string(),
});

型と構造体を別々に定義する必要があり、重複が発生します。

yup：inferType による限定的推論

yup は yup.InferType<typeof schema> を使って型を推論できますが、すべてのケースで正確に動作するわけではありません（特にカスタムテストや条件付きバリデーションでは）。

const schema = yup.object({
  email: yup.string().email(),
});

type SchemaType = yup.InferType<typeof schema>; // { email?: string }

オプショナルフィールドや複雑な条件では、期待通りの型にならないことがあります。

⚙️ バリデーションの柔軟性と拡張性

joi：最も豊富なビルトインルール

joi はメール、URL、日付、範囲、パターンマッチなど、非常に多くのバリデーションルールを標準で提供しています。

const schema = Joi.object({
  email: Joi.string().email(),
  age: Joi.number().min(18).max(100),
  password: Joi.string().pattern(/^[a-zA-Z0-9]{8,}$/),
});

yup：チェーン式で直感的

yup も同様に多くのルールを持ち、メソッドチェーンで記述できるため読みやすいです。

const schema = yup.object({
  email: yup.string().email().required(),
  age: yup.number().min(18).max(100).required(),
});

superstruct：シンプルだが拡張可能

superstruct は基本的な型（string, number, boolean, array, object など）に加え、define や union、intersection などでカスタムロジックを追加できます。

const email = define<string>('email', (value) => typeof value === 'string' && value.includes('@'));
const User = object({ email });

io-ts：合成と再利用に強い

io-ts は関数型プログラミングの原則に基づき、intersection、union、partial、record などの組み合わせで複雑なスキーマを構築できます。

const OptionalUser = t.partial({
  name: t.string,
});
const FullUser = t.intersection([User, OptionalUser]);

📦 フロントエンドでの実用性：バンドルサイズと DX

• io-ts：TypeScript プロジェクトで型安全を最優先するなら最適。ただし、学習曲線や冗長さがある。
• joi：Node.js 向けに最適化されており、フロントエンドではやや重たい印象。ブラウザ向けには非推奨とされている（公式ドキュメントに記載あり）。
• superstruct：軽量でシンプル。React や Vue などのフロントエンドフレームワークと相性が良い。
• yup：フォームライブラリ（例：Formik）との統合が広く使われており、UI との連携に強い。

💡 注：joi は npm ページおよび GitHub リポジトリで「ブラウザ環境での使用は推奨されない」と明記されています。フロントエンドプロジェクトでは代替手段を検討すべきです。

🔄 エラーハンドリングとフィードバック

io-ts：詳細なエラー構造

io-ts のエラーは階層的で、どのフィールドで何が失敗したかを正確にトレースできます。

const result = User.decode({ id: 'not a number', name: 123 });
// result.left には Path[] と Value のリストが含まれる

yup：ユーザーフレンドリーなエラーメッセージ

yup はエラーメッセージをカスタマイズしやすく、フォーム表示に直接使える文字列を返します。

try {
  await schema.validate(data, { abortEarly: false });
} catch (err) {
  console.log(err.errors); // ['email must be a valid email', ...]
}

superstruct：例外ベースのシンプルなハンドリング

assert は不正なデータで例外を投げるため、try/catch で処理します。エラー内容は比較的シンプルです。

joi：包括的なエラーオブジェクト

joi は error.details に各フィールドのエラー理由を配列で返し、国際化やカスタムメッセージにも対応しています。

📌 まとめ：各ライブラリの強みと選定基準

💡 最終的なアドバイス

• TypeScript プロジェクトで「型と実行時チェックを1つに統合したい」 → io-ts
• フロントエンドで軽くてシンプルなバリデーションが欲しい → superstruct
• フォームバリデーションでユーザーフレンドリーなエラーメッセージが必要 → yup
• Node.js サーバーで高機能なバリデーションが必要 → joi（ただしフロントエンドでは避ける）

これらの選択は、プロジェクトの規模、チームのスキルセット、そして「どこまで型安全を求めるか」によって変わります。一つの正解はありませんが、目的に合ったツールを選ぶことで、開発体験とアプリの信頼性を大きく向上させられます。