18

Descobri uma proposta do TC39 que está em estágio 3 de um novo objeto para se trabalhar com datas. Este se chama Temporal.

Analisei um código de exemplo que usa esta nova API:

console.log(
  "Initialization",
  Temporal.now.instant()
);

// Initialization 2021-01-13T20:57:01.500944804Z

Ele funciona como um método static (semelhante aos statics do objeto Math), e no exemplo acima ele retorna "quase" uma string na mesma forma que new Date().toISOString():

console.log(new Date().toISOString());

Sobre o assunto, foi dito que Temporal seria uma solução mais simples para desenvolvedores JavaScript/TypeScript que precisam trabalhar e manipular datas. Esta solução poderia até dispensar o uso de bibliotecas externas como date-fns e momentjs. Na hora me despertou interesse e gostaria de saber mais sobre esta nova implementação.

  1. Esta é uma implementação nova que veio pra substituir o objeto Date? Sei que o Date não vai a lugar algum, mas a API Temporal veio pra resolver alguns problemas?

    1. Se sim, quais?
  2. Sei que está em estágio 3, mas é possível usá-lo no Node.js em alguma versão através de uma flag?

  3. Alguma versão do TypeScript suporta, mesmo que experimentalmente, esta nova API?

  4. As dores de cabeça que eu tenho ao trabalhar com datas vão finalmente ser resolvidas com um "objeto salvador"? (sei que bala de prata não existe)

1
  • 1
    (Off-topic) Só para constar, "bala de prata" se refere a uma solução ou tecnologia capaz de aumentar substancialmente a produtividade dos projetos, não tem sido encontrada num nível mais "macro" (como a troca do paradigma de programação) porém ganhos significativos em nível mais "micro" existem, por exemplo adotar a tecnologia certa para o problema em questão (em oposição a adotar uma menos adequada) ou usar uma biblioteca que melhora a produtividade para resolver certo problema. Aí entraria também uma API mais moderna para lidar com datas (que não sei se uma classe só dá conta de melhorar).
    – Piovezan
    Commented 15/02/2021 às 6:58

2 Respostas 2

14

A API Temporal é, no momento em que escrevo esta resposta, uma proposta de adição ao ECMAScript que se encontra no estágio 3 do processo de incorporação à especificação (o famigerado TC39 process). Repositório referente à proposta.

Mediante estandardização, a API Temporal consistirá de um objeto global Temporal (similar aos já existentes Math, Date, JSON etc) que irá aglutinar classes, funções e utilitários para a manipulação de datas e horas no JavaScript. Embora a API desta proposta não deva ser alterada, os implementadores desta proposta NÃO DEVEM enviar implementações Temporal não sinalizadas até que a IETF padronize os formatos de serialização de sequência de fuso horário / calendário.

Sobre a API podemos citar:

  • Construtores notáveis do objeto Temporal:
    • Temporal.Instant
    • Temporal.PlainDateTime
    • Temporal.PlainDate
    • Temporal.PlainTime
    • Temporal.PlainYearMonth
    • Temporal.PlainMonthDay
    • Temporal.TimeZone
    • Temporal.Duration
  • Outras propriedades do objeto Temporal:
    • Temporal.now

Já quero deixar uma vontade: cada um dos construtores acima tem uma funcionalidade específica e seus próprios métodos. :-) Para detalhes individuais, consultar a especificação e documentação da proposta.

Até então, o único meio "nativo do JavaScript" para lidar com datas e horas no JavaScript é utilizar o objeto Date e suas respectivas funções e métodos. No entanto, essa API é extremamente antiga e possui vários problemas de design.

Como é de conhecimento comum, o JavaScript foi implementado num prazo extremamente curto por Brendan Eich, que baseou o funcionamento do Date na API (hoje majoritariamente depreciada) java.Util.Date. Apesar de, com atualizações futuras, o Java ter ganhado novos meios de lidar com datas e horas, o JavaScript permaneceu com a infame API Date. A Temporal API é a "evolução" do gerenciamento de datas e horas no JavaScript, sem os problemas da API antiga.

A nova API Temporal visa à resolução desses problemas, uma vez que:

  • Fornece APIs simples e fáceis de usar para executar computações relacionadas à datas e horas.
  • Suporte de primeira classe para todas as time zones, o que inclui suporte a horários de verão (cálculos DST-safe)
  • Lida somente com objetos imutáveis (ao contrário da maioria das APIs Date, que são mutáveis).
  • Analisa somente formatos de string estritamente especificadas.
  • Suporta outros calendários, além do Gregoriano.

