【無料配布】10日間で学べるTypeScript学習資料

TypeScriptの非同期処理(Promise/async・await)型定義とエラーハンドリング

TypeScriptでWebアプリやAPI連携を実装しようとすると、つまずくのが「非同期処理(Promise/async・await)の型定義」と「エラーハンドリング」です。

「async関数の戻り値にはどんな型を書けばいいの?」
「try / catchのerrorで型エラーが出てしまい、どう処理すればいいかわからない……」

と手が止まってしまった経験はありませんか?

結論から言うと、TypeScriptの非同期処理は「戻り値をPromise<T>で定義すること」と、「catch節のunknown型をinstanceof Error 等で安全に絞り込むこと」の2点さえ押さえれば、実務でも迷わず型安全に書けるようになります。

本記事では、Promise<T>の基本からasync / await×fetchの実践パターン、そしてtry / catchや実務で人気のResult型を使ったエラーハンドリングまで、図解とサンプルコード付きでわかりやすく整理します。

この記事を読み終えれば、API通信やデータベース取得などの非同期処理で型エラーに悩むことがなくなり、バグの起きにくい堅牢なコードを書けるようになります。

目次

TypeScriptの非同期処理は「Promise」と「unknown型」が基本

TypeScriptで非同期処理を書くとき、最も大切なルールは「成功したときの値」と「失敗したときのエラー」の2つの型を明確に分けて扱うことです。

TypeScriptの非同期処理
  • 成功時:async関数は必ずPromise<T>(将来T型の値が返ってくる約束)を返す
  • 失敗時:try / catchで受け取るエラーはunknown型になるため、型チェックしてから使う

この2つの基本さえ理解しておけば、非同期処理特有の型エラーに悩まされることはなくなります。

async関数の戻り値はPromise<T>になる

通常の関数であれば、数値を返すときの戻り値型は: number、文字列なら: stringと書きます。

しかし、関数の前にasyncを付けた瞬間、その関数は「非同期で値を返す箱(Promise)」を返すようになるため、戻り値の型は必ずPromise<number>やPromise<string>のようにPromise<...>で包む必要があります。

returnする値そのものはnumberでも、呼び出し元に届く形はPromise<number>になる点がポイントです。

通常の関数と async 関数の戻り値型の違い
同期関数(通常の関数)
値そのものをそのまま返す
function getAge(): number

呼び出した瞬間に number 型の値が手に入る。

非同期関数(async付き)
Promiseという「箱」で包んで返す
async function getAge(): Promise<number>

await で箱を開けることで、中の number を取り出せる。

通常の関数とasync関数の戻り値型を確認しましょう。

// 通常の関数:戻り値はそのまま string
function getGreeting(): string {
  return "こんにちは";
}

// async 関数:戻り値は必ず Promise<string> になる
async function getGreetingAsync(): Promise<string> {
  return "こんにちは(非同期)";
}

async function main(): Promise<void> {
  const syncText = getGreeting();             // string 型
  const asyncText = await getGreetingAsync(); // await で Promise を外して string 型に

  console.log(syncText, asyncText);
}

main();

returnしているのは"こんにちは(非同期)"という文字列ですが、asyncが付いているため戻り値型は: Promise<string>と指定します。

main関数のようにreturnで値を返さないasync関数は、戻り値型をPromise<void>と書きます。

awaitを付けることでPromise<string>の箱から中身のstringを取り出しています。

非同期処理で型定義が重要になる理由(API通信・データ取得)

非同期処理は、主に「外部APIからのデータ取得」「データベースの読み書き」「ファイル読み込み」など、プログラムの外部とやり取りする場面で使われます。

外部から受け取るデータは「いつ届くか分からない」だけでなく、「どんな形(プロパティ)で届くか」をTypeScriptが自動で知ることはできません。

そのため、あらかじめ型定義を用意しておかないと、データの中身がすべてany型(ノーチェック状態)になり、画面表示の瞬間にエラーで落ちる原因になります。

API通信などの非同期処理で型定義が欠かせない理由
型定義なし(anyのまま)
  • APIからどんな項目が返るか補完が出ない
  • プロパティ名のタイプミスに実行時まで気づけない
  • 通信失敗時の error をそのまま参照してクラッシュ
