Promise.race Polyfill in Javascript - Detailed Explanation

Table of Content

1. How does Promise.race work in javascript?
   • Examples
   • Expected Functionality for Custom Promise.race Implementation
2. Promise.race Polyfill in Javascript - Detailed Explanation

# How does Promise.race work in JavaScript?

Promise.race takes the iterable (such as array) of promises, and returns the first settled promise, here settled promise can be resolved or rejected. As name "race" suggested, whichever promise settled first will be returned by Promise.race() method.

Examples

Example 1: First settled promise: Rejected

In the below example the P3 promise rejected in the minimum time 50ms, that's why it get rejected before the other 2 promises and race will return the first settled (either resolved or rejected) promise.

// First settled promise - rejected
const p1 = new Promise((resolve) => setTimeout(() => resolve("P1 resolved"), 100));
const p2 = new Promise((resolve) => setTimeout(() => resolve("P2 resolved"), 200));
const p3 = new Promise((resolve, reject) => setTimeout(() => reject("P3 rejected"), 50));

Promise.race([p1, p2, p3])
    .then((value) => console.log(`Fulfilled: ${value}`)) 
    .catch((error) => console.log(`Error: ${error}`));


// Output
"Error: P3 rejected"

Example 2: First settled promise - Resolved

In the below example the P1 promise resolves in the minimum time 100ms, that's why it resolves before the other 2 promises and race will return the first settled (either resolved or rejected) promise.

// First settled promise - Resolved
const p1 = new Promise((resolve) => setTimeout(() => resolve("P1 resolved"), 100));
const p2 = new Promise((resolve) => setTimeout(() => resolve("P2 resolved"), 200));
const p3 = new Promise((resolve, reject) => setTimeout(() => reject("P3 rejected"), 150));

Promise.race([p1, p2, p3])
    .then((value) => console.log(`Fulfilled: ${value}`)) 
    .catch((error) => console.log(`Error: ${error}`));


// Output
"Fulfilled: P1 resolved"

Expected Functionality for Custom Promise.race Implementation

Before understanding the custom implementation of Promise.race(), its important to understand the scenarios which Promise.race() needs to fulfill

1. First settled promise should be retuned (Resolved or Rejected)

// Promise resolved fist
const p1 = new Promise((resolve) => setTimeout(() => resolve("P1 resolved"), 50));
const p2 = new Promise((resolve) => setTimeout(() => resolve("P2 resolved"), 100));
Promise.race([p1, p2]).then(console.log); // Output: "P1 resolved"

// Promise rejected first
const p3 = new Promise((resolve, reject) => setTimeout(() => resolve("P3 rejected"), 50));
const p4 = new Promise((resolve) => setTimeout(() => resolve("P4 resolved"), 100));
Promise.race([p3, p4]).then(console.log); // Output: "P3 rejected"

2. Non-promise values should resolved immediately

If iterable contains any non-promise values (example - 45, 'Apple'), then these non-promise values should resolved immediately.

const p1 = new Promise((resolve) => setTimeout(() => resolve("P1 resolved"), 50));

Promise.race([42, p1]).then(console.log); // Output: 42

3. Immediate rejecting promise, will caught first

In case, if immediate rejecting promise (Promise.reject) passed It will caught first by Promise.race()

const p1 = new Promise((resolve) => setTimeout(() => resolve("P1 resolved"), 50));
const pImmediateReject = Promise.reject("Immediate rejection");

Promise.race([p1, pImmediateReject]).catch(console.log); 
// Output: "Immediate rejection"


const p2 = new Promise((resolve, reject) => setTimeout(() => reject("P2 reject"), 50));

Promise.race([pImmediateReject, p2]).catch(console.log); 
// Output: "Immediate rejection"

4. Throw error in case of invalid input

If an input is not iterable, it should throw a TypeError.

Promise.race(45)
  .then((value) => console.log(value))
  .catch((error) => console.log(error)); 

// TypeError: number 45 is not iterable (cannot read property Symbol(Symbol.iterator))

5. In case of Empty array

In case of Empty array, the return promise from Promise.race() will never settled.

Promise.race([])
  .then((value) => console.log(value))
  .catch((error) => console.log(error)); 

// Output: Returned promise never settled to return any value or error

# Promise.race Polyfill in Javascript - Detailed Explanation

Step 1: Create a custom function which takes an iterable of promises.

Step 2: It returns a new Promise that resolves or rejects as soon as one of the promises in the iterable settles (resolves or rejects).

Step 3: In this step, Loop over the iterable of Promises, and wrapped each promise in Promise.resolve() to handle non-promise values.

First settled promise's result is used to settle the returned promise.

Promise.race Polyfill Implementation Code

function customRace(promises) {
    return new Promise((resolve, reject) => {
        if (!Array.isArray(promises)) {
            return reject(new TypeError("Argument must be an iterable"));
        }

        for (const promise of promises) {
            Promise.resolve(promise).then(resolve, reject);
        }
    });
}

⏩Learn Next

1. Notes to Master Promise Methods in JavaScript: all(), allSettled(), race() and any()
2. Promise Polyfill in JavaScript - Step by Step Explanation
3. Promise.all Polyfill in JavaScript - Detailed Explanation [For Interviews]
4. Promise.allSettled Polyfill in JavaScript - Step by Step Explanation