【Node.js24.x】Promise::race()メソッドの使い方

raceメソッドは、複数の非同期処理が並行して実行されている中で、最も早く結果が出た処理の結末を取得するメソッドです。これは、JavaScriptの組み込みオブジェクトであるPromiseクラスの静的メソッドとして提供されています。

このメソッドは、Promiseオブジェクトを含むIterable（例えば配列）を単一の引数として受け取ります。そして、引数に渡されたPromise群の中から、最初に解決（成功）または拒否（失敗）されたPromiseの結果を、自身の解決または拒ちの結果として返します。つまり、最も早く完了したPromiseの値やエラーが、Promise.raceが返すPromiseの値やエラーとなります。

たとえば、複数のAPIにリクエストを送り、一番最初にレスポンスを返してきたものだけを使いたい場合や、処理に時間制限（タイムアウト）を設けたい場合に非常に有用です。他のPromiseがまだ保留（ペンディング）状態であったり、後から完了したりしても、最初に完了したPromiseの結果が採用されるため、残りのPromiseの結果は無視される特性があります。

ただし、引数として空のIterableを渡した場合、このメソッドが返すPromiseは永遠に解決も拒否もされず、常に保留状態のままになる点に注意が必要です。これにより、アプリケーションが意図せず停止する可能性があるため、引数には少なくとも一つのPromiseが含まれるようにすることが推奨されます。

Promise.race([
  new Promise(resolve => setTimeout(() => resolve('一つ目のPromise'), 100)),
  new Promise(resolve => setTimeout(() => resolve('二つ目のPromise'), 50)),
  new Promise(resolve => setTimeout(() => resolve('三つ目のPromise'), 200))
]).then(value => {
  console.log(value);
});

iterable

• iterable: Promiseインスタンス、またはPromiseに解決する可能性のある値のコレクション。このコレクション内のいずれかのPromiseが最初に解決または拒否された結果（値またはエラー）を返します。

Promise

raceメソッドは、引数として渡されたPromiseのうち、最初にsettle（fulfilledまたはrejected）したPromiseの結果を反映した新しいPromiseを返します。