型定義あり(Promise<T> + unknown)
  • 取得データの項目がエディタで自動補完される
  • 存在しないプロパティ参照をコンパイル時に防止
  • 失敗時のエラー処理も型安全に強制できる

成功時(Promise<User>)と失敗時(unknown)の基本形を確認しましょう。

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

// 成功時は Promise<User> を返し、失敗時は try/catch の unknown 型で受け止める
async function loadUser(): Promise<User | null> {
  try {
    const res = await fetch("https://jsonplaceholder.typicode.com/users/1");
    if (!res.ok) {
      throw new Error(`HTTPエラー: ${res.status}`);
    }
    const data = (await res.json()) as User;
    return data;
  } catch (error: unknown) {
    if (error instanceof Error) {
      console.error("取得失敗:", error.message);
    }
    return null;
  }
}

成功したときはUser型、通信失敗などで取得できなかったときはnullを返すことを型で明示しています。

これにより、呼び出し側でnullチェックを忘れるミスを防げます。

TypeScriptでは失敗時のerrorに何が飛んでくるか保証されないため、unknown型として受け取り、if (error instanceof Error)で安全に絞り込んでから.messageを参照します。

Promiseの型定義の基本と書き方

Promiseの型を正確に書けるようになると、非同期処理のコードの見通しが劇的に良くなります。

ここでは基本のジェネリクス構文から、実務で頻出するAPIレスポンス型・Promise.allの型推論まで整理します。

Promise<T>の構文と型推論の仕組み

Promise<T>の<T>(ジェネリクス)には、「処理が成功したときに最終的に得られる値の型」を入れます。

たとえばnew Promise<string>(...)と書けば「成功時に文字列を返すPromise」になり、async関数でreturn 100と書けば、TypeScriptが自動でPromise<number>と型推論してくれます。

ただし、実務ではチームで型を共有しやすくするため、関数の戻り値型は明示的に: Promise<...>と書くのが推奨されます。

Promise<T> の構造:<T> の部分に「成功時の戻り値型」が入る
Promise<T>
Promise<string>

成功すると「文字列」が返る

Promise<User[]>

成功すると「User配列」が返る

Promise<void>

完了を待つだけで「返り値なし」

new Promise<T>での型指定例を確認しましょう。

// 指定ミリ秒だけ待機してからメッセージを返す Promise<string>
function waitMessage(ms: number): Promise<string> {
  return new Promise<string>((resolve) => {
    setTimeout(() => {
      resolve(`${ms}ミリ秒待機しました`);
    }, ms);
  });
}

async function run() {
  const result = await waitMessage(1000); // result は自動で string 型と推論される
  console.log(result);
}

run();

<string>を指定することで、resolve(...)の引数に文字列以外(数値など)を渡そうとすると即座に型エラーになります。

waitMessageの戻り値がPromise<string>であるため、awaitを付けた変数resultは型を書かなくても自動でstring型として扱われます。

APIレスポンスの型を定義してPromise<User>を返す例

実務では、単なるstringやnumberではなく、APIから取得したオブジェクトや配列を扱うケースがほとんどです。

あらかじめtypeやinterfaceでレスポンスの型を定義し、Promise<User>やPromise<User[]>として返却する形を作っておきます。

APIレスポンスに型を付けて安全に画面へ渡す流れ
1. 型を定義

type User = { ... } で構造を宣言

▶
2. 関数に指定

戻り値を Promise<User> に固定

▶
3. 安全に利用

user.name 等が補完付きで使える

オブジェクト型Userを返す非同期関数の例を確認しましょう。

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

async function fetchUserById(userId: number): Promise<User> {
  const res = await fetch(`https://jsonplaceholder.typicode.com/users/${userId}`);
  if (!res.ok) {
    throw new Error("ユーザー情報の取得に失敗しました");
  }
  const user: User = await res.json();
  return user;
}

async function showUser() {
  const user = await fetchUserById(1);
  console.log(`${user.name} (${user.email})`); // name や email が自動補完される
}

