items

An async iterable, iterable, or array-like object to convert to an array.

mapFnOptional

A function to call on every element of the array. If provided, every value to be added to the array is first passed through this function, andmapFn's return value is added to the array instead (after beingawaited). The function is called with the following arguments:

element

The current element being processed in the array. Ifitems is a sync iterable or array-like object, then all elements are firstawaited, andelement will never be athenable. Ifitems is an async iterable, then each yielded value is passed as-is.

index

The index of the current element being processed in the array.

thisArgOptional

Value to use asthis when executingmapFn.

A newPromise whose fulfillment value is a newArray instance.

Array.fromAsync() lets you create arrays from:

• async iterable objects (objects such asReadableStream andAsyncGenerator); or, if the object is not async iterable,
• iterable objects (objects such asMap andSet); or, if the object is not iterable,
• array-like objects (objects with alength property and indexed elements).

Array.fromAsync() iterates the async iterable in a fashion very similar tofor await...of.Array.fromAsync(items) is generally equivalent to the following code, ifitems is an async iterable or sync iterable:

const result = [];for await (const element of items) {  result.push(element);}

Array.fromAsync() is almost equivalent toArray.from() in terms of behavior, except the following:

• Array.fromAsync() handles async iterable objects.
• Array.fromAsync() returns aPromise that fulfills to the array instance.
• IfArray.fromAsync() is called with a non-async iterable object, each element to be added to the array is firstawaited.
• If amapFn is provided, its output is also internally awaited.

Array.fromAsync() andPromise.all() can both turn an iterable of promises into a promise of an array. However, there are two key differences:

• Array.fromAsync() awaits each value yielded from the object sequentially.Promise.all() awaits all values concurrently.
• Array.fromAsync() iterates the iterable lazily, and doesn't retrieve the next value until the current one is settled.Promise.all() retrieves all values in advance and awaits them all.

const asyncIterable = (async function* () {  for (let i = 0; i < 5; i++) {    await new Promise((resolve) => setTimeout(resolve, 10 * i));    yield i;  }})();Array.fromAsync(asyncIterable).then((array) => console.log(array));// [0, 1, 2, 3, 4]

Whenitems is an async iterable where each result'svalue is also a promise, then those promises are added to the resulting array without being awaited. This is consistent with the behavior offor await...of.

function createAsyncIter() {  let i = 0;  return {    [Symbol.asyncIterator]() {      return {        async next() {          if (i > 2) return { done: true };          i++;          return { value: Promise.resolve(i), done: false };        },      };    },  };}Array.fromAsync(createAsyncIter()).then((array) => console.log(array));// (3) [Promise, Promise, Promise]

Whenitems is a sync iterable or array-like object, both the input and output ofmapFn are awaited internally byArray.fromAsync().

function delayedValue(v) {  return new Promise((resolve) => setTimeout(() => resolve(v), 100));}Array.fromAsync(  [delayedValue(1), delayedValue(2), delayedValue(3)],  (element) => delayedValue(element * 2),).then((array) => console.log(array));// [2, 4, 6]

Whenitems is an async iterable, the input tomapFn is not awaited, but the output is. Using the samecreateAsyncIter function as above:

Array.fromAsync(createAsyncIter(), async (element) => (await element) * 2).then(  (array) => console.log(array),);// [2, 4, 6]

Curiously, this means thatArray.fromAsync(createAsyncIter()) is not equivalent toArray.fromAsync(createAsyncIter(), (element) => element), because the latter awaits each yielded value, while the former does not.

Array.fromAsync(createAsyncIter(), (element) => element).then((array) =>  console.log(array),);// [1, 2, 3]

Array.fromAsync() awaits each value yielded from the object sequentially.Promise.all() awaits all values concurrently.

function* makeIterableOfPromises() {  for (let i = 0; i < 5; i++) {    yield new Promise((resolve) => setTimeout(resolve, 100));  }}(async () => {  console.time("Array.fromAsync() time");  await Array.fromAsync(makeIterableOfPromises());  console.timeEnd("Array.fromAsync() time");  // Array.fromAsync() time: 503.610ms  console.time("Promise.all() time");  await Promise.all(makeIterableOfPromises());  console.timeEnd("Promise.all() time");  // Promise.all() time: 101.728ms})();

Similar tofor await...of, if the object being iterated is a sync iterable, and an error is thrown while iterating, thereturn() method of the underlying iterator will not be called, so the iterator is not closed.

function* generatorWithRejectedPromises() {  try {    yield 0;    yield Promise.reject(new Error("error"));  } finally {    console.log("called finally");  }}(async () => {  try {    await Array.fromAsync(generatorWithRejectedPromises());  } catch (e) {    console.log("caught", e);  }})();// caught Error: error// No "called finally" message

If you need to close the iterator, you need to use afor...of loop instead, andawait each value yourself.

(async () => {  const arr = [];  try {    for (const val of generatorWithRejectedPromises()) {      arr.push(await val);    }  } catch (e) {    console.log("caught", e);  }})();// called finally// caught 3

• Polyfill ofArray.fromAsync incore-js
• Indexed collections guide
• Array
• Array()
• Array.of()
• Array.from()
• for await...of