ReactでZodを使い、APIの応答を実行時に確かめる方法

type CatByHand = { id: number; name: string; age: number };

const body = '[{"id":1,"name":"たま","age":"3"}]';
const cats = JSON.parse(body) as CatByHand[];
const next = cats[0].age + 1;
console.log('来年の年齢:', next, typeof next);

$ npx tsx src/without-zod.ts
来年の年齢: 31 string

import * as z from 'zod';

export const Cat = z.object({
  id: z.number().int(),
  name: z.string(),
  age: z.number(),
  status: z.enum(['indoor', 'outdoor']),
  adoptedAt: z.iso.datetime().transform((s) => new Date(s)),
  note: z.string().nullable(),
});

export const CatList = z.array(Cat);

export type Cat = z.infer<typeof Cat>;

$ npx tsc -p .; echo "exit code: $?"
src/types-check.ts(12,3): error TS2322: Type '"sleeping"' is not assignable to type '"indoor" | "outdoor"'.
src/types-check.ts(13,3): error TS2531: Object is possibly 'null'.
exit code: 1

import * as z from 'zod';

export class ApiResponseError extends Error {
  constructor(
    public url: string,
    public zodError: z.ZodError,
  ) {
    super(`応答の形が想定と違います: ${url}\n${z.prettifyError(zodError)}`);
    this.name = 'ApiResponseError';
  }
}

export async function fetchJson<T extends z.ZodType>(
  url: string,
  schema: T,
  init?: RequestInit,
): Promise<z.output<T>> {
  const res = await fetch(url, init);
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
  const json: unknown = await res.json();
  const result = schema.safeParse(json);
  if (!result.success) throw new ApiResponseError(url, result.error);
  return result.data;
}

# age が文字列
success: false
✖ Invalid input: expected number, received string
  → at [0].age

[
  {
    expected: 'number',
    code: 'invalid_type',
    path: [ 0, 'age' ],
    message: 'Invalid input: expected number, received string'
  }
]

const TolerantCat = Cat.extend({
  status: z.enum(['indoor', 'outdoor', 'unknown']).catch('unknown'),
});
console.log(TolerantCat.parse({ ...ok, status: 'away' }).status);
// => unknown

import { useEffect, useState } from 'react';
import { CatList, type Cat } from './schema';
import { fetchJson } from './fetch-json';

type State =
  | { status: 'loading' }
  | { status: 'success'; cats: Cat[] }
  | { status: 'error'; error: Error };

export function useCats(url: string): State {
  const [state, setState] = useState<State>({ status: 'loading' });

  useEffect(() => {
    const controller = new AbortController();
    setState({ status: 'loading' });
    fetchJson(url, CatList, { signal: controller.signal })
      .then((cats) => setState({ status: 'success', cats }))
      .catch((error: Error) => {
        if (controller.signal.aborted) return;
        console.error(error);
        setState({ status: 'error', error });
      });
    return () => controller.abort();
  }, [url]);

  return state;
}

function CatListView() {
  const state = useCats('/api/cats');

  if (state.status === 'loading') return <p>読み込み中…</p>;
  if (state.status === 'error') {
    const message =
      state.error instanceof ApiResponseError
        ? 'サーバーから届いたデータの形が想定と違うため、表示できません。'
        : '読み込みに失敗しました。';
    return <p role="alert">{message}</p>;
  }

  return (
    <ul>
      {state.cats.map((cat) => (
        <li key={cat.id}>
          {cat.name}（{cat.age}歳）
          {cat.adoptedAt.toLocaleDateString('ja-JP', { timeZone: 'UTC' })}から
        </li>
      ))}
    </ul>
  );
}

[console.error] ApiResponseError: 応答の形が想定と違います: /api/cats
✖ Invalid input: expected number, received string
  → at [1].age