promise.raceとは？初心者にもわかる使い方と注意点を徹底解説共起語・同意語・対義語も併せて解説！

この記事を書いた人

高岡智則

年齢：33歳性別：男性職業：Webディレクター（兼ライティング・SNS運用担当）居住地：東京都杉並区・永福町の1LDKマンション出身地：神奈川県川崎市身長：176cm 体系：細身〜普通（最近ちょっとお腹が気になる）血液型：A型誕生日：1992年11月20日最終学歴：明治大学・情報コミュニケーション学部卒通勤：京王井の頭線で渋谷まで（通勤20分）家族構成：一人暮らし、実家には両親と2歳下の妹恋愛事情：独身。彼女は2年いない（本人は「忙しいだけ」と言い張る）

はじめに

JavaScript には非同期処理と呼ばれる特別な動きがあります。promise.race はその非同期処理をまとめて扱える便利な機能です。promise.race は複数の非同期処理を同時に走らせ、最初に settled したものの結果を返します。つまり最初に解決された値か、最初に拒否された理由だけを取り出すことができます。

promise.raceとは何か

promise.race は Promise のメソッドのひとつで、引数として反復可能なものを受け取ります。返り値は新しい Promise です。この新しい Promise は、引数に入れた中のいずれかが最初に解決または拒否されると、同じ結果で解決または拒否されます。全体としては誰が先に settle するかに依存して動きます。

仕組みと動作の原理

仕組みとしては各 input の Promise が走り出し、どれかが最初に解決されるか拒否されると、race 自体もその結果で決着します。他の Promise はまだ動作を止めるわけではなく、まだ走っていますが、外側の race はすでに解決した結果を返します。

使い方の例

以下は p1 p2 p3 という三つの非同期処理を同時に実行し、最初に終わったものの結果を得る例です。実際のコード風の表現としては次のようになります。

p1 は 100 ミリ秒後に解決、p2 は 200 ミリ秒後に解決、p3 は 50 ミリ秒後に拒否します。Promise.race([p1, p2, p3]) は最初に起きたことに応じて結果を返します。

コード風の表現: const p1 = new Promise(resolve => setTimeout(() => resolve(1), 100));

const p2 = new Promise(resolve => setTimeout(() => resolve(2), 200));

const p3 = new Promise((_, reject) => setTimeout(() => reject(3), 50));

Promise.race([p1, p2, p3]).then(console.log).catch(console.error);

注意点と落とし穴

最初に解決された結果だけを受け取るという性質は強力ですが、他の入力の Promise はまだ実行を続けている点に注意しましょう。外側の race が解決しても、残りの非同期処理を自動で止めてくれるわけではありません。キャンセルしたい場合は別途 abort の仕組みやフラグを用意する必要があります。

また 拒否が先に来た場合も対応が必要です。エラーをハンドリングしないとアプリ全体が落ちることがあります。実際のコードでは catch でエラーを取り扱い、必要に応じて再処理や代替処理を入れておくと安定します。

応用と活用のヒント

promise.race は「最速を選ぶ」場面に向いています。例えば次のような使い方が想定されます。都合の良い API を複数用意して、どれが一番速く応答するかを競わせ、最速のものだけを採用するといった戦略です。また API 呼び出しのタイムアウトを実装する際にも便利です。タイムアウト処理を promise で作り、race で速い方を選ばせると、実質的な待機時間を短縮できます。

表で見る Promise.race の挙動

状況	説明
最初に解決	race はその解決値で解決され、他の入力は影響を与えません。
最初に拒否	race はその拒否理由で拒否され、エラー処理へ移ります。
他の入力の動作	他の Promise はまだ動作を続ける場合があり、不要な処理が走り続けることがあります。

まとめ

promise.race は複数の非同期処理のうち最初に結果が出たものの値をすばやく取得できる便利な機能です。使い方はシンプルで、複数の Promise を配列として渡すだけです。ただし、最初に決着した結果だけを取り出す性質上、他の処理を自動で止めるわけではありません。適切なエラーハンドリングと必要なキャンセル機構を組み合わせることが、安定した非同期処理設計のコツです。

promise.raceの同意語

最速で結果が出るPromise: Promise.raceは、複数のPromiseのうち“最初に解決または拒否したもの”の結果で全体の結果を決定します。したがって“最速で結果が出る約束”という意味合いを持つ表現です。
最初に解決された結果を返すPromise: 複数の非同期処理のうち、最初に解決された値を返す約束のこと。これを使うと他の処理を待たずに結果を受け取れます。
先着で決着する約束: 並行実行している複数のPromiseの中で、先に結果が出た方の成否で全体の結論を出す約束です。
最速の拒否・解決で決まる約束: Promise.raceは、最初に拒否されるか最初に解決されるかのいずれかで結果が確定します。
競争型Promiseの表現: 複数の非同期処理を“競争”させ、最初に成立した結果で全体の流れを決めるという考え方を表す言い換えです。

promise.raceの対義語・反対語

Promise.all: すべてのプロミスが解決されるまで待ち、途中の一つでも拒否されれば全体が拒否になる。race が最初に解決または拒否された1つで終わるのに対して、全体の完了を待つ点が対義的。
Promise.allSettled: すべてのプロミスが解決または拒否のいずれかで完了するまで待つ。結果は各プロミスの状態を含む。race の最初の決着を待つ挙動とは対照的に、全てが揃うまで待つ点が対義的。
Promise.any: 最初に成功したプロミスが返される。拒否は無視され、すべてが拒否された場合のみエラーになる。race が最初の決着を返すのに対し、any は最初の成功を重視する点で異なる挙動。

