Promise.any()

iterable

一个可迭代的对象，例如 Array。

• 如果传入了一个空的可迭代对象，那么就会返回一个已经被拒的 promise
• 如果传入了一个不含有 promise 的可迭代对象，那么就会返回一个异步兑现的 promise
• 其余情况下都会返回一个处于等待状态的 promise。如果可迭代对象中的任意一个 promise 兑现了，那么这个处于等待状态的 promise 就会异步地（调用栈为空时）切换至兑现状态。如果可迭代对象中的所有 promise 都被拒绝了，那么这个处于等待状态的 promise 就会异步地切换至被拒状态。

该方法用于获取首个兑现的 promise 的值。只要有一个 promise 兑现了，那么此方法就会提前结束，而不会继续等待其他的 promise 全部敲定。

不像 Promise.all() 会返回一组兑现值那样，我们只能得到一个兑现值（假设至少有一个 promise 兑现）。当我们只需要一个 promise 兑现，而不关心是哪一个兑现时此方法很有用的。

同时，也不像 Promise.race() 总是返回第一个敲定值（兑现或拒绝）那样，这个方法返回的是第一个兑现的值。这个方法将会忽略掉所有的被拒绝的 promise，直到第一个 promise 兑现。

该方法所返回的 promise 会以可迭代对象内首个兑现的 promise 的兑现值来作为它自己的兑现值，或者会以可迭代对象内首个非 promise 值来作为它自己的兑现值，该方法不会关心其他的 promise 是兑现了还是被拒了。

• 如果传入的可迭代对象是非空的，那么当可迭代对象内的任意一个 promise 兑现后，或者当可迭代对象内存在非 promise 值时，该方法所返回的 promise 都会异步的变成兑现状态。

如果可迭代对象内所有的 promises 都被拒绝了，那么该方法所返回的 promise 就会异步的切换至被拒状态，并用一个 AggregateError（继承自 Error）实例来作为它的拒因。它包含一个 errors 属性，该属性是一个用于存储拒因的数组。

• 如果传入了一个空的可迭代数组，那么该方法就会返回一个已经被拒 promise，其拒因是一个 AggregateError 实例，该实例的 errors 属性会是一个空数组。

如果可迭代数组内的任意一个 promise 兑现了，那么该方法所返回的 promise 也会切换至兑现状态，哪怕首个敲定的 promise 是被拒的。不同的是，Promise.race() 所返回的 promise 的状态会跟随首个敲定的 promise 的状态。

const pErr = new Promise((resolve, reject) => {
  reject("总是失败");
});

const pSlow = new Promise((resolve, reject) => {
  setTimeout(resolve, 500, "最终完成");
});

const pFast = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, "很快完成");
});

Promise.any([pErr, pSlow, pFast]).then((value) => {
  console.log(value);
  // pFast fulfils first
})
// 期望输出: "很快完成"

如果没有 promise 被兑现，那么 Promise.any() 所返回的 promise 就会切换至被拒状态，并以 AggregateError 实例来作为拒因。

const pErr = new Promise((resolve, reject) => {
  reject('总是失败');
});

Promise.any([pErr]).catch((err) => {
  console.log(err);
})
// 期望输出: "AggregateError: No Promise in Promise.any was resolved"

在这个例子，我们有一个获取图片并返回 blob 的函数，我们使用 Promise.any() 来获取一些图片并显示第一张有效的图片（即最先 resolved 的那个 promise）。

function fetchAndDecode(url) {
  return fetch(url).then(response => {
    if(!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    } else {
      return response.blob();
    }
  })
}

let coffee = fetchAndDecode('coffee.jpg');
let tea = fetchAndDecode('tea.jpg');

Promise.any([coffee, tea]).then(value => {
  let objectURL = URL.createObjectURL(value);
  let image = document.createElement('img');
  image.src = objectURL;
  document.body.appendChild(image);
})
.catch(e => {
  console.log(e.message);
});

• Promise
• Promise.all()
• Promise.race()