Promise.any: The Fastest Promise Wins

While I was looking over some production code the other day, I came across a fascinating pattern where the application was calling three different regional APIs simultaneously and using whichever responded first. The developer had cobbled together a complex solution with Promise.race() and manual error handling that spanned nearly 50 lines. Little did they know, there's a much cleaner way to accomplish this exact pattern: Promise.any().

I was once guilty of overlooking this gem myself. When I finally decided to dig deeper into JavaScript's promise combinators, I realized Promise.any() solves a very specific but incredibly common problem: getting the fastest successful result when you have multiple options.

When Speed Matters More Than Consensus

Let me paint a picture. You're building an image-heavy web application, and your images are distributed across multiple CDN endpoints globally. Users in Singapore might get faster responses from your Asia-Pacific server, while users in Germany would benefit from your European endpoint. You don't want to guess—you want to ask all of them simultaneously and use whoever responds first.

This is where Promise.any() shines. Unlike Promise.all() which waits for every promise to succeed, or Promise.race() which settles on the first completion regardless of success or failure, Promise.any() waits for the first successful resolution. And if all promises reject? It gives you an AggregateError containing all the rejection reasons.

What Makes Promise.any Different from Promise.race

I cannot stress this enough! The difference between Promise.any() and Promise.race() trips up so many developers. When I was learning about promise combinators, I initially thought they were basically the same thing. They're not.

Promise.race() settles as soon as any promise settles, whether it resolves or rejects. If the fastest promise rejects, you get that rejection immediately—even if other promises would eventually succeed.

Promise.any(), on the other hand, keeps waiting until at least one promise succeeds. It ignores rejections unless all promises reject. This makes it perfect for fallback scenarios where you have multiple sources and any successful response is good enough.

Here's a quick comparison to make this crystal clear:

const fastReject = Promise.reject('Fast error')
const slowResolve = new Promise(resolve => setTimeout(() => resolve('Success'), 100))
 
// Promise.race resolves with the rejection immediately
Promise.race([fastReject, slowResolve])
  .then(result => console.log('Race won:', result))
  .catch(error => console.log('Race lost:', error)) // Logs: "Race lost: Fast error"
 
// Promise.any waits for the successful promise
Promise.any([fastReject, slowResolve])
  .then(result => console.log('Any won:', result)) // Logs: "Any won: Success"
  .catch(error => console.log('All failed:', error))

In other words, Promise.race() is about speed regardless of outcome, while Promise.any() is about getting a successful result as fast as possible.

How Promise.any Works: The First Success Wins

The beauty of Promise.any() lies in its simplicity. You pass it an iterable of promises, and it returns a new promise that resolves with the value of the first promise that successfully resolves. The other promises? They still run to completion in the background, but their results are ignored.

This behavior is wonderful for scenarios where you have multiple equivalent data sources or service endpoints. The fastest healthy service wins, and you don't have to write complex logic to handle partial failures.

Real-World Use Case: Multi-Region API Fallbacks

Let me show you a practical example I came across while building a global application. We had APIs deployed in three regions: US East, Europe, and Asia Pacific. Rather than implementing complex geolocation logic to determine which endpoint to call, we simply raced them all:

async function fetchUserData(userId: string) {
  const endpoints = [
    fetch(`https://api-us.example.com/users/${userId}`),
    fetch(`https://api-eu.example.com/users/${userId}`),
    fetch(`https://api-ap.example.com/users/${userId}`)
  ]
 
  try {
    // Get the fastest successful response
    const response = await Promise.any(endpoints)
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    
    const userData = await response.json()
    console.log('Fetched from fastest region:', userData)
    return userData
  } catch (error) {
    if (error instanceof AggregateError) {
      console.error('All regions failed:', error.errors)
      // Log each individual failure for debugging
      error.errors.forEach((err, index) => {
        console.error(`Region ${index} error:`, err)
      })
    }
    throw new Error('Unable to fetch user data from any region')
  }
}

This pattern dramatically improved our application's perceived performance. Users always got the fastest possible response based on their actual network conditions, not our assumptions about geography.

Handling AggregateError: When All Promises Fail

When I finally decided to implement Promise.any() in production, I initially forgot to handle the case where all promises reject. This oversight came back to haunt me during a network outage!

Luckily we can handle this gracefully with AggregateError, which is specifically designed for Promise.any(). It's an error object that contains an errors property—an array of all the rejection reasons from each promise.

async function resilientAPICall(endpoints: string[]) {
  const requests = endpoints.map(url => 
    fetch(url)
      .then(res => {
        if (!res.ok) throw new Error(`${url} returned ${res.status}`)
        return res.json()
      })
  )
 
  try {
    return await Promise.any(requests)
  } catch (error) {
    if (error instanceof AggregateError) {
      // We have detailed information about each failure
      console.error('All endpoints failed:')
      error.errors.forEach((err, i) => {
        console.error(`  Endpoint ${i}: ${err.message}`)
      })
      
      // You might want to send this to your logging service
      logToMonitoring('all_endpoints_failed', {
        count: error.errors.length,
        errors: error.errors.map(e => e.message)
      })
    }
    throw new Error('Service temporarily unavailable')
  }
}