promise.raceの共起語

Promise: JavaScriptの非同期処理を扱う基本的なオブジェクト。resolve/拒否される値を返す構造を持つ。
Promise.race: 複数のPromiseのうち、最初に解決または拒否したものの結果を返す挙動。最速勝ちの競争のような動き。
非同期処理: 処理がすぐに完了するのを待たず、別の処理と同時に進める仕組み。Promiseは代表的な実現方法。
複数のPromise: 同時に複数の非同期処理を開始して、最初の結果を取得するパターンでよく使われる。
resolve: Promiseが成功したときに呼ばれる関数。最終的な値を返す役割。
reject: Promiseが失敗したときに呼ばれる関数。エラー情報を返す役割。
then: Promiseが解決したときの処理を連結する方法。複数の処理を順番につなげられる。
catch: Promiseが拒否された場合の処理を連結する方法。エラーハンドリングに使う。
async/await: 非同期処理を直感的に書くための構文。Promiseと組み合わせて使うと読みやすいコードになる。
タイムアウト: 一定時間で処理を打ち切る、または先に終わる方を選ぶ機能を実装する際に重要な概念。
先に解決した結果: raceでは最速で解決したPromiseの値を使うのが基本動作。
競合 / レース: 複数の処理が同時に進み、どちらが先に終わるかを競うイメージ。
Promise.all: 複数のPromiseをすべて待ち、全てが解決したときに全結果の配列を返す。
Promise.any: 複数のPromiseのうち、いずれかが解決した時点でその値を返す。全てが拒否されると拒否になる。
Promise.allSettled: 全てのPromiseの結果を、成功・失敗を問わず配列で返す。
pending: まだ解決/拒否されていない、未確定の状態。
fulfilled: Promiseが解決済みの状態。
rejected: Promiseが拒否済みの状態。
HTTPリクエスト / fetch: fetchのようなHTTPリクエストもPromiseを返す。Promise.raceと組み合わせる場面が多い。
AbortController: 外部操作を中止するための仕組み。キャンセルを目的に使われることがある。
サンプル例: 例えば、一定時間内に応答が来なければタイムアウトを設定するなど、実践的な使い方の例が多い。

promise.raceの関連用語

Promise.race: 複数の Promise のうち最初に決着したものの結果で新しい Promise を返します。入力は iterable で、各要素は Promise または値として解釈され、最初に解決または拒否した時点で結果が得られます。空の iterable を渡すと返される Promise は決着しません。
Promise.all: すべての input Promise が解決するまで待ち、解決値を配列として返します。途中で一つでも拒否されると拒否の原因で返されます。
Promise.allSettled: すべての input の結果を待ち、それぞれの結果を {status: 'fulfilled', value} または {status: 'rejected', reason} の形で配列として返します。
Promise.any: すべての input が拒否されるまで待ち、最初に fulfilled となった値を返します。すべて拒否された場合は AggregateError が返されます。
Promise.resolve: 値を Promise に変換します。すでに Promise であればそのまま返します。
Promise.reject: 拒否された状態の Promise を作成して返します。
then: 前の Promise が解決したときに実行される成功側のコールバックを登録します。
catch: 前の Promise が拒否されたときに実行されるエラーハンドリングのコールバックを登録します。
finally: 結果の成否に関係なく実行される後処理を登録します。
executor: 新しい Promise の実行関数。引数に resolve と reject を受け取り、非同期処理の完了時にどちらかを呼び出します。
settled 状態: Promise が解決済みまたは拒否済みの状態で、値や拒絶理由を持つことを指します。
pending 状態: まだ決着していない未解決の状態です。
fulfilled 状態: 解決された状態です。値を持っています。
rejected 状態: 拒否された状態です。理由を持っています。
iterable: Promise.race が受け取る反復可能オブジェクト。配列やセットなどを渡します。
thenable: then メソッドを持つオブジェクト。Promise 自体ではなくても扱える可能性があります。
microtask queue: Promise の解決処理や then/catch のコールバックが入る実行待機列。現在のタスクが終わるとすぐ実行されます。
macrotask queue: setTimeout などの大きなタスクが入る待機列。イベントループで順次処理されます。
イベントループ: JavaScript が非同期処理を管理する仕組み。コールスタックとキューを連携させます。
non-blocking I/O: UI を止めずに入出力を処理する非同期手法です。
setTimeout: 指定した遅延で処理を実行する関数。タイムアウトパターンで Promise.race と組み合わせて実装することが多いです。
タイムアウトパターン: Promise.race を使って処理が一定時間内に終わらない場合にエラーを返す方法です。例として fetch とタイムアウトの競合を使います。
AbortController: 一連の非同期処理を中止するための API。主に fetch などでキャンセル信号を送るのに使います。
Fetch のキャンセル: AbortController で fetch を途中で中止する方法のことです。
空の iterable の動作: Promise.race に空の iterable を渡すと、決着がつかず永遠に保留になります。
AggregateError: 複数のエラーをまとめたエラーオブジェクト。特に Promise.any が全て拒否されたときに利用されます。
利用ケース: 複数の後方データ源から最初の応答を得たい場合や、処理のタイムアウトを設定したい場合などに Promise.race を活用します。