colocando comentários legais

agrupador_magico.js

//pessoas é apenas um caso de teste, esse array pode ser até jabota_a_jato_detona_geral
const pessoas = [
  { nome: "maria", idade: 20, cidade: "Goiania" },
  { nome: "joao", idade: 20, cidade: "São Paulo" },
  { nome: "maria", idade: 38, cidade: "Goiania" },
  { nome: "maria", idade: 38, cidade: "Goiania" },
  { nome: "maria", idade: 38, cidade: "Goiania" },
  { nome: "maria", idade: 38, cidade: "Goiania" },
  { nome: "maria", idade: 38, cidade: "Goiania" },
  { nome: "maria", idade: 38, cidade: "Goiania" },
  { nome: "maria", idade: 38, cidade: "Goiania" },
  { nome: "joao", idade: 38, cidade: "Santana do Araguaia" },
  { nome: "maria", idade: 37, cidade: "São Paulo" },
  { nome: "joao", idade: 41, cidade: "São Paulo" },
  { nome: "rafael", idade: 37, cidade: "Santana do Araguaia" },
  { nome: "joana", idade: 37, cidade: "São Paulo" },
  { nome: "rafael", idade: 41, cidade: "Goiania" },
  { nome: "joana", idade: 38, cidade: "Goiania" },
  { nome: "maria", idade: 37, cidade: "São Paulo" },
  { nome: "joao", idade: 38, cidade: "São Paulo" }
];

//abaixo umas documentações legais q o erick gosta de usar, sdds Erick 2018 ★ - 2020 †

/**
 *
 * @param props props é um array de strings, quem chamou definiu um array com strings dentro
 */
const groupBy = (props, pessoas) => {
  let agrupados = [];

  if (props && props.length > 0) {
    //estou assumindo que prop é uma propriedade do objeto Pessoa, suponho o usuario dessa função conheça o objeto a ser agrupado
    let prop = props.shift();
    //ordem dos elementos do reduce: acumulador: grupos, elemento atual: pessoa
    agrupados = pessoas.reduce((grupos, pessoa) => {
      let valorAtual = pessoa[prop];
      //findIndex sempre roda passando uma função como parametro q retorna booleana
      let indexValorAtual = grupos.findIndex(g => {
        //estou procurando um header (cabeça do agrupamento) que seja igual o valor atual
        return g.header === valorAtual;
      });
      //se ja existir algum grupo com esse mesmo header no array, o indexValorAtual vai ser > 0
      //caso contrário, o index vai pro estagio de criação de um novo grupo, com o elemento atual dentro
      //tecnicamente o grupo nasce aqui
      if (indexValorAtual === -1) {
        grupos.push({
          //header é pra referenciar o titulo/tag do meu grupo
          header: valorAtual,
          //os filhos de fato os itens ou os subgrupos que pertencem a esse agrupamento
          filhos: [pessoa]
        });
      } else {
        //no caso de ja existir um grupo criado, eu vou adicionar esse atual elemento no grupo existente
        grupos[indexValorAtual].filhos.push(pessoa);
      }
      //aqui so retorno os grupos mesmo
      return grupos;
      //to iniciando o reduce com um array pq eu quero gerar grupos, e não acumular um valor de fato
      //o objetivo do reduce geralmente é acumular, nesse caso eu quero acumular segmentando
    }, []);
    // essa ultima fase garante a recursividade, aplicao a função groupBy a cada grupo no array de grupos
    agrupados.forEach(item => {
      if (props.length >= 1) {
        // o array de props está com uma prop a menos, que consumimos na execução atual
        item.filhos = groupBy(props, item.filhos);
      }
    });
  } else
    console.log(
      'vc esqueceu de passar um array de props preenchido... ["nome", "idade", ...]'
    );
  //aqui retorno o que foi de fato agrupado
  return agrupados;
};