Destructuring em JavaScript: objetos, arrays e defaults

Destructuring em JavaScript: casamento de padrões sobre estruturas

A desestruturação (destructuring) permite escrever um padrão que espelha o formato de um objeto ou array e, em uma única linha, extrair valores por nome ou posição. Em vez de acessar propriedade por propriedade, você descreve o que quer e o JavaScript entrega.

Os dois sabores são:

const user = { name: "Ada", age: 36 };
const { name, age } = user;
console.log(name, age);

const scores = [90, 85, 72];
const [first, second, third] = scores;
console.log(first, second, third);

As chaves fazem o match com um objeto pelo nome da propriedade. Os colchetes fazem o match com um array pela posição. Nos dois casos, as variáveis antes do = são novas declarações — você não está indexando o valor, está descrevendo um padrão que extrai as partes.

Antes do destructuring existir, esse mesmo código ficava assim:

const name = user.name;
const age = user.age;
const first = scores[0];
const second = scores[1];

Não é o fim do mundo, mas vira uma repetição chata quando você faz isso em toda função.

Desestruturação de objetos usa o nome das propriedades

No caso de objetos, os nomes dentro das chaves precisam bater com as propriedades do objeto de origem. A ordem não importa — o JavaScript faz a busca pela chave.

const book = {
    title: "The Pragmatic Programmer",
    author: "Hunt & Thomas",
    year: 1999,
};

const { year, title } = book;
console.log(title, year);

Quando a propriedade não existe no objeto, a variável fica como undefined — sem erro nenhum:

const book = { title: "Refactoring" };
const { title, author } = book;
console.log(title);
console.log(author);

Esse comportamento silencioso de retornar undefined é importante ter em mente quando um errinho de digitação no nome da propriedade te deixa quebrando a cabeça às duas da manhã.

Renomeando variáveis no destructuring

Às vezes o nome da propriedade no objeto não é o nome que você quer pra variável — ou porque conflita com algo que já existe no escopo, ou porque a API usa uma convenção de nomenclatura que não te agrada. Use nomeOriginal: novoNome para renomear:

const response = { id: 42, msg: "ok" };
const { id: userId, msg: message } = response;

console.log(userId, message);

Leia como "pega a propriedade id e chama de userId." O nome da propriedade vem antes, o nome da nova variável depois dos dois-pontos. Parece anotação de tipo de outras linguagens — mas não é.

Destructuring com valor padrão

Quando uma propriedade pode não existir, já defina um valor padrão direto no próprio padrão de desestruturação:

function connect(options) {
    const { host = "localhost", port = 5432, timeout = 5000 } = options;
    console.log(`conectando em ${host}:${port} (timeout ${timeout}ms)`);
}

connect({ host: "db.example.com" });
connect({});

Os valores padrão só entram em ação quando a propriedade é undefined. Já null, 0 e "" passam direto, sem acionar o default:

const { retries = 3 } = { retries: null };
console.log(retries);

Essa pega muita gente. Se você quiser que null também dispare o valor padrão, precisa fazer uma checagem explícita — ou usar o operador de coalescência nula ?? depois de desestruturar.

Dá pra combinar valor padrão com renomeação:

const { host: hostname = "localhost" } = {};
console.log(hostname);

Destructuring de arrays usa a posição

Arrays não têm nomes, apenas índices — por isso o padrão casa por posição. Use vírgulas para pular os valores que não te interessam:

const coords = [40.7, -74.0, 10];
const [lat, lon] = coords;
console.log(lat, lon);

const [, , altitude] = coords;
console.log(altitude);

As duas vírgulas no começo dizem "pula o índice 0 e o 1". Fica um pouco denso visualmente, mas quebra um galho enorme quando você só quer um valor lá do meio.

O destructuring de arrays brilha mesmo em funções que devolvem tuplas:

function minMax(nums) {
    return [Math.min(...nums), Math.max(...nums)];
}

const [low, high] = minMax([5, 2, 9, 1, 7]);
console.log(low, high);

O mesmo padrão aparece o tempo todo nos hooks do React: const [count, setCount] = useState(0).

Rest pattern: juntando o que sobrou

Dentro de um padrão de desestruturação, ...nome reúne em uma nova variável tudo o que não foi capturado por nome ou posição.

No caso de arrays, o rest pega o final:

const [head, ...tail] = [1, 2, 3, 4, 5];
console.log(head);
console.log(tail);

Já em objetos, o rest captura todas as propriedades que não foram nomeadas explicitamente:

const user = { id: 1, name: "Ada", email: "ada@example.com", role: "admin" };
const { id, ...rest } = user;

console.log(id);
console.log(rest);

Essa é a forma idiomática de remover um campo de um objeto sem mutá-lo — rest é um novo objeto com tudo, exceto id.

O rest precisa ser o último elemento do padrão. const [...init, last] gera erro de sintaxe.

Destructuring aninhado

Os padrões podem ser aninhados. Se uma propriedade é, ela mesma, um objeto ou array, dá para desestruturar direto na mesma expressão:

const response = {
    status: 200,
    data: {
        user: { name: "Ada", age: 36 },
        tags: ["admin", "beta"],
    },
};

const {
    status,
    data: {
        user: { name },
        tags: [primaryTag],
    },
} = response;

console.log(status, name, primaryTag);

Poderoso, mas use com cautela. Três níveis de chaves aninhadas já começam a parecer um quebra-cabeça. Quando chegar nesse ponto, extraia valores intermediários para variáveis próprias — legibilidade vale mais do que esperteza.

Uma pegadinha: data: { user } no padrão não cria uma variável chamada data. Isso é uma instrução dizendo "entre em data e continue desestruturando". Se você precisa do próprio data, adicione separadamente:

const response = { data: { user: { name: "Ada" } } };
const { data, data: { user } } = response;
console.log(data);
console.log(user);

Desestruturação nos parâmetros de função

O lugar onde você mais vai usar destructuring no dia a dia é na lista de parâmetros de uma função. Isso transforma aquele clássico "passa um objeto de opções" numa assinatura que já se documenta sozinha:

function createUser({ name, email, role = "member", active = true }) {
    console.log({ name, email, role, active });
}

createUser({ name: "Ada", email: "ada@example.com" });
createUser({ name: "Boris", email: "b@example.com", role: "admin" });

No ponto da chamada, parece uma função comum que recebe um objeto de opções. Só que, dentro da função, você já ganha variáveis nomeadas com valores padrão — chega daquele options.name || "default" repetido toda hora.

Tem uma pegadinha: chamar essa função sem argumento quebra tudo, porque não dá pra desestruturar undefined. A solução é dar um valor padrão pro parâmetro inteiro:

function createUser({ name = "anon", role = "member" } = {}) {
    console.log(name, role);
}

createUser();

O = {} depois do padrão diz o seguinte: "se nenhum argumento for passado, finge que veio um objeto vazio". A partir daí, os valores padrão internos assumem o controle.

Trocando e reatribuindo valores

O destructuring também funciona com variáveis já declaradas, mas é preciso envolver o padrão do objeto em parênteses (caso contrário, o JavaScript interpreta o { como o início de um bloco):

let a = 1;
let b = 2;

[a, b] = [b, a];
console.log(a, b);

let user = { name: "Ada" };
({ name: user.name } = { name: "Boris" });
console.log(user);

O swap de arrays fica limpo demais. Já reatribuir objetos é mais raro, mas vale guardar o truque dos parênteses para quando precisar.

Um exemplo do mundo real

Juntando boa parte do que vimos até aqui — uma função que processa uma resposta de API:

function summarise({
    status,
    data: { items = [] } = {},
    meta: { total = 0 } = {},
} = {}) {
    const [firstItem, ...rest] = items;
    return {
        ok: status === 200,
        first: firstItem?.name ?? "nenhum",
        remaining: rest.length,
        total,
    };
}

console.log(summarise({
    status: 200,
    data: { items: [{ name: "alpha" }, { name: "beta" }, { name: "gamma" }] },
    meta: { total: 3 },
}));

console.log(summarise());

Cada camada desestruturada tem um valor padrão, então a função sobrevive a dados incompletos sem uma pilha de if para proteger cada caso. Esse é o ganho de verdade: assinaturas ao mesmo tempo precisas e tolerantes.

Próximo passo: spread de objetos

A desestruturação tira valores de dentro de objetos. Já o spread faz o oposto — copia, mescla e sobrescreve. Os dois andam juntos no JavaScript moderno, e o spread é o nosso próximo tema.