Array Promise Utilities

/**
 * Wait for all promises to fulfill or any to reject (fail-fast)
 * @param array - Array of promises or values
 * @param label - Optional string for debugging/tooling
 * @returns Promise that fulfills with array of results in same order
 */
function all(array: Array, label?: string): Promise;

import { all, resolve } from "rsvp";

// Basic usage with promises
all([
  fetchUser(1),
  fetchUser(2),
  fetchUser(3)
]).then(function(users) {
  console.log("All users loaded:", users);
}).catch(function(error) {
  console.error("At least one user failed to load:", error);
});

// Mixed promises and values
all([
  resolve("immediate"),
  Promise.resolve("also immediate"),
  fetchAsync()
]).then(function(results) {
  // results[0] === "immediate"
  // results[1] === "also immediate"  
  // results[2] === result from fetchAsync()
});

/**
 * Wait for all promises to settle regardless of outcome
 * @param entries - Array of promises or values
 * @param label - Optional string for debugging/tooling
 * @returns Promise with array of {state, value/reason} objects
 */
function allSettled(entries: Array, label?: string): Promise;

import { allSettled, resolve, reject } from "rsvp";

allSettled([
  resolve(1),
  reject(new Error("failed")),
  resolve(3)
]).then(function(results) {
  // results[0] === { state: 'fulfilled', value: 1 }
  // results[1] === { state: 'rejected', reason: Error }
  // results[2] === { state: 'fulfilled', value: 3 }
  
  const successful = results.filter(r => r.state === 'fulfilled');
  const failed = results.filter(r => r.state === 'rejected');
});

/**
 * Race promises, settling with the first to settle
 * @param array - Array of promises or values
 * @param label - Optional string for debugging/tooling
 * @returns Promise that settles with first settled value/reason
 */
function race(array: Array, label?: string): Promise;

import { race, Promise } from "rsvp";

// Timeout pattern
race([
  fetchData(),
  new Promise((_, reject) => 
    setTimeout(() => reject(new Error("Timeout")), 5000)
  )
]).then(function(result) {
  console.log("Got result within timeout:", result);
}).catch(function(error) {
  console.error("Failed or timed out:", error);
});

// First successful response from multiple endpoints
race([
  fetch("/api/v1/data"),
  fetch("/api/v2/data"),
  fetch("/backup-api/data")
]).then(response => response.json());

/**
 * Transform array of promises/values using mapping function
 * @param promises - Array of promises or values to transform
 * @param mapFn - Function to transform each resolved value
 * @param label - Optional string for debugging/tooling
 * @returns Promise with array of transformed values
 */
function map(promises: Array, mapFn: Function, label?: string): Promise;

import { map, resolve } from "rsvp";

// Transform resolved values
map([
  resolve(1),
  resolve(2), 
  resolve(3)
], function(value) {
  return value * 2;
}).then(function(results) {
  console.log(results); // [2, 4, 6]
});

// Async mapping function
map([
  "user1",
  "user2", 
  "user3"
], function(username) {
  return fetchUserProfile(username); // returns a promise
}).then(function(profiles) {
  console.log("All user profiles:", profiles);
});

// Error handling - fails on first rejection
map([
  resolve(1),
  reject(new Error("failed")),
  resolve(3)
], x => x * 2).catch(function(error) {
  console.error("Mapping failed:", error);
});

/**
 * Filter array of promises/values using predicate function
 * @param promises - Array of promises or values to filter
 * @param filterFn - Function to test each resolved value
 * @param label - Optional string for debugging/tooling
 * @returns Promise with array of values that pass the test
 */
function filter(promises: Array, filterFn: Function, label?: string): Promise;

import { filter, resolve } from "rsvp";

// Filter resolved values
filter([
  resolve(1),
  resolve(2),
  resolve(3),
  resolve(4)
], function(value) {
  return value > 2;
}).then(function(results) {
  console.log(results); // [3, 4]
});

// Async filter function
filter([
  "user1",
  "user2",
  "user3"
], function(username) {
  return checkUserPermissions(username).then(function(permissions) {
    return permissions.canAccess;
  });
}).then(function(allowedUsers) {
  console.log("Users with access:", allowedUsers);
});

// Error handling - fails on first rejection
filter([
  resolve(1),
  reject(new Error("failed")),
  resolve(3)
], x => x > 0).catch(function(error) {
  console.error("Filtering failed:", error);
});

import { all, allSettled } from "rsvp";

// This will reject as soon as any promise rejects
all([promise1, promise2, promise3])
  .catch(error => console.log("First error:", error));

// This will wait for all to complete
allSettled([promise1, promise2, promise3])
  .then(results => {
    const errors = results
      .filter(r => r.state === 'rejected')
      .map(r => r.reason);
    console.log("All errors:", errors);
  });