Aula 95 — Introdução à Temporal API

Na aula anterior, vimos por que o objeto Date causa tantos problemas.

Agora vamos conhecer a resposta moderna do JavaScript para trabalhar com datas e horários:

a Temporal API.

🎯 Objetivo da aula

Ao final desta aula, você será capaz de:

• Entender o que é a Temporal API
• Conhecer os principais tipos de data e hora
• Compreender a filosofia por trás da API
• Perceber como ela corrige os problemas do Date

O que é a Temporal API?

A Temporal API é uma API moderna do JavaScript criada para:

• substituir o objeto Date
• tratar datas e horários de forma correta
• eliminar ambiguidades de fuso e formatação

Ela foi projetada com base em anos de problemas reais enfrentados por desenvolvedores.

Estado atual da Temporal API

É importante ser transparente:

• a Temporal API é um padrão em evolução
• já está disponível em ambientes modernos
• pode exigir polyfill em alguns navegadores

A filosofia da Temporal API

A Temporal API segue alguns princípios claros:

• imutabilidade
• tipos explícitos
• separação de responsabilidades

Cada tipo representa um conceito específico de tempo.

Principais tipos da Temporal API

Vamos conhecer os mais importantes:

• Temporal.Now
• Temporal.PlainDate
• Temporal.PlainTime
• Temporal.PlainDateTime
• Temporal.ZonedDateTime
• Temporal.Duration

Não se preocupe em memorizar tudo agora — vamos por partes.

Temporal.Now — o “agora” correto

Para obter o momento atual:

 
  const agora = Temporal.Now.instant();
  console.log(agora.toString());
  // Saída será algo como: 2026-01-21T17:00:00Z

Aqui:

• o valor é absoluto
• independente de fuso
• ideal para registros e logs

Temporal.PlainDate — apenas a data

Quando você só precisa de uma data:

 
  const aniversario = Temporal.PlainDate.from("2026-01-21");
  console.log(aniversario.toString());
  // Saída será: 2026-01-21

Sem hora, sem fuso, sem surpresas.

Temporal.PlainTime — apenas o horário

 
  const horario = Temporal.PlainTime.from("14:30");
  console.log(horario.toString());
  // Saída será: 14:30:00

Perfeito para:

• horários comerciais
• agendas

Temporal.PlainDateTime — data + hora

 
  const evento = Temporal.PlainDateTime.from("2026-01-21T14:30");
  console.log(evento.toString());
  // Saída será: 2026-01-21T14:30:00

Aqui ainda não existe fuso horário.

Temporal.ZonedDateTime — data, hora e fuso

Quando o fuso importa:

 
  const eventoSP = Temporal.ZonedDateTime.from("2026-01-21T14:30[America/Sao_Paulo]");
  console.log(eventoSP.toString());
  // Saída será algo como: 2026-01-21T14:30:00-03:00[America/Sao_Paulo]

Temporal.Duration — períodos de tempo

 
  const duracao = Temporal.Duration.from({ days: 7 });
  console.log(duracao.toString());
  // Saída será: P7D

Ideal para:

• prazos
• intervalos
• cálculos de tempo

Por que a Temporal API é melhor?

• imutável (não muda sem você querer)
• tipos claros
• sem meses começando em zero
• fusos explícitos

Cada problema clássico do Date foi tratado diretamente.

Integração com Intl

A Temporal API cuida da lógica.

A API Intl cuida da exibição.

Essa separação é proposital e saudável.

Na próxima aula, vamos trabalhar com datas e fusos horários na prática usando a Temporal API.