🏁 Promise.race: First to Complete in TypeScript

🎯 Introduction

Welcome to the thrilling world of Promise racing! 🏁 Imagine having multiple racers competing to bring you data - API endpoints, database queries, or file operations all racing to the finish line. Promise.race() lets you work with whichever promise crosses the finish line first!

Whether you’re implementing timeout patterns ⏰, building fallback systems 🛡️, or optimizing for the fastest response time 🚀, Promise.race is your go-to tool for competitive async operations.

By the end of this tutorial, you’ll be a Promise racing champion, able to orchestrate complex async scenarios where speed and resilience matter most. Let’s start your engines! 🏎️

📚 Understanding Promise.race()

🤔 What is Promise.race()?

Think of Promise.race() as a sprint competition 🏃‍♂️🏃‍♀️. You line up several runners (promises), fire the starting gun, and whoever finishes first wins the entire race - regardless of what happens to the other runners!

// 🏁 Basic Promise.race example
const fastPromise = new Promise<string>((resolve) => {
  setTimeout(() => resolve("I'm fast! 🚀"), 100);
});

const slowPromise = new Promise<string>((resolve) => {
  setTimeout(() => resolve("I'm slow... 🐌"), 1000);
});

// 🏆 Race them - fastest wins!
const winner = await Promise.race([fastPromise, slowPromise]);
console.log(winner); // "I'm fast! 🚀" (after ~100ms)

💡 Key Characteristics

• 🥇 First Wins All: The first settled promise (resolved OR rejected) determines the outcome
• 🎯 Type Safety: TypeScript preserves union types across all competing promises
• ⚡ Immediate: Returns as soon as ANY promise settles
• 🏃‍♂️ No Waiting: Doesn’t wait for slower promises to complete

// 🎨 TypeScript's type inference with Promise.race
const raceTypes = Promise.race([
  Promise.resolve("string result"), // Promise<string>
  Promise.resolve(42),              // Promise<number>
  Promise.resolve(true)             // Promise<boolean>
]); // Type: Promise<string | number | boolean>

🔧 Basic Syntax and Usage

📝 Simple Racing Examples

Let’s explore the fundamentals:

// 🎮 Gaming scenario: Multiple save locations
interface SaveData {
  playerId: string;
  level: number;
  score: number;
  timestamp: Date;
}

class GameSaveService {
  
  // 💾 Save to local storage (fast)
  private saveToLocal(data: SaveData): Promise<string> {
    return new Promise((resolve) => {
      setTimeout(() => {
        localStorage.setItem('gameData', JSON.stringify(data));
        resolve("✅ Saved locally!");
      }, 50); // Very fast
    });
  }
  
  // ☁️ Save to cloud (slower but persistent)
  private saveToCloud(data: SaveData): Promise<string> {
    return new Promise((resolve) => {
      setTimeout(() => {
        // Simulate cloud API call
        resolve("☁️ Saved to cloud!");
      }, 300); // Slower
    });
  }
  
  // 🎯 Save wherever is fastest!
  async quickSave(data: SaveData): Promise<string> {
    console.log("🏁 Starting save race...");
    
    const localSave = this.saveToLocal(data);
    const cloudSave = this.saveToCloud(data);
    
    // 🏆 Race them - first one wins!
    const result = await Promise.race([localSave, cloudSave]);
    console.log(`🎉 Winner: ${result}`);
    
    return result; // TypeScript knows this is string
  }
}

// 🎮 Using the game save service
async function demonstrateGameSave() {
  const saveService = new GameSaveService();
  
  const gameData: SaveData = {
    playerId: "player123",
    level: 42,
    score: 98765,
    timestamp: new Date()
  };
  
  const winner = await saveService.quickSave(gameData);
  console.log(`🏆 Save completed: ${winner}`);
}

🎯 Timeout Patterns

One of the most common uses of Promise.race is implementing timeouts:

// ⏰ Timeout utility function
function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
  const timeoutPromise = new Promise<never>((_, reject) => {
    setTimeout(() => {
      reject(new Error(`⏰ Operation timed out after ${timeoutMs}ms`));
    }, timeoutMs);
  });
  
  return Promise.race([promise, timeoutPromise]);
}

// 🌐 API service with timeout protection
class APIService {
  
  // 📡 Fetch user data with timeout
  async fetchUserWithTimeout(userId: string): Promise<{ name: string; email: string }> {
    const userPromise = fetch(`/api/users/${userId}`)
      .then(response => {
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        return response.json();
      });
    
    // 🏁 Race against timeout
    return withTimeout(userPromise, 5000); // 5 second timeout
  }
  