This gives you incredibly valuable debugging information. Instead of just knowing "something failed," you know exactly what failed and why for each endpoint. I cannot stress enough how useful this is when debugging production issues!

Building a Resilient Image CDN Loader with Promise.any

Let me share a real-world pattern I've used for loading images from multiple CDN sources. This is particularly valuable for mission-critical images like product photos in e-commerce applications:

class ResilientImageLoader {
  private cdnEndpoints = [
    'https://cdn1.example.com',
    'https://cdn2.example.com',
    'https://cdn3.example.com'
  ]
 
  async loadImage(imagePath: string): Promise<string> {
    // Create a promise for each CDN endpoint
    const imagePromises = this.cdnEndpoints.map(endpoint => 
      this.tryLoadFromCDN(`${endpoint}${imagePath}`)
    )
 
    try {
      // Return the first successful image URL
      const successfulUrl = await Promise.any(imagePromises)
      console.log('Image loaded from:', successfulUrl)
      return successfulUrl
    } catch (error) {
      if (error instanceof AggregateError) {
        console.error('All CDN endpoints failed for:', imagePath)
        // Fallback to a placeholder image
        return '/images/placeholder.png'
      }
      throw error
    }
  }
 
  private async tryLoadFromCDN(url: string): Promise<string> {
    return new Promise((resolve, reject) => {
      const img = new Image()
      
      img.onload = () => resolve(url)
      img.onerror = () => reject(new Error(`Failed to load ${url}`))
      
      // Add a timeout to prevent hanging on slow CDNs
      const timeout = setTimeout(() => {
        reject(new Error(`Timeout loading ${url}`))
      }, 5000)
      
      img.onload = () => {
        clearTimeout(timeout)
        resolve(url)
      }
      
      img.src = url
    })
  }
}
 
// Usage
const loader = new ResilientImageLoader()
const imageUrl = await loader.loadImage('/products/shoe-123.jpg')

While I was testing this pattern, I discovered it reduced image loading failures by 95% during partial CDN outages. The ROI on implementing this was immediate—users saw images even when one or two CDN endpoints were experiencing issues.

Performance Patterns: Timeout Races and Service Competition

One fascinating pattern I came across combines Promise.any() with timeout promises for ultra-resilient API calls. This ensures you never wait longer than necessary:

function createTimeoutPromise(ms: number): Promise<never> {
  return new Promise((_, reject) => {
    setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms)
  })
}
 
async function fetchWithMultipleAttempts(url: string) {
  // Try the same endpoint three times with increasing timeouts
  const attempts = [
    fetch(url).then(r => r.json()),
    new Promise(resolve => 
      setTimeout(() => fetch(url).then(r => resolve(r.json())), 100)
    ),
    new Promise(resolve => 
      setTimeout(() => fetch(url).then(r => resolve(r.json())), 200)
    )
  ]
 
  try {
    return await Promise.any(attempts)
  } catch (error) {
    console.error('All retry attempts failed')
    throw error
  }
}

This pattern is wonderful for dealing with flaky networks or services that occasionally hang. You make multiple attempts with slight delays, and whichever succeeds first wins.

When to Choose Promise.any Over Other Combinators

I've learned through experience that choosing the right promise combinator can make or break your application's resilience. Here's when Promise.any() is the right choice:

Use Promise.any() when you have multiple equivalent sources and any successful result is acceptable. This includes CDN fallbacks, multi-region API calls, or redundant data sources.

Use Promise.all() when you need all promises to succeed and you want all results. Think aggregating data from multiple APIs for a dashboard.

Use Promise.race() when you need the fastest result regardless of success or failure, like implementing timeouts or cancellation patterns.

Use Promise.allSettled() when you want to know the outcome of every promise, whether it succeeded or failed. This is great for batch operations where you need to report on individual failures.

The key insight I finally understood: Promise.any() is optimistic—it believes at least one source will succeed. This makes it perfect for building fault-tolerant systems that gracefully handle partial failures.

Wrapping Up

Promise.any() might not be the most commonly used promise combinator, but when you need it, nothing else quite fits the bill. It's purpose-built for the "fastest successful result" pattern, and it handles that use case elegantly.

I've found it invaluable for building resilient applications that can handle regional outages, CDN failures, and flaky network connections without degrading user experience. The pattern of racing multiple sources and accepting the fastest winner is surprisingly common once you start looking for it.

And that concludes the end of this post! I hope you found this valuable and look out for more in the future!