Objetos e JSON

Um objeto agrupa valores relacionados sob nomes. Cada propriedade associa uma chave a um valor. Use um objeto para um registro e um vetor de objetos para uma lista ordenada. Vetores paralelos podem perder seu alinhamento quando apenas um deles é ordenado ou alterado.

Crie e leia um registro

const book = { title: "Dune", pages: 412, available: true };
book.title;    // "Dune"
book["title"]; // "Dune"

Valores de propriedades podem ser vetores, objetos ou funções, além de valores primitivos. Chaves são cadeias de caracteres ou símbolos; estes exemplos usam cadeias de caracteres. Chaves de cadeia de caracteres que são identificadores válidos não precisam de aspas. Chaves que contêm espaços ou hífens precisam de aspas: { "release-year": 1965 }. Chaves numéricas tornam-se cadeias de caracteres, então { 1: "a" } tem a chave "1". Literais de objeto permitem uma vírgula final.

O acesso por ponto usa o nome literal após o ponto. O acesso por colchetes avalia uma expressão:

const field = "pages";
book[field]; // 412
book.field;  // undefined

A segunda expressão procura uma propriedade chamada "field". Colchetes também permitem usar book["release-year"]. Uma propriedade ausente retorna undefined; continuar o acesso por ela, como em book.author.name, lança um TypeError quando author está ausente.

Altere o conteúdo do objeto

book.author = "Frank Herbert";
book.pages = 896;
delete book.available;

A atribuição adiciona uma propriedade ausente ou substitui um valor existente. A exclusão remove a própria propriedade, então "available" in book agora é falso. const mantém a variável vinculada a esse objeto, mas permite alterações em seu conteúdo.

Para const reading = { city: "Nairobi", tempC: 24.5 };, reading.tempC += 1.5; armazena 26. Em seguida, reading.humidity = 61; adiciona um campo. Com const key = "humidity";, reading[key] lê 61. Um nome como tempC deixa visível a unidade da medida.

Use variáveis em um literal

const name = "Lena";
const age = 29;
const person = { name, age };
const lang = "nl";
const greeting = { [lang]: "Hallo" };

A sintaxe abreviada { name, age } significa { name: name, age: age }. Um nome computado avalia a expressão dentro dos colchetes: greeting tem a propriedade "nl". Sem esses colchetes, { lang: "Hallo" } criaria a chave literal "lang".

Verificar se um campo existe é diferente de verificar seu valor. Uma cadeia de caracteres vazia, zero ou false pode ser um valor armazenado perfeitamente válido.

Faça a pergunta certa sobre existência

const item = { stock: 0, note: undefined };
Object.hasOwn(item, "stock"); // true
"note" in item;                // true
Boolean(item.stock);          // false

Object.hasOwn(obj, key) verifica apenas as propriedades próprias do objeto. O operador in também verifica propriedades herdadas: "toString" in {} é true, enquanto Object.hasOwn({}, "toString") é false. Código mais antigo costuma chamar obj.hasOwnProperty(key).

Uma condição como if (item.stock) testa se o valor é avaliado como verdadeiro. Ela não consegue distinguir um campo ausente de um campo presente que contém zero. O mesmo problema se aplica a "", false, null, undefined e NaN. Até mesmo um valor undefined pode pertencer a uma propriedade existente, como acontece com note acima.

Escolha chaves, valores ou pares

Para const scores = { Ana: 82, Ben: 74, Chen: 91 };, estas funções retornam vetores das propriedades próprias enumeráveis com chaves de cadeia de caracteres:

O objeto não tem tamanho como um vetor: scores.length é undefined. Object.keys(scores).length conta três propriedades. Para somar as pontuações, reduza os valores com zero como valor inicial. A soma é 247 e a média é aproximadamente 82,33.

Percorra com ambas as partes disponíveis

let bestName;
let bestScore = -Infinity;
for (const [name, score] of Object.entries(scores)) {
  if (score > bestScore) {
    bestName = name;
    bestScore = score;
  }
}

O laço compara 82, 74 e depois 91 com a maior pontuação encontrada até então. Ele termina com "Chen" e 91. O padrão entre colchetes dá nomes às duas partes de cada par.

Um objeto comum não é iterável, então for...of scores lança um TypeError. Object.entries(scores) fornece um vetor iterável. O laço mais antigo for...in produz chaves de cadeia de caracteres e pode incluir propriedades enumeráveis herdadas.

Transforme pares chave-valor novamente em um objeto

const weightsG = { flour: 500, sugar: 250, salt: 5 };
const weightsKg = Object.fromEntries(
  Object.entries(weightsG).map(([item, g]) => [item, g / 1000])
);

entries produz pares, map altera cada valor mantendo sua chave e fromEntries reconstrói o registro. O resultado é { flour: 0.5, sugar: 0.25, salt: 0.005 }; weightsG permanece inalterado.

A ordem das propriedades próprias é definida. Chaves de índice de vetor de "0" até "4294967294" aparecem primeiro em ordem crescente; as demais chaves de cadeia de caracteres seguem a ordem de inserção. Um zero à esquerda, como em "01", impede que uma chave seja um índice de vetor. Assim, Object.keys({ b: 1, 2: "x", a: 2, 1: "y" }) resulta em ["1", "2", "b", "a"]. Use um vetor quando as posições tiverem significado.

Duas variáveis podem se referir a um objeto. Antes de prever uma atualização, decida se o código criou um novo objeto ou copiou uma referência a um objeto existente.

