Zodは直感的な記法と豊富なメソッド群を持ち、データの検証・変換・整形に強力な機能を提供します。

Zodでよく使うメソッドをカテゴリ別に整理し、具体例とともに詳しく解説します。

---

基本スキーマ作成

Zodではプリミティブ型に対応したスキーマを使って、シンプルに定義できます。

メソッド	説明	例
z.string()	文字列のスキーマ	z.string()
z.number()	数値スキーマ	z.number()
z.boolean()	真偽値	z.boolean()
z.date()	日付	z.date()
z.undefined()	undefined値のみ	z.undefined()
z.null()	null値	z.null()

例：

tsCopy codeconst nameSchema = z.string();
nameSchema.parse("Alice"); // OK
nameSchema.parse(123);     // ❌

---

バリデーション用メソッド

基本スキーマにチェーンすることで、より詳細な条件を付与できます。

メソッド	説明	例
.min(n)	最小文字数や数値（inclusive）	z.string().min(3)
.max(n)	最大文字数や数値（inclusive）	z.number().max(100)
.length(n)	ちょうどの文字数・配列長	z.string().length(6)
.email()	メール形式の検証	z.string().email()
.url()	URL形式	z.string().url()
.regex(regexp)	正規表現による制約	z.string().regex(/^\d+$/)
.int()	整数であること	z.number().int()
.positive()	正の数	z.number().positive()
.nonempty()	空を禁止	z.string().nonempty()
.uuid()	UUID形式	z.string().uuid()

例：

tsCopy codeconst passwordSchema = z.string().min(8).max(32).regex(/[A-Z]/);

---

複雑な型構造のメソッド

複雑な構造を定義するためのメソッドです。オブジェクト、配列、ユニオン、リテラルなどに対応。

メソッド	説明	例
z.object({...})	オブジェクト構造	z.object({ name: z.string() })
z.array(schema)	特定スキーマの配列	z.array(z.string())
z.union([...])	複数の型のいずれか	z.union([z.string(), z.number()])
z.literal(value)	値が指定のリテラルであること	z.literal("ok")
z.enum([...])	指定の文字列値のみ許可	z.enum(["draft", "published"])
z.tuple([...])	固定長タプル型	z.tuple([z.string(), z.number()])
z.record(key, val)	キー・値が型に従う連想配列	z.record(z.string(), z.number())

例：

tsCopy codeconst articleSchema = z.object({
  title: z.string(),
  tags: z.array(z.string()),
  status: z.enum(["draft", "published", "archived"]),
});

---

カスタムバリデーション・条件分岐

ビジネスロジックに即した条件を加えたいときに便利なメソッドです。

メソッド	説明	例
.refine(fn)	値が条件を満たさなければエラー	.refine(val => val.length > 5)
.superRefine(fn)	オブジェクト全体の中で相関バリデーション	superRefine(({ a, b }, ctx) => { ... })
.transform(fn)	値を変換（例：string→number）	.transform(val => Number(val))

例：

tsCopy codeconst confirmSchema = z
  .object({
    password: z.string(),
    confirm: z.string(),
  })
  .superRefine((val, ctx) => {
    if (val.password !== val.confirm) {
      ctx.addIssue({
        path: ["confirm"],
        code: z.ZodIssueCode.custom,
        message: "パスワードが一致しません",
      });
    }
  });

---

オプション/Nullable/Default系メソッド

メソッド	説明	例
.optional()	省略可能（undefined許容）	z.string().optional()
.nullable()	nullを許容	z.string().nullable()
.nullish()	null or undefined	z.string().nullish()
.default(value)	未定義時にデフォルト値を設定	z.string().default("default")
.catch(value)	パース失敗時にフォールバック	z.number().catch(0)

例：

tsCopy codeconst userSchema = z.object({
  nickname: z.string().optional().default("名無しさん"),
  age: z.number().nullable(),
});

---

構造変換・出力形式変更

メソッド	説明	例
.transform(fn)	値を変換して返す	.transform(str => parseInt(str))
.pipe(schema)	スキーマを別のスキーマに通す（中間処理）	.pipe(z.number().min(0))

例：

tsCopy codeconst priceSchema = z
  .string()
  .transform((val) => parseFloat(val))
  .pipe(z.number().positive());

---

パース・検証メソッド（実行時）

メソッド	説明	例
.parse(data)	成功すれば値、失敗ならthrow	schema.parse(input)
.safeParse(data)	成功/失敗を返すオブジェクト	const res = schema.safeParse(data)
.parseAsync()	非同期パース（例：refineがasync）	await schema.parseAsync(input)
.safeParseAsync()	非同期safeParse	await schema.safeParseAsync(input)

---

型推論メソッド

メソッド	説明	例
z.infer<typeof schema>	ZodスキーマからTypeScript型を生成	type User = z.infer<typeof userSchema>

---

まとめ

Zodには非常に多くのメソッドがありますが、頻出パターンをしっかり覚えることで、型安全な開発と堅牢なバリデーションが実現できます。

開発フロー別おすすめメソッド：

フェーズ	おすすめメソッド
入力フォーム検証	.min(), .email(), .superRefine()
APIリクエスト検証	.object(), .optional(), .default()
APIレスポンス検証	.union(), .literal(), .transform()
データ変換	.transform(), .pipe()
型定義共有	z.infer

Zodのメソッドを理解すれば、バックエンドとフロントエンドをまたぐ全体設計が統一され、コードの信頼性とメンテナンス性が飛躍的に向上します。ぜひ日々の実装に取り入れてください。