引数userIdは数値、成功時の戻り値はUserオブジェクトであることを明記しています。

呼び出し側のshowUser()では、user.と入力した時点でid/name/emailがエディタに補完表示されるため、プロパティ名の書き間違いを防げます。

Promise.allで複数の非同期処理を並列実行するときの型

「ユーザー情報」と「投稿一覧」のように、互いに依存しない2つのAPIを同時に取得したいときはPromise.allを使います。

TypeScriptのPromise.allは優秀で、配列で渡した各Promiseの型を順番どおりに保ったタプル型([User, Post[]])として自動推論してくれます。

Promise.all は異なる型をまとめても順番通りに型推論される
[0] Promise<User>
[1] Promise<Post[]>
await Promise.all(…)
──────▶
[0] user: User 型
[1] posts: Post[] 型

異なる型の非同期処理をPromise.allで並列実行する例を確認しましょう。

type User = { id: number; name: string };
type Post = { id: number; title: string };

async function fetchUser(): Promise<User> {
  return { id: 1, name: "田中" };
}

async function fetchPosts(): Promise<Post[]> {
  return [{ id: 10, title: "TypeScript入門" }];
}

async function loadDashboard(): Promise<void> {
  // user は User 型、posts は Post[] 型として正確に推論される
  const [user, posts] = await Promise.all([fetchUser(), fetchPosts()]);

  console.log(user.name);       // "田中"
  console.log(posts[0]?.title); // "TypeScript入門"
}

1つ目の要素にfetchUser()、2つ目にfetchPosts()を渡しているため、分割代入で受け取るuserはUser型、postsはPost[]型に自動で分かれます。

2つの処理を直列(1つずつawait)で待つより実行時間を短縮でき、なおかつ型安全性も完全に保たれます。

async/awaitを使った型安全な実装パターン

Promiseの.then()を繋げて書くよりも、現在のTypeScript開発ではasync / awaitを使って同期処理のように上から下へ読みやすく書くのが主流です。

ここでは実務でそのまま使える型安全な書き方と、初心者がよく踏むミスへの対処法を解説します。

async/awaitの基本構文と戻り値の型指定

async/awaitを使うときのルールはシンプルです。

  • 非同期処理を扱う関数の前にasyncを付ける
  • Promise<T>を返す処理の前にawaitを付けて結果を取り出す
  • 関数の戻り値型にはPromise<返却する型>を書く

なお、アロー関数(const fn = async () => ...)でも通常の関数宣言でも考え方はまったく同じです。

async / await で型を保つ3つの基本ルール
ルール 1
関数に async を付ける

関数内で await を使うための宣言。戻り値は自動でPromise化される。

ルール 2
戻り値は Promise<T>

return する値の型を Promise<...> の中に明記する。

ルール 3
await で中身を取り出す

Promise<T> の箱を外し、純粋な T 型として変数に受け取る。

アロー関数でのasync / await型定義例を確認しましょう。

引数の後ろに: Promise<number>を書くことで、アロー関数でも戻り値の型を明確に指定できます。

awaitを付けているため、totalはPromise<number>ではなくnumber型として受け取れます。

fetchと組み合わせた実践的な型付きデータ取得

Web開発で最もよく使うfetchAPIと組み合わせる場合、res.json()の戻り値はTypeScript上ではPromise<any>扱いになる点に注意が必要です。

そのままでは型チェックが効かないため、ジェネリクス<T>を使った共通のfetchJson関数を1つ用意しておくと、どんなAPIエンドポイントに対しても安全に型を付けてデータを取得できます(fetchのラッパー作成やモックテストの詳細は【TypeScript】fetchの使い方もあわせてご覧ください)。

fetchJson<T> ラッパー関数で res.json() の any を型安全にする仕組み
res.json() の素の状態

戻り値が Promise<any> で危険

▶
fetchJson<T>(url)

ステータス確認+型 T を付与

▶
呼び出し元の受け取り

Promise<Article> として安全に利用

ジェネリクスを使った型付きfetch関数の例を確認しましょう。

type Article = {
  id: number;
  title: string;
};