  // 🔄 Multiple endpoints race
  async getFastestUserData(userId: string): Promise<any> {
    const endpoints = [
      `/api/v1/users/${userId}`,    // Old API
      `/api/v2/users/${userId}`,    // New API
      `/cdn/users/${userId}.json`   // CDN cache
    ];
    
    const promises = endpoints.map(endpoint => 
      fetch(endpoint).then(res => res.json())
    );
    
    // 🏆 First successful response wins
    return Promise.race(promises);
  }
}

💡 Practical Examples

🛒 Example 1: Smart Shopping Price Checker

Let’s build a price comparison service that gets the fastest price quote:

// 🏪 Store and pricing interfaces
interface Product {
  id: string;
  name: string;
  emoji: string;
}

interface PriceQuote {
  store: string;
  price: number;
  availability: boolean;
  shippingTime: string;
  storeEmoji: string;
}

interface PriceComparisonResult {
  fastestQuote: PriceQuote;
  allQuotes?: PriceQuote[];
  responseTime: number;
}

class PriceComparison {
  
  // 🛍️ Get quote from Amazon (slow but reliable)
  private getAmazonPrice(product: Product): Promise<PriceQuote> {
    return new Promise((resolve) => {
      const delay = 800 + Math.random() * 400; // 800-1200ms
      setTimeout(() => {
        resolve({
          store: "Amazon",
          price: 29.99 + Math.random() * 10,
          availability: true,
          shippingTime: "2 days",
          storeEmoji: "📦"
        });
      }, delay);
    });
  }
  
  // 🎯 Get quote from Best Buy (medium speed)
  private getBestBuyPrice(product: Product): Promise<PriceQuote> {
    return new Promise((resolve) => {
      const delay = 400 + Math.random() * 300; // 400-700ms
      setTimeout(() => {
        resolve({
          store: "Best Buy",
          price: 32.99 + Math.random() * 8,
          availability: Math.random() > 0.2, // 80% chance available
          shippingTime: "3-5 days",
          storeEmoji: "🏪"
        });
      }, delay);
    });
  }
  
  // ⚡ Get quote from local store (fast)
  private getLocalPrice(product: Product): Promise<PriceQuote> {
    return new Promise((resolve) => {
      const delay = 150 + Math.random() * 200; // 150-350ms
      setTimeout(() => {
        resolve({
          store: "Local Store",
          price: 35.99 + Math.random() * 5,
          availability: Math.random() > 0.3, // 70% chance available
          shippingTime: "Same day",
          storeEmoji: "🏬"
        });
      }, delay);
    });
  }
  
  // 🏁 Get fastest price quote
  async getFastestPrice(product: Product): Promise<PriceComparisonResult> {
    console.log(`🔍 Searching for best price on ${product.emoji} ${product.name}...`);
    const startTime = Date.now();
    
    const amazonQuote = this.getAmazonPrice(product);
    const bestBuyQuote = this.getBestBuyPrice(product);
    const localQuote = this.getLocalPrice(product);
    
    try {
      // 🏆 Race for the fastest quote
      const fastestQuote = await Promise.race([amazonQuote, bestBuyQuote, localQuote]);
      const responseTime = Date.now() - startTime;
      
      console.log(`⚡ Fastest response from ${fastestQuote.storeEmoji} ${fastestQuote.store} in ${responseTime}ms!`);
      
      return {
        fastestQuote,
        responseTime
      };
      
    } catch (error) {
      throw new Error(`💥 All price checks failed: ${error.message}`);
    }
  }
  
  // 🎯 Get fastest available product
  async getFastestAvailablePrice(product: Product): Promise<PriceComparisonResult> {
    console.log(`🎯 Finding fastest available price for ${product.emoji} ${product.name}...`);
    const startTime = Date.now();
    
    // 🔄 Keep racing until we find an available item
    const stores = [
      () => this.getAmazonPrice(product),
      () => this.getBestBuyPrice(product),
      () => this.getLocalPrice(product)
    ];
    
    for (let attempt = 0; attempt < 3; attempt++) {
      try {
        const promises = stores.map(storeFunc => storeFunc());
        const quote = await Promise.race(promises);
        
        if (quote.availability) {
          const responseTime = Date.now() - startTime;
          console.log(`✅ Found available item at ${quote.storeEmoji} ${quote.store}!`);
          return { fastestQuote: quote, responseTime };
        } else {
          console.log(`❌ ${quote.store} is out of stock, trying others...`);
        }
      } catch (error) {
        console.log(`🔄 Attempt ${attempt + 1} failed, retrying...`);
      }
    }
    
    throw new Error("😞 No stores have this item available");
  }
}

