【TypeScript】非同期処理の型定義 完全ガイド｜Promise・async/await・Fetch APIの型を実例で解説

この記事で学べること

• Promise<T> の型定義基礎と関数シグネチャへの組み込み方
• async/await 関数の戻り値型の明示と型推論の仕組み
• Promise.all・allSettled・race・any の型推論の違い
• Fetch API の型安全な使い方と汎用ラッパー関数の実装
• try-catch における unknown 型のエラーハンドリング
• Result 型パターンで型安全な非同期処理を実装する方法
• 実務で使える APIクライアント・非同期状態の型定義パターン
• よくある型エラーと解決方法

前提知識：TypeScriptの基本型（string, number, boolean, Union型など）を理解していることを前提とします。基礎から学びたい方は【TypeScript】型の書き方 完全入門を、関数の型については【TypeScript】関数の型定義 完全ガイドをご参照ください。

// 1秒後に文字列を返す Promise
function wait(): Promise<string> {
  return new Promise((resolve) => {
    setTimeout(() => resolve("完了"), 1000);
  });
}

// Promise: 数値を返す
const p1: Promise<number> = Promise.resolve(42);

// Promise: 値を返さない（副作用のみの関数）
const p2: Promise<void> = Promise.resolve();

型パラメータの省略：Promise.resolve(42) のように値から型が推論できる場合、TypeScript が自動的に Promise<number> と推論するため明示不要です。型の明示は「関数シグネチャで意図を宣言したい場合」に特に重要です。

function readFile(path: string): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    // resolve の引数は string 型のみ受け付ける
    resolve("ファイル内容");        // OK
    // resolve(42);               // NG: number は string に代入不可
    reject(new Error("読み込み失敗"));  // reject は any を受け付ける
  });
}

注意：Promise の型パラメータは resolve の値のみに型チェックが働きます。reject に渡す値の型は any であり、TypeScript は拒否理由の型を追跡しません。エラー型を型安全に扱うには後述の「Result 型パターン」が有効です。

// 型推論：TypeScript が Promise と推論
async function getNumber() {
  return 42;  // 推論: Promise
}

// 明示的な戻り値型（公開 API・複雑なロジックに推奨）
async function getUser(id: number): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json() as User;
}

// Promise：値を返さない async 関数
async function sendLog(msg: string): Promise<void> {
  await postToServer(msg);
  // return しない → void
}

async function example() {
  const p: Promise<number> = Promise.resolve(42);
  const n: number = await p;  // Promise → number

  // ネストした Promise も1段ずつアンラップ
  const nested = Promise.resolve(Promise.resolve("hi"));
  const s = await nested;  // 型: string（Promise は自動フラット化）
}

// Awaited: Promise を再帰的にアンラップ
type A = Awaited<Promise<string>>;          // type A = string
type B = Awaited<Promise<Promise<number>>>;  // type B = number (再帰的にアンラップ)

// ReturnType と組み合わせて非同期関数の解決型を取得
async function fetchUser(id: number) {
  return { id, name: Alice, age: 30 };
}

// fetchUser の解決値の型を取得（型定義の再利用に便利）
type UserType = Awaited<ReturnType<typeof fetchUser>>;
// type UserType = { id: number; name: string; age: number }

// Promise.all の戻り値型取得にも活用
type AllResult = Awaited<ReturnType<typeof loadAll>>;

Awaited<T> の実務活用：async 関数の戻り値型を別の場所で再利用したい場合、Awaited<ReturnType<typeof functionName>> のパターンで型定義の重複を避けられます。インターフェースを別途定義しなくても、関数自体から型を抽出できる強力なテクニックです。

async function loadAll() {
  const [user, posts, count] = await Promise.all([
    fetchUser(1),       // Promise
    fetchPosts(1),      // Promise
    fetchPostCount(1),  // Promise
  ]);
  // 推論: [User, Post[], number]
  console.log(user.name, posts.length, count);
}

async function loadWithFallback() {
  const results = await Promise.allSettled([
    fetchUser(1),  // Promise
    fetchUser(2),  // Promise
  ]);
  // 型: PromiseSettledResult[]

  results.forEach((result) => {
    if (result.status === "fulfilled") {
      console.log(result.value.name);  // User 型
    } else {
      console.error(result.reason);      // 失敗理由
    }
  });
}

// Promise.race: 最初に解決/拒否した Promise の型を返す
const fast: string = await Promise.race([
  fetchFast(),  // Promise
  fetchSlow(),  // Promise
]);

// Promise.any: 最初に成功した Promise の型を返す（全部失敗→ AggregateError）
const result: Data = await Promise.any([
  tryPrimary(),   // Promise
  tryFallback(),  // Promise
]);

interface Post {
  id: number;
  title: string;
  body: string;
}

async function getPost(id: number): Promise<Post> {
  const response: Response = await fetch(`/api/posts/${id}`);

  if (!response.ok) {
    throw new Error(`HTTP Error: ${response.status}`);
  }

  // Response.json() は Promise。型アサーションで型を付ける
  const data = await response.json() as Post;
  return data;
}

async function apiFetch<T>(
  url: string,
  options?: RequestInit
): Promise<T> {
  const response = await fetch(url, options);

  if (!response.ok) {
    const msg = await response.text();
    throw new Error(`API Error ${response.status}: ${msg}`);
  }

  return response.json() as Promise<T>;
}

