JavaScript Promise Methods Guide

JavaScript provides several Promise combinators for handling multiple async operations. Here's how to use them.

Promise.all#

// Wait for all promises to resolve
const promise1 = fetch('/api/users');
const promise2 = fetch('/api/posts');
const promise3 = fetch('/api/comments');

Promise.all([promise1, promise2, promise3])
  .then(([users, posts, comments]) => {
    console.log('All data loaded');
  })
  .catch(error => {
    // If ANY promise rejects, catch fires
    console.error('One request failed:', error);
  });

// With async/await
async function loadAllData() {
  try {
    const [users, posts, comments] = await Promise.all([
      fetch('/api/users').then(r => r.json()),
      fetch('/api/posts').then(r => r.json()),
      fetch('/api/comments').then(r => r.json()),
    ]);

    return { users, posts, comments };
  } catch (error) {
    console.error('Failed to load data:', error);
    throw error;
  }
}

// Parallel processing
async function processItems(items) {
  const results = await Promise.all(
    items.map(async item => {
      const processed = await processItem(item);
      return processed;
    })
  );

  return results;
}

// With timeout
function withTimeout(promise, ms) {
  const timeout = new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Timeout')), ms)
  );
  return Promise.race([promise, timeout]);
}

const results = await withTimeout(
  Promise.all([fetch('/api/a'), fetch('/api/b')]),
  5000
);

Promise.allSettled#

// Wait for all promises, regardless of outcome
const promises = [
  fetch('/api/users'),
  fetch('/api/broken-endpoint'), // This will fail
  fetch('/api/posts'),
];

Promise.allSettled(promises)
  .then(results => {
    results.forEach((result, index) => {
      if (result.status === 'fulfilled') {
        console.log(`Promise ${index} succeeded:`, result.value);
      } else {
        console.log(`Promise ${index} failed:`, result.reason);
      }
    });
  });

// Separate successes and failures
async function fetchAllWithStatus(urls) {
  const results = await Promise.allSettled(
    urls.map(url => fetch(url).then(r => r.json()))
  );

  const successes = results
    .filter(r => r.status === 'fulfilled')
    .map(r => r.value);

  const failures = results
    .filter(r => r.status === 'rejected')
    .map(r => r.reason);

  return { successes, failures };
}

// Retry failed requests
async function fetchWithRetry(urls, maxRetries = 3) {
  let remaining = urls;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const results = await Promise.allSettled(
      remaining.map(url => fetch(url).then(r => r.json()))
    );

    const succeeded = [];
    const failed = [];

    results.forEach((result, index) => {
      if (result.status === 'fulfilled') {
        succeeded.push(result.value);
      } else {
        failed.push(remaining[index]);
      }
    });

    if (failed.length === 0) {
      return succeeded;
    }

    remaining = failed;
  }

  throw new Error(`Failed after ${maxRetries} retries`);
}

Promise.race#

// First promise to settle wins
const fast = new Promise(resolve =>
  setTimeout(() => resolve('fast'), 100)
);

const slow = new Promise(resolve =>
  setTimeout(() => resolve('slow'), 500)
);

Promise.race([fast, slow])
  .then(result => console.log(result)); // 'fast'

// Timeout pattern
function fetchWithTimeout(url, timeout) {
  const fetchPromise = fetch(url);
  const timeoutPromise = new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Request timeout')), timeout)
  );

  return Promise.race([fetchPromise, timeoutPromise]);
}

try {
  const response = await fetchWithTimeout('/api/data', 5000);
  const data = await response.json();
} catch (error) {
  if (error.message === 'Request timeout') {
    console.log('Request took too long');
  }
}

// First successful response from multiple sources
async function fetchFromMirrors(mirrors) {
  return Promise.race(
    mirrors.map(url =>
      fetch(url).then(response => {
        if (!response.ok) throw new Error('Failed');
        return response;
      })
    )
  );
}

// Cancel on first result
function raceWithCancellation(promises, signal) {
  return Promise.race([
    ...promises,
    new Promise((_, reject) => {
      signal.addEventListener('abort', () => {
        reject(new DOMException('Aborted', 'AbortError'));
      });
    }),
  ]);
}

Promise.any#

// First promise to FULFILL wins (ignores rejections)
const promises = [
  Promise.reject('Error 1'),
  new Promise(resolve => setTimeout(() => resolve('Success'), 100)),
  Promise.reject('Error 2'),
];

Promise.any(promises)
  .then(result => console.log(result)) // 'Success'
  .catch(error => {
    // AggregateError if ALL promises reject
    console.log(error.errors); // All rejection reasons
  });

