Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Date.prototype.toJSON: Date na serialização JSON

toJSON devolve texto ISO para uma data válida, null para uma inválida e é invocado automaticamente por JSON.stringify.

Versão: ECMAScript 5 (2009) onward; example target: Node.js 24.22.2

Sintaxe

date.toJSON(key)

date.toJSON(key) normalmente devolve a mesma string que date.toISOString(). JSON.stringify chama-o com a chave da propriedade, mas o algoritmo padrão não usa key. Para um Date inválido, a conversão numérica não é finita, por isso devolve null em vez de lançar o RangeError de toISOString().

O método é deliberadamente genérico: obtém primeiro um primitivo com hint number. Só se for um Number não finito devolve null; caso contrário invoca a propriedade toISOString do receiver. Pode assim funcionar num objeto não Date. Lança se a conversão lançar ou se toISOString não for invocável ou lançar.

JSON conserva o instante como texto UTC mas perde o tipo Date; depois de analisar obtém-se uma string. É padrão desde ECMAScript 5 (2009).

Exemplos

const payload = {
  when: new Date("2024-01-02T03:04:05.006Z"),
  missing: new Date(NaN),
};
console.log(JSON.stringify(payload));
console.log(payload.when.toJSON());

const custom = {valueOf: () => 0, toISOString: () => "custom-time"};
console.log(Date.prototype.toJSON.call(custom));

Resultado

{"when":"2024-01-02T03:04:05.006Z","missing":null}
2024-01-02T03:04:05.006Z
custom-time

Fontes