// 使用例：型引数で返り値の型を明示
const post  = await apiFetch<Post>("/api/posts/1");
const users = await apiFetch<User[]>("/api/users");
// post は Post 型、users は User[] 型として推論される

async function fetchWithTimeout<T>(
  url: string,
  timeoutMs: number = 5000
): Promise<T> {
  const controller = new AbortController();
  const timer = setTimeout(
    () => controller.abort(),
    timeoutMs
  );
  try {
    return await apiFetch<T>(url, { signal: controller.signal });
  } finally {
    clearTimeout(timer);
  }
}

型アサーション（as T）の制限：上記のラッパーは as Promise<T> でキャストしますが、実際のレスポンス構造を TypeScript は検証しません。型が一致しないデータが返ってきた場合も型エラーにならないため、本番環境では Zod や yup などのバリデーションライブラリを併用することを推奨します。

// axios.get で response.data の型を指定
import axios from axios;

async function getUser(id: number): Promise<User> {
  const response = await axios.get<User>();
  return response.data;  // User 型として推論される
}

// axios のエラー型: AxiosError を使って型ガード
import { axios, AxiosError } from axios;

try {
  await getUser(1);
} catch (err) {
  if (axios.isAxiosError(err)) {
    console.log(err.response?.status);  // number | undefined
    console.log(err.message);         // string
  }
}

async function safeFetch(url: string) {
  try {
    return await apiFetch<unknown>(url);
  } catch (err) {
    // TypeScript 4.0+: err は unknown 型
    if (err instanceof Error) {
      console.error(err.message);  // OK: string として推論
    } else {
      console.error("予期しないエラー:", err);
    }
  }
}

class ApiError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly endpoint: string,
    message: string
  ) {
    super(message);
    this.name = "ApiError";
  }
}

async function callApi(url: string) {
  const res = await fetch(url);
  if (!res.ok) {
    throw new ApiError(res.status, url, await res.text());
  }
  return res.json();
}

// 使用時: instanceof で ApiError を絞り込む
try {
  await callApi("/api/data");
} catch (err) {
  if (err instanceof ApiError) {
    console.log(err.statusCode);  // number
    console.log(err.endpoint);   // string
  }
}

// Result 型の定義
type Ok<T> = { ok: true;  value: T };
type Err<E> = { ok: false; error: E };
type Result<T, E = Error> = Ok<T> | Err<E>;

// ヘルパー関数
const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
const err = <E>(error: E): Err<E> => ({ ok: false, error });

// Result 型を返す非同期関数
async function safeGetUser(id: number): Promise<Result<User>> {
  try {
    const user = await apiFetch<User>(`/api/users/${id}`);
    return ok(user);
  } catch (e) {
    return err(e instanceof Error ? e : new Error(String(e)));
  }
}

// 呼び出し元: ok フラグで型を絞り込む
const result = await safeGetUser(1);
if (result.ok) {
  console.log(result.value.name);   // User 型
} else {
  console.error(result.error.message);
}

// 単一リソース
interface ApiResponse<T> {
  data:    T;
  message: string;
  success: boolean;
}

// ページネーション
interface Paginated<T> {
  data:     T[];
  total:    number;
  page:     number;
  pageSize: number;
}

// 使用例
async function getUsers(page: number): Promise<Paginated<User>> {
  return apiFetch<Paginated<User>>(`/api/users?page=${page}`);
}

type AsyncState<T> =
  | { status: "idle"                          }
  | { status: "loading"                       }
  | { status: "success"; data: T          }
  | { status: "error";   error: Error      };

// 使用例（React useState）
const [state, setState] = useState<AsyncState<User>>({ status: "idle" });

async function loadUser(id: number) {
  setState({ status: "loading" });
  try {
    const user = await apiFetch<User>(`/api/users/${id}`);
    setState({ status: "success", data: user });
  } catch (e) {
    const error = e instanceof Error ? e : new Error(String(e));
    setState({ status: "error", error });
  }
}

// render 時: status で data の存在が型レベルで保証される
if (state.status === "success") {
  console.log(state.data.name);  // OK: User 型
}

// ❌ NG: catch 節の err を直接使う
try { /* ... */ } catch (err) {
  console.log(err.message);  // Error: Object is of type 'unknown'
}

// ✅ OK: instanceof で型ガード
try { /* ... */ } catch (err) {
  if (err instanceof Error) {
    console.log(err.message);  // OK: string
  }
}

// ❌ NG: async 関数の戻り値を await なしで使う
const user: User = getUser(1);  // Error: Promise は User に代入不可

// ✅ OK: await する
const user: User = await getUser(1);

TypeScript 非同期処理 型定義まとめ

• Promise<T> は「将来的に T を返す」型。async 関数は自動的に Promise<T> を返す
• await は Promise<T> を T にアンラップ。TypeScript も型を追跡する
• Promise.all はタプル型を返す。allSettled は PromiseSettledResult<T>[] を返す
• fetch の Response.json() は any 型。型アサーションか汎用ラッパーで型を付ける
• catch 節の変数は unknown 型（TS 4.0+）。instanceof Error で型ガードが必要
• Result 型パターン で例外を使わない型安全なエラーハンドリングが可能
• AsyncState<T>（idle/loading/success/error）で UI の状態管理を型安全に