Map : méthode groupBy()
Baseline
2024
Newly available
Depuis March 2024, cette fonctionnalité fonctionne sur les appareils et les versions de navigateur les plus récents. Elle peut ne pas fonctionner sur les appareils ou navigateurs plus anciens.
Note :
Dans certaines versions de certains navigateurs, cette méthode a été implémentée sous le nom Array.prototype.groupToMap(). En raison de problèmes de compatibilité web, elle est désormais implémentée comme une méthode statique. Consultez le tableau de compatibilité des navigateurs pour plus de détails.
La méthode statique Map.groupBy() regroupe les éléments d'un itérable donné en utilisant les valeurs retournées par une fonction de rappel fournie. L'objet Map retourné utilise les valeurs uniques de la fonction de test comme clés, qui permettent d'obtenir le tableau des éléments de chaque groupe.
Cette méthode est principalement utile pour regrouper des éléments associés à un objet, en particulier lorsque cet objet peut évoluer au fil du temps. Si l'objet est invariant, il est possible de le représenter par une chaîne de caractères et de regrouper les éléments avec Object.groupBy().
Exemple interactif
const inventory = [
{ name: "asperge", type: "legumes", quantity: 9 },
{ name: "banane", type: "fruit", quantity: 5 },
{ name: "chevre", type: "viande", quantity: 23 },
{ name: "cerises", type: "fruit", quantity: 12 },
{ name: "poisson", type: "viande", quantity: 22 },
];
const restock = { restock: true };
const sufficient = { restock: false };
const result = Map.groupBy(inventory, ({ quantity }) =>
quantity < 6 ? restock : sufficient,
);
console.log(result.get(restock));
// [{ name: "banane", type: "fruit", quantity: 5 }]
Syntaxe
Map.groupBy(items, callbackFn)
Paramètres
items-
Un itérable (comme un objet
Array) dont les éléments seront groupés. callbackFn-
Une fonction à exécuter pour chaque élément de l'itérable. Elle doit retourner une valeur (objet ou valeur primitive) indiquant le groupe de l'élément courant. La fonction est appelée avec les arguments suivants :
Valeur de retour
Un objet Map avec une clé pour chaque groupe, chacune associée à un tableau contenant les éléments du groupe correspondant.
Description
Map.groupBy() appelle la fonction callbackFn fournie une fois pour chaque élément d'un itérable. La fonction de rappel doit retourner une valeur indiquant le groupe de l'élément associé. Les valeurs retournées par callbackFn sont utilisées comme clés pour l'objet Map retourné par Map.groupBy(). Chaque clé est associée à un tableau contenant tous les éléments pour lesquels la fonction de rappel a retourné la même valeur.
Les éléments de l'objet Map retourné et de l'itérable d'origine sont les mêmes (il ne s'agit pas de copies profondes). Toute modification de la structure interne des éléments sera répercutée à la fois dans l'itérable d'origine et dans l'objet Map retourné.
Cette méthode est utile lorsque vous devez regrouper des informations associées à un objet particulier qui peut potentiellement changer au fil du temps. En effet, même si l'objet est modifié, il continuera de fonctionner comme clé pour la Map retournée. Si vous créez plutôt une représentation sous forme de chaîne de caractères pour l'objet et que vous l'utilisez comme clé de regroupement dans Object.groupBy(), vous devrez maintenir la correspondance entre l'objet original et sa représentation lorsque l'objet change.
Note :
Pour accéder aux groupes dans la Map retournée, vous devez utiliser le même objet que celui qui a été initialement utilisé comme clé dans la Map (même si vous pouvez modifier ses propriétés). Vous ne pouvez pas utiliser un autre objet qui aurait simplement le même nom et les mêmes propriétés.
Map.groupBy ne lit pas la valeur de this. Elle peut être appelée sur n'importe quel objet et une nouvelle instance de Map sera retournée.
Exemples
Utiliser Map.groupBy()
On définit un tableau contenant des objets qui représentent un inventaire alimentaire. Chaque type d'aliment a une propriété type et une propriété quantite.
const inventaire = [
{ nom: "asperge", type: "legume", quantite: 9 },
{ nom: "banane", type: "fruit", quantite: 5 },
{ nom: "agneau", type: "viande", quantite: 23 },
{ nom: "cerise", type: "fruit", quantite: 12 },
{ nom: "poisson", type: "viande", quantite: 22 },
];
Le code ci-dessous utilise Map.groupBy() avec une fonction fléchée qui retourne les objets clés nommés restock ou sufficient, selon que l'élément a quantity < 6. L'objet result retourné est une Map, il faut donc appeler get() avec la clé pour obtenir le tableau.
const restock = { restock: true };
const suffisant = { restock: false };
const resultat = Map.groupBy(inventaire, ({ quantite }) =>
quantite < 6 ? restock : suffisant,
);
console.log(resultat.get(restock));
// résultat attendu : Array [Object { nom: "banane", type: "fruit", quantite: 5 }]
Ici, l'argument { quantite } passé à la fonction est un exemple de décomposition objet pour les arguments d'une fonction. Cela récupère la propriété quantite de l'objet passé en paramètre et affecte cette valeur à une variable nommée quantite dans le corps de la fonction. Il s'agit d'une écriture concise pour accéder aux valeurs des propriétés pertinentes d'un objet dans une fonction.
La clé d'un objet Map peut être modifiée et continuer d'être utilisée. Toutefois, on ne peut pas recréer un autre objet ayant la même structure que la clé et l'utiliser. Il est donc important que tout ce qui doit utiliser la Map garde une référence vers ses clés.
// La clé peut être modifiée et continuer d'être utilisée
restock["rapide"] = true;
console.log(resultat.get(restock));
// résultat attendu : Array [Object { nom: "banane", type: "fruit", quantite: 5 }]
// Une nouvelle clé ne peut pas être utilisée, même si elle a la même structure !
const restock2 = { restock: true };
console.log(resultat.get(restock2));
// résultat attendu : undefined
Spécifications
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-map.groupby |