// ジェネリクス <T> を使い、呼び出し元が指定した型で返す汎用関数
async function fetchJson<T>(url: string): Promise<T> {
  const res = await fetch(url);
  if (!res.ok) {
    throw new Error(`HTTPエラー: ${res.status}`);
  }
  return (await res.json()) as T;
}

async function main(): Promise<void> {
  // <Article> を渡すだけで、article が Article 型になる
  const article = await fetchJson<Article>("https://jsonplaceholder.typicode.com/posts/1");
  console.log(article.title);
}

main();

<T>という仮の型パラメータを用意しておくことで、呼び出すときに<Article>や<User[]>など好きな型を当てはめられます。

fetchはサーバーが404や500を返してもエラーを投げない仕様のため、res.okで明示的にチェックしてからres.json()に進むのが実務の定石です。

よくあるエラー「await忘れでPromise<T>が返る」対処法

TypeScriptの非同期処理で初心者が最もよく遭遇するエラーが、「awaitを付け忘れて、Promise<string>のまま文字列関数に渡してしまう」というミスです。

JavaScriptでは実行するまで気づけませんが、TypeScriptではProperty '...' does not exist on type 'Promise<...>'というエラーメッセージで即座に教えてくれます。

このメッセージを見たら「awaitの付け忘れ」を疑ってください。

await を忘れたときの型エラーと正しい修正方法
NG:await 忘れ const name = getName();

name は Promise<string> のまま。name.toUpperCase() で型エラー発生。

OK:await を付ける const name = await getName();

箱が開いて string 型になり、文字列メソッドが安全に使える。

await忘れによるエラーと修正例を確認しましょう。

async function getUserName(): Promise<string> {
  return "alice";
}

async function printUpperName(): Promise<void> {
  // NG:await を忘れると Promise<string> が入ってしまいエラーになる
  // const name = getUserName();
  // console.log(name.toUpperCase()); // ← Property 'toUpperCase' does not exist on type 'Promise<string>'.

  // OK:await を付けて string を取り出す
  const name = await getUserName();
  console.log(name.toUpperCase()); // "ALICE"
}

printUpperName();

getUserName()はPromise<string>を返すため、awaitを付けないとnameには文字列ではなく「Promiseオブジェクト」が入ります。

await getUserName()に修正すれば、nameがstring型に変わるため.toUpperCase()が問題なく動作します。

非同期処理のエラーハンドリング(try/catchとResult型)

非同期処理はネットワーク切断やサーバーエラーなど「失敗する可能性」が常につきまといます。

TypeScriptで安全にエラーを処理するための3つの知識を押さえましょう。

catch節のerrorがunknown型になる理由と安全な絞り込み

TypeScript(strict: true環境)では、try / catchのcatch (error)で受け取る変数の型はunknown型 になります。

理由は、JavaScriptの仕様上throw "エラー文字列"やthrow 404のように、Errorオブジェクト以外のどんな値でも投げられてしまうためです。

したがって、error.messageとそのまま書くと「errorはunknown型なので.messageがあるか保証できない」という型エラーが発生します。

catch節の error (unknown型) は型チェックしてから使うのが鉄則
error: unknown

文字列・数値・Errorオブジェクト等、何が飛んでくるか不明。直接 error.message は不可。

型を絞り込む
──▶
安全にエラー処理

if (error instanceof Error) などで型を確定させてからメッセージを取得。

unknown型エラーと安全な分岐の基本を確認しましょう。

async function riskyTask(): Promise<void> {
  try {
    throw new Error("通信がタイムアウトしました");
  } catch (error: unknown) {
    // NG:unknown のままでは参照できない
    // console.error(error.message); // ← 'error' is of type 'unknown'.

    // OK:型を調べてから参照する
    if (error instanceof Error) {
      console.error("エラー内容:", error.message);
    } else {
      console.error("予期しないエラー:", error);
    }
  }
}

riskyTask();

errorにunknown型を指定することで、「何の型かチェックせずにプロパティへアクセスする危険なコード」をコンパイル時に防げます。

elseブロックを用意しておくことで、万が一外部ライブラリがError以外の文字列などをthrowした場合も安全にログ出力できます。

instanceof Errorを使ったエラーメッセージの取り出し方

実務では、複数の箇所でtry / catchを書くたびにif (error instanceof Error)を毎回書くのが面倒になりがちです。

そこで、「どんな値が来ても確実に文字列メッセージへ変換するヘルパー関数」を1つ作っておくとコードがスッキリします。

getErrorMessage ヘルパー関数による分岐パターン
パターン 1
Errorインスタンス

error instanceof Error が真なら error.message を返す。

パターン 2
文字列のエラー

typeof error === "string" ならそのまま文字列として返す。

パターン 3
その他の不明な値

"不明なエラーが発生しました" 等の固定文言にフォールバック。

エラーメッセージ抽出ヘルパー関数の実装を確認しましょう。

function getErrorMessage(error: unknown): string {
  if (error instanceof Error) {
    return error.message;
  }
  if (typeof error === "string") {
    return error;
  }
  return "不明なエラーが発生しました";
}

async function fetchProfile(): Promise<void> {
  try {
    const res = await fetch("https://example.com/api/profile");
    if (!res.ok) throw new Error(`ステータス異常: ${res.status}`);
  } catch (error: unknown) {
    const message = getErrorMessage(error);
    console.error("画面表示用メッセージ:", message);
  }
}

この関数を通すことで、どんな型のエラーが飛んできても確実にstring型のメッセージを受け取れるようになります。

UIにエラー通知(トーストやアラート)を表示する際にも、型エラーを気にせずそのまま渡せるため非常に実用的です。

例外を投げずに型で表現するResult型パターン(実務向け)

try / catchは便利ですが、「この関数がエラーを投げる可能性があるかどうか、関数の型だけ見てもわからない」という弱点があります。

そこで近年の中〜大規模TypeScript開発で人気なのが、成功と失敗を両方とも戻り値の型として返すResult型(判別可能なユニオン型) パターンです。

Result型:成功と失敗を ok フラグで型安全に分岐する
成功時(ok: true) { ok: true; data: T }

if (res.ok) の中では確実に res.data が取り出せる。

失敗時(ok: false) { ok: false; error: string }

else 側では res.error だけが存在し、エラー処理漏れを防げる。

Result<T>を使った非同期関数の実装例を確認しましょう。

type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: string };

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

async function safeFetchUser(id: number): Promise<Result<User>> {
  try {
    const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`);
    if (!res.ok) {
      return { ok: false, error: `HTTPエラー: ${res.status}` };
    }
    const data = (await res.json()) as User;
    return { ok: true, data };
  } catch (e: unknown) {
    return { ok: false, error: e instanceof Error ? e.message : "通信エラー" };
  }
}

async function run(): Promise<void> {
  const result = await safeFetchUser(1);

  if (!result.ok) {
    console.error("失敗:", result.error); // ここでは result.error が確実に存在する
    return;
  }
  console.log("成功:", result.data.name); // ここでは result.data が確実に User 型になる
}

関数の中でtry / catchを完結させ、成功も失敗もResult型として返すため、呼び出し元のrun()側ではtry / catchを書く必要がなくなります。

if (!result.ok)で早期リターンすると、その後の行では TypeScriptが自動で「成功パターン(data: User)」だと認識してくれるため、安全かつ見通しの良いコードになります。

まとめ:型安全な非同期処理で実務バグを防ごう

最後に、TypeScriptの非同期処理で押さえるべきポイントを振り返ります。

まとめ
  • async関数の戻り値型は必ずPromise<T>になる(返り値がないときはPromise<void>)
  • fetchのres.json()はany型になるため、ジェネリクス<T>を使ったラッパー関数で型を付ける
  • catch (error: unknown)はinstanceof Errorで型を絞り込むか、実務ではResult型を活用する

「非同期処理や型定義を、実際のWebアプリ開発の中で体系的に身につけたい」という方は、本サイトで無料公開している【無料配布】10日間で学べるTypeScript学習資料もぜひお役立てください。

基礎からサンプルアプリの実装コードまで一通り手に入ります。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!
目次