Acompanhe a identidade separadamente dos dados

const p1 = { x: 1 };
const p2 = p1;
p2.x = 99;
p1.x;       // 99
p1 === p2;  // true

A atribuição copiou a referência. Ambos os nomes acessam a mesma propriedade. A atribuição de valores primitivos funciona de modo diferente: após let a = 5; let b = a; b = 6;, a continua sendo 5.

Objetos são comparados por identidade tanto com === quanto com ==. Dois literais criam objetos separados mesmo quando todos os campos coincidem: ({ x: 1 } === { x: 1 }) é false. Para comparar seus dados, compare as propriedades relevantes. Ter a mesma aparência quando impressos não é uma verificação de identidade.

Passar um objeto para uma função também copia sua referência. Uma função que executa order.status = "shipped"; altera o objeto de quem a chamou. Retornar { ...order, status: "shipped" } cria um novo registro no nível superior.

Distinga const, congelamento e cópia

const cart = { items: 2 }; permite cart.items = 3;, mas reatribuir com cart = {}; lança um TypeError. Object.freeze(cart) impede alterações em suas propriedades próprias. Em modo estrito, tentativas de adicioná-las, removê-las ou sobrescrevê-las lançam um TypeError.

O congelamento é superficial. Se um registro congelado contém outro objeto, os campos desse objeto aninhado ainda podem mudar. Um contêiner congelado e uma estrutura completamente imutável são coisas diferentes.

Acompanhe uma cópia superficial

const settings = { theme: "dark", font: { size: 14 } };
const copy = { ...settings };
copy.theme = "light";
copy.font.size = 18;

O espalhamento cria um novo objeto externo. Seu valor theme é copiado, então alterar copy.theme mantém settings.theme como "dark". Seu valor font é uma referência, copiada para ambos os registros. Atualizar copy.font.size também faz settings.font.size ser igual a 18.

Object.assign({}, settings) também faz uma cópia superficial. Uma cópia superficial separa o registro externo, mantendo a identidade dos objetos e vetores aninhados.

Copie dados aninhados quando precisarem ser independentes

const deep = structuredClone(settings);
deep.font.size = 22;
settings.font.size; // 18

structuredClone copia objetos e vetores aninhados, além de valores compatíveis como Map, Set e Date. Ele também trata referências circulares. O novo font aninhado pode mudar independentemente. Funções não podem ser clonadas dessa maneira: um objeto que contém um método causa um DataCloneError.

Uma conversão de ida e volta por JSON, JSON.parse(JSON.stringify(obj)), copia apenas dados compatíveis com JSON. Ela descarta propriedades de objeto que contêm undefined ou funções, transforma datas em cadeias de caracteres e perde entradas de Map e Set, a menos que você os converta. Escolha uma clonagem para obter dados JavaScript compatíveis e independentes e escolha JSON quando quiser criar uma representação em texto.

Dados aninhados combinam registros e listas. Leia um caminho uma etapa por vez, verificando se cada etapa chega a um objeto, um vetor ou um valor final.

Leia e processe uma lista dentro de um registro

const order = {
  id: 1042,
  customer: { name: "Sara", city: "Lisbon" },
  items: [
    { product: "Tea", qty: 2, unitPrice: 4.5 },
    { product: "Mug", qty: 1, unitPrice: 9 }
  ]
};

order.customer.city lê "Lisbon". order.items[1].product primeiro seleciona o vetor de itens, depois seu segundo registro e então "Mug". order.items.length é 2.

Os métodos de vetor que você já conhece funcionam com propriedades de registros. map(item => item.product) produz nomes de produtos. filter(item => item.qty > 1) mantém o item de chá. find(item => item.product === "Mug") retorna o registro existente da caneca, então alterar o registro retornado altera o item no pedido.

Para calcular o total, use order.items.reduce((sum, item) => sum + item.qty * item.unitPrice, 0). O primeiro item adiciona 9; o segundo adiciona mais 9, produzindo 18. Calcular um total quando necessário impede que um total armazenado separadamente fique desatualizado quando os itens mudarem.

Leia dados opcionais com uma alternativa de contingência

order.shipping?.date;                 // undefined
order.customer?.city ?? "unknown";    // "Lisbon"

O encadeamento opcional, ?., para quando o valor imediatamente à sua esquerda é null ou undefined. Um acesso direto order.shipping.date lançaria um TypeError. Use uma verificação em cada parte opcional de um caminho mais longo. O acesso por colchetes e as chamadas também aceitam esse recurso: order.items?.[0] e order.print?.().

O encadeamento opcional é para valores que podem estar ausentes. Campos obrigatórios ainda precisam de verificações ou erros que revelem um registro inválido. Ele não pode aparecer à esquerda de uma atribuição: order.shipping?.date = "2026-05-01" é um erro de sintaxe.

O operador de coalescência nula, ??, usa seu lado direito apenas para null ou undefined. Ele preserva zero, false e "". Para const qty = 0;, qty ?? 1 continua sendo zero, enquanto qty || 1 se torna 1 porque || substitui todo valor avaliado como falso.

Escolha uma estrutura útil

Um vetor de registros é adequado para listagem, filtragem e ordenação. Um objeto indexado por ID permite consulta direta: usersById["u23"].name. Um Map é útil quando chaves de consulta são adicionadas e removidas com frequência.

O JavaScript mais recente oferece Object.groupBy, amplamente disponível desde 2024:

