A outra resposta já deu uma visão geral, só gostaria de complementar alguns pontos.
Obs: como a API ainda está sujeita a mudanças, não me aprofundei muito nos exemplos. Coloquei apenas alguns que usam a versão atual do polyfill (que pode ou não ter mudado quando você estiver lendo esta resposta), para dar uma noção do que a API é capaz.
Podemos começar com a principal motivação desta proposta, segundo seus próprios criadores:
Date
has been a long-standing pain point in ECMAScript. This proposes Temporal
... that brings a modern date/time API to the ECMAScript language.
Em tradução livre, seria: "Date
tem sido há muito tempo um ponto problemático em ECMAScript. Propomos Temporal
... que traz uma API de datas moderna para a linguagem".
A ideia da proposta, portanto, é criar uma nova API de datas, para corrigir alguns pontos que eles consideram problemáticos em Date
.
Uma curiosidade é que alguns dos responsáveis pela proposta são os criadores do Moment.js.
Um dos problemas é o fato de Date
, apesar do nome, não ser exatamente uma data (no sentido de representar um único valor de dia, mês, ano, hora, minuto e segundo). Conforme já explicado aqui e aqui, o Date
na verdade representa um timestamp: a quantidade de milissegundos decorrida desde o Unix Epoch (que por sua vez equivale a 1970-01-01T00:00Z
- 1 de janeiro de 1970 à meia-noite, em UTC).
Ou seja, o Date
representa um instante único, um ponto na linha do tempo. Pense no "agora": neste exato momento, que dia é hoje e que horas são? Em cada parte do mundo, a resposta será diferente (em algumas partes do mundo, é 14 de fevereiro, em outras pode ser dia 13 ou 15, e o horário também será diferente). Apesar da data e hora serem diferentes, o instante (o valor do timestamp) é o mesmo para todos. E o Date
, segundo a especificação da linguagem, só guarda a informação do timestamp.
Quando você imprime a data (via alert
ou console.log
) ou quando obtém informações dela (seja via os getters ou toString()
), este timestamp é convertido para o fuso horário que está configurado no ambiente onde o código está rodando (browser, Node, etc). Ou seja, o Date
usa a configuração do fuso horário para converter o timestamp para os valores corretos de data e hora (ou converte para UTC, quando você usa métodos como toISOString()
ou os "getters UTC", como getUTCHours
, getUTCMonth
, etc).
Essa abordagem one-size-fits-all (um tipo para a todos governar todas as situações) pode até "simplificar" as coisas (pois assim temos um único tipo de propósito geral), mas também acaba gerando várias situações - na minha opinião - inconvenientes.
Por exemplo, se você só quer uma data de aniversário (somente dia, mês e ano), sem se importar com o horário ou timezone, bastaria fazer algo como new Date(ano, mes, dia)
. Porém, na verdade internamente o horário será ajustado para meia-noite no fuso horário do ambiente no qual o código roda (seja o browser, ou o Node, etc). Isso porque somente o dia, mês e ano não é o suficiente para obter o timestamp (por exemplo, uma data como o dia 14/02/2021 não representa um instante único, você precisa saber qual o horário e em qual fuso horário ele se refere, para ter um valor de timestamp). Então com Date
você sempre está lidando com timestamps e fusos horários, mesmo quando não quer ou não precisa.
Um exemplo (rodando no Node - lembrando que ajustar o process.env.TZ
não funciona no Windows, e ajustá-lo no meio do script só funciona a partir do Node 13):
let d = new Date(2021, 1, 14); // em Date, fevereiro é mês 1 :-(
let t = Temporal.PlainDate.from({ year: 2021, month: 2, day: 14 }); // fevereiro é mês 2 \o/
console.log(d.toString(), t);
// mudar para o timezone da Califórnia
process.env.TZ = 'America/Los_Angeles';
console.log(d.toString(), t);
Eu crio um Date
e um Temporal.PlainDate
que correspondem a 14 de fevereiro de 2021 - aliás, outro bônus incrível desta API: os meses não são indexados em zero - janeiro é 1 e não zero!
O timezone configurado no meu ambiente é America/Sao_Paulo
(vulgo "Horário de Brasília"). Então o Date
terá o horário ajustado para meia-noite no Horário de Brasília, e este é o timezone usado para imprimir a data.
Mas quando eu mudo o timezone do ambiente, isso afeta a saída de toString()
(o timestamp do Date
ainda é o mesmo, mas este será convertido para o novo timezone ao ser impresso). Já PlainDate
não é afetado por esta configuração, pois ele só guarda o dia, mês e ano, sem se importar com o horário ou o timezone. A saída é:
Sun Feb 14 2021 00:00:00 GMT-0300 (Brasilia Standard Time) Temporal.PlainDate <2021-02-14>
Sat Feb 13 2021 19:00:00 GMT-0800 (Pacific Standard Time) Temporal.PlainDate <2021-02-14>
Lembrando que o resultado pode variar de acordo com o timezone que estiver configurado no seu ambiente.
Repare que Date.toString()
mostra um valor diferente de acordo com o timezone que está configurado (aliás, o mesmo ocorre com os getters: d.getDate()
retornaria 14 ou 13, dependendo do timezone configurado). Já PlainDate
, por não ter nenhuma informação sobre horários ou timezones, não é afetado por nenhuma configuração e mantém seu valor constante.
Creio que isso evitará muitos erros que costumam ocorrer até hoje ("Criei um Date
mas ele mostra o dia/horário errado").
Além disso, a nova API define vários tipos diferentes, um para cada situação (indo no caminho oposto do one-size-fits-all): tem um tipo para data (somente dia, mês e ano), outro para horário (somente hora, minuto, segundo), outro para data e hora, mas sem fuso horário, outro para data/hora e fuso, outro para timestamp, etc.
Esta imagem (retirada da documentação) nos dá um bom resumo dos tipos disponíveis:
E esta mostra a relação entre estes tipos:
Conversão entre timezones
Uma coisa que o JavaScript não tem é conversão entre diferentes timezones.
O mais próximo que temos é algo como d.toLocaleString('pt-BR', { timeZone: 'Europe/Berlin' })
, que de fato retorna os valores de data e hora convertidos para o timezone indicado. Mas o problema é que o formato depende do locale, e não temos controle sobre isso. E se quisermos a data/hora em um timezone específico, mas em outro formato? Eu teria que ir trocando o locale até encontrar um, mas e se nenhum tiver o formato específico que eu quero? Ou se eu simplesmente não quiser um formato, e sim um objeto contendo os valores de data e hora convertidos para outro timezone?
Com Date
, não dá. Já o Temporal
prevê várias formas de converter:
- mantendo o horário local: tenho um objeto que representa 14/02/2021 às 10h no Horário de Brasília, quero mudar somente o timezone (ou seja, converter para 14/02/2021 às 10h no fuso do Japão, por exemplo)
- mantendo o instante: quando é 14/02/2021 às 10h no Horário de Brasília, que dia e hora é no Japão? (R: 22h do mesmo dia)
A API ainda trata casos mais complexos que só os timezones trazem para você, como as transições de horário de verão: permite que você trate os vários corner cases que ocorrem (quando uma hora é pulada, ou quando ela ocorre 2 vezes - nos casos em que o relógio é atrasado em uma hora quando termina o horário de verão, por exemplo), além de permitir consultar o histórico de mudanças de cada timezone.
Aritmética de datas
Atualmente o JavaScript não possui um bom suporte para aritmética de datas. Na prática, o melhor que dá para fazer para calcular a diferença entre duas datas é subtrair os valores dos timestamps e depois fazer os cálculos na mão.
Mas nem sempre isso é suficiente. Só para ficar em um caso, a diferença em meses não é algo tão trivial quanto parece: por exemplo, entre 01/01/2019 e 01/02/2019 há 31 dias. Dividindo por 30 e arredondando, dá 1 mês.
Mas entre 01/02/2019 e 01/03/2019 há 28 dias. Dividindo por 30, dá 0,93: se arredondar pra baixo, dá zero meses. Mas entre 1 de fevereiro e 1 de março a diferença não é de um mês? Então devemos arredondar pra cima nesse caso?
Mas e se fosse entre 01/01/2019 e 29/01/2019, a diferença também é de 28 dias. Só que entre 1 de janeiro e 29 de janeiro ainda não se passou 1 mês, então eu não posso arredondar pra cima nesse caso. "Ah, então eu só arredondo pra cima se não estiver no mesmo mês".
Aí você vê que entre 01/01/2019 e 27/02/2019 a diferença é de 57 dias, que dividido por 30 dá 1,9. Se arredondar pra cima dá 2, mas entre 1 de janeiro e 27 de fevereiro ainda não se passaram dois meses. E agora?
Com Temporal
, bastaria fazer algo do tipo:
const today = Temporal.PlainDate.from('2019-01-01');
const futureDate = Temporal.PlainDate.from('2019-02-27');
const until = today.until(futureDate, { largestUnit: 'months' });
console.log(until); // 1 mês e 26 dias
// ou, se quiser apenas a quantidade de meses, use until.months
Aliás, está previsto um tipo específico para durações: Temporal.Duration
. Com isso ficará mais simples fazer operações como "somar dias/meses/anos/qualquer-outra-quantidade-de-tempo a uma data".
Claro, isso poderá mudar o comportamento de alguns corner cases. Por exemplo, se você somar 1 mês à 31 de janeiro:
let d = new Date(2021, 0, 31); // 31 de janeiro de 2021
// somar 1 mês
d.setMonth(d.getMonth() + 1);
console.log(d.toString()); // 3 de março!
Na verdade a "soma" é feita ajustando-se o valor do mês e mantendo os demais campos. No caso acima, mudamos o mês para fevereiro, e o dia mantém-se em 31, mas como fevereiro não tem 31 dias, é feito um ajuste para 3 de março (os dias "excedentes" acabam "dando overflow" e "invadindo" o mês seguinte).
Mas aí entra uma questão semântica: se tenho uma data em janeiro e somo 1 mês, por que o resultado é uma data em março? Não deveria ser em fevereiro? Tudo bem que isso é discutível, já que não existe uma regra "oficial" para aritmética de datas (tal como existe na matemática) e cada API implementa de um jeito. Mas o Temporal
(usando a implementação atual do polyfill) ajusta a data para o último dia de fevereiro, caso o valor do dia exceda a quantidade de dias do mês:
let d = Temporal.PlainDate.from('2021-01-31'); // 31 de janeiro de 2021
d = d.add(Temporal.Duration.from({ months: 1 }));
console.log(d); // Temporal.PlainDate <2021-02-28> (28 de fevereiro de 2021)
Enfim, um bom resumo das possibilidades está na própria documentação.
Resumindo, os problemas de se trabalhar com datas vão continuar existindo (como tratar corretamente, converter entre timezones, fazer cálculos, etc). O que pode ficar mais fácil - assim espero - é resolver esses problemas :-)
E lembrando que Date
não vai sumir, inclusive a nova API prevê a conversão de Date
para Temporal.Instant
.