Aula 96 — Trabalhando com datas e fusos

Até aqui, aprendemos por que o Date é problemático e conhecemos a Temporal API.

Agora vamos aplicar esse conhecimento ao cenário mais delicado de todos:

datas que dependem de fuso horário.

🎯 Objetivo da aula

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

• Entender o que é um fuso horário
• Trabalhar com datas absolutas e locais
• Converter datas entre fusos corretamente
• Evitar erros comuns em aplicações globais

O que é um fuso horário?

Um fuso horário define:

• a diferença em relação ao UTC
• como a hora local deve ser interpretada

Exemplos:

• America/Sao_Paulo
• Europe/London
• Asia/Tokyo

Esses nomes vêm do banco de dados IANA Time Zone.

Data absoluta vs data local

Antes de escrever código, precisamos separar dois conceitos:

• Data absoluta → um instante no tempo (UTC)
• Data local → como esse instante aparece em um fuso

Misturar esses conceitos é a raiz da maioria dos bugs.

Temporal.Instant — o tempo absoluto

Temporal.Instant representa um momento exato no tempo:

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

Aqui:

• não existe fuso
• não existe localidade
• é ideal para banco de dados

Convertendo um instante para um fuso

Para exibir esse instante para um usuário:

   const agora = Temporal.Now.instant();
   const agoraSP = agora.toZonedDateTimeISO("America/Sao_Paulo");
   const agoraTokyo = agora.toZonedDateTimeISO("Asia/Tokyo");
   console.log(agoraSP.toString());
   // Saída será algo como: 2026-01-21T14:00:00-03:00[America/Sao_Paulo]
   console.log(agoraTokyo.toString());
   // Saída será algo como: 2026-01-22T02:00:00+09:00[Asia/Tokyo]

O instante é o mesmo — o que muda é a interpretação local.

Criando eventos locais corretamente

Imagine um evento marcado para:

21 de janeiro de 2026 às 14h em São Paulo

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

Aqui:

• a data é local
• o fuso é explícito
• não há ambiguidade

Convertendo o evento para outro fuso

 
  const eventoTokyo = eventoSP.withTimeZone("Asia/Tokyo");
  console.log(eventoTokyo.toString());
  // Saída será algo como: 2026-01-22T02:00:00+09:00[Asia/Tokyo]

O horário muda, mas o evento continua sendo o mesmo.

Erro clássico com Date (comparação)

Com Date, esse cenário costuma gerar bugs:

• strings interpretadas em fusos diferentes
• horários deslocados sem aviso
• datas “pulando” de dia

Calculando diferenças entre datas

Com Temporal, cálculos são semânticos:

 
  const inicio = Temporal.ZonedDateTime.from( "2026-01-01T00:00[America/Sao_Paulo]" );
  const fim = Temporal.ZonedDateTime.from("2026-01-21T00:00[America/Sao_Paulo]");
  const diferenca = fim.since(inicio);
  console.log(diferenca.days);
  // Saída será: 20

Nada de milissegundos sem significado.

Quando usar cada tipo?

• Temporal.Instant → registros, logs, banco de dados
• Temporal.PlainDate → datas sem hora
• Temporal.ZonedDateTime → eventos com fuso

Integração com Intl (exibição)

Depois de resolver a lógica com Temporal:

• use Intl para formatar
• respeite idioma e cultura do usuário

Na próxima aula, vamos fechar esse bloco com:

Boas práticas modernas com datas.