▪️

ZodのsafeParseで型安全に必要なデータだけを抽出する

に公開
TypeScript
zod
tech

はじめに

TypeScriptでAPIレスポンスを扱うなら、型の検証は避けて通れない。
この記事では、Zodを使って 必要なデータだけを抽出し、型安全に整形する方法 を解説する。
実務で使った実装ベースなので、そのまま再利用できるはず。

zodとは

Zodは、TypeScript向けのスキーマベースのバリデーションライブラリ。
1つのスキーマで型定義と実行時バリデーションを同時に扱えるのが特徴。

実装方法

スキーマ定義（必要な項目のみ）

import { z } from 'zod';

export const articleSchema = z.object({
  id: z.string(),
  title: z.string()
})

// 型推論を活用するための型定義
export type ArticleType = z.infer<typeof articleSchema>;

ここでは、idとtitleが文字列であることをスキーマで定義している。
content や created_at などの項目は画面表示には不要なため、
スキーマから除外する。

また、z.infer を使うことで、このスキーマから対応する型を自動的に生成できる。

APIレスポンスの取得

記事一覧を取得する関数を実行。

const res = await getArticles();
console.log("res.articles", res.articles);

レスポンスは以下のような形で返ってくる。

res.articles [
  {
    id: '1',
    title: 'おはよう',
    content: 'こんにちは',
    created_at: '2024-08-22T23:35:07.079Z',
    updated_at: '2024-08-22T23:35:07.079Z'
  },
  {
    id: '2',
    title: 'こんにちは',
    content: 'つかれた',
    created_at: '2024-08-23T08:30:38.926Z',
    updated_at: '2024-08-23T08:30:38.926Z'
  }
]

目的は、この中から id と title だけを安全に取り出すこと。

データ整形（Zodでバリデーション＋抽出）

const parsedArticles = res.articles
  .map((article: Article) => {
    const result = articleSchema.safeParse(article);
    
    if (result.success) {
      return result.data; // id と title のみを含むオブジェクト
    } else {
      console.error('Validation error:', result.error.format());
      return null; // エラーハンドリング
    }
  })
  .filter(Boolean);
  
console.log('parsedArticles', parsedArticles);

ここでやっていること：

  • 各記事に対して safeParse を実行
  • 成功時のみ id と title を含むオブジェクトとして返却
  • 失敗時はログ出力＋除外

safeParse メソッドは、データ検証が失敗しても例外をスローせず、成功時は検証済みデータを、失敗時はエラー情報を含むオブジェクトを返します。これによって、簡潔かつ安全にエラーハンドリングができます。

If you don't want Zod to throw errors when validation fails, use .safeParse. This method returns an object containing either the successfully parsed data or a ZodError instance containing detailed information about the validation problems.

https://zod.dev/?id=safeparse

出力結果

最終的な整形結果は以下のようになる。

parsedArticles [
  { id: '1', title: 'おはよう' },
  { id: '2', title: 'こんにちは' }
]

不要なプロパティはすべて除外され、UI表示に必要な最低限の構造に。

おわりに

Zodを使えば、APIレスポンスを効率よく検証し、必要なデータだけを抽出できる。
型安全性と保守性が向上するため、動的なデータを扱うプロジェクトで特に有効。
構文もシンプルで、初学者にも扱いやすい。

参考

https://zod.dev/

Discussion