TypeScriptでZodを使った型安全なバリデーション導入ガイド！初心者のためのデータチェック方法

1. バリデーションと型安全の基本を知ろう

1. バリデーションと型安全の基本を知ろう

インターネットの画面で、お名前やメールアドレス、年齢などを入力する枠を見たことがあると思います。ユーザーが入力したデータが、システムで処理できる正しい形式になっているかどうかを確認する作業のことを、プログラミングの世界ではバリデーション（データ入力チェック）と呼びます。

例えば、年齢を入力する場所に、文字の「あいうえお」が入力されてしまったら、プログラムは混乱してしまいます。エラーを起こさないために、事前に「ここは数字でなければいけません」というルールを敷いて見張る必要があります。これがバリデーションの役割です。

さらに、TypeScriptというプログラミング言語には型安全という強力な特徴があります。型安全とは、プログラム内で扱うデータが「文字列なのか」「数値なのか」をあらかじめ明確に決めておくことで、間違った種類のデータを混ぜてしまったときに、パソコンが実行する前に「そこがおかしいですよ」と教えてくれる仕組みのことです。これにより、開発中に間違いをすぐに見つけることができ、安全にプログラムを作ることができます。

2. Zodとは何かを分かりやすく解説

2. Zodとは何かを分かりやすく解説

TypeScript単体でも、データの種類を定義することは得意ですが、実はインターネットの向こう側から送られてくるデータや、ユーザーがその場で入力するデータのように、動的に中身が変わるデータそのものを、実行中に直接チェックすることは少し苦手です。そこで登場するのがZod（ゾッド）という、とても便利な拡張ツールです。

Zodは、データのチェックルール（スキーマと呼びます）を簡単に定義できるライブラリです。Zodを使えば、データの形を検査するルールを一度作るだけで、中身のチェックと同時に、TypeScriptの型安全な定義も自動的に一緒に作ってくれます。これにより、二重にコードを書く手間が省け、コードがシンプルに保たれます。

パソコンを触ったことがない方向けに例えるなら、Zodは「仕分け用の魔法のふるい」です。丸い穴の空いたふるいに、四角いブロックを通そうとすると、ふるいが自動的に検知して弾いてくれます。このふるいの役割を、プログラム内で簡単に行えるのがZodの最大の強みです。

3. Zodをパソコンに導入する手順

3. Zodをパソコンに導入する手順

Zodを使用するためには、まず自分の作業環境にZodをインストールという、組み込みの作業を行う必要があります。通常、Webの開発では、Node.jsというシステムを使って外部の部品を取り込みます。

コマンドプロンプトやターミナルと呼ばれる、文字を入力してパソコンを操作する専用の画面を開き、以下の命令文を打ち込んで実行します。これにより、インターネット経由でZodが自動的にダウンロードされ、自分のプロジェクトの中で使えるようになります。

// 以下のコマンドを実行してZodを取り込みます
// npm i zod
import { z } from "zod";

上記のコードにあるimportという言葉は、「別の場所にあるZodという部品から、必要な機能をこのプログラム内に持ってきます」という意味の宣言です。これで準備は完了です。

4. 最もシンプルな文字列チェックの方法

4. 最もシンプルな文字列チェックの方法

まずは、最も基本となる「文字列」のチェックを行ってみましょう。例えば、ユーザーが入力したユーザー名が、ちゃんと文字データになっているかを調べます。Zodを使って、まずは文字だけを受け付けるルールを作ります。

import { z } from "zod";

// 文字列だけを許可するルール（スキーマ）を作ります
const textSchema = z.string();

// ルールに沿ってデータをチェックします
const result1 = textSchema.safeParse("たろう");
console.log("結果1:", result1.success);

const result2 = textSchema.safeParse(12345);
console.log("結果2:", result2.success);

上記のプログラムで使われているz.string()が、「文字列でなければいけない」というルールを定義している部分です。そして、safeParseという命令を使って、実際のデータがそのルールに合格しているかを判定しています。

実行結果は以下のようになります。合格した場合は真実を意味するtrue、不合格の場合は間違いを意味するfalseが返ってきます。

結果1: true
結果2: false

「たろう」は正しい文字なので成功ですが、数字の「12345」はルール違反となり、しっかりと不合格として弾かれていることがわかります。

5. 複数の項目をまとめたオブジェクトのバリデーション

5. 複数の項目をまとめたオブジェクトのバリデーション

実際のWebサイトでは、名前だけでなく、年齢やメールアドレスなど、複数の項目を一度にまとめてチェックすることがほとんどです。このように、複数のデータを一つのお弁当箱のようにひとまとめにした構造体を、プログラミングではオブジェクトと呼びます。

Zodでは、z.object()という命令を使うことで、お弁当箱の中身それぞれのルールを細かく指定することができます。会員登録の場面を想定したプログラムを書いてみましょう。

import { z } from "zod";

// 会員登録用のルール一式を定義します
const userRegistrationSchema = z.object({
    username: z.string(),
    age: z.number()
});

// 正しいデータを用意してチェックします
const sampleInput = {
    username: "はなこ",
    age: 20
};

const checkResult = userRegistrationSchema.safeParse(sampleInput);

if (checkResult.success) {
    console.log("データは正しいです。登録処理を進めます。");
} else {
    console.log("データに不備があります。");
}

このプログラムでは、名前は文字列（z.string()）、年齢は数値（z.number()）でなければならないという、二つのルールを同時に課しています。このように記述することで、複雑に入り組んだ入力データも、一括できれいに検閲をかけることが可能になります。

実行結果は、入力されたデータが両方のルールを完璧に満たしているため、成功のメッセージが表示されます。

データは正しいです。登録処理を進めます。

6. 条件を細かく追加する詳細なデータチェック

6. 条件を細かく追加する詳細なデータチェック

ただの「文字」や「数字」という大雑把な分類だけでなく、「文字の長さは5文字以上でなければならない」とか、「年齢は20歳以上の大人でなければならない」といった、実務でよく使う細かな条件を付け足したいこともあります。Zodなら、後ろに条件を数珠つなぎに連結していくだけで、そうした詳細な指定が実現できます。

import { z } from "zod";

// パスワード専用の厳しいルールを作ります
// 6文字以上、かつ文字列であること
const passwordSchema = z.string().min(6);

const normalCheck = passwordSchema.safeParse("abc");
console.log("3文字の場合の成否:", normalCheck.success);

const strictCheck = passwordSchema.safeParse("abcdefg");
console.log("7文字の場合の成否:", strictCheck.success);

ここで登場した.min(6)という記述が、「最低でも6文字以上必要」という意味を持つ制限命令です。このように、元のデータ型にドットを繋げて条件を追加していく方法を、プログラミングではメソッドチェーンと呼んだりします。

実行結果を確認すると、3文字しか入力されなかった場合は条件を満たせず失敗となり、7文字の入力では合格していることが分かります。

3文字の場合の成否: false
7文字の場合の成否: true

7. エラーメッセージを分かりやすくカスタマイズする方法

7. エラーメッセージを分かりやすくカスタマイズする方法

チェックに引っかかって不合格になった際、ただ「失敗しました」とだけ言われても、画面を見ているユーザーは何が原因でダメだったのかが分かりません。「パスワードは6文字以上で入力してください」といった、親切な案内文を表示させたいものです。Zodでは、ルールの設定と同時に、エラーが起きた際に出力する専用の日本語の文言を指定することができます。

import { z } from "zod";

// エラーのときのメッセージをあらかじめ仕込みます
const customProfileSchema = z.object({
    nickname: z.string({
        required_error: "ニックネームは必ず入力してください"
    }).min(1, { message: "ニックネームが空欄になっています" })
});

// わざと空っぽの文字を渡してエラーを発生させます
const invalidData = { nickname: "" };
const errorOutput = customProfileSchema.safeParse(invalidData);

if (!errorOutput.success) {
    // 発生したエラーメッセージを取り出して表示します
    console.log(errorOutput.error.issues[0].message);
}

ルールを設定する括弧の中に、{ message: "..." }という形式で文字を書き込むことで、標準で用意されている英語のエラー文を、自分好みの分かりやすい日本語に書き換えることができます。

上記のプログラムを実行すると、不合格の理由として設定した独自のメッセージが正確に取り出されます。

ニックネームが空欄になっています

これを使えば、誰が見てもどこを直せば良いかが一目でわかる、親切で使いやすい案内フォームを作成することができます。

8. ZodのスキーマからTypeScriptの型を自動抽出する裏技

8. ZodのスキーマからTypeScriptの型を自動抽出する裏技

最後にご紹介するのが、Zodの最も素晴らしい機能である型の自動抽出です。通常であれば、データのルール定義とは別に、TypeScript用の型定義をもう一度キーボードで手入力して作成する必要があります。しかしこれでは、ルールを変更したときに両方を修正せねばならず、書き忘れや修正漏れによる不具合の原因になります。

Zodに備わっているz.inferという機能を使えば、先に作成したZodのルール設定を元にして、一瞬でTypeScript用の型定義を自動的に生成して抽出してくれます。

import { z } from "zod";

// 元となるルールを定義します
const itemSchema = z.object({
    itemName: z.string(),
    price: z.number()
});

// ルールからTypeScriptの型を自動的に抽出して作成します
type Item = z.infer<typeof itemSchema>;

// 作成された型を使って安全にオブジェクトを作成できます
const myItem: Item = {
    itemName: "美味しいリンゴ",
    price: 150
};

console.log("商品名:", myItem.itemName);

type Item = z.infer<typeof itemSchema>という呪文のような一文を書くだけで、itemNameが文字列でpriceが数値であるという専用の型が自動生成されます。これにより、手動で何度も同じような構造を書く必要がなくなり、安全かつ効率的なプログラミングが可能になります。

実行すると、安全に定義された型情報に基づいて、中身のデータにアクセスできていることが確認できます。

商品名: 美しいリンゴ

データのバリデーションを正確に行うこと、そしてその結果を型安全に連携させることの重要性を理解し、ぜひZodを活用してみてください。