TypeScript × Aspida × Zodで型安全なHTTPリクエストについて考えてみた

export type User = {
  id: number;
  name: string;
};

export type Users = User[]

const isUser = (arg: unknown): arg is User => {
  const u = arg as User;

  return (
    typeof u.id === 'number' &&
    typeof u.name === 'string'
  );
};

const isUsers = (args: unknown): args is Users => {
  const us = args as Users;

  return us.every((u) => isUser(u));
};

export { isUser, isUsers }

import * as z from 'zod';

const stringSchema = z.string();
const blob: any = 'Albuquerque';
if (stringSchema.check(blob)) {
  // blob is now of type `string`
  // within this if statement
}

import { z } from "zod";

// creating a schema for strings
const mySchema = z.string();

// parsing
mySchema.parse("tuna"); // => "tuna"
mySchema.parse(12); // => throws ZodError

// "safe" parsing (doesn't throw error if validation fails)
mySchema.safeParse("tuna"); // => { success: true; data: "tuna" }
mySchema.safeParse(12); // => { success: false; error: ZodError }

const A = z.string();
type A = z.infer<typeof A>; // string

const u: A = 12; // TypeError
const u: A = "asdf"; // compiles

import * as z from "zod";

// zodに渡せる型に変換する型
type toZod<T extends Record<string, any>> = {
  [K in keyof T]-?: z.ZodType<T[K]>;
}

interface Hoge {
  hello: string;
  world: string;
}

// Hogeを型引数として渡す
const HogeSchema = z.object<toZod<IHoge>>({
  hello: z.string(),
  world: z.string()
})

（ルート）
┣ src
║  ┣ api/  #Adpida 用の API 型定義置き場
║  ║  ┣ users/
║  ║  ║  ┣ _userId@number/
║  ║  ║  ║    ┗ index.ts
║  ║  ║  ┗ index.ts
║  ║  ┗ $api.ts
║  ┣ compnents/  #各種コンポーネント置き場
║  ┣ domains/  #ドメイン（HTTP リクエストロジック置き場）
║  ┣ hooks/  #カスタムフック置き場（domains のラッパー）
║  ┣ lib/  #ライブラリの設定やユーティリティなどの置き場
║  ┣ mock/  #モックデータ置き場
║  ┣ models/  #モデル型定義置き場
║  ┗ pages/
║      ┣ api
║      ┣ _app.tsx
║      ┗ index.tsx
┣ .gitignore
┣ aspida.config.js
┣ package.json
┣ tsconfig.json
┗ yarn.lock

yarn add @aspida/fetch zod

yarn add -D npm-run-all

module.exports = {
  input: 'src/api',
};

{
  // ...
  "compilerOptions": {
    // ...
    "strict": true
  }
}

import { z } from 'zod';

export type ToZod<T extends Record<string, any>> = {
  [K in keyof T]-?: z.ZodType<T[K]>;
};

import { z } from 'zod';
import { ToZod } from '@/lib/zod';

export type GetListRequestQuery = {
  limit?: number;
};

export const getListRequestQuerySchema = z
  .object<ToZod<GetListRequestQuery>>({
    limit: z.number().optional(),
  })
  .strict();

export type PostRequestBody = Pick<User, 'name'>;

export const postRequestBodySchema = z
  .object<ToZod<PostRequestBody>>({
    name: z.string(),
  })
  .strict();

export type RequestPathParams = {
  userId: string;
};

// パスパラメータとしては全て文字列になるので、文字列で数字のみにする
export const requestPathParamsSchema = z.object<ToZod<RequestPathParams>>({
  userId: z.string().regex(/\d+/),
});

export type User = {
  id: number;
  name: string;
};

export const userSchema = z
  .object<ToZod<User>>({
    id: z.number(),
    name: z.string(),
  })
  .strict();

export type Users = User[];

export const usersSchema = z.array(userSchema);

import { z } from 'zod';
import { ToZod } from '@/lib/zod';

export type ErrorResponse = {
  message: string;
};

export const errorResponseSchema = z.object<ToZod<ErrorResponse>>({
  message: z.string(),
});

import { Users } from '@/models/User';

const users: Users = [
  {
    id: 1,
    name: 'Adam',
  },
  {
    id: 2,
    name: 'Scott',
  },
  {
    id: 3,
    name: 'Matt',
  },
  {
    id: 4,
    name: 'John',
  },
  {
    id: 5,
    name: 'Frank',
  },
  {
    id: 6,
    name: 'Nicole',
  },
  {
    id: 7,
    name: 'Katie',
  },
  {
    id: 8,
    name: 'Nina',
  },
  {
    id: 9,
    name: 'Nancy',
  },
  {
    id: 10,
    name: 'Carol',
  },
];

export { users };