// 🎮 Demo the price comparison
async function demonstratePriceComparison() {
  const priceChecker = new PriceComparison();
  
  const product: Product = {
    id: "ts-book-001",
    name: "TypeScript Handbook",
    emoji: "📘"
  };
  
  try {
    // 🏁 Race for fastest price
    console.log("🚀 Starting price race...\n");
    const result = await priceChecker.getFastestPrice(product);
    
    console.log(`\n🏆 Winner: ${result.fastestQuote.storeEmoji} ${result.fastestQuote.store}`);
    console.log(`💰 Price: $${result.fastestQuote.price.toFixed(2)}`);
    console.log(`📦 Shipping: ${result.fastestQuote.shippingTime}`);
    console.log(`⚡ Response time: ${result.responseTime}ms\n`);
    
    // 🎯 Find fastest available
    const availableResult = await priceChecker.getFastestAvailablePrice(product);
    console.log(`\n✅ Fastest available option: ${availableResult.fastestQuote.storeEmoji} ${availableResult.fastestQuote.store}`);
    
  } catch (error) {
    console.error("💥 Price comparison failed:", error.message);
  }
}

🌟 Example 2: Multi-Server Health Check

Let’s create a system that checks which server responds fastest:

// 🖥️ Server and health check interfaces
interface ServerInfo {
  name: string;
  url: string;
  region: string;
  emoji: string;
}

interface HealthCheckResult {
  server: ServerInfo;
  status: "healthy" | "degraded" | "down";
  responseTime: number;
  timestamp: Date;
}

interface FastestServerResult {
  fastest: HealthCheckResult;
  allResults?: HealthCheckResult[];
  totalCheckTime: number;
}

class ServerHealthChecker {
  private servers: ServerInfo[] = [
    { name: "US East", url: "https://api-east.example.com", region: "us-east-1", emoji: "🇺🇸" },
    { name: "EU West", url: "https://api-eu.example.com", region: "eu-west-1", emoji: "🇪🇺" },
    { name: "Asia Pacific", url: "https://api-asia.example.com", region: "ap-southeast-1", emoji: "🌏" },
    { name: "Australia", url: "https://api-au.example.com", region: "ap-southeast-2", emoji: "🇦🇺" }
  ];
  
  // 🏥 Check single server health
  private async checkServerHealth(server: ServerInfo): Promise<HealthCheckResult> {
    const startTime = Date.now();
    
    try {
      // 🌐 Simulate health check (replace with real fetch in production)
      await new Promise((resolve, reject) => {
        const responseTime = 50 + Math.random() * 500; // 50-550ms
        const isHealthy = Math.random() > 0.1; // 90% success rate
        
        setTimeout(() => {
          if (isHealthy) {
            resolve(undefined);
          } else {
            reject(new Error("Server timeout"));
          }
        }, responseTime);
      });
      
      const responseTime = Date.now() - startTime;
      
      return {
        server,
        status: responseTime < 200 ? "healthy" : "degraded",
        responseTime,
        timestamp: new Date()
      };
      
    } catch (error) {
      return {
        server,
        status: "down",
        responseTime: Date.now() - startTime,
        timestamp: new Date()
      };
    }
  }
  
  // 🏁 Find fastest healthy server
  async getFastestHealthyServer(): Promise<FastestServerResult> {
    console.log("🔍 Checking server health across all regions...");
    const startTime = Date.now();
    
    // 🚀 Race all servers simultaneously
    const healthChecks = this.servers.map(server => this.checkServerHealth(server));
    
    try {
      // 🏆 First healthy server wins
      const fastest = await Promise.race(healthChecks);
      const totalCheckTime = Date.now() - startTime;
      
      if (fastest.status === "down") {
        throw new Error("Fastest server is down, checking others...");
      }
      
      console.log(`⚡ Fastest server: ${fastest.server.emoji} ${fastest.server.name} (${fastest.responseTime}ms)`);
      
      return {
        fastest,
        totalCheckTime
      };
      
    } catch (error) {
      console.log("🔄 First server failed, waiting for others...");
      
      // 🛡️ Fallback: wait for all results and pick best healthy one
      const allResults = await Promise.allSettled(healthChecks);
      const healthyServers = allResults
        .filter((result): result is PromiseFulfilledResult<HealthCheckResult> => 
          result.status === 'fulfilled' && result.value.status !== 'down'
        )
        .map(result => result.value)
        .sort((a, b) => a.responseTime - b.responseTime);
      
      if (healthyServers.length === 0) {
        throw new Error("😞 All servers are down!");
      }
      
      const fastest = healthyServers[0];
      const totalCheckTime = Date.now() - startTime;
      
      console.log(`🛡️ Fallback server: ${fastest.server.emoji} ${fastest.server.name}`);
      
      return {
        fastest,
        allResults: allResults.map(r => r.status === 'fulfilled' ? r.value : null).filter(Boolean) as HealthCheckResult[],
        totalCheckTime
      };
    }
  }
  
