Jeff Bruchado
Voltar para o Blog

ES2026 Temporal API: O Fim do Sofrimento Com Datas em JavaScript

Ola HaWkers, depois de anos de espera e desenvolvimento, a Temporal API finalmente faz parte do ECMAScript 2026. Essa nova API promete resolver os problemas historicos que todo desenvolvedor JavaScript enfrentou ao trabalhar com datas e horarios.

Vamos explorar o que muda, como usar, e por que voce vai querer abandonar o objeto Date o mais rapido possivel.

O Problema Com Date

Por Que Date e Tao Ruim

O objeto Date do JavaScript foi copiado do Java 1.0 em 1995 e herdou todos os seus problemas. A propria linguagem Java ja deprecou a maioria dos metodos originais.

Problemas classicos:

// Meses comecam em 0 (Janeiro = 0, nao 1)
const data = new Date(2026, 0, 15); // 15 de Janeiro, nao Fevereiro

// Mutabilidade inesperada
const original = new Date();
const copia = original;
copia.setMonth(5); // Ops, mudou o original tambem!

// Parsing inconsistente entre browsers
new Date('2026-01-15'); // Pode ser interpretado diferente

// Timezone hell
const local = new Date();
const utc = new Date(local.toISOString());
// Qual e a diferenca? Depende de onde voce esta

// Operacoes matematicas estranhas
const d1 = new Date(2026, 0, 31);
d1.setMonth(1); // Deveria ser 31 de Fevereiro?
// Na verdade vira 3 de Marco (overflow automatico)

Por que bibliotecas existem:

Moment.js, date-fns, Luxon e Day.js existem precisamente porque Date e inadequado para trabalho serio. Mas adicionar dependencias para algo tao fundamental sempre foi subotimo.

A Temporal API

Conceitos Fundamentais

A Temporal API introduz varios novos tipos, cada um com proposito especifico.

Tipos principais:

Tipo Proposito Exemplo
Temporal.Instant Momento exato no tempo (UTC) Timestamp de log
Temporal.ZonedDateTime Data/hora com timezone Hora de reuniao
Temporal.PlainDateTime Data/hora sem timezone Hora local generica
Temporal.PlainDate Apenas data Data de nascimento
Temporal.PlainTime Apenas hora Alarme
Temporal.Duration Duracao 2 horas e 30 minutos

Principio fundamental:

"Cada tipo representa exatamente o que voce precisa - nada mais, nada menos."

Imutabilidade

Todos os objetos Temporal sao imutaveis. Operacoes retornam novos objetos.

// Temporal - imutavel e seguro
const data = Temporal.PlainDate.from('2026-01-15');
const proximoMes = data.add({ months: 1 });

console.log(data.toString()); // 2026-01-15 (nao mudou!)
console.log(proximoMes.toString()); // 2026-02-15

// Comparacao com Date - mutavel e perigoso
const dataAntiga = new Date('2026-01-15');
dataAntiga.setMonth(dataAntiga.getMonth() + 1);
// Original foi modificado!

Exemplos Praticos

Trabalhando Com Datas

Operacoes comuns ficam muito mais intuitivas.

// Criar uma data
const aniversario = Temporal.PlainDate.from('2026-06-15');
// ou
const aniversario2 = Temporal.PlainDate.from({
  year: 2026,
  month: 6,
  day: 15
});

// Adicionar/subtrair tempo
const emUmaSemana = aniversario.add({ weeks: 1 });
const haTresDias = aniversario.subtract({ days: 3 });

// Comparar datas (finalmente faz sentido!)
const hoje = Temporal.Now.plainDateISO();

if (Temporal.PlainDate.compare(aniversario, hoje) > 0) {
  console.log('O aniversario ainda nao chegou');
}

// Calcular diferenca
const diasAteAniversario = hoje.until(aniversario, {
  largestUnit: 'day'
});
console.log(`Faltam ${diasAteAniversario.days} dias`);