const tasks = [
  { title: "Book flights", status: "done" },
  { title: "Pack", status: "todo" },
  { title: "Renew passport", status: "done" }
];
const grouped = Object.groupBy(tasks, task => task.status);

grouped.done contém dois registros e grouped.todo contém um. O resultado não tem protótipo, então não tem o método herdado toString. Uma alternativa mais antiga constrói os vetores explicitamente para essas chaves de status:

const groupedOlder = tasks.reduce((groups, task) => {
  if (!Object.hasOwn(groups, task.status)) {
    groups[task.status] = [];
  }
  groups[task.status].push(task);
  return groups;
}, {});

O primeiro registro de cada grupo cria seu vetor. Os registros seguintes são adicionados a esse mesmo vetor. Esse acumulador é um objeto comum; o resultado do método mais recente não tem protótipo. Use nomes e tipos de valor consistentes entre registros; nomes como distanceKm e tempC também mantêm as unidades visíveis.

Um método é uma propriedade cujo valor é uma função chamada por meio de um objeto. Ele permite que uma ação use os dados atuais do registro.

Escreva um método com this

const counter = {
  count: 0,
  increment() {
    this.count += 1;
    return this.count;
  }
};
counter.increment(); // 1
counter.increment(); // 2

A sintaxe abreviada increment() { ... } define uma propriedade cujo valor é uma função comum. Em counter.increment(), o objeto receptor counter se torna this. Cada chamada lê a contagem armazenada, adiciona um e retorna o novo número.

Um count isolado seleciona uma variável, não a propriedade. Sem uma variável correspondente, count += 1 lança um ReferenceError. Use this.count para acessar o campo do objeto receptor.

Leia uma função ou execute-a

counter.increment lê um valor do tipo "function". Os parênteses em counter.increment() executam a função e fornecem seu valor de retorno. Ao passar uma ação para uso posterior, o código que a recebe precisa da função, não do resultado de executá-la agora.

Métodos nativos também usam essa forma de chamada: Math.max(3, 7) retorna 7 e "abc".toUpperCase() retorna "ABC".

Reutilize uma ação

function describe() {
  return this.name + " (" + this.year + ")";
}
const film = { name: "Up", year: 2009, describe };
const song = { name: "Hello", year: 2015, describe };

film.describe() retorna "Up (2009)"; song.describe() retorna "Hello (2015)". Usar this permite que a mesma função leia qualquer um dos objetos receptores. Fixar film.name no código a vincularia à variável film.

Retorne o objeto receptor para outra ação

const playlist = {
  tracks: [],
  add(title) { this.tracks.push(title); return this; },
  count() { return this.tracks.length; }
};
playlist.add("Rain").add("Waves").count(); // 2

Cada chamada de add retorna a lista de reprodução, permitindo procurar o próximo método nesse objeto. Retornar um número de add quebraria a cadeia, pois o próximo add seria procurado nesse número.

A conversão comum para JSON omite métodos: converter { name: "Kit", hi() { return 1; } } em texto escreve apenas name. A análise sintática não consegue restaurar código omitido. Registros para salvar ou trocar frequentemente mantêm dados simples e usam funções de processamento separadas.

Para uma função comum, a chamada determina this. Armazenar uma função em um objeto não a vincula permanentemente a esse objeto.

Acompanhe o objeto receptor na chamada

const a = { n: "A", who() { return this.n; } };
const b = { n: "B" };
b.who = a.who;
a.who(); // "A"
b.who(); // "B"

Ambas as propriedades contêm a mesma função. O objeto receptor antes do ponto é diferente, então os resultados são diferentes. O local original da função não determina qual objeto ela lê.

Para uma chamada simples, f(), o modo estrito fornece undefined como this. Módulos JavaScript sempre são executados em modo estrito; um script ou função também pode começar com "use strict";. Uma função comum não estrita chamada de forma simples usa o objeto global, globalThis. Em um navegador, esse objeto global é window.

Reconheça o contexto ao redor de uma função de seta

Uma função de seta não tem this próprio. Ela mantém o this do código ao redor do local onde foi criada. Um literal de objeto não cria um novo contexto de this.

// At the top level of a module:
const user = {
  name: "Ida",
  hi: () => "Hi, " + this.name
};

Chamar user.hi() lança um TypeError: a função de seta capturou o this do nível superior do módulo, que é undefined. Alterar a chamada para que pareça um método não pode dar um novo objeto receptor à função de seta. No nível superior de um script clássico, o this ao redor é o objeto global.

Use um método comum quando a ação precisar do objeto que faz a chamada. Use uma função de seta dentro desse método quando uma função de retorno precisar manter o contexto do método:

const group = {
  title: "Team",
  members: ["Ana", "Ben"],
  list() {
    return this.members.map(m => this.title + ": " + m);
  }
};
group.list(); // ["Team: Ana", "Team: Ben"]

list recebe group de sua chamada de método. A função de seta é criada dentro desse método em execução e mantém o mesmo this. Uma função de retorno comum em modo estrito, sem um objeto receptor fornecido, receberia undefined, então this.title falharia nela.

Use uma ordem de decisão

Quando encontrar uma chamada, primeiro identifique a função que está sendo chamada:

