Temporal API é a substituta confiável para a API de Date do JavaScript

O problema com Date

A API Date do JavaScript, escrita em dez dias em 1995 e modelada na classe java.util.Date (que o próprio Java depois depreciou), acumula armadilhas que corrompem lógica de datas em produção há trinta anos. O artigo percorre cada uma delas e mostra como a API Temporal resolve cada caso.

Parsing não confiável

new Date('2026-07-21') é interpretado como meia-noite UTC, enquanto new Date('2026/07/21') é interpretado como meia-noite local - duas strings visualmente idênticas podem produzir timestamps com 12 horas de diferença. Date() sem new ignora o argumento e retorna a data atual. Strings inválidas não lançam erro: criam um objeto Invalid Date que propaga NaN silenciosamente.

Meses 0-indexed e mutação

O construtor usa meses baseados em zero (7 = agosto). Objetos Date são mutáveis: funções auxiliares que chamam setDate ou setMonth alteram o objeto original sem sinalizar, causando drift em campos de auditoria e chaves de cache. Overflow de dia (ex.: setDate(32)) faz rollover silencioso para o mês seguinte.

Timezones e DST

Date armazena um instante (milissegundos desde o epoch), mas métodos como getDate() projetam esse instante no fuso local da máquina. Isso gera bugs de "off by one day" em relatórios. Dias de transição de DST têm 23 ou 25 horas, quebrando qualquer lógica que assuma 24h por dia. JSON.stringify sempre emite UTC, apagando o offset original.

Aritmética frágil

Não existe tipo de duração nativo. "Adicionar um mês" via setMonth e "adicionar 30 dias" via milissegundos produzem resultados diferentes - e nenhum dos dois é necessariamente o que o domínio pede.

Serialização perde intenção

Um round-trip JSON descarta o offset de fuso horário. Dados movidos entre regiões ou abertos em máquinas com fuso diferente começam a driftar.

Como Temporal resolve

Temporal separa conceitos em tipos distintos: Temporal.Instant (ponto no tempo), Temporal.PlainDate (data de calendário sem fuso), Temporal.ZonedDateTime (data com fuso explícito). Todas as operações são imutáveis, meses são 1-indexed, e parsing ambíguo vira erro em vez de comportamento silencioso.

Adoção incremental

O artigo recomenda não fazer big-bang rewrite. A estratégia sugerida:

• Manter Date em bordas de interoperabilidade (APIs legadas, SDKs de terceiros)
• Usar Temporal para nova lógica de domínio onde corretude importa
• Converter explicitamente nas fronteiras
• Priorizar caminhos de alto custo: ciclos de billing, janelas de relatório, políticas de retenção, agendamentos
• Adicionar testes para transições de DST, fim de mês e conversões de fuso

Regras práticas para código que ainda usa Date

1. Banir parsing ambíguo - aceitar apenas formatos estritos
2. Separar campos de instante e campos de calendário no schema
3. Manter UTC para transporte e armazenamento
4. Nunca mutar instâncias compartilhadas de Date
5. Centralizar aritmética de datas em um módulo com testes
6. Rodar CI em múltiplos fusos horários
7. Logar contexto de máquina e calendário em fluxos críticos