Array.prototype.groupBy()

callbackFn

Une fonction à exécuter pour chaque élément du tableau

La fonction est appelée avec les arguments suivants :

element

La valeur de l'élément courant du tableau.

index

L'indice de l'élément courant du tableau.

array

Le tableau sur lequel groupBy() a été appelée.

L'objet renvoyé par la fonction de rappel indique le groupe de l'élément courant. Il doit être possible de convertir la valeur fournie par le callback en une chaîne de caractères (celle-ci étant ensuite utilisée comme le nom d'une propriété de l'objet renvoyé par la méthode).

thisArg Facultatif

L'objet qui doit être utilisé comme valeur this au sein de callbackFn.

Cet argument est ignoré pour les fonctions fléchées, celles-ci ayant leur propre portée lexicale. Sinon, si thisArg n'est pas fourni, c'est le this de la portée d'exécution qui est utilisé ou undefined si la fonction est appelée en mode strict.

Un objet contenant une propriété pour chacun des groupes. Chaque propriété a pour valeur un tableau contenant les éléments du groupe associé. Cet objet n'hérite pas de Object.prototype.

TypeError

La fonction de rappel passée en argument ne peut pas être appelée.

La méthode groupBy() exécute la fonction callbackFn pour chaque indice du tableau et renvoie une chaîne de caractères (ou une valeur pouvant être convertie en chaîne de caractères) qui indique le groupe de l'élément à cet indice. Pour chaque nom de groupe renvoyé par la fonction de rappel, une nouvelle propriété et un nouveau tableau sont créés sur l'objet résultant et chaque élément est ajouté au tableau de la propriété correspondant à son groupe.

On notera que l'objet ainsi créé porte des références vers les mêmes éléments que le tableau original (il ne s'agit pas de copies profondes (en-US)). Toute modification de la structure interne de ces éléments sera visible à la fois sur le tableau original et sur la valeur de retour.

callbackFn est appelée avec la valeur de l'élément courant, l'indice courant et le tableau lui-même. Bien que les groupes constitués dépendent la plupart du temps de la seule valeur de l'élément, il est possible d'implémenter des méthodes de groupement prenant en compte les valeurs des autres éléments du tableau.

callbackFn est appelée pour chaque indice du tableau et pas uniquement ceux pour lesquels des valeurs sont affectées. Cela signifie que cette méthode pour les tableaux peu densément peuplés, contrairement aux méthodes qui visitent uniquement les valeurs affectées.

Si le paramètre thisArg est fourni à groupBy(), il sera utilisé comme valeur pour this à chaque appel de callbackFn. S'il n'est pas fourni, c'est undefined qui sera utilisé.

La méthode groupBy() ne modifie pas le tableau sur lequel elle est appelée, mais la fonction callbackFn peut le modifier. On notera toutefois que les éléments traités par groupBy() sont déterminés avant le premier appel à callbackFn.

Ainsi :

• callbackFn ne parcourra pas les éléments ajoutés au tableau après le début de l'appel à groupBy().
• Les éléments qui sont affectés à des indices déjà parcourus ou à des indices en dehors de ceux du tableau ne seront pas parcourus par callbackFn.
• Si un élément existant, mais pas encore parcouru, est modifié par callbackFn, la valeur passée à callbackFn sera celle de l'élément au moment du parcours de l'indice correspondant.
• Les éléments supprimés sont toujours parcourus.

On définit ici un tableau contenant des objets décrivant un inventaire de différents produits alimentaires. Chaque produit possède une propriété type et une propriété quantite.

const inventaire = [
  { nom: 'asperges', type: 'legumes', quantite: 5 },
  { nom: 'bananes',  type: 'fruit', quantite: 0 },
  { nom: 'brebis', type: 'viande', quantite: 23 },
  { nom: 'cerises', type: 'fruit', quantite: 5 },
  { nom: 'poisson', type: 'viande', quantite: 22 }
];

Le code qui suit permet de regrouper les éléments selon la valeur de leur propriété type.

const resultat = inventaire.groupBy( ({type}) => type );

/* resultat vaudra :
{
  legumes: [
    { nom: 'asperges', type: 'legumes', quantite: 5 },
  ],
  fruit: [
    { nom: "bananes", type: "fruit", quantite: 0 },
    { nom: "cerises", type: "fruit", quantite: 5 }
  ],
  viande: [
    { nom: "brebis", type: "viande", quantite: 23 },
    { nom: "poisson", type: "viande", quantite: 22 }
  ]
}
*/

La fonction fléchée renvoie uniquement le type de chaque élément du tableau lorsqu'elle est appelée. La forme de l'argument { type } est un exemple de décomposition d'un objet pour les arguments d'une fonction. Cela extrait la propriété type de l'objet passé en paramètre et l'affecte à une variable intitulée type dans le corps de la fonction. On accède ainsi de façon concise aux propriétés voulues des éléments au sein de la fonction.

On peut aussi créer des groupes déterminés à partir des valeurs de plusieurs propriétés des éléments. L'exemple qui suit est similaire au précédent, mais répartir les produits en deux groupes : ok ou restock en fonction de la valeur portée par la propriété quantite.

function maFonctionDeRappel({quantite}) {
  return quantite > 5 ? 'ok' : 'restock';
}

const resultat = inventaire.groupBy(maFonctionDeRappel);

/* resultat vaudra :
{
  restock: [
    { nom: "asperges", type: "legumes", quantite: 5 },
    { nom: "bananes", type: "fruit", quantite: 0 },
    { nom: "cerises", type: "fruit", quantite: 5 }
  ],
  ok: [
    { nom: "brebis", type: "viande", quantite: 23 },
    { nom: "poisson", type: "viande", quantite: 22 }
  ]
}
*/

• Array.prototype.groupByToMap() qui groupe un tableau sous forme d'un objet Map où n'importe quelle valeur peut être une clé ou une valeur.
• Une prothèse d'émulation pour Array.prototype.groupBy() avec la bibliothèque core-js