1. Uma função de seta mantém o this ao seu redor; call, apply e bind não podem substituí-lo.
2. Uma função comum vinculada mantém seu this vinculado, mesmo com call ou apply.
3. Uma função comum não vinculada chamada com call ou apply usa o this fornecido.
4. Uma chamada comum obj.method() usa obj.
5. Uma chamada simples de função comum usa undefined em modo estrito ou o objeto global em modo não estrito.

Funções de retorno podem receber um objeto receptor de quem as chama. Por exemplo, um ouvinte de evento DOM comum registrado com addEventListener recebe como this o elemento no qual está registrado. Veja como o código que recebe uma função de retorno a chama antes de supor que se trata de uma chamada simples.

Extrair um método de seu objeto preserva a função, mas perde a expressão de chamada original. Uma função de retorno deve ser chamada de uma forma que forneça o objeto de que ela precisa.

Diagnostique um método desvinculado

const counter = {
  count: 0,
  increment() {
    this.count += 1;
    return this.count;
  }
};
const inc = counter.increment;
inc(); // TypeError in strict mode

inc() é uma chamada simples, então this é undefined. A leitura de this.count falha antes que um incremento possa ocorrer. Em código não estrito, uma chamada simples usa o objeto global e pode escrever em um count global; ela não acessa o contador.

O mesmo problema aparece em funções de retorno de vetores. [1, 2].map(counter.increment) fornece uma função a map sem seu objeto receptor original. Os valores do vetor passados como argumentos não fornecem this.

Envolva a chamada do método

const results = [1, 2].map(() => counter.increment());
// results is [1, 2]; counter.count is 2

A função de retorno é uma função de seta que faz uma chamada normal de counter.increment(). Essa chamada tem um objeto receptor. A função envoltória ignora deliberadamente os valores passados por map; cada chamada apenas incrementa uma vez. Essa forma é conveniente quando a função de retorno é necessária em um único uso.

Vincule uma função reutilizável

Começando com um novo contador em zero:

const boundInc = counter.increment.bind(counter);
const results = [1, 2].map(boundInc);
// results is [1, 2]; counter.count is 2

bind retorna uma nova função; ele ainda não chama o método. A nova função mantém counter como seu objeto receptor. Vinculá-la novamente a outro objeto não pode substituir esse receptor. Cada chamada de bind cria uma função distinta, então salve o resultado quando o código precisar reconhecer exatamente a mesma função de retorno mais tarde.

A vinculação também pode fixar argumentos iniciais. function multiply(a, b) { return a * b; } seguido de const double = multiply.bind(null, 2); faz double(21) retornar 42. null ocupa a posição do objeto receptor porque essa função não usa this; 2 ocupa seu primeiro parâmetro comum.

Execute uma vez com call ou apply

function describe(unit) {
  return this.value + " " + unit;
}
describe.call({ value: 12 }, "kg");    // "12 kg"
describe.apply({ value: 12 }, ["kg"]); // "12 kg"

Ambas as formas executam imediatamente com o objeto receptor escolhido. call fornece os argumentos separadamente; apply os fornece em um vetor. O contexto de uma função de seta é fixado pelo que a envolve, então esses métodos não podem substituir seu this.

Passar counter.increment() como função de retorno executa o método imediatamente e passa o número retornado. Esse não é o tipo de função de que map precisa. Em um registro de evento como button.addEventListener("click", counter.increment()), o contador muda imediatamente e o ouvinte numérico causa um TypeError. Passe uma função como valor, uma função envoltória de seta ou uma função vinculada armazenada.

A desestruturação de objetos lê campos nomeados para variáveis locais. Ela seleciona valores sem copiar todo o registro de origem.

Faça a correspondência e renomeie

const book = { title: "Dune", pages: 412 };
const { pages, title: bookTitle, rating: stars = 0 } = book;

A correspondência usa nomes de propriedades, não sua ordem. Isso declara pages como 412, bookTitle como "Dune" e stars como 0. Não declara variáveis title ou rating: o nome após os dois-pontos é a variável local de destino.

Um campo ausente fornece undefined. Um valor padrão substitui apenas undefined, preservando null, zero, false e cadeias de caracteres vazias. const { a = 5 } = { a: null }; deixa, portanto, a como null.

Acompanhe campos aninhados

const data = {
  location: { name: "Oslo" },
  current: { tempC: -3, windKph: 18 }
};
const {
  location: { name },
  current: { tempC, windKph: wind }
} = data;

As variáveis declaradas são name, tempC e wind, com os valores "Oslo", -3 e 18. Os nomes externos location e current selecionam caminhos; eles não se tornam variáveis.

Um objeto externo ausente faz uma leitura aninhada falhar. const { shipping: { date } } = {}; lança TypeError. Forneça um valor padrão externo quando esse campo puder ser undefined:

const { shipping: { date } = {} } = {};
// date is undefined

Isso não substitui shipping quando seu valor é null. Desestruturar null ou undefined diretamente também lança um erro, então a origem deve ser utilizável antes do início da extração.

Receba opções nomeadas

function formatUser({ name, age = "unknown" }) {
  return name + ", " + age;
}

formatUser({ name: "Mo" }) retorna "Mo, unknown". Reordenar os campos em { age: 40, name: "Ines" } ainda retorna "Ines, 40". Chamar formatUser sem argumento falha porque não há objeto para desestruturar. Um valor padrão para todo o parâmetro permite essa chamada:

function greet({ name = "guest" } = {}) {
  return "Hi, " + name;
}
greet(); // "Hi, guest"