Desse modo, como vimos acima, o novo objeto Temporal fornecerá uma grande variedade de construtores e objetos para:

  • Representar propriamente informações relativas à datas e horas.
  • Possibilitar computações apropriadas baseadas em cada tipo.

Não acho que vale a pena alongar mais que isso, uma vez que a documentação da proposta é bem completa e expressiva, além de que, como vimos, pode estar sujeita à mudanças. Quando a API for estabilizada, comprometo-me a atualizar esta resposta com informações mais detalhadas.


FAQ da pergunta

Esta é uma implementação nova que veio pra substituir o objeto Date? Sei que o Date não vai a lugar algum, mas o Temporal veio pra resolver alguns problemas?

Não. O Date realmente não vai a lugar nenhum, até porque isso quebraria a web, o que iria contra um dos principais princípios do processo TC39, que é não quebrar APIs antigas do JavaScript.

A API Temporal veio para tornar o trabalho com datas e horas mais simples. É bem provável que torne a API Date menos comum em novos projetos e aplicações, mas Date jamais deixará de existir no JavaScript.

Sei que está em estágio 2, mas é possível usá-lo no Node.js em alguma versão através de uma flag?

Editado ao dia 11 de março de 2021: Acabou de passar para o estágio 3, o que significa que as engine poderão começar implementações iniciais – ainda sem estabilidade garantida.

O Node.js (baseado no motor V8) ainda não possui suporte nativo à API Temporal, mas existe polyfill que pode ser utilizado.

No entanto, não acho sábio fazer uso dessa API neste momento para projetos "reais", uma vez que ainda não está totalmente estabilizado.

Alguma versão do TypeScript suporta, mesmo que experimentalmente, esta nova API?

Não. O TypeScript ainda não fornece definições de tipos “nativas” para a API Temporal.

As dores de cabeça que eu tenho ao trabalhar com datas vão finalmente ser resolvidas com um "objeto salvador"? (sei que bala de prata não existe)

Todas, provavelmente, não. :-) Mas como vimos acima, a API Temporal resolverá diversos problemas históricos da API Date, o que decerto facilitará o trabalho com datas e horas.

No entanto, é um campo complicado e repleto de edge-cases. Apesar de facilitar, a API Temporal não faz com que eles sumam.

2
  • 1
    Pois é, o Date sempre vai existir por causa da retrocompatibilidade, que é um dos "pilares" da web moderna. Mas não se preocupe! Assim que Temporal for estandardizada (e o suporte se disseminar), Date raramente será usada em novos projetos — pelo menos eu espero. :P Commented 14/02/2021 às 19:25
  • @CmteCardeal, pode editar, se quiser, estou meio sem tempo para ver isso em detalhes agora. Ainda planejo rescrever essa resposta do zero quando avançar ao estágio 4. O pior mesmo é achar o tempo... :D Commented 25/05/2021 às 23:58
10

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:

Temporal types

E esta mostra a relação entre estes tipos:

Temporal types relationship


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.

3
  • 1
    @CmteCardeal Adicionei mais algumas coisas na resposta. Mas acho que não vou mais adicionar muita coisa pois a API ainda está sujeita à mudanças (inclusive, eu cheguei a testar algumas semanas atrás e realmente a versão atual mudou bastante, até os nomes de algumas classes e métodos inclusive), então acho que vou esperar ela ser oficialmente lançada para poder atualizar a resposta com mais exemplos...
    – hkotsubo
    Commented 17/02/2021 às 13:15
  • 1
    Tivemos essa atualização no Github da proposta: ""NOTA: Embora a API desta proposta não deva ser alterada, os implementadores desta proposta NÃO DEVEM enviar implementações Temporal não sinalizadas até que a IETF padronize os formatos de serialização de sequência de fuso horário / calendário."" Acho que a API em si não vai mais mudar. O que falta agora é só questões de implementações. Não cheguei a verificar completamente, mas pode ser que a API siga esse padrão agora, logo mudanças no estágio 3 já são bom difíceis de acontecer. Commented 26/05/2021 às 18:49
  • 1
    @CmteCardeal Bom, mesmo assim, acho que vou esperar mais um pouco pra atualizar a resposta. Ainda nem terminei de ler toda a documentação...
    – hkotsubo
    Commented 26/05/2021 às 18:51

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .