ES2026 Temporal API: JavaScript Finalmente Resolve o Problema de Datas Apos 25 Anos

Ola HaWkers, depois de mais de 25 anos, JavaScript finalmente vai ter uma API de datas decente. A Temporal API esta confirmada para o ES2026 e promete acabar com todas as dores de cabeca que conhecemos do objeto Date. Nao mais bibliotecas externas para fazer operacoes basicas com datas.

Quantas vezes voce ja precisou instalar moment.js, date-fns ou dayjs so para formatar uma data ou calcular a diferenca entre dois dias? Esses dias estao contados.

O Problema com Date em JavaScript

O objeto Date do JavaScript e notoriamente problematico. Ele foi copiado do Java 1.0 em 1995 e carrega todos os problemas daquela epoca:

Problemas Classicos do Date

Mutabilidade:

// Date e mutavel - isso e um problema
const data = new Date('2026-01-04');
data.setMonth(5); // Modifica o objeto original!
console.log(data); // Jun 04 2026 - surpresa!

Meses comecam em 0:

// Janeiro e 0, Dezembro e 11 - confuso!
const janeiro = new Date(2026, 0, 1); // Janeiro
const dezembro = new Date(2026, 11, 25); // Dezembro

// Quem nunca errou isso?
const erroComum = new Date(2026, 1, 1); // Fevereiro, nao Janeiro!

Timezone inconsistente:

// Comportamento imprevisivel com timezones
const data = new Date('2026-01-04');
console.log(data.getDate()); // Pode retornar 3 ou 4 dependendo do timezone!

// Parsing de string e perigoso
const perigoso = new Date('01-04-2026'); // Formato ambiguo

Operacoes matematicas manuais:

// Adicionar 7 dias - muito verboso
const hoje = new Date();
const proximaSemana = new Date(hoje.getTime() + 7 * 24 * 60 * 60 * 1000);
// E se tiver horario de verao? Boa sorte!

Conhecendo a Temporal API

A Temporal API resolve todos esses problemas com uma abordagem moderna e bem pensada.

Tipos Principais

A Temporal introduz varios tipos especializados:

// Temporal.PlainDate - apenas data, sem hora ou timezone
const aniversario = Temporal.PlainDate.from('2026-03-15');
const aniversario2 = Temporal.PlainDate.from({ year: 2026, month: 3, day: 15 });

// Temporal.PlainTime - apenas hora, sem data ou timezone
const reuniao = Temporal.PlainTime.from('14:30:00');
const reuniao2 = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });

// Temporal.PlainDateTime - data + hora, sem timezone
const evento = Temporal.PlainDateTime.from('2026-03-15T14:30:00');

// Temporal.ZonedDateTime - data + hora + timezone (mais completo)
const voo = Temporal.ZonedDateTime.from('2026-03-15T14:30:00[America/Sao_Paulo]');

// Temporal.Instant - momento exato no tempo (como Unix timestamp)
const agora = Temporal.Now.instant();

// Temporal.Duration - duracao de tempo
const duracao = Temporal.Duration.from({ hours: 2, minutes: 30 });

Imutabilidade Garantida

Todos os objetos Temporal sao imutaveis:

const hoje = Temporal.PlainDate.from('2026-01-04');

// Operacoes retornam NOVOS objetos
const amanha = hoje.add({ days: 1 });
const ontem = hoje.subtract({ days: 1 });

console.log(hoje.toString());   // 2026-01-04 (inalterado!)
console.log(amanha.toString()); // 2026-01-05
console.log(ontem.toString());  // 2026-01-03

Operacoes Praticas com Temporal

Vamos ver exemplos praticos que voce usara no dia a dia:

Calculando Diferencas Entre Datas

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

// Calcular diferenca
const diferenca = inicio.until(fim);
console.log(diferenca.toString()); // P2M11D (2 meses e 11 dias)

// Especificar unidades desejadas
const diasAte = inicio.until(fim, { largestUnit: 'day' });
console.log(diasAte.days); // 70

// Comparacao simples
const mesmoDia = inicio.equals(fim); // false
const anterior = Temporal.PlainDate.compare(inicio, fim); // -1 (inicio < fim)

Trabalhando com Timezones

// Converter entre timezones
const reuniaoNY = Temporal.ZonedDateTime.from(
  '2026-03-15T09:00:00[America/New_York]'
);

const reuniaoSP = reuniaoNY.withTimeZone('America/Sao_Paulo');
console.log(reuniaoSP.toString());
// 2026-03-15T11:00:00-03:00[America/Sao_Paulo]

// Listar timezones disponiveis
const timezones = Temporal.Timezone.allTimeZones;
console.log(timezones);
// ['Africa/Abidjan', 'Africa/Accra', 'America/Sao_Paulo', ...]

// Obter timezone local
const local = Temporal.Now.timeZone();
console.log(local.toString()); // 'America/Sao_Paulo'

Formatacao de Datas

const data = Temporal.PlainDate.from('2026-03-15');

// Usando Intl.DateTimeFormat (ja existe no JS)
const formatter = new Intl.DateTimeFormat('pt-BR', {
  dateStyle: 'full',
});
console.log(formatter.format(data));
// 'domingo, 15 de marco de 2026'