O valor padrão externo trata um argumento omitido; o valor padrão interno trata um nome ausente. Passar null ainda causa uma falha. Para atribuir valores a variáveis existentes, envolva uma instrução com padrão de objeto entre parênteses: let x, y; ({ x, y } = { x: 4, y: 7 });. Caso contrário, as chaves iniciais são interpretadas como um bloco de instruções.

A desestruturação de vetores lê valores por posição de um iterável. As vírgulas controlam quais valores são selecionados; os nomes das variáveis não escolhem posições.

Selecione ou ignore posições

const medals = ["gold", "silver", "bronze"];
const [first, second] = medals;
const [, , third] = medals;

As variáveis recebem "gold", "silver" e "bronze". Posições vazias consomem valores sem declarar variáveis. Um nome além dos valores disponíveis recebe undefined. Valores padrão substituem apenas undefined:

const [p, q = 10] = [1]; // p is 1; q is 10
const [r = 10] = [null]; // r is null

Reúna os valores restantes

const [head, ...tail] = [1, 2, 3, 4];
// head is 1; tail is [2, 3, 4]

O elemento rest final cria um novo vetor, vazio quando nada resta. Ele deve ser o último. Quaisquer valores que sejam objetos dentro desse vetor mantêm suas identidades; coletá-los não os clona profundamente.

Leia um par retornado ou troque variáveis

function minMax(nums) {
  return [Math.min(...nums), Math.max(...nums)];
}
const [lo, hi] = minMax([4, 9, 1]);
// lo is 1; hi is 9

Quem chama segue a ordem definida pela função que retorna os valores. Para muitos campos de resultado, propriedades nomeadas em objetos evitam ter de lembrar posições.

Com let x = 1, y = 2;, [x, y] = [y, x]; troca os valores das variáveis. O vetor à direita é avaliado como [2, 1] antes de qualquer atribuição, preservando os dois valores antigos sem uma variável temporária.

Extraia valores de outros iteráveis

Cadeias de caracteres e Sets também podem ser desestruturados: const [initial] = "Zoe"; resulta em "Z". Sets fornecem valores na ordem de inserção. Entradas de Map são pares ordenados:

const distances = new Map([["park", 2], ["lake", 5]]);
for (const [place, distanceKm] of distances) {
  console.log(place, distanceKm);
}

O laço recebe um par e, em seguida, o padrão separa sua chave e seu valor. Object.entries fornece a mesma estrutura de par.

Um objeto comum não é iterável, então const [name] = { name: "Ana" }; lança TypeError. Use chaves para selecionar seu campo nomeado: const { name } = { name: "Ana" };. Colchetes exigem uma sequência de valores; chaves selecionam propriedades pelo nome.

Os três pontos, ..., têm duas funções relacionadas. O espalhamento expande dados existentes em um valor ou uma chamada. Rest reúne valores em uma variável declarada por um padrão ou parâmetro.

Mescle na ordem de prioridade

const defaults = { lang: "en", units: "metric", alerts: true };
const user = { lang: "pt", alerts: false };
const options = { ...defaults, ...user };
// { lang: "pt", units: "metric", alerts: false }

O espalhamento de objetos copia propriedades próprias enumeráveis. Quando uma chave aparece novamente, prevalece o valor posterior. Colocar user antes de defaults sobrescreveria as configurações do usuário. Espalhar null ou undefined em um objeto não adiciona nada.

Cópias por espalhamento são superficiais. Se um registro aninhado mudar, copie esse nível também:

const settings = { theme: "dark", font: { size: 14, family: "serif" } };
const next = {
  ...settings,
  font: { ...settings.font, size: 18 }
};

O espalhamento externo preserva theme. O interno preserva family enquanto substitui size. settings.font.size permanece 14 porque o registro aninhado alterado é novo.

Substitua um registro em uma lista

const todos = [{ id: 1, done: false }, { id: 2, done: false }];
const updated = todos.map(t =>
  t.id === 2 ? { ...t, done: true } : t
);

map cria um novo vetor. O item correspondente se torna um novo objeto, então updated[1].done é true enquanto todos[1].done continua sendo false. O primeiro item, inalterado, é reutilizado: updated[0] === todos[0] é true. Atualizações independentes não exigem copiar registros inalterados.

Expanda valores iteráveis

Em um literal de vetor ou chamada de função, o espalhamento extrai valores de um iterável. [...a, ...b] junta seus valores em um novo vetor. Math.max(...[4, 9, 1]) passa três argumentos e retorna 9. Um objeto comum não pode ser expandido em um vetor: [...{ a: 1 }] lança um TypeError. O espalhamento de objetos e o espalhamento de iteráveis usam regras diferentes para determinar o que leem.

Reúna argumentos ou propriedades restantes

function total(...nums) {
  return nums.reduce((sum, n) => sum + n, 0);
}
total(2, 3, 5); // 10
total();        // 0

Um parâmetro rest recebe um vetor verdadeiro, mesmo quando não recebe valores. Ele deve ser o último parâmetro, e só pode haver um. O antigo objeto arguments não é um vetor verdadeiro. Funções de seta não têm arguments próprio, embora possam ler a vinculação de uma função comum que as envolve.

A sintaxe rest de objetos coleta propriedades próprias enumeráveis que ainda não foram selecionadas:

const userRecord = { id: 8, name: "Rae", password: "x9!k" };
const { password, ...publicUser } = userRecord;
// publicUser is { id: 8, name: "Rae" }

