Join egghead, unlock knowledge.

Want more egghead?

This lesson is for members. Join us? Get access to all 3,000+ tutorials + a community with expert developers around the world.

Unlock This Lesson

Already subscribed? Sign In


    Wait for the Fastest JavaScript Promise to Settle with Promise.race()

    Marius SchulzMarius Schulz

    The Promise.race() method accepts an array (or any other iterable) of promises as a parameter. It returns a Promise object that is fulfilled or rejected once the first input promise is fulfilled or rejected:

    • As soon as any input promise is fulfilled, the returned Promise object is fulfilled with that value.
    • As soon as any input promise is rejected, the returned Promise object is rejected with that reason.

    Promise.race() can be used to race multiple promises against each other and find the first promise to settle.



    Become a Member to view code

    You must be a Member to view code

    Access all courses and lessons, track your progress, gain confidence and expertise.

    Become a Member
    and unlock code for this lesson


    Instructor: 00:00 Let's take a look at the promise.race method, but before we do that, we need a little bit of set up. I'm going to create a function called resolve after that accepts a number of milliseconds and a value. This function returns a new promise that is resolved with the given value after the given number milliseconds.

    00:21 We can now create two promises for testing. Promise A resolves after one second and promise B resolves after two seconds. Now, we can race those two promises against each other using that promise.race method.

    00:36 Promise.race returns a promise itself, which is set out the same way as the first input promise that settles, but differently as soon as any of the input promises resolves or rejects, the promise return by promise.race is resolved or rejected accordingly.

    00:52 The promise.race method will return the fastest of the input promises if you will. Also, if you pass an empty array, or any other empty attribute, the return promise will forever be pending. Let's attach a fulfillment handler to this promise and see promise.race in action.

    01:13 Let's pull up the console and run this program. After one second, we can see that A is the faster promise. If we go back in here and resolve B after 500 milliseconds, run this again, we can now see that promise B is settled first.

    01:33 All right. Now that, you've seen how promise.race works, let's go ahead and build something slightly more useful. In practice, I don't find myself using promise.race very often, but I have used it to implement a timeout function, so that is exactly what we're going to do.

    01:48 The timeout function will receive a number of milliseconds and a promise that we want to timeout. Within the body of the timeout function, we're going to create a timeout promise.

    01:58 This promise is automatically going to be rejected after the given number of milliseconds. Within the executive function, I'm going to set a timeout and I'm going to reject the promise with an error saying that the operation timed out after this many milliseconds.

    02:18 Notice that we don't need the resolve parameter here, which is why I've named it underscore. This is not special JavaScript syntax. It's just the naming convention. We can now call promise.race to race our actual promise against the timeout promise. That is what we're going to be returning from the function.

    02:36 The idea here is that, if our timeout promise is the promise that settles first, we're going to return a rejected promise from the timeout function. If that's not the case, this promise will settle first, so we didn't run into the timeout.

    02:51 Here is how we would use the timeout function. Let's create a promise again that is resolved after one second. We're going to say it resolve after 1,000 milliseconds with the value A. Then, I'm going to call timeout, pass it 500 milliseconds and our promise.

    03:07 I'm also going to attach fulfillment and rejection handlers, so we can see what is happening. This is the fulfillment handler and for the rejection handler we're going to call console.error, and we're going to log the error message.

    03:21 Let's give this a go, and sure enough we can see the timeout message. Let's now set a five second timeout and run this again. We see the value A log to the console. However, you might have noticed that the process was running for a quite a bit of time.

    03:43 Let's execute the program one more time. At this time, I want to track the number of seconds that the process is running. As you can see, the process was running for just over five seconds. This is because we've been calling setTimeout with a delay of 5,000 milliseconds.

    04:05 Therefore, node doesn't terminate the process until this callback has been run. We can fix this by properly clearing the timeout. We're going to just store the timeout ID in a local variable.

    04:17 Then, we're going to use the finally method to clear the timeout once the promise has been settled. Let's run this one last time. Now, we can see that the process only runs for roughly a second.