import {
  GetListRequestQuery,
  PostRequestBody,
  User,
  Users,
} from '@/models/User';

export type Methods = {
  get: {
    query?: GetListRequestQuery;

    resBody: Users;
  };

  post: {
    reqBody: PostRequestBody;

    resBody: User;
    /**
     * reqHeaders(?): ...
     * reqFormat: ...
     * status: ...
     * resHeaders(?): ...
     * polymorph: [...]
     */
  };
};

import { User } from '@/models/User';

export type Methods = {
  get: {
    resBody: User;
  };
};

/* eslint-disable */
// prettier-ignore
import { AspidaClient, dataToURLString } from 'aspida'
// prettier-ignore
import { Methods as Methods0 } from './users'
// prettier-ignore
import { Methods as Methods1 } from './users/_userId@number'

// prettier-ignore
const api = <T>({ baseURL, fetch }: AspidaClient<T>) => {
  const prefix = (baseURL === undefined ? '' : baseURL).replace(/\/$/, '')
  const PATH0 = '/users'
  const GET = 'GET'
  const POST = 'POST'

  return {
    users: {
      _userId: (val1: number) => {
        const prefix1 = `${PATH0}/${val1}`

        return {
          get: (option?: { config?: T }) =>
            fetch<Methods1['get']['resBody']>(prefix, prefix1, GET, option).json(),
          $get: (option?: { config?: T }) =>
            fetch<Methods1['get']['resBody']>(prefix, prefix1, GET, option).json().then(r => r.body),
          $path: () => `${prefix}${prefix1}`
        }
      },
      get: (option?: { query?: Methods0['get']['query'], config?: T }) =>
        fetch<Methods0['get']['resBody']>(prefix, PATH0, GET, option).json(),
      $get: (option?: { query?: Methods0['get']['query'], config?: T }) =>
        fetch<Methods0['get']['resBody']>(prefix, PATH0, GET, option).json().then(r => r.body),
      post: (option: { body: Methods0['post']['reqBody'], config?: T }) =>
        fetch<Methods0['post']['resBody']>(prefix, PATH0, POST, option).json(),
      $post: (option: { body: Methods0['post']['reqBody'], config?: T }) =>
        fetch<Methods0['post']['resBody']>(prefix, PATH0, POST, option).json().then(r => r.body),
      $path: (option?: { method?: 'get'; query: Methods0['get']['query'] }) =>
        `${prefix}${PATH0}${option && option.query ? `?${dataToURLString(option.query)}` : ''}`
    }
  }
}

// prettier-ignore
export type ApiInstance = ReturnType<typeof api>
// prettier-ignore
export default api

"scripts": {
    "dev": "run-p dev:*",
    "dev:next": "next dev",
    "dev:aspida": "aspida --watch",
    "build": "aspida && next build",
    ...
  },

## aspida
$api.ts

import aspida, { FetchConfig } from '@aspida/fetch';
import api from '@/api/$api';

const fetchConfig: FetchConfig = {
  credentials: 'include',
  baseURL: '/api',
  throwHttpErrors: true, // throw an error on 4xx/5xx, default is false
};

export const client = api(aspida(fetch, fetchConfig));

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import { NextApiRequest, NextApiResponse } from 'next';
import {
  getListRequestQuerySchema,
  postRequestBodySchema,
  User,
} from '@/models/User';
import { ErrorResponse } from '@/models/ErrorResponse';
import { users } from '@/mock/user';
import { ZodError } from 'zod';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  switch (req.method) {
    case 'GET':
      try {
        const query = getListRequestQuerySchema.parse(req.query);
        if (query.limit && query.limit < users.length) {
          res.status(200).json(users.slice(0, query.limit));
        } else {
          res.status(200).json(users);
        }
      } catch (e) {
        if (e instanceof ZodError) {
          const errorResponse: ErrorResponse = {
            message: '不正なクエリパラメータです。',
          };
          console.error(errorResponse, e);
          res.status(400).json(errorResponse);
        }
      }
      break;
    case 'POST':
      try {
        const body = postRequestBodySchema.parse(req.body);
        const newUser: User = {
          id: users.length + 1,
          name: body.name,
        };
        res.status(201).json(newUser);
      } catch (e) {
        if (e instanceof ZodError) {
          const errorResponse: ErrorResponse = {
            message: '不正なリクエストパラメータです。',
          };
          console.error(errorResponse, e);
          res.status(400).json(errorResponse);
        }
      }
      break;
    default:
      const errorResponse: ErrorResponse = {
        message: 'このエンドポイントで、そのメソッドは定義されていません。',
      };
      console.error(errorResponse);
      res.status(405).json(errorResponse);
  }
}

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import { NextApiRequest, NextApiResponse } from 'next';
import { requestPathParamsSchema } from '@/models/User';
import { ErrorResponse } from '@/models/ErrorResponse';
import { users } from '@/mock/user';
import { ZodError } from 'zod';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  switch (req.method) {
    case 'GET':
      try {
        const query = requestPathParamsSchema.parse(req.query);
        const user = users.find((user) => user.id === Number(query.userId));
        if (user) {
          res.status(200).json(user);
        } else {
          const errorResponse: ErrorResponse = {
            message: '指定のIDを持つユーザは存在しません',
          };
          console.error(errorResponse);
          res.status(404).json(errorResponse);
        }
      } catch (e) {
        if (e instanceof ZodError) {
          const errorResponse: ErrorResponse = {
            message: '不正なパスパラメータです。',
          };
          console.error(errorResponse, e);
          res.status(400).json(errorResponse);
        }
      }
      break;
    default:
      const errorResponse: ErrorResponse = {
        message: 'このエンドポイントで、そのメソッドは定義されていません。',
      };
      console.error(errorResponse);
      res.status(405).json(errorResponse);
  }
}