Isso cria um novo registro e deixa a origem inalterada. A propriedade rest deve ser a última. Observe a posição para distinguir as funções: três pontos em um literal ou chamada espalham valores para fora; três pontos em uma lista de parâmetros ou em um destino de desestruturação reúnem valores.

Um Map armazena associações entre chaves e valores. Diferentemente das chaves de cadeia de caracteres de um objeto comum, uma chave de Map pode ser um número, um objeto ou outro valor sem ser convertida em uma cadeia de caracteres.

Crie e mantenha entradas

const stock = new Map();
stock.set("apples", 12).set("pears", 7);
stock.get("apples"); // 12
stock.has("kiwis");  // false
stock.size;           // 2

set adiciona uma entrada ou substitui seu valor e retorna o Map para encadeamento. get retorna undefined para uma chave ausente; use has para distinguir isso de uma entrada que armazena undefined. delete(key) retorna se removeu uma entrada, e clear() esvazia a coleção.

A notação de colchetes usa uma área de armazenamento diferente: stock["plums"] = 5; adiciona uma propriedade comum ao objeto Map. Ela não cria uma entrada visível para get, has ou size. Use os métodos de Map para entradas.

Mantenha tipos e identidades das chaves

m.set(1, "number"); m.set("1", "text"); cria duas entradas. As chaves 1 e "1" de um objeto comum se refeririam a uma única propriedade. Chaves de Map são comparadas como em ===, exceto que NaN corresponde a si mesmo e zeros com sinais diferentes compartilham uma chave.

const person = { id: 1 };
const notes = new Map([[person, "ready"]]);
notes.get(person);      // "ready"
notes.get({ id: 1 });   // undefined

A segunda consulta cria um novo objeto. Campos iguais não fazem dele a mesma chave. Guarde e reutilize a referência ao objeto original quando usar um objeto como chave.

Percorra e converta pares

for (const [name, count] of stock) {
  console.log(name, count);
}

Um Map fornece pares [key, value] na ordem da primeira inserção. Substituir um valor não muda a posição de sua chave. keys(), values() e entries() retornam iteradores que você pode percorrer ou espalhar em vetores. forEach passa à sua função de retorno primeiro o valor e depois a chave.

new Map(Object.entries(obj)) transforma as entradas de um registro em um Map. Object.fromEntries(map) cria um objeto; use-o quando as chaves forem cadeias de caracteres, pois chaves de objeto não conseguem preservar todos os tipos de chave de Map. [...map] cria um vetor de pares, útil para salvar as entradas de um Map como JSON.

Conte chaves que mudam

const words = "the cat saw the dog and the bird".split(" ");
const counts = new Map();
for (const word of words) {
  counts.set(word, (counts.get(word) ?? 0) + 1);
}

A primeira ocorrência começa em zero e depois soma um. Ocorrências posteriores leem e aumentam a contagem armazenada. counts.get("the") é 3 e counts.size é 6: o tamanho conta palavras distintas, não todas as oito ocorrências.

Escolha um objeto comum para um registro com campos conhecidos, especialmente dados compatíveis com JSON. Escolha um Map para chaves que mudam, verificações frequentes de tamanho ou chaves cujos tipos precisam ser preservados. O Map.groupBy mais recente preserva os tipos das chaves de grupo:

const owner = { name: "Ari" };
const jobs = [{ owner, done: false }, { owner, done: true }];
const byOwner = Map.groupBy(jobs, job => job.owner);
byOwner.get(owner).length; // 2

Em código mais antigo, percorra jobs em um laço. Para cada owner, use has e set para criar um vetor de grupo uma vez e depois get(owner).push(job) para adicionar o registro. Manter owner como chave de objeto distingue responsáveis diferentes mesmo quando seus campos de nome são iguais. Um WeakMap pode associar metadados a objetos sem manter vivos objetos usados como chaves que, de outro modo, seriam inalcançáveis. Ele não permite iteração nem tem tamanho. WeakMaps modernos também aceitam símbolos não registrados como chaves.

Um Set armazena valores únicos. Suas principais questões são se um valor está presente e como duas coleções se sobrepõem.

Adicione e teste valores

const tags = new Set(["js", "css", "js"]);
tags.size;       // 2
tags.add("html");
tags.has("css"); // true

Adicionar um valor existente não altera nada. add retorna o Set para encadeamento. delete(value) retorna se o valor foi removido, enquanto clear() remove todos os valores. O construtor recebe um iterável: use new Set([1, 2, 3]). new Set(1, 2, 3) lança um TypeError porque sua primeira entrada não é iterável. Uma cadeia de caracteres é iterável, então new Set("hello") contém "h", "e", "l" e "o".

Um Set não tem posições indexadas. tags[0] é undefined. Percorra-o com for...of, chame forEach ou converta-o em um vetor para operações como map e filter. A iteração segue a ordem de inserção; remover um valor e adicioná-lo novamente o coloca no fim.

Remova duplicatas sem ordenar

const unique = [...new Set([3, 1, 3, 2, 1])];
// [3, 1, 2]

O Set mantém a primeira ocorrência de cada valor. O espalhamento fornece esses valores em um vetor. Array.from(set) faz a mesma conversão.

Os valores são comparados como em ===, exceto que NaN corresponde a si mesmo; zeros com sinais diferentes contam como um valor. Valores que são objetos são comparados por identidade: new Set([{ id: 1 }, { id: 1 }]).size é 2. Para manter um registro por ID, construa um Map indexado por esse ID e depois leia seus valores. Registros posteriores com o mesmo ID substituem os anteriores, porque set atualiza uma entrada existente.

