How to Use Promise.race in JavaScript: Complete Guide

const winner = await Promise.race([
  new Promise((resolve) => setTimeout(() => resolve("slow"), 500)),
  new Promise((resolve) => setTimeout(() => resolve("fast"), 100)),
  new Promise((resolve) => setTimeout(() => resolve("medium"), 300)),
]);
 
console.log(winner); // "fast" — settled at 100ms

const result = await Promise.race([
  new Promise((_, reject) => setTimeout(() => reject(new Error("fast fail")), 100)),
  new Promise((resolve) => setTimeout(() => resolve("slow success"), 500)),
]).catch((err) => `Caught: ${err.message}`);
 
console.log(result); // "Caught: fast fail"

function withTimeout(promise, ms, label = "Operation") {
  const timeout = new Promise((_, reject) =>
    setTimeout(
      () => reject(new Error(`${label} timed out after ${ms}ms`)),
      ms
    )
  );
  return Promise.race([promise, timeout]);
}
 
// Usage
async function loadUserWithTimeout(userId) {
  try {
    const user = await withTimeout(fetchUser(userId), 3000, "fetchUser");
    return user;
  } catch (err) {
    if (err.message.includes("timed out")) {
      console.warn(err.message);
      return cachedUser(userId) || null;
    }
    throw err; // Non-timeout error: re-throw
  }
}

class TimeoutError extends Error {
  constructor(ms, label) {
    super(`${label} timed out after ${ms}ms`);
    this.name = "TimeoutError";
    this.ms = ms;
  }
}
 
function withTimeout(promise, ms, label = "Operation") {
  let timer;
  const timeout = new Promise((_, reject) => {
    timer = setTimeout(() => reject(new TimeoutError(ms, label)), ms);
  });
 
  // Clean up the timer if the main promise wins
  return Promise.race([
    promise.finally(() => clearTimeout(timer)),
    timeout,
  ]);
}
 
// Check by type:
try {
  const data = await withTimeout(fetchData(url), 5000, "fetchData");
} catch (err) {
  if (err instanceof TimeoutError) {
    showStaleData();
  } else {
    showError(err);
  }
}

async function fetchFromFastest(path) {
  const endpoints = [
    "https://us.api.example.com",
    "https://eu.api.example.com",
    "https://ap.api.example.com",
  ];
 
  return Promise.race(
    endpoints.map((base) =>
      fetch(`${base}${path}`).then((res) => {
        if (!res.ok) throw new Error(`${base}: HTTP ${res.status}`);
        return res.json();
      })
    )
  );
}

async function fetchWithTimeoutAndCancel(url, ms) {
  const controller = new AbortController();
  const { signal } = controller;
 
  const fetchPromise = fetch(url, { signal }).then((r) => r.json());
 
  const timeoutPromise = new Promise((_, reject) =>
    setTimeout(() => {
      controller.abort(); // Cancel the fetch
      reject(new TimeoutError(ms, url));
    }, ms)
  );
 
  try {
    return await Promise.race([fetchPromise, timeoutPromise]);
  } catch (err) {
    if (err.name === "AbortError") {
      throw new TimeoutError(ms, url); // Normalize the abort error
    }
    throw err;
  }
}

async function loadWithDelayedSpinner(fetchFn, spinnerDelay = 200) {
  let spinnerTimeout;
  let spinnerShown = false;
 
  const spinnerPromise = new Promise((resolve) => {
    spinnerTimeout = setTimeout(() => {
      showSpinner();
      spinnerShown = true;
      resolve();
    }, spinnerDelay);
  });
 
  try {
    // Race the fetch with the spinner timer
    const result = await Promise.race([
      fetchFn().then((data) => ({ type: "data", data })),
      spinnerPromise.then(() => ({ type: "spinner" })),
    ]);
 
    if (result.type === "spinner") {
      // Spinner shown, wait for the actual data
      const data = await fetchFn(); // Not ideal — see note below
      return data;
    }
 
    clearTimeout(spinnerTimeout);
    return result.data;
  } finally {
    if (spinnerShown) hideSpinner();
  }
}
 
// Better approach: run fetch independently, race just determines spinner
async function loadWithDelayedSpinnerV2(fetchFn, spinnerDelay = 200) {
  const dataPromise = fetchFn();
  const spinnerTimer = setTimeout(() => showSpinner(), spinnerDelay);
 
  try {
    const data = await dataPromise;
    return data;
  } finally {
    clearTimeout(spinnerTimer);
    hideSpinner();
  }
}

// race: a rejection at 100ms beats a fulfillment at 200ms
const r = await Promise.race([
  delay(100).then(() => Promise.reject("fast error")),
  delay(200).then(() => "slow success"),
]).catch((e) => e);
console.log(r); // "fast error"
 
// any: skips the rejection, waits for first success
const a = await Promise.any([
  delay(100).then(() => Promise.reject("fast error")),
  delay(200).then(() => "slow success"),
]);
console.log(a); // "slow success"

// Empty iterable: pending forever
Promise.race([]); // Never settles — avoid this
 
// Already-settled Promises: settles synchronously (in next microtask)
const p = await Promise.race([Promise.resolve(1), Promise.resolve(2)]);
console.log(p); // 1 — order determines winner for already-resolved
 
// Non-Promise values: treated as already-resolved
const v = await Promise.race([42, fetchData()]);
console.log(v); // 42 — plain value wins immediately