Trabalhando Com Timezones

Timezones deixam de ser um pesadelo.

// Criar data/hora com timezone
const reuniao = Temporal.ZonedDateTime.from({
  year: 2026,
  month: 1,
  day: 27,
  hour: 15,
  minute: 0,
  timeZone: 'America/Sao_Paulo'
});

console.log(reuniao.toString());
// 2026-01-27T15:00:00-03:00[America/Sao_Paulo]

// Converter para outro timezone
const reuniaoEmNY = reuniao.withTimeZone('America/New_York');
console.log(reuniaoEmNY.toString());
// 2026-01-27T13:00:00-05:00[America/New_York]

// Obter hora atual em timezone especifico
const agoraEmTokyo = Temporal.Now.zonedDateTimeISO('Asia/Tokyo');
console.log(`Em Tokyo sao ${agoraEmTokyo.hour}:${agoraEmTokyo.minute}`);

Trabalhando Com Duracoes

Duracoes tem representacao propria e operacoes intuitivas.

// Criar duracao
const tempoDeCorrida = Temporal.Duration.from({
  hours: 1,
  minutes: 45,
  seconds: 30
});

// Operacoes com duracao
const duasCorridas = tempoDeCorrida.add(tempoDeCorrida);
console.log(duasCorridas.toString()); // PT3H31M

// Arredondar duracao
const arredondado = tempoDeCorrida.round({
  smallestUnit: 'minute',
  roundingMode: 'ceil'
});
console.log(arredondado.toString()); // PT1H46M

// Calcular duracao entre dois momentos
const inicio = Temporal.PlainTime.from('09:00');
const fim = Temporal.PlainTime.from('17:30');
const jornada = inicio.until(fim);
console.log(`Jornada: ${jornada.hours}h ${jornada.minutes}min`);

Formatacao

A formatacao e integrada com Intl.

const data = Temporal.PlainDate.from('2026-01-27');

// Formatacao com Intl
const formatoBR = new Intl.DateTimeFormat('pt-BR', {
  dateStyle: 'full'
});

console.log(formatoBR.format(data));
// terça-feira, 27 de janeiro de 2026

// Formatacao customizada
const formatoCustom = new Intl.DateTimeFormat('pt-BR', {
  weekday: 'short',
  day: 'numeric',
  month: 'short'
});

console.log(formatoCustom.format(data));
// ter., 27 de jan.

Casos de Uso Comuns

Agendamento de Eventos

Um caso classico que Date torna complicado.

// Agendar evento recorrente
function proximasOcorrencias(
  inicio,
  intervalo,
  quantidade
) {
  const ocorrencias = [];
  let atual = inicio;

  for (let i = 0; i < quantidade; i++) {
    ocorrencias.push(atual);
    atual = atual.add(intervalo);
  }

  return ocorrencias;
}

const primeiraReuniao = Temporal.ZonedDateTime.from({
  year: 2026,
  month: 2,
  day: 1,
  hour: 10,
  minute: 0,
  timeZone: 'America/Sao_Paulo'
});

const reunioesSemanais = proximasOcorrencias(
  primeiraReuniao,
  { weeks: 1 },
  4
);

reunioesSemanais.forEach((r, i) => {
  console.log(`Reuniao ${i + 1}: ${r.toPlainDate().toString()}`);
});
// Reuniao 1: 2026-02-01
// Reuniao 2: 2026-02-08
// Reuniao 3: 2026-02-15
// Reuniao 4: 2026-02-22

Calculo de Idade

Outro caso que Date torna desnecessariamente complicado.

function calcularIdade(dataNascimento) {
  const nascimento = Temporal.PlainDate.from(dataNascimento);
  const hoje = Temporal.Now.plainDateISO();

  const duracao = nascimento.until(hoje, {
    largestUnit: 'year'
  });

  return {
    anos: duracao.years,
    meses: duracao.months,
    dias: duracao.days
  };
}

const idade = calcularIdade('1990-05-15');
console.log(`${idade.anos} anos, ${idade.meses} meses e ${idade.dias} dias`);

Trabalhando Com Calendarios

A Temporal API suporta multiplos sistemas de calendario.

// Calendario gregoriano (padrao)
const dataGregoria = Temporal.PlainDate.from('2026-01-27');

// Converter para calendario hebraico
const dataHebraica = dataGregoria.withCalendar('hebrew');
console.log(dataHebraica.toString());
// Exemplo: 2026-01-27[u-ca=hebrew]

// Calendario japones
const dataJaponesa = dataGregoria.withCalendar('japanese');
console.log(`Era: ${dataJaponesa.era}, Ano: ${dataJaponesa.eraYear}`);

// Calendario islamico
const dataIslamica = dataGregoria.withCalendar('islamic');
console.log(dataIslamica.toString());

Migracao de Date e Bibliotecas

De Date Para Temporal

Como converter codigo existente.

// Date para Temporal
const dateAntigo = new Date();

// Para Instant (momento exato)
const instant = Temporal.Instant.fromEpochMilliseconds(
  dateAntigo.getTime()
);

// Para ZonedDateTime (com timezone local)
const zdt = instant.toZonedDateTimeISO(
  Temporal.Now.timeZoneId()
);

// Para PlainDate (apenas data)
const plainDate = zdt.toPlainDate();

// Temporal para Date (quando necessario para APIs antigas)
const deVoltaParaDate = new Date(
  instant.epochMilliseconds
);

De Moment/Day.js Para Temporal

// Moment.js
// moment('2026-01-27').add(1, 'month').format('YYYY-MM-DD')

// Temporal equivalente
Temporal.PlainDate.from('2026-01-27')
  .add({ months: 1 })
  .toString();

// Day.js
// dayjs('2026-01-27').diff(dayjs('2026-01-01'), 'day')

// Temporal equivalente
Temporal.PlainDate.from('2026-01-01')
  .until(Temporal.PlainDate.from('2026-01-27'))
  .total('day');

Suporte e Polyfills

Status de Implementacao

Em Janeiro de 2026, o suporte esta em expansao.

Browsers:

Browser Status
Chrome Disponivel (flag ate v130, padrao v135+)
Firefox Em implementacao
Safari Preview disponivel
Edge Segue Chrome

Runtimes:

Runtime Status
Node.js Disponivel v23+
Deno Disponivel v2.0+
Bun Disponivel v1.2+

Usando Polyfill

Para ambientes sem suporte nativo.

// Instalacao
// npm install @js-temporal/polyfill

// Uso
import { Temporal } from '@js-temporal/polyfill';

// O codigo funciona identico ao nativo
const hoje = Temporal.Now.plainDateISO();
console.log(hoje.toString());

Conclusao

A Temporal API representa uma das maiores melhorias ao JavaScript em anos. Apos decadas sofrendo com o objeto Date, finalmente temos uma API de datas e horas que faz sentido, e imutavel, e suporta timezones adequadamente.

Pontos principais:

  1. Temporal API faz parte do ES2026 e esta chegando aos browsers
  2. Multiplos tipos para diferentes necessidades (Instant, ZonedDateTime, PlainDate, etc.)
  3. Imutabilidade por padrao evita bugs comuns
  4. Timezones funcionam corretamente
  5. Polyfills disponiveis para uso imediato

Para desenvolvedores JavaScript, a recomendacao e: comece a usar Temporal o mais rapido possivel, seja via polyfill ou em ambientes com suporte nativo. E uma daquelas mudancas que, uma vez adotadas, voce nunca mais vai querer voltar atras.

Para mais sobre novas features do JavaScript, leia: Pattern Matching em JavaScript: A Proposta TC39 Que Vai Mudar Seu Codigo.

Bora pra cima! 🦅

Comentários (0)

Esse artigo ainda não possui comentários 😢. Seja o primeiro! 🚀🦅

Adicionar comentário