Para testes de pertinência repetidos em coleções grandes, um Set evita a busca um a um feita por includes em um vetor. Use-o quando a presença for mais importante que a posição.

Compare duas coleções

Métodos mais recentes de Set estão disponíveis nos principais navegadores desde 2024. Com a contendo 1, 2, 3, 4 e b contendo 3, 4, 5:

Essas operações retornam novos Sets. isSubsetOf verifica se cada valor está na outra coleção. isSupersetOf verifica a relação inversa de inclusão. isDisjointFrom verifica se as coleções não compartilham valores. Os três retornam booleanos. Por exemplo, new Set([3, 4]).isSubsetOf(a) é true. A diferença tem uma direção: os valores em b, mas não em a, seriam apenas 5.

Em um ambiente mais antigo, uma interseção pode ser escrita como new Set([...a].filter(x => b.has(x))).

A chamada comum JSON.stringify(set) produz "{}", perdendo os valores armazenados. Converta para um vetor antes de escrever JSON e depois use new Set(parsedArray) ao ler. Um WeakSet pode marcar objetos como processados sem manter vivos objetos que, de outro modo, seriam inalcançáveis. Ele não pode ser percorrido. WeakSets modernos também aceitam símbolos não registrados.

JSON, abreviação de JavaScript Object Notation, é um formato de texto independente de linguagem para dados estruturados. Um objeto é um valor JavaScript em uso; JSON é texto que pode descrever esse valor.

Reconheça os seis tipos de valor

JSON aceita objetos, vetores, cadeias de caracteres, números, booleanos e null. Qualquer um deles pode ser o valor de nível superior. O texto 42 é JSON válido mesmo sem chaves. JSON não tem representação para funções, undefined, datas como um tipo distinto, Map, Set, NaN ou Infinity.

{
  "name": "Amara",
  "age": 34,
  "languages": ["en", "yo"],
  "address": null,
  "member": true
}

As mesmas ideias estruturais aparecem em literais JavaScript, mas a forma permitida é mais restrita. JSON é usado em configurações e na troca de dados. JSON trocado entre sistemas usa a codificação UTF-8 e o tipo de mídia application/json; arquivos JSON usam a extensão .json.

Aplique as regras de sintaxe

Toda chave de objeto deve ser uma cadeia de caracteres entre aspas duplas. Cadeias de caracteres também exigem aspas duplas. Vírgulas separam propriedades ou itens de vetor, mas nenhuma vírgula pode vir após o último. Comentários são proibidos. Espaços em branco entre valores e sinais de pontuação são permitidos.

Números usam notação decimal. 1.5e3, -0.25 e 0 são válidos. 07, +1 e 0x1F são inválidos porque JSON proíbe zeros à esquerda, um sinal de adição inicial e notação hexadecimal.

Use sequências de escape dentro de cadeias de caracteres

Use \" para aspas duplas, \\ para uma barra invertida, \n para uma nova linha e \t para uma tabulação dentro de uma cadeia JSON. Uma quebra de linha literal não pode aparecer dentro de uma cadeia JSON. Deixe JSON.stringify gerar sequências de escape a partir dos valores reais das cadeias de caracteres, para que aspas internas não invalidem a saída.

Uma sequência de escape Unicode consiste em uma barra invertida, a letra u e quatro dígitos hexadecimais para uma unidade de código UTF-16. Por exemplo, \u00e9 representa é. Um caractere fora desse intervalo pode precisar de duas dessas sequências; ele também pode ser escrito diretamente na cadeia. As aspas ao redor de um texto JSON no código-fonte JavaScript são uma camada separada das aspas dentro do próprio JSON.

Preserve identificadores e evite chaves duplicadas

Números JavaScript preservam todos os inteiros no intervalo seguro de -9007199254740991 até 9007199254740991. Fora desse intervalo, alguns inteiros permanecem exatos e outros são arredondados. Analisar '{"id":9007199254740993}' fornece um valor id de 9007199254740992. Armazene identificadores longos como cadeias de caracteres JSON quando seus dígitos exatos forem importantes.

Chaves devem ser únicas dentro de cada objeto JSON. O JSON.parse do JavaScript mantém a última ocorrência quando uma chave se repete: analisar '{"a":1,"a":2}' produz { a: 2 }. Não é possível recuperar propriedades distintas desse nome repetido.

JSON.stringify converte valores JavaScript compatíveis em texto JSON. Decida o que o texto deve preservar antes de converter um registro com métodos ou valores de coleções.

Escreva texto compacto ou indentado

const person = { name: "Amara", age: 34, tags: ["admin"] };
const text = JSON.stringify(person);
// '{"name":"Amara","age":34,"tags":["admin"]}'

O resultado é uma cadeia de caracteres, então typeof text é "string". Propriedades próprias enumeráveis com chaves de cadeia de caracteres são escritas na ordem de Object.keys. JSON.stringify(person, null, 2) adiciona quebras de linha e dois espaços de indentação por nível. O segundo argumento é null porque nenhum substituidor está sendo usado. A indentação numérica é limitada a 10 espaços; uma cadeia de caracteres usada para indentação é limitada aos seus primeiros 10 caracteres.

Preveja valores descartados e alterados

