Promise

`Promise.race`

Takes an iterable of promises and returns a promise that settles with the eventual state of the first promise that settles

Syntax

JavaScript

Promise.race(iterable)

Parameters

Parameter	Type	Description
iterable	Iterable<Promise<T>>	An iterable of promises

Return Value

A Promise that settles with the first settled value or reason

Examples

Basic Usage

const p1 = new Promise(r => setTimeout(() => r('slow'), 500));
const p2 = new Promise(r => setTimeout(() => r('fast'), 100));
const result = await Promise.race([p1, p2]);
console.log(result); // 'fast'

Practical Example

function timeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  const timer = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error('Timeout')), ms)
  );
  return Promise.race([promise, timer]);
}

Advanced Usage

const controller = new AbortController();
const fetchP = fetch('/api', { signal: controller.signal });
const result = await Promise.race([
  fetchP,
  new Promise(r => setTimeout(r, 5000)),
]);

Understanding Promise.race

The Promise.race method in JavaScript takes an iterable of promises and returns a promise that settles with the eventual state of the first promise that settles. It belongs to the Promise object and is one of the most widely used methods for working with promise values in modern JavaScript and TypeScript applications.

The method signature is Promise.race(iterable). It accepts 1 parameter: iterable. When called, it returns a promise that settles with the first settled value or reason. Understanding when and how to use race() helps you write more expressive, readable code.

Common use cases for Promise.race include data transformation, input validation, API response processing, and building reusable utility functions. It works well alongside related methods like promise-any, promise-all, promise-allsettled, enabling you to chain operations together for complex data manipulation pipelines.

Browser support for Promise.race is excellent across all modern browsers including Chrome, Firefox, Safari, and Edge. It is also fully supported in Node.js and Deno. For older environments, transpilation with Babel or a polyfill may be needed.

Browser Compatibility

Supported in all modern browsers (Chrome, Firefox, Safari, Edge) and Node.js. Part of the ECMAScript standard.

Related Methods

Promise.any

Takes an iterable of promises and returns a promise that resolves as soon as any of the promises fulfills, with the value of the first fulfilled promise

Promise.all

Takes an iterable of promises and returns a single promise that resolves when all of the input promises have resolved, or rejects when any input promise rejects

Promise.allSettled

Takes an iterable of promises and returns a promise that resolves after all promises have settled (fulfilled or rejected)