Temporal API

Trabalhar com datas em JavaScript sempre foi uma dor de cabeça. O Date tem uma API confusa, meses começando em zero, mutabilidade inesperada e um suporte fraco para fuso horário. A Temporal API nasce justamente para resolver isso, trazendo um jeito moderno, imutável e muito mais previsível de lidar com datas e horas.

O problema com o Date

const data = new Date(2024, 0, 15); // mês 0 = Janeiro
data.setDate(data.getDate() + 1); // muta o objeto original
console.log(data.getMonth()); // 0 (ainda é "Janeiro", mesmo confuso)

Além da contagem de meses começando em zero, o Date é mutável: qualquer método que "altera" a data modifica o próprio objeto, o que causa bugs difíceis de rastrear quando a mesma instância é compartilhada em vários lugares do código.

Como funciona a Temporal API

A Temporal API separa os conceitos de data, hora e fuso horário em tipos diferentes, todos imutáveis. Os principais são Temporal.PlainDate, Temporal.PlainTime, Temporal.PlainDateTime e Temporal.ZonedDateTime:

const data = Temporal.PlainDate.from('2024-01-15');

console.log(data.month); // 1 (Janeiro é 1, não 0)
console.log(data.dayOfWeek); // dia da semana, de 1 a 7

Somando e subtraindo datas

Em vez de métodos que mutam o objeto, a Temporal API sempre retorna uma nova instância:

const data = Temporal.PlainDate.from('2024-01-15');
const amanha = data.add({ days: 1 });

console.log(data.toString()); // '2024-01-15' (não mudou)
console.log(amanha.toString()); // '2024-01-16'

Trabalhando com fuso horário

O Temporal.ZonedDateTime resolve um dos maiores problemas do Date: lidar corretamente com fusos horários e horário de verão.

const agora = Temporal.Now.zonedDateTimeISO('America/Sao_Paulo');

console.log(agora.toString());
// 2024-01-15T14:30:00-03:00[America/Sao_Paulo]

const emNovaYork = agora.withTimeZone('America/New_York');
console.log(emNovaYork.toString());
// 2024-01-15T12:30:00-05:00[America/New_York]

Converter entre fusos horários deixa de exigir bibliotecas externas como moment-timezone ou date-fns-tz para os casos mais comuns.

Comparando e calculando diferenças

const inicio = Temporal.PlainDate.from('2024-01-01');
const fim = Temporal.PlainDate.from('2024-03-15');

const diferenca = inicio.until(fim);
console.log(diferenca.toString()); // 'P2M14D' (2 meses e 14 dias)

Vantagens

Objetos imutáveis, sem efeitos colaterais inesperados.
Meses e dias da semana numerados de forma intuitiva (sem começar em zero).
Suporte nativo e correto para fuso horário e horário de verão.
Tipos específicos para cada necessidade (só data, só hora, data com fuso, etc.), reduzindo erros de uso.
Reduz a dependência de bibliotecas como Moment.js, Luxon ou date-fns para boa parte dos casos.

Compatibilidade

A Temporal API é uma adição recente à linguagem e ainda está em expansão entre os navegadores. Vale sempre checar o suporte antes de usar em produção, principalmente se o projeto precisar suportar navegadores mais antigos.

caniuse

Conclusão

A Temporal API é uma das mudanças mais aguardadas do JavaScript moderno, resolvendo de vez problemas que acompanhavam a linguagem desde sempre. Vale a pena acompanhar sua evolução e começar a experimentar aos poucos, principalmente em projetos novos.