const data = {
  a: undefined,
  b: () => 1,
  c: NaN,
  d: [undefined, Infinity]
};
JSON.stringify(data); // '{"c":null,"d":[null,null]}'

Uma propriedade de objeto que contém undefined, uma função ou um símbolo é omitida. Em um vetor, esse valor se torna null, preservando a posição. NaN e Infinity tornam-se null em ambos os lugares. No nível superior, valores não suportados como undefined ou uma função fazem stringify retornar undefined, não texto JSON.

Um Date escreve sua cadeia ISO em UTC por meio de toJSON. Entradas comuns de Map e Set não são escritas, então qualquer uma das coleções se torna {}. Converta valores de Set em um vetor e entradas de Map em pares ou em um objeto com chaves de cadeia de caracteres antes de escrevê-los.

Uma referência circular e um BigInt comum como 10n causam um TypeError. Referências compartilhadas que não formam um ciclo podem ser serializadas, mas JSON não preservará sua identidade compartilhada.

Escolha dados com um substituidor

const user = { name: "Rae", email: "rae@example.com", password: "x9!k", age: 31 };
JSON.stringify(user, ["name", "email"]);
// '{"name":"Rae","email":"rae@example.com"}'

Um vetor substituidor seleciona nomes de propriedades. Uma função substituidora transforma valores à medida que são visitados, começando com toda a entrada sob a chave "":

JSON.stringify(user, (key, value) =>
  key === "password" ? undefined : value
);

Retornar undefined omite uma propriedade de objeto, transforma uma posição de vetor em null ou causa um resultado geral undefined quando retornado para a raiz. Retorne o valor inalterado para os dados que você quer manter.

O método toJSON() de um objeto pode escolher sua representação. Para { celsius: 21, toJSON() { return { c: this.celsius }; } }, a conversão em texto escreve '{"c":21}'.

Não construa JSON juntando você mesmo cadeias de caracteres entre aspas: aspas internas ou novas linhas podem invalidar sua sintaxe. Também não converta novamente em texto um texto já serializado esperando uma representação de objeto. Converter '{"a":1}' em texto codifica uma cadeia de caracteres; analisar esse resultado uma vez retorna uma cadeia de caracteres, não um objeto.

JSON.parse lê texto JSON e retorna o valor que ele descreve. A análise sintática verifica a sintaxe do texto; verificar se o resultado é adequado ao seu programa é uma tarefa separada.

Leia o valor e depois examine seus campos

const data = JSON.parse('{"city":"Lima","tempC":19.5}');
data.tempC + 1; // 20.5

As aspas simples externas delimitam uma cadeia de caracteres JavaScript. As aspas duplas dentro dela pertencem ao JSON. A análise sintática cria um objeto comum com uma propriedade numérica tempC. Um texto que descreve um vetor produz um vetor; textos JSON primitivos produzem seus valores primitivos correspondentes.

Dados que já são um objeto não precisam de uma etapa de análise sintática. JSON.parse({ a: 1 }) primeiro converte esse argumento em "[object Object]" e depois lança um SyntaxError. JSON.parse(undefined) também falha porque "undefined" não é texto JSON válido.

Trate texto inválido

function safeParse(text, fallback) {
  try {
    return JSON.parse(text);
  } catch (error) {
    return fallback;
  }
}
safeParse("{ok:true}", null); // null

Uma entrada malformada, incluindo uma cadeia de caracteres vazia, cadeias JSON entre aspas simples, chaves sem aspas e vírgulas finais, lança um SyntaxError. Capturar essa falha dá ao programa uma alternativa de contingência definida, em vez de interrompê-lo. Um null analisado com sucesso também é possível, então escolha como quem chama distinguirá uma alternativa de contingência de dados válidos quando essa diferença importar.

Restaure valores selecionados com uma função restauradora

Uma data armazenada como texto retorna como uma cadeia de caracteres. Um vetor de pares chave-valor permanece um vetor até que new Map(pairs) o transforme em um Map. Funções omitidas durante a escrita não podem ser recuperadas do texto restante.

const text = '{"title":"Dentist","due":"2026-03-01T09:00:00.000Z"}';
const event = JSON.parse(text, (key, value) =>
  key === "due" ? new Date(value) : value
);

A função restauradora visita valores internos antes de seus contêineres, terminando com o resultado inteiro sob a chave "". Retornar um valor substitui o valor atual. Retornar undefined remove essa propriedade; retorná-lo para a raiz faz todo o resultado da análise ser undefined. Esquecer return value para outras chaves pode, portanto, apagar os dados que você queria manter.

Verifique a estrutura e planeje uma conversão de ida e volta

JSON válido ainda pode ter os tipos errados. Analisar '{"temp":"19"}' deixa uma cadeia de caracteres, então data.temp + 1 concatenaria para "191". Verifique campos e tipos obrigatórios, como typeof data?.temp === "number", antes de calcular. Converta com Number apenas quando o formato pretendido permitir uma cadeia numérica; o encadeamento opcional e ?? podem tratar campos que podem estar ausentes.

Para const settings = { theme: "dark", volume: 0.8, recent: ["a.txt"] };, a conversão em texto produz 48 caracteres de texto JSON. A análise sintática restaura os mesmos dados dos campos, mas loaded === settings é falso porque ela cria novos objetos. Um Date retorna como uma cadeia de caracteres, uma propriedade de objeto com valor undefined desaparece e um Set não convertido retorna como {}. Converta valores especiais antes de escrever e restaure seus tipos pretendidos após a leitura.