  // 📊 Get comprehensive health report
  async getHealthReport(): Promise<{ fastest: HealthCheckResult; all: HealthCheckResult[] }> {
    console.log("📊 Generating comprehensive health report...");
    
    const healthChecks = this.servers.map(server => this.checkServerHealth(server));
    
    // 🏁 Race for fastest + wait for all
    const [fastest, ...allResults] = await Promise.all([
      Promise.race(healthChecks),
      ...healthChecks
    ]);
    
    return { fastest, all: allResults };
  }
}

// 🎮 Demo the server health checker
async function demonstrateServerHealthCheck() {
  const healthChecker = new ServerHealthChecker();
  
  try {
    // 🏁 Find fastest server
    console.log("🚀 Racing servers for fastest response...\n");
    const result = await healthChecker.getFastestHealthyServer();
    
    console.log(`\n🏆 Fastest healthy server:`);
    console.log(`  ${result.fastest.server.emoji} ${result.fastest.server.name}`);
    console.log(`  📍 Region: ${result.fastest.server.region}`);
    console.log(`  ⚡ Response: ${result.fastest.responseTime}ms`);
    console.log(`  💚 Status: ${result.fastest.status}`);
    console.log(`  ⏱️ Total check time: ${result.totalCheckTime}ms\n`);
    
    // 📊 Get full report
    console.log("📊 Getting full health report...");
    const report = await healthChecker.getHealthReport();
    
    console.log(`\n📈 All server results:`);
    report.all.forEach(result => {
      const statusEmoji = result.status === 'healthy' ? '💚' : result.status === 'degraded' ? '💛' : '❤️';
      console.log(`  ${result.server.emoji} ${result.server.name}: ${statusEmoji} ${result.status} (${result.responseTime}ms)`);
    });
    
  } catch (error) {
    console.error("💥 Health check failed:", error.message);
  }
}

🚀 Advanced Concepts

🧙‍♂️ Competitive Loading with Fallbacks

Handle complex scenarios where you want the fastest result but need fallbacks:

// 🎯 Advanced race with intelligent fallbacks
class SmartDataLoader<T> {
  
  // 🏁 Race with fallback chain
  async loadWithFallbacks<T>(
    primary: () => Promise<T>,
    fallbacks: (() => Promise<T>)[],
    timeoutMs: number = 5000
  ): Promise<{ data: T; source: string; attemptCount: number }> {
    
    // 🎯 Try primary first
    try {
      const primaryPromise = primary();
      const timeoutPromise = new Promise<never>((_, reject) => {
        setTimeout(() => reject(new Error('Timeout')), timeoutMs);
      });
      
      const data = await Promise.race([primaryPromise, timeoutPromise]);
      return { data, source: 'primary', attemptCount: 1 };
      
    } catch (primaryError) {
      console.log("🔄 Primary failed, trying fallbacks...");
      
      // 🛡️ Race all fallbacks
      if (fallbacks.length === 0) {
        throw new Error("No fallbacks available");
      }
      
      for (let i = 0; i < fallbacks.length; i++) {
        try {
          const fallbackPromises = fallbacks.slice(i).map(fallback => fallback());
          const timeoutPromise = new Promise<never>((_, reject) => {
            setTimeout(() => reject(new Error('Fallback timeout')), timeoutMs);
          });
          
          const data = await Promise.race([...fallbackPromises, timeoutPromise]);
          return { data, source: `fallback-${i + 1}`, attemptCount: i + 2 };
          
        } catch (fallbackError) {
          console.log(`🔄 Fallback ${i + 1} failed...`);
          continue;
        }
      }
      
      throw new Error("All sources failed");
    }
  }
  