// Diferentes locales
const formatterEN = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'long',
});
console.log(formatterEN.format(data));
// 'March 15, 2026'

Casos de Uso Reais

Sistema de Agendamento

interface Appointment {
  id: string;
  title: string;
  start: Temporal.ZonedDateTime;
  duration: Temporal.Duration;
}

class Scheduler {
  private appointments: Appointment[] = [];

  addAppointment(
    title: string,
    start: string,
    timezone: string,
    durationMinutes: number
  ): Appointment {
    const appointment: Appointment = {
      id: crypto.randomUUID(),
      title,
      start: Temporal.ZonedDateTime.from(`${start}[${timezone}]`),
      duration: Temporal.Duration.from({ minutes: durationMinutes }),
    };

    // Verificar conflitos
    if (this.hasConflict(appointment)) {
      throw new Error('Horario conflita com outro agendamento');
    }

    this.appointments.push(appointment);
    return appointment;
  }

  hasConflict(newAppointment: Appointment): boolean {
    const newEnd = newAppointment.start.add(newAppointment.duration);

    return this.appointments.some((existing) => {
      const existingEnd = existing.start.add(existing.duration);

      // Verifica se ha sobreposicao
      return (
        Temporal.ZonedDateTime.compare(newAppointment.start, existingEnd) < 0 &&
        Temporal.ZonedDateTime.compare(newEnd, existing.start) > 0
      );
    });
  }

  getAppointmentsForDate(date: Temporal.PlainDate): Appointment[] {
    return this.appointments.filter((apt) =>
      apt.start.toPlainDate().equals(date)
    );
  }
}

// Uso
const scheduler = new Scheduler();

scheduler.addAppointment(
  'Reuniao com cliente',
  '2026-03-15T10:00:00',
  'America/Sao_Paulo',
  60
);

scheduler.addAppointment(
  'Daily standup',
  '2026-03-15T09:00:00',
  'America/Sao_Paulo',
  15
);

Calculadora de Idade

function calculateAge(birthDate: string): {
  years: number;
  months: number;
  days: number;
} {
  const birth = Temporal.PlainDate.from(birthDate);
  const today = Temporal.Now.plainDateISO();

  const age = birth.until(today, { largestUnit: 'year' });

  return {
    years: age.years,
    months: age.months,
    days: age.days,
  };
}

const idade = calculateAge('1990-05-15');
console.log(`${idade.years} anos, ${idade.months} meses e ${idade.days} dias`);
// "35 anos, 9 meses e 20 dias"

Countdown para Eventos

function createCountdown(eventDate: string, eventTimezone: string) {
  const event = Temporal.ZonedDateTime.from(`${eventDate}[${eventTimezone}]`);

  return function getRemaining(): Temporal.Duration {
    const now = Temporal.Now.zonedDateTimeISO(eventTimezone);
    return now.until(event);
  };
}

const countdown = createCountdown('2026-12-31T23:59:59', 'America/Sao_Paulo');
const remaining = countdown();

console.log(`Faltam ${remaining.days} dias, ${remaining.hours} horas`);
// "Faltam 361 dias, 8 horas"

Suporte e Polyfills

A Temporal API esta em Stage 3 do TC39 e prevista para ES2026:

Status Atual

Navegadores:

Chrome 144+: Suporte nativo (Janeiro 2026)
Firefox: Em desenvolvimento
Safari: Em desenvolvimento

Runtimes:

Node.js: Flag experimental
Deno: Suporte nativo
Bun: Suporte nativo

Usando Polyfill Hoje

# Instalar polyfill oficial
npm install @js-temporal/polyfill

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

// Usar normalmente
const hoje = Temporal.Now.plainDateISO();
console.log(hoje.toString());

Migracao do Date para Temporal

Se voce tem codigo existente usando Date, aqui esta como migrar:

// ANTES: Date
const oldDate = new Date('2026-03-15T10:00:00');
const oldNextWeek = new Date(oldDate.getTime() + 7 * 24 * 60 * 60 * 1000);
const oldFormatted = oldDate.toLocaleDateString('pt-BR');

// DEPOIS: Temporal
const newDate = Temporal.PlainDateTime.from('2026-03-15T10:00:00');
const newNextWeek = newDate.add({ days: 7 });
const newFormatted = newDate.toLocaleString('pt-BR');

Conclusao

A Temporal API e uma das adicoes mais esperadas ao JavaScript. Depois de decadas dependendo de bibliotecas externas para operacoes basicas com datas, finalmente teremos uma solucao nativa, imutavel e bem projetada.

Se voce trabalha com datas em JavaScript (e quem nao trabalha?), comece a estudar a Temporal API agora. Use o polyfill em projetos novos e prepare-se para quando o suporte nativo estiver amplamente disponivel.

Se voce se sente inspirado pela evolucao do JavaScript, recomendo que de uma olhada em outro artigo: ES Modules Domina 2026: Por Que o CommonJS Esta Sendo Abandonado onde voce vai descobrir outra grande mudanca no ecossistema JavaScript.