// Fallback pattern
async function fetchWithFallbacks(urls) {
  try {
    const response = await Promise.any(
      urls.map(url => fetch(url).then(r => {
        if (!r.ok) throw new Error(`HTTP ${r.status}`);
        return r;
      }))
    );
    return response.json();
  } catch (error) {
    if (error instanceof AggregateError) {
      console.log('All sources failed:', error.errors);
    }
    throw error;
  }
}

// First available service
async function connectToService(endpoints) {
  try {
    const connection = await Promise.any(
      endpoints.map(async endpoint => {
        const health = await fetch(`${endpoint}/health`);
        if (!health.ok) throw new Error('Unhealthy');
        return { endpoint, status: 'connected' };
      })
    );
    return connection;
  } catch (error) {
    throw new Error('No healthy services available');
  }
}

Promise.resolve and Promise.reject#

// Create resolved promise
const resolved = Promise.resolve(42);
resolved.then(value => console.log(value)); // 42

// Wrap sync value in promise
function maybeAsync(value) {
  return Promise.resolve(value);
}

// Create rejected promise
const rejected = Promise.reject(new Error('Failed'));
rejected.catch(error => console.log(error.message)); // 'Failed'

// Normalize to promise
async function getData(source) {
  // Handle both sync and async sources
  const data = await Promise.resolve(source);
  return process(data);
}

// Thenable conversion
const thenable = {
  then(resolve) {
    resolve('from thenable');
  }
};

Promise.resolve(thenable)
  .then(value => console.log(value)); // 'from thenable'

Practical Patterns#

// Batch processing with concurrency limit
async function batchProcess(items, fn, concurrency = 5) {
  const results = [];

  for (let i = 0; i < items.length; i += concurrency) {
    const batch = items.slice(i, i + concurrency);
    const batchResults = await Promise.all(batch.map(fn));
    results.push(...batchResults);
  }

  return results;
}

// Sequential execution
async function sequential(tasks) {
  const results = [];

  for (const task of tasks) {
    results.push(await task());
  }

  return results;
}

// Or with reduce
function sequentialReduce(tasks) {
  return tasks.reduce(
    (promise, task) => promise.then(results =>
      task().then(result => [...results, result])
    ),
    Promise.resolve([])
  );
}

// Retry with exponential backoff
async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 1000) {
  let lastError;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      const delay = baseDelay * Math.pow(2, i);
      await new Promise(r => setTimeout(r, delay));
    }
  }

  throw lastError;
}

// Poll until condition
async function pollUntil(fn, condition, interval = 1000, timeout = 30000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    const result = await fn();
    if (condition(result)) {
      return result;
    }
    await new Promise(r => setTimeout(r, interval));
  }

  throw new Error('Polling timeout');
}

// Usage
const status = await pollUntil(
  () => fetch('/api/job/123').then(r => r.json()),
  result => result.status === 'complete',
  2000,
  60000
);

Error Handling#

// Catch specific errors
class NetworkError extends Error {}
class ValidationError extends Error {}

async function fetchData(url) {
  try {
    const response = await fetch(url);

    if (!response.ok) {
      throw new NetworkError(`HTTP ${response.status}`);
    }

    const data = await response.json();

    if (!isValid(data)) {
      throw new ValidationError('Invalid data');
    }

    return data;
  } catch (error) {
    if (error instanceof NetworkError) {
      // Handle network errors
    } else if (error instanceof ValidationError) {
      // Handle validation errors
    } else {
      // Unknown error
      throw error;
    }
  }
}

// Finally for cleanup
async function withCleanup() {
  const resource = await acquire();

  try {
    return await useResource(resource);
  } finally {
    await release(resource);
  }
}

// Promise.prototype.finally
fetch('/api/data')
  .then(response => response.json())
  .catch(error => console.error(error))
  .finally(() => {
    hideLoadingSpinner();
  });

Best Practices#

Choosing Methods:
✓ Promise.all - all must succeed
✓ Promise.allSettled - need all results
✓ Promise.race - first to settle
✓ Promise.any - first to succeed

Error Handling:
✓ Always handle rejections
✓ Use specific error types
✓ Add timeouts to prevent hanging
✓ Log errors appropriately

Performance:
✓ Parallelize independent operations
✓ Limit concurrency for resources
✓ Batch large operations
✓ Cancel unnecessary requests

Avoid:
✗ Unhandled promise rejections
✗ Infinite parallel requests
✗ Forgetting await
✗ Nested promise chains

Promise combinators enable powerful async patterns. Use Promise.all when all operations must succeed, Promise.allSettled when you need all results regardless of outcome, Promise.race for timeouts and first-response patterns, and Promise.any for fallback strategies. Combine these with proper error handling for robust async code.