Array : mthode statique fromAsync()

Syntaxe

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

Paramtres

items

Un objet itrable asynchrone, itrable ou semblable un tableau convertir en tableau.

mapFn Facultatif

Une fonction appele sur chaque lment du tableau. Si elle est fournie, chaque valeur ajouter au tableau est d'abord transmise cette fonction, et la valeur de retour de mapFn est ajoute au tableau la place (aprs avoir t attendue). La fonction est appele avec les arguments suivants :

element

L'lment en cours de traitement dans le tableau. Si items est un itrable synchrone ou un objet semblable un tableau, tous les lments sont d'abord attendus, et element n'est jamais une semi-promesse. Si items est un itrable asynchrone, chaque valeur produite est transmise telle quelle.

index

L'indice de l'lment en cours de traitement dans le tableau.

thisArg Facultatif

La valeur utiliser comme this lors de l'excution de la fonction mapFn.

Valeur de retour

Une nouvelle promesse (Promise) dont la valeur de retour est une nouvelle instance de Array.

Description

Array.fromAsync() permet de crer des tableaux partir :

• d'objets itrables asynchrones (des objets comme ReadableStream et AsyncGenerator) ; ou, si l'objet n'est pas un itrable asynchrone,
• d'objets itrables (des objets comme Map et Set) ; ou, si l'objet n'est pas itrable,
• d'objets semblables des tableaux (objets avec une proprit length et des lments indexs).

Array.fromAsync() parcourt l'itrable asynchrone d'une manire trs similaire for await...of. Array.fromAsync(items) est gnralement quivalent au code suivant, si items est un itrable asynchrone ou synchrone :

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

Array.fromAsync() est presque quivalent Array.from() en termes de comportement, l'exception des points suivants :

• Array.fromAsync() gre les objets itrables asynchrones.
• Array.fromAsync() retourne une promesse (Promise) qui se rsout en une instance de tableau.
• Si Array.fromAsync() est appele avec un objet itrable non asynchrone, chaque lment ajout au tableau est d'abord attendu.
• Si un mapFn est fourni, sa sortie est galement attendue en interne.

Array.fromAsync() et Promise.all() peuvent toutes deux transformer un itrable de promesses dans une promesse d'un tableau. Cependant, il existe deux diffrences majeures :

• Array.fromAsync() attend chaque valeur produite par l'objet de faon squentielle. Promise.all() attend toutes les valeurs en parallle.
• Array.fromAsync() parcourt l'itrable de faon diffre, et ne rcupre la valeur suivante que lorsque la prcdente est rsolue. Promise.all() rcupre toutes les valeurs l'avance et les attend toutes.

Exemples

Tableau partir d'un objet itrable asynchrone

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]

Lorsque items est un itrable asynchrone dont chaque rsultat value est aussi une promesse, ces promesses sont ajoutes au tableau rsultant sans tre attendues. Cela correspond au comportement de for 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]

Tableau partir d'un objet itrable synchrone

Array.fromAsync(
  new Map([
    [1, 2],
    [3, 4],
  ]),
).then((array) => console.log(array));
// [[1, 2], [3, 4]]

Tableau partir d'un objet itrable synchrone qui produit des promesses

Array.fromAsync(
  new Set([Promise.resolve(1), Promise.resolve(2), Promise.resolve(3)]),
).then((array) => console.log(array));
// [1, 2, 3]

Tableau partir d'un objet semblable un tableau de promesses

Array.fromAsync({
  length: 3,
  0: Promise.resolve(1),
  1: Promise.resolve(2),
  2: Promise.resolve(3),
}).then((array) => console.log(array));
// [1, 2, 3]

Utiliser mapFn avec un objet itrable synchrone

Lorsque items est un itrable synchrone ou un objet semblable un tableau, l'entre et la sortie de mapFn sont attendues en interne par Array.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]

Utiliser mapFn avec un objet itrable asynchrone

Lorsque items est un itrable asynchrone, l'entre de mapFn n'est pas attendue, mais la sortie l'est. En utilisant la mme fonction createAsyncIter que ci-dessus :

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

Curieusement, cela signifie que Array.fromAsync(createAsyncIter()) n'est pas quivalent Array.fromAsync(createAsyncIter(), (element) => element), car la seconde attend chaque valeur produite, alors que la premire ne le fait pas.

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

Comparaison avec Promise.all()

Array.fromAsync() attend chaque valeur produite par l'objet de faon squentielle. Promise.all() attend toutes les valeurs en parallle.

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
})();

Fermer les itrables synchrones en cas de rejet

Comme pour for await...of, si l'objet parcouru est un itrable synchrone et qu'une promesse produite est rejete, la mthode return() de l'itrateur sous-jacent est appele, si elle existe, afin de permettre l'itrateur d'effectuer son nettoyage.

function* generatorWithRejectedPromises() {
  try {
    yield 0;
    yield Promise.reject(new Error("error"));
  } finally {
    console.log("appel final");
  }
}

(async () => {
  try {
    await Array.fromAsync(generatorWithRejectedPromises());
  } catch (e) {
    console.log("caught", e);
  }
})();
// appel final
// intercept Error: error

Spcifications

Compatibilit des navigateurs

Voir aussi

• Guide des collections indexes
• L'objet natif Array
• La mthode Array()
• La mthode Array.of()
• La mthode Array.from()
• L'instruction for await...of
• La prothse d'mulation de Array.fromAsync dans core-js (angl.)