  // 🎮 Smart cache-first loading
  async smartLoad(
    cacheLoader: () => Promise<T>,
    networkLoader: () => Promise<T>,
    maxCacheAge: number = 60000 // 1 minute
  ): Promise<{ data: T; source: 'cache' | 'network'; fresh: boolean }> {
    
    const cachePromise = cacheLoader().then(data => ({ data, source: 'cache' as const }));
    const networkPromise = networkLoader().then(data => ({ data, source: 'network' as const }));
    
    try {
      // 🏁 Race cache vs network (cache usually wins)
      const result = await Promise.race([cachePromise, networkPromise]);
      
      if (result.source === 'cache') {
        // 🔍 Check if cache is fresh enough
        const cacheTimestamp = Date.now(); // In real app, get from cache metadata
        const isFresh = cacheTimestamp > Date.now() - maxCacheAge;
        
        if (isFresh) {
          console.log("⚡ Using fresh cache data");
          return { ...result, fresh: true };
        } else {
          console.log("🔄 Cache stale, waiting for network...");
          const networkResult = await networkPromise;
          return { ...networkResult, fresh: true };
        }
      }
      
      console.log("🌐 Using network data");
      return { ...result, fresh: true };
      
    } catch (error) {
      throw new Error(`Smart load failed: ${error.message}`);
    }
  }
}

// 🎮 Using smart data loader
async function demonstrateSmartLoader() {
  const loader = new SmartDataLoader<string>();
  
  // 📊 Example: Loading user profile with fallbacks
  const primaryLoader = () => 
    new Promise<string>((resolve, reject) => {
      setTimeout(() => {
        Math.random() > 0.7 ? resolve("Primary data 🎯") : reject(new Error("Primary failed"));
      }, 200);
    });
  
  const fallbackLoaders = [
    () => new Promise<string>((resolve) => 
      setTimeout(() => resolve("Fallback 1 data 🛡️"), 300)
    ),
    () => new Promise<string>((resolve) => 
      setTimeout(() => resolve("Fallback 2 data 🆘"), 400)
    )
  ];
  
  try {
    const result = await loader.loadWithFallbacks(primaryLoader, fallbackLoaders, 1000);
    console.log(`✅ Loaded from ${result.source} in ${result.attemptCount} attempts: ${result.data}`);
  } catch (error) {
    console.error("💥 All loading attempts failed:", error.message);
  }
}

🏗️ Race with Progress Tracking

Track which promises are still racing:

// 📊 Race with detailed progress tracking
class ProgressiveRace<T> {
  
  async raceWithProgress<T>(
    promises: Promise<T>[],
    onProgress?: (completed: number, total: number, result?: T) => void
  ): Promise<T> {
    
    return new Promise((resolve, reject) => {
      let completed = 0;
      let resolved = false;
      const total = promises.length;
      
      promises.forEach((promise, index) => {
        promise
          .then(result => {
            completed++;
            onProgress?.(completed, total, result);
            
            if (!resolved) {
              resolved = true;
              console.log(`🏆 Promise ${index + 1} won the race!`);
              resolve(result);
            }
          })
          .catch(error => {
            completed++;
            onProgress?.(completed, total);
            
            if (completed === total && !resolved) {
              reject(new Error("All promises failed"));
            }
          });
      });
    });
  }
}

// 🎮 Demo progressive race
async function demonstrateProgressiveRace() {
  const progressRace = new ProgressiveRace();
  
  const promises = [
    new Promise<string>(resolve => setTimeout(() => resolve("Result A 🅰️"), 800)),
    new Promise<string>(resolve => setTimeout(() => resolve("Result B 🅱️"), 300)),
    new Promise<string>(resolve => setTimeout(() => resolve("Result C 🆘"), 1200))
  ];
  
  console.log("🏁 Starting progressive race...");
  
  try {
    const winner = await progressRace.raceWithProgress(
      promises,
      (completed, total, result) => {
        if (result) {
          console.log(`🎯 First result: ${result}`);
        }
        console.log(`📊 Progress: ${completed}/${total} promises completed`);
      }
    );
    
    console.log(`🎉 Final winner: ${winner}`);
  } catch (error) {
    console.error("💥 Race failed:", error.message);
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Ignoring Rejected Promises

// ❌ Dangerous - race can reject immediately!
async function badRace() {
  const promises = [
    Promise.reject(new Error("I fail fast! 💥")),     // Rejects immediately
    Promise.resolve("I'm slow but successful 🐌")     // Resolves later
  ];
  
  // 💥 This will throw immediately!
  return Promise.race(promises);
}

// ✅ Safe - handle rejections properly
async function safeRace() {
  const promises = [
    Promise.reject(new Error("I fail fast! 💥")).catch(() => null),
    Promise.resolve("I'm slow but successful 🐌")
  ];
  
  const result = await Promise.race(promises);
  return result || "No successful result";
}

// ✅ Even better - filter failed promises
async function smartRace<T>(promises: Promise<T>[]): Promise<T> {
  const wrappedPromises = promises.map(async (promise, index) => {
    try {
      const result = await promise;
      return { success: true, result, index };
    } catch (error) {
      return { success: false, error, index };
    }
  });
  
  const firstResult = await Promise.race(wrappedPromises);
  
  if (firstResult.success) {
    return firstResult.result;
  } else {
    throw new Error(`Promise ${firstResult.index} failed: ${firstResult.error.message}`);
  }
}

🤯 Pitfall 2: Memory Leaks with Unfinished Promises

// ❌ Potential memory leak - other promises keep running
async function leakyRace() {
  const promises = [
    fetch('/fast-api'),           // Finishes first
    fetch('/slow-api'),           // Still running in background!
    fetch('/very-slow-api')       // Still running in background!
  ];
  
  return Promise.race(promises); // Other fetches continue consuming resources
}

// ✅ Clean up with AbortController
async function cleanRace() {
  const controller = new AbortController();
  
  const promises = [
    fetch('/fast-api', { signal: controller.signal }),
    fetch('/slow-api', { signal: controller.signal }),
    fetch('/very-slow-api', { signal: controller.signal })
  ];
  
  try {
    const result = await Promise.race(promises);
    controller.abort(); // 🧹 Cancel other requests
    return result;
  } catch (error) {
    controller.abort(); // 🧹 Clean up on error too
    throw error;
  }
}

🎯 Pitfall 3: Wrong Type Expectations

// ❌ Wrong - assuming all promises have same type
function badTyping() {
  const promises = [
    Promise.resolve("string"),
    Promise.resolve(42),
    Promise.resolve(true)
  ];
  
  // 🚫 TypeScript error - result could be string | number | boolean
  return Promise.race(promises).then((result: string) => result.toUpperCase());
}

// ✅ Correct - handle union types properly
function goodTyping() {
  const promises = [
    Promise.resolve("string"),
    Promise.resolve(42),
    Promise.resolve(true)
  ];
  
  return Promise.race(promises).then(result => {
    if (typeof result === 'string') {
      return result.toUpperCase(); // ✅ TypeScript knows this is safe
    }
    return String(result).toUpperCase(); // 🎯 Convert others to string
  });
}

🛠️ Best Practices

1. 🛡️ Always Handle Rejections: First settled promise (even failures) wins the race
2. 🧹 Clean Up Resources: Use AbortController or cleanup logic for unfinished promises
3. 🎯 Type Union Handling: Expect union types when racing different promise types
4. ⏰ Implement Timeouts: Use race for timeout patterns with actual operations
5. 🔄 Plan for Failures: Have fallback strategies when fastest promise fails
6. 📊 Consider All Results: Sometimes you need the fastest + all results for comparison

🧪 Hands-On Exercise

🎯 Challenge: Build a Multi-Source Data Aggregator

Create a system that races multiple data sources but falls back intelligently:

📋 Requirements:

• 🌐 Race multiple API endpoints for fastest response
• ⏰ Implement timeout protection (2 seconds)
• 🛡️ Fall back to cached data if all APIs fail
• 📊 Track response times and success rates
• 🔄 Retry failed sources with exponential backoff
• 🧹 Clean up ongoing requests when one wins

🚀 Bonus Points:

• Add health monitoring for each source
• Implement adaptive timeout based on historical performance
• Create a load balancer that prefers faster sources
• Add real-time performance metrics dashboard

💡 Solution

// 🏗️ Multi-source data aggregator with intelligent racing
interface DataSource {
  name: string;
  url: string;
  priority: number;
  emoji: string;
}

interface SourceResult<T> {
  data: T;
  source: DataSource;
  responseTime: number;
  fromCache: boolean;
}

interface SourceMetrics {
  totalRequests: number;
  successCount: number;
  avgResponseTime: number;
  lastError?: string;
}

class MultiSourceAggregator<T> {
  private metrics = new Map<string, SourceMetrics>();
  private cache = new Map<string, { data: T; timestamp: number }>();
  private activeControllers = new Set<AbortController>();
  
  constructor(
    private sources: DataSource[],
    private cacheMaxAge: number = 60000 // 1 minute
  ) {
    // 📊 Initialize metrics
    sources.forEach(source => {
      this.metrics.set(source.name, {
        totalRequests: 0,
        successCount: 0,
        avgResponseTime: 0
      });
    });
  }
  
  // 🏁 Race all sources with intelligent fallbacks
  async fetchData(endpoint: string, timeoutMs: number = 2000): Promise<SourceResult<T>> {
    console.log(`🏁 Racing ${this.sources.length} sources for: ${endpoint}`);
    
    // 🧹 Clean up any previous requests
    this.cleanupActiveRequests();
    
    const racePromises = this.sources.map(source => 
      this.fetchFromSource(source, endpoint, timeoutMs)
    );
    
    try {
      // 🏆 Race all sources
      const result = await Promise.race(racePromises);
      console.log(`⚡ Winner: ${result.source.emoji} ${result.source.name} (${result.responseTime}ms)`);
      
      // 🧹 Cancel other requests
      this.cleanupActiveRequests();
      
      // 💾 Cache the result
      this.cacheResult(endpoint, result.data);
      
      return result;
      
    } catch (error) {
      console.log("🔄 All sources failed, checking cache...");
      
      // 🛡️ Fallback to cache
      const cachedData = this.getCachedData(endpoint);
      if (cachedData) {
        console.log("💾 Using cached data as fallback");
        return {
          data: cachedData,
          source: { name: "Cache", url: "local", priority: 0, emoji: "💾" },
          responseTime: 0,
          fromCache: true
        };
      }
      
      throw new Error(`All sources failed and no cache available: ${error.message}`);
    }
  }
  
  // 🌐 Fetch from a single source
  private async fetchFromSource(
    source: DataSource, 
    endpoint: string, 
    timeoutMs: number
  ): Promise<SourceResult<T>> {
    const controller = new AbortController();
    this.activeControllers.add(controller);
    
    const startTime = Date.now();
    const metrics = this.metrics.get(source.name)!;
    metrics.totalRequests++;
    
    try {
      // 🌐 Simulate API call (replace with real fetch)
      const data = await this.simulateAPICall(source, endpoint, controller.signal, timeoutMs);
      const responseTime = Date.now() - startTime;
      
      // 📊 Update metrics
      metrics.successCount++;
      metrics.avgResponseTime = (metrics.avgResponseTime + responseTime) / 2;
      
      this.activeControllers.delete(controller);
      
      return {
        data,
        source,
        responseTime,
        fromCache: false
      };
      
    } catch (error) {
      const responseTime = Date.now() - startTime;
      metrics.lastError = error.message;
      
      this.activeControllers.delete(controller);
      throw new Error(`${source.emoji} ${source.name} failed (${responseTime}ms): ${error.message}`);
    }
  }
  
  // 🎲 Simulate API call (replace with real implementation)
  private simulateAPICall(
    source: DataSource, 
    endpoint: string, 
    signal: AbortSignal,
    timeoutMs: number
  ): Promise<T> {
    return new Promise((resolve, reject) => {
      // 🎯 Simulate different response times based on priority
      const baseDelay = (6 - source.priority) * 200; // Higher priority = lower delay
      const randomDelay = Math.random() * 500;
      const totalDelay = baseDelay + randomDelay;
      
      const timeoutId = setTimeout(() => {
        if (signal.aborted) {
          reject(new Error("Request aborted"));
          return;
        }
        
        // 🎲 90% success rate
        if (Math.random() > 0.1) {
          resolve({
            message: `Data from ${source.name}`,
            timestamp: new Date(),
            endpoint,
            source: source.name
          } as T);
        } else {
          reject(new Error("Simulated API failure"));
        }
      }, Math.min(totalDelay, timeoutMs));
      
      // 🧹 Handle abort
      signal.addEventListener('abort', () => {
        clearTimeout(timeoutId);
        reject(new Error("Request aborted"));
      });
      
      // ⏰ Handle timeout
      setTimeout(() => {
        if (!signal.aborted) {
          reject(new Error("Request timeout"));
        }
      }, timeoutMs);
    });
  }
  
  // 💾 Cache management
  private cacheResult(key: string, data: T): void {
    this.cache.set(key, {
      data,
      timestamp: Date.now()
    });
  }
  
  private getCachedData(key: string): T | null {
    const cached = this.cache.get(key);
    if (!cached) return null;
    
    const age = Date.now() - cached.timestamp;
    if (age > this.cacheMaxAge) {
      this.cache.delete(key);
      return null;
    }
    
    return cached.data;
  }
  
  // 🧹 Cleanup active requests
  private cleanupActiveRequests(): void {
    this.activeControllers.forEach(controller => {
      controller.abort();
    });
    this.activeControllers.clear();
  }
  
  // 📊 Get performance metrics
  getMetrics(): Map<string, SourceMetrics> {
    return new Map(this.metrics);
  }
  
  // 🎯 Get best performing source
  getBestSource(): DataSource | null {
    let bestSource: DataSource | null = null;
    let bestScore = -1;
    
    for (const source of this.sources) {
      const metrics = this.metrics.get(source.name);
      if (!metrics || metrics.totalRequests === 0) continue;
      
      const successRate = metrics.successCount / metrics.totalRequests;
      const avgTime = metrics.avgResponseTime || 1000;
      
      // 🏆 Score = success rate / avg response time
      const score = successRate / (avgTime / 1000);
      
      if (score > bestScore) {
        bestScore = score;
        bestSource = source;
      }
    }
    
    return bestSource;
  }
}

// 🎮 Demo the multi-source aggregator
async function demonstrateMultiSourceAggregator() {
  const sources: DataSource[] = [
    { name: "Primary API", url: "https://api.example.com", priority: 5, emoji: "🎯" },
    { name: "Backup API", url: "https://backup.example.com", priority: 3, emoji: "🛡️" },
    { name: "CDN", url: "https://cdn.example.com", priority: 4, emoji: "⚡" },
    { name: "Edge Cache", url: "https://edge.example.com", priority: 2, emoji: "🌐" }
  ];
  
  const aggregator = new MultiSourceAggregator<any>(sources, 30000);
  
  try {
    // 🚀 Test multiple requests
    for (let i = 1; i <= 3; i++) {
      console.log(`\n🔄 Request ${i}:`);
      const result = await aggregator.fetchData(`/api/data/${i}`, 1500);
      
      console.log(`✅ Success: ${result.source.emoji} ${result.source.name}`);
      console.log(`📊 Response time: ${result.responseTime}ms`);
      console.log(`💾 From cache: ${result.fromCache ? 'Yes' : 'No'}`);
    }
    
    // 📈 Show performance metrics
    console.log(`\n📊 Performance Metrics:`);
    const metrics = aggregator.getMetrics();
    metrics.forEach((metric, sourceName) => {
      const successRate = metric.totalRequests > 0 
        ? (metric.successCount / metric.totalRequests * 100).toFixed(1)
        : '0';
      
      console.log(`  ${sourceName}:`);
      console.log(`    📈 Success rate: ${successRate}%`);
      console.log(`    ⏱️ Avg response: ${metric.avgResponseTime.toFixed(0)}ms`);
      console.log(`    🔢 Total requests: ${metric.totalRequests}`);
    });
    
    // 🏆 Show best performing source
    const bestSource = aggregator.getBestSource();
    if (bestSource) {
      console.log(`\n🏆 Best performing source: ${bestSource.emoji} ${bestSource.name}`);
    }
    
  } catch (error) {
    console.error("💥 Aggregator demo failed:", error.message);
  }
}

// 🚀 Run the demo
demonstrateMultiSourceAggregator();

🎓 Key Takeaways

You’ve mastered Promise.race! Here’s what you can now do:

• ✅ Race promises effectively for fastest responses and timeouts 💪
• ✅ Handle rejection scenarios and implement smart fallbacks 🛡️
• ✅ Build competitive async systems with proper cleanup 🎯
• ✅ Use advanced patterns like progressive racing and metrics 🚀
• ✅ Avoid common pitfalls like memory leaks and type issues 🐛

Remember: Promise.race is perfect when you need the fastest result, but always plan for what happens when the winner fails! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered Promise.race in TypeScript!

Here’s what to explore next:

1. 💻 Practice with the multi-source aggregator exercise above
2. 🏗️ Build a real-time performance monitoring system
3. 📚 Move on to our next tutorial: “Promise.allSettled: Handling Mixed Results”
4. 🌟 Explore advanced patterns like Promise scheduling and queuing

Remember: The fastest doesn’t always win - but with proper fallbacks, you’ll always have a winner! 🚀

Happy coding! 🎉🚀✨