Temporal API

A Temporal API é a nova especificação oficial do JavaScript (incorporada no ECMAScript 2026 depois de alcançar o Stage 4 em março de 2026), criada para substituir de vez o antigo e problemático objeto Date.

Porque é que a Temporal API é revolucionária?

• Imutabilidade: qualquer alteração num objeto (como somar dias) gera uma nova instância, evitando bugs de mutação acidental.

• Meses a começar em 1: janeiro passa a ser oficialmente o número 1, e já não 0.

• Tipos especializados: em vez de um único objeto para tudo, a Temporal traz ferramentas específicas para cada necessidade:

  • Temporal.PlainDate: apenas a data de calendário (ano, mês, dia).

  • Temporal.PlainTime: apenas a hora do relógio (hora, minuto, segundo).

  • Temporal.ZonedDateTime: data, hora e fuso horário completo (essencial para agendamentos globais).

  • Temporal.Duration: representa uma quantidade exata de tempo (por exemplo, "2 horas e 30 minutos").

1. Obter a data atual e somar dias (sem mutações)

// Obtém apenas a data atual do sistema (por exemplo: 2026-08-24)

const hoje = Temporal.Now.plainDateISO();

console.log(hoje.toString());

// Acrescenta 10 dias, de forma limpa e intuitiva

const entrega = hoje.add({ days: 10 });

console.log(entrega.toString()); // 2026-09-03 (o hoje continua intacto!)

2. Calcular a diferença exata entre duas datas

const inicioProjeto = Temporal.PlainDate.from('2026-01-15');

const fimProjeto = Temporal.PlainDate.from('2026-08-24');

// Calcula o tempo decorrido. Sem o largestUnit, a diferença vem toda em dias
// e o número de meses seria sempre zero.

const duracao = fimProjeto.since(inicioProjeto, { largestUnit: 'month' });

console.log(`O projeto durou ${duracao.months} meses e ${duracao.days} dias.`);

3. Trabalhar com fusos horários diferentes de forma simples

// Cria um momento exato com o fuso de Tóquio

const reuniaoToquio = Temporal.ZonedDateTime.from('2026-08-25T09:00:00[Asia/Tokyo]');

// Converte de imediato para o fuso horário de Lisboa

const reuniaoLisboa = reuniaoToquio.withTimeZone('Europe/Lisbon');

console.log(reuniaoLisboa.toString()); // mostra a hora convertida para o fuso local