Zodの使い方ガイド

ZodはTypeScript向けのスキーマ定義ライブラリで、型安全なバリデーションを簡単に実現できます。この記事では、Zodの基本的な使い方をおさらいしつつ、実際に使用して感じたポイントを具体例とともに紹介します。

---

基本的な使い方

単純な文字列スキーマの作成

import { z } from "zod";

// 文字列のスキーマを作成する
const mySchema = z.string();
// スキーマから型を生成する
type MySchema = z.infer<typeof mySchema>;
/*
  生成される型の中身:
  type MySchema = string;
*/

const input: MySchema = 100; // エラー (型 'number' は 'string' に割り当てられません)
const input: MySchema = "hello!"; // OK!

z.infer<typeof T> を使うことで、スキーマから型を自動生成できます。

オブジェクトスキーマの作成

フォーム入力のバリデーションでよく使われるオブジェクトスキーマの例を示します。

import { z } from "zod";

// オブジェクトのスキーマを作成する
const user = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
});
type User = z.infer<typeof user>;
/*
  生成される型の中身:
  type User = {
    name: string;
    age: number;
    email: string;
  }
*/

基本的な使い方の詳細は公式ドキュメントをご参照ください。

---

具体例

ここからは、実際にZodを使って気づいたポイントを具体例を挙げて説明します。

エラーメッセージのカスタマイズ

ほとんどのバリデーションにおいて、エラーメッセージをカスタマイズ可能です。

z.string().min(5, { message: "5文字以上である必要があります。" });

状態に応じて異なるエラーメッセージを設定することもできます。

const name = z.string({
  required_error: "名前は必須です。",
  invalid_type_error: "名前は文字列である必要があります。",
});

---

正規表現の使用

郵便番号のバリデーション例を見てみましょう。

const POST_CODE = new RegExp("^[0-9]{3}-[0-9]{4}$");
const postCode = z.string().regex(
  POST_CODE,
  "半角数字、ハイフン付きで入力してください（例: 123-4567）"
);

regexを使えば正規表現に対応したスキーマも簡単に作成できます。

---

条件付き入力のバリデーション

入力が必須ではないが、入力する場合は条件を満たす必要があるケースの例です。

const inputName = z.string().min(2).or(z.literal(""));
type InputName = z.infer<typeof inputName>;
/*
  生成される型:
  type InputName = string; // 実際は以下のような意味
  type InputName = 2文字以上のstring | "";
*/

.optional()を使うとundefinedも許容されますが、""とundefinedは別物である点に注意が必要です。

const inputName = z.string().min(2).optional();
type InputName = z.infer<typeof inputName>;
/*
  生成される型:
  type InputName = string | undefined;
*/

---

ネストしたオブジェクトのスキーマ

オブジェクト内にさらにオブジェクトがある場合も簡単に定義可能です。

const userSchema = z.object({
  name: z.string(),
  blogs: z
    .object({
      title: z.string(),
      body: z.string(),
    })
    .array(),
});
type UserSchema = z.infer<typeof userSchema>;
/*
  生成される型:
  type UserSchema = {
    name: string;
    blogs: {
        title: string;
        body: string;
    }[];
}
*/

---

transformによるデータの変換

フォーム入力時に、別々の値を統合して新しいプロパティを生成する例です。

const schema = z
  .object({
    lastName: z.string(),
    firstName: z.string(),
  })
  .transform((arg) => ({
    ...arg,
    fullName: `${arg.lastName} ${arg.firstName}`,
  }));
type User = z.infer<typeof schema>;
/*
  生成される型:
  type User = {
    fullName: string; // 追加されたプロパティ
    lastName: string;
    firstName: string;
  };
*/

---

まとめ

Zodはスキーマの定義とバリデーションをシンプルかつ強力にサポートするライブラリです。公式ドキュメントを活用しつつ、紹介した具体例を参考に、より複雑なバリデーションやデータ変換に挑戦してみてください。