import { HTTPError } from '@aspida/fetch';
import { GetListRequestQuery, usersSchema } from '@/models/User';
import { errorResponseSchema } from '@/models/ErrorResponse';
import { client } from '@/lib/aspida';

const getUsers = async (query?: GetListRequestQuery) => {
  try {
    const res = await client.users.get({ query });
    return usersSchema.parse(res.body);
  } catch (e) {
    if (e instanceof HTTPError) {
      errorResponseSchema.parse(await e.response.json());
    }
    throw e;
  }
};

export default getUsers;

import { HTTPError } from '@aspida/fetch';
import { userSchema } from '@/models/User';
import { errorResponseSchema } from '@/models/ErrorResponse';
import { client } from '@/lib/aspida';

const getUser = async (userId: number) => {
  try {
    const res = await client.users._userId(userId).get();
    return userSchema.parse(res.body);
  } catch (e) {
    if (e instanceof HTTPError) {
      errorResponseSchema.parse(await e.response.json());
    }
    throw e;
  }
};

export default getUser;

import { HTTPError } from '@aspida/fetch';
import { PostRequestBody, userSchema } from '@/models/User';
import { errorResponseSchema } from '@/models/ErrorResponse';
import { client } from '@/lib/aspida';

const postUser = async (body: PostRequestBody) => {
  try {
    const res = await client.users.post({ body });
    return userSchema.parse(res.body);
  } catch (e) {
    if (e instanceof HTTPError) {
      errorResponseSchema.parse(await e.response.json());
    }
    throw e;
  }
};

export default postUser;

import { useState, useEffect, useCallback } from 'react';
import { HTTPError } from '@aspida/fetch';
import { ZodError } from 'zod';
import { Users } from '@/models/User';
import getUsers from '@/domains/getUsers';

const useUsers = () => {
  const [isLoading, setIsLoading] = useState<boolean>(false);
  const [errorMessage, setErrorMessage] = useState<string>();
  const [users, setUsers] = useState<Users>();

  useEffect(() => {
    setIsLoading(true);
    getUsers()
      .then((data) => {
        setErrorMessage('');
        setUsers(data);
      })
      .catch((err) => {
        if (err instanceof HTTPError) {
          setErrorMessage('ユーザ一覧情報の取得に失敗しました');
        } else if (err instanceof ZodError) {
          setErrorMessage('想定しないデータの取得が行われました');
        }
      })
      .finally(() => {
        setIsLoading(false);
      });
  }, []);

  return { isLoading, errorMessage, users };
};

export default useUsers;

import { ChangeEvent, FormEvent, useState, useCallback } from 'react';
import { HTTPError } from '@aspida/fetch';
import { ZodError } from 'zod';
import { User } from '@/models/User';
import getUser from '@/domains/getUser';

const useSearchUser = () => {
  const [userId, setUserId] = useState<number>(1);
  const [isLoading, setIsLoading] = useState<boolean>(false);
  const [errorMessage, setErrorMessage] = useState<string>();
  const [user, setUser] = useState<User>();

  const handleChangeUserId = useCallback((e: ChangeEvent<HTMLInputElement>) => {
    setUserId(Number(e.target.value));
  }, []);

  const handleSearchUser = useCallback(
    (e: FormEvent<HTMLFormElement>) => {
      e.preventDefault();

      setIsLoading(true);
      getUser(userId)
        .then((data) => {
          setErrorMessage('');
          setUser(data);
        })
        .catch((err) => {
          if (err instanceof HTTPError) {
            err.response.status === 404
              ? setErrorMessage('指定のIDを持つユーザは存在しません')
              : setErrorMessage('ユーザ情報の取得に失敗しました');
          } else if (err instanceof ZodError) {
            setErrorMessage('想定しないデータの取得が行われました');
          }
        })
        .finally(() => {
          setIsLoading(false);
        });
    },
    [userId]
  );

  return {
    userId,
    isLoading,
    errorMessage,
    user,
    handleChangeUserId,
    handleSearchUser,
  };
};

export default useSearchUser;

import { ChangeEvent, FormEvent, useState, useCallback } from 'react';
import { HTTPError } from '@aspida/fetch';
import { ZodError } from 'zod';
import postUser from '@/domains/postUser';

type FormData = {
  name: string;
};

const useCreateUser = () => {
  const [values, setValues] = useState<FormData>({
    name: '',
  });
  const [isLoading, setIsLoading] = useState<boolean>(false);
  const [errorMessage, setErrorMessage] = useState<string>();

  const clearValues = useCallback(() => {
    setValues({ name: '' });
  }, []);

  const handleChangeInput = useCallback(
    (key: keyof FormData) => (e: ChangeEvent<HTMLInputElement>) => {
      setValues({ ...values, [key]: e.target.value });
    },
    [values]
  );

  const handleCreateUser = useCallback(
    (e: FormEvent<HTMLFormElement>) => {
      e.preventDefault();

      setIsLoading(true);
      postUser(values)
        .then((data) => {
          setErrorMessage('');
          alert(
            `id: ${data.id} name: ${data.name}\nユーザを新規作成しました（モックなので実際には作成されてません）`
          );
          clearValues();
        })
        .catch((err) => {
          if (err instanceof HTTPError) {
            setErrorMessage('ユーザ新規作成に失敗しました');
          } else if (err instanceof ZodError) {
            setErrorMessage(
              'ユーザ新規作成に成功しました（モック）が、想定しないデータが返却されました'
            );
          }
        })
        .finally(() => {
          setIsLoading(false);
        });
    },
    [values, clearValues]
  );

  return {
    values,
    isLoading,
    errorMessage,
    handleChangeInput,
    handleCreateUser,
  };
};

export default useCreateUser;

import { Fragment } from 'react';
import Head from 'next/head';
import HomePage from '@/components/page/Home';

export default function Home() {
  return (
    <Fragment>
      <Head>
        <title>Type Safe Request</title>
        <meta name="description" content="型安全なHTTPリクエスト検証" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <HomePage />
    </Fragment>
  );
}

import { VFC } from 'react';
import styles from './Home.module.css';
import useUsers from '@/hooks/useUsers';
import useSearchUser from '@/hooks/useSearchUser';
import useCreateUser from '@/hooks/useCreateUser';

const Home: VFC = () => {
  const { isLoading, errorMessage, users } = useUsers();
  const {
    values,
    isLoading: createIsLoading,
    errorMessage: createErrMsg,
    handleChangeInput,
    handleCreateUser,
  } = useCreateUser();
  const {
    userId,
    isLoading: searchIsLoading,
    errorMessage: searchErrMsg,
    user,
    handleChangeUserId,
    handleSearchUser,
  } = useSearchUser();

  return (
    <div className={styles.container}>
      <div className={styles.layout}>
        <div>
          <h2>ユーザ一覧</h2>
          {(isLoading || errorMessage) && (
            <p className={errorMessage && styles.errorText}>
              {isLoading ? '読み込み中...' : errorMessage}
            </p>
          )}
          {!(isLoading || errorMessage) &&
            users?.map((user) => {
              return (
                <div key={user.id}>
                  <p>{`id: ${user.id} name: ${user.name}`}</p>
                </div>
              );
            })}
        </div>
        <div className={styles.rightBlock}>
          <div>
            <h2>ユーザ検索</h2>
            <form onSubmit={handleSearchUser}>
              <label>
                id:{' '}
                <input
                  type="search"
                  required
                  pattern="^\d+$"
                  title="数値で入力してください。"
                  value={userId}
                  onChange={handleChangeUserId}
                />
              </label>
              <button type="submit" disabled={searchIsLoading}>
                検索
              </button>
            </form>
            {!(searchIsLoading || searchErrMsg) && user && (
              <p>{`id: ${user.id} name: ${user.name}`}</p>
            )}
            {!searchIsLoading && searchErrMsg && (
              <p className={styles.errorText}>{searchErrMsg}</p>
            )}
          </div>
          <div>
            <h2>ユーザ新規作成</h2>
            <form onSubmit={handleCreateUser}>
              <label>
                name:{' '}
                <input
                  type="text"
                  required
                  value={values.name}
                  onChange={handleChangeInput('name')}
                />
              </label>
              <button type="submit" disabled={createIsLoading}>
                新規作成
              </button>
            </form>
            {createErrMsg && <p className={styles.errorText}>{createErrMsg}</p>}
          </div>
        </div>
      </div>
    </div>
  );
};

export default Home;