Collection and Array Operations

/**
 * Turns array of promises into promise for array of values
 * @param promises - Array of promises or values
 * @returns Promise that resolves to array of all resolved values
 */
function Q.all(promises);

/**
 * Instance version of Q.all for promise of array
 * @returns Promise for array of resolved values
 */
promise.all();

const Q = require("q");

// Static version with array of promises
const allPromise = Q.all([
  Q.resolve(1),
  Q.resolve(2),
  Q.resolve(3)
]);

allPromise.then(values => {
  console.log(values); // [1, 2, 3]
});

// Instance version with promise of array
const arrayPromise = Q.resolve([
  fetchUser(1),
  fetchUser(2),
  fetchUser(3)
]);

arrayPromise.all().then(users => {
  console.log("All users:", users);
});

// Mixed values and promises
Q.all([
  "immediate value",
  Q.delay("delayed", 100),
  Promise.resolve("native promise")
]).then(results => {
  console.log(results); // ["immediate value", "delayed", "native promise"]
});

/**
 * Returns promise for array of inspection states when all promises settle
 * @param promises - Array of promises or values
 * @returns Promise resolving to array of {state, value?, reason?} objects
 */
function Q.allSettled(promises);

/**
 * Instance version of Q.allSettled for promise of array
 * @returns Promise for array of settlement states
 */
promise.allSettled();

const Q = require("q");

// Handle mix of successful and failed promises
const settledPromise = Q.allSettled([
  Q.resolve("success"),
  Q.reject(new Error("failure")),
  Q.delay("delayed success", 100)
]);

settledPromise.then(results => {
  results.forEach((result, index) => {
    if (result.state === "fulfilled") {
      console.log(`Promise ${index} succeeded:`, result.value);
    } else {
      console.log(`Promise ${index} failed:`, result.reason.message);
    }
  });
});

// Instance version
const arrayPromise = Q.resolve([
  apiCall1(),
  apiCall2(),
  apiCall3()
]);

arrayPromise.allSettled().then(results => {
  const successes = results.filter(r => r.state === "fulfilled");
  const failures = results.filter(r => r.state === "rejected");
  console.log(`${successes.length} succeeded, ${failures.length} failed`);
});

/**
 * Spreads array values as arguments to callback
 * @param promise - Promise that resolves to array
 * @param fulfilled - Callback receiving spread array elements as arguments
 * @param rejected - Optional rejection handler
 * @returns Promise for callback result
 */
function Q.spread(promise, fulfilled, rejected);

/**
 * Instance version that spreads promise array values as function arguments
 * @param fulfilled - Callback receiving spread elements as arguments
 * @param rejected - Optional rejection handler  
 * @param ms - Optional timing estimate
 * @returns Promise for callback result
 */
promise.spread(fulfilled, rejected, ms);

const Q = require("q");

// Static version
const arrayPromise = Q.all([
  fetchUserName(),
  fetchUserAge(),
  fetchUserEmail()
]);

Q.spread(arrayPromise, (name, age, email) => {
  console.log(`User: ${name}, Age: ${age}, Email: ${email}`);
});

// Instance version
const coordinatesPromise = Q.resolve([10, 20]);

coordinatesPromise.spread((x, y) => {
  return calculateDistance(x, y, 0, 0);
}).then(distance => {
  console.log("Distance from origin:", distance);
});

// With error handling
const dataPromise = Q.all([fetchA(), fetchB(), fetchC()]);

dataPromise.spread(
  (a, b, c) => processData(a, b, c),
  error => console.error("Failed to fetch data:", error)
);

/**
 * Returns promise for first fulfilled value from array of promises
 * @param promises - Array of promises to race
 * @returns Promise that settles with first settled promise
 */
function Q.race(promises);

const Q = require("q");

// Race between multiple data sources
const racePromise = Q.race([
  fetchFromPrimaryAPI(),
  fetchFromBackupAPI(),
  fetchFromCache()
]);

racePromise.then(data => {
  console.log("Got data from fastest source:", data);
});

// Timeout pattern with race
function timeoutAfter(ms) {
  return Q.delay(ms).then(() => {
    throw new Error("Operation timed out");
  });
}

Q.race([
  longRunningOperation(),
  timeoutAfter(5000)
]).then(
  result => console.log("Completed:", result),
  error => console.error("Failed or timed out:", error)
);

// Race with immediate values
Q.race([
  "immediate",
  Q.delay("delayed", 100)
]).then(winner => {
  console.log(winner); // "immediate"
});

// Settlement state interface
interface SettlementState {
  state: "fulfilled" | "rejected";
  value?: any;      // Present when state is "fulfilled"
  reason?: any;     // Present when state is "rejected"
}

// Spread callback signatures
type SpreadCallback<T extends any[]> = (...args: T) => any;