Array.fromAsync()

Baseline 2024

Newly available

Since January 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

The Array.fromAsync() static method creates a new, shallow-copied Array instance from an async iterable, iterable, or array-like object.

Syntax

Array.fromAsync(items)
Array.fromAsync(items, mapFn)
Array.fromAsync(items, mapFn, thisArg)

Parameters

items

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

mapFn Optional

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, and mapFn's return value is added to the array instead (after being awaited). The function is called with the following arguments:

element: The current element being processed in the array. If items is a sync iterable or array-like object, then all elements are first awaited, and element will never be a thenable. If items is an async iterable, then each yielded value is passed as-is.
index: The index of the current element being processed in the array.

thisArg Optional

Value to use as this when executing mapFn.

Return value

A new Promise whose fulfillment value is a new Array instance.

Description

Array.fromAsync() lets you create arrays from:

async iterable objects (objects such as ReadableStream and AsyncGenerator); or, if the object is not async iterable,
iterable objects (objects such as Map and Set); or, if the object is not iterable,
array-like objects (objects with a length property and indexed elements).

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

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

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

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

Array.fromAsync() and Promise.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.

Examples

Array from an async iterable

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]

When items is an async iterable where each result's value is also a promise, then those promises are added to the resulting array without being awaited. This is consistent with the behavior of