Promise.any()

Promise.any() 接收一个Promise可迭代对象,只要其中的一个 promise 完成,就返回那个已经有完成值的 promise 。如果可迭代对象中没有一个 promise 完成(即所有的 promises 都失败/拒绝),就返回一个拒绝的 promise,返回值还有待商榷:无非是拒绝原因数组或AggregateError类型的实例,它是 Error 的一个子类,用于把单一的错误集合在一起。本质上,这个方法和Promise.all()是相反的。

注意! Promise.any() 方法依然是实验性的,尚未被所有的浏览器完全支持。它当前处于 TC39 第三阶段草案(Stage 3)

语法

Promise.any(iterable);

参数

iterable
一个 可迭代 的对象, 例如 Array

返回值

  • 如果传入的参数是一个空的可迭代对象,则返回一个 已完成(already resolved) 状态的 Promise
  • 如果传入的参数不包含任何 promise,则返回一个 异步完成 (asynchronously resolved)的 Promise
  • 其他情况下都会返回一个处理中(pending) 的 Promise。 只要传入的迭代对象中的任何一个 promise 变成完成(resolve)状态,或者其中的所有的 promises 都被拒绝,那么返回的 promise 就会 异步地(当调用栈为空时) 变成完成/拒绝(resolved/reject)状态。

说明

这个方法对于返回第一个已完成的 promise 是有用的。在一个 promise 完成后它就会终止,因此它不用等待其他的 promise 全部完成,只要发现一个就够了。

不像 Promise.all() 会返回一组完成值那样(resolved values),我们只能得到一个完成值(假设至少有一个 promise 完成)。当我们只需要一个 promise 完成,而不需要关心是哪一个完成时会很有用的。

同时, 也不像 Promise.race() 总是返回第一个结果值(resolved/reject)那样,这个方法返回的是第一个 完成的 值。这个方法将会忽略掉所有被拒绝的 promise,直到第一个 promise 完成。

完成(Fulfillment):

当任何一个被传入的 promise 完成的时候, 无论其他的 promises 完成还是被拒绝,此函数返回的 promise 将异步完成,其值为传入的完成的那个 promise 的值。

  • 如果传入的参数是一个空的可迭代对象, 这个方法将会同步返回一个已经完成的 promise
  • 如果传入的任何一个 promise 已完成, 或者传入的参数不包括任何 promise, 那么 Promise.any 返回一个异步完成的 promise

失败/拒绝(Rejection):

如果所有传入的 promises 都被拒绝, Promise.any 将会异步拒绝,其返回结果可能是以下之一(返回哪个目前还没有一致的决定):

  • 一个数组,其中包含作为参数传入的可迭代对象被拒绝的所有原因
  • 一个 AggregateError 对象,它继承自 Error,并且包含了一个指向异常(exceptions)数组的指针

参见