Temporal API no Node.js 26: como funciona e quando trocar o Date

A Temporal API chega ativada por padrão no Node.js 26 — sem flag, sem polyfill, sem --harmony. O release de 5 de maio trouxe o motor V8 14.6 e, com ele, a implementação nativa de Temporal, a alternativa moderna ao objeto Date que o JavaScript arrasta há mais de duas décadas com problemas conhecidos: mutabilidade, ausência de suporte real a fusos horários e aritmética de datas que quebra em edge cases. A questão prática não é se vale aprender, mas quando Temporal resolve melhor que Date — e quando o overhead conceitual não compensa.

O que Temporal muda na prática em relação a Date

O Date do JavaScript representa um único ponto no tempo: milissegundos desde 1º de janeiro de 1970 UTC. Toda operação de fuso horário é delegada ao sistema operacional, e o resultado muda conforme o locale da máquina. Temporal desmembra esse conceito monolítico em tipos distintos, cada um com responsabilidade clara:

• Temporal.Instant — ponto absoluto no tempo (equivalente a timestamp UTC), imutável.
• Temporal.PlainDate — data sem hora e sem fuso: "2026-05-11", ponto. Não muda se o servidor está em São Paulo ou Tokyo.
• Temporal.PlainTime — hora sem data e sem fuso: "14:30:00".
• Temporal.PlainDateTime — data + hora, mas ainda sem fuso. Representa um "relógio de parede".
• Temporal.ZonedDateTime — data + hora + fuso horário explícito. É o tipo que resolve a maioria dos bugs reais de timezone.
• Temporal.Duration — intervalo de tempo ("2 horas e 30 minutos"), com aritmética que respeita meses de tamanho diferente.

A diferença mais importante: todos os tipos Temporal são imutáveis. Chamar .add() ou .subtract() retorna um novo objeto. Com Date, chamar setMonth() muta o objeto original — fonte histórica de bugs silenciosos em scheduling, geração de relatórios e qualquer lógica que reutilize a mesma instância.

ZonedDateTime vs toLocaleString: fusos no Brasil sem gambiarras

O Brasil opera com quatro fusos horários oficiais e, dependendo do estado, horário de verão pode ou não existir (foi abolido em 2019 mas pode voltar). Quem precisa agendar um job, gerar um recibo com hora local ou exibir deadline pro usuário final enfrenta dois problemas com Date: o construtor assume UTC ou o locale da máquina, e converter entre fusos exige bibliotecas como date-fns-tz ou luxon.

Temporal.ZonedDateTime resolve isso nativamente. O fuso é parte do tipo, não uma string passada pra função de formatação. Quem lida com fusos horários em JavaScript conhece as dores de offset manualmente calculado — Temporal elimina essa camada.

A vantagem não é estética. É que Temporal.ZonedDateTime carrega o IANA timezone database junto, então a conversão entre America/Sao_Paulo e America/Manaus (fuso -4h sem horário de verão) funciona sem lookup manual. Quem persiste timestamps no banco de dados pode converter pra Temporal.Instant antes de salvar e reconstruir o ZonedDateTime na leitura.

Aritmética de datas: onde Temporal evita bugs reais

Somar 1 mês a 31 de janeiro com Date é um clássico: o resultado é 3 de março (porque fevereiro não tem 31 dias e Date transborda silenciosamente). Temporal.PlainDate lança erro ou resolve com overflow controlado:

Duration também resolve a ambiguidade de "1 mês". Com Date, somar 30 dias não é a mesma coisa que somar 1 mês (março tem 31 dias). Temporal.Duration distingue { months: 1 } de { days: 30 } — e a aritmética respeita o calendário.

Quando Date nativo ainda resolve (e Temporal é excesso)

Nem todo código que toca em data precisa migrar. Para operações simples e UTC-only, Date continua funcional e mais direto:

• Timestamp de log: Date.now() retorna milissegundos UTC. Funciona, é rápido, não precisa de Temporal.
• Comparação simples entre dois pontos: dateA.getTime() > dateB.getTime() resolve. Temporal.Instant.compare() faz o mesmo com mais cerimônia.
• Exibição formatada sem fuso: toISOString() gera ISO 8601 e é suficiente para APIs internas que só trafegam UTC.
• Scripts pontuais e CLIs: se o código roda uma vez, no mesmo fuso, e não persiste resultado, a complexidade extra de Temporal não paga.

Comparação direta: Temporal vs Date vs date-fns/luxon

Até agora, quem queria timezone handling decente em Node.js dependia de libs externas. Com Temporal nativo no Node 26, a equação muda:

Armadilhas ao adotar Temporal em produção

A API é bem desenhada, mas tem ciladas que aparecem em uso real:

1. Serialização e persistência. Temporal.ZonedDateTime.toString() gera uma string como 2026-06-10T09:00:00-03:00[America/Sao_Paulo]. Nem todo banco ou ORM parseia isso. Ao gravar, converta pra Instant (epoch millis ou ISO 8601 UTC) e persista o timezone como coluna separada, se necessário. Essa lógica é parecida com a decisão entre DATETIME e TIMESTAMP em bancos relacionais.
2. `Temporal.Now` não é mockável por padrão. Em testes, quem usa jest.useFakeTimers() controla Date.now(). Temporal.Now.instant() não é interceptado pela mesma API. Isolar a chamada num módulo próprio (wrapper injetável) resolve, mas exige refactor.
3. Conversão Date ↔ Temporal não é automática. Libs que retornam Date (drivers de banco, SDKs de terceiros) não viram Temporal.Instant sozinhas. O caminho é Temporal.Instant.fromEpochMilliseconds(date.getTime()) — funcional mas verboso.
4. Performance em loops pesados. Criar milhares de Temporal.ZonedDateTime em loop (relatório com linha por minuto, por exemplo) pode ser mais lento que operar milissegundos crus com Date. Se a operação é bulk e sem exibição pra usuário, considerar manter timestamps numéricos e converter só na saída.
5. Confusão entre Plain e Zoned. PlainDateTime parece completo (tem data e hora), mas não tem fuso. Comparar um PlainDateTime de São Paulo com um de Manaus não faz sentido — são relógios de parede sem referência absoluta. Usar ZonedDateTime ou Instant quando precisar comparar entre fusos.

Exemplo real: agendar job em fuso brasileiro e converter pra UTC

Um cenário comum: um sistema precisa disparar e-mail de cobrança às 9h no horário do cliente, que está em São Paulo. O servidor roda em UTC (Vercel, Cloudflare Workers, qualquer cloud). Com Temporal, o código fica explícito e auditável:

Repare que dayOfWeek retorna 1–7 (segunda a domingo), diferente de Date.getDay() que retorna 0–6 (domingo a sábado). Essa mudança de convenção é um ponto de atenção na migração. Quem já trabalha com Unix timestamps vai notar que o epochMilliseconds mantém compatibilidade direta com o ecossistema existente.

Como migrar gradualmente sem reescrever tudo

Trocar todo Date por Temporal de uma vez é receita pra quebrar coisas. Uma migração pragmática funciona em camadas:

1. Isolar a camada de tempo. Criar um módulo time.ts que exporta funções como now(), fromEpoch(), toUserTimezone(). Internamente, migrar essas funções pra Temporal. O resto do código continua chamando as mesmas funções.
2. Converter nas bordas. Na entrada (request do usuário, webhook, fila), converter pra Temporal.Instant ou ZonedDateTime. Na saída (resposta JSON, gravação no banco), converter de volta pra ISO string ou epoch millis. O core da aplicação opera com tipos Temporal.
3. Manter Date nos testes que já funcionam. Não refatorar suíte de testes que está verde só pra usar Temporal. Adicionar testes novos com Temporal nas funções migradas.
4. Remover date-fns/luxon só depois de cobertura. Quando todas as funções do módulo time.ts estiverem com Temporal e testes passando, remover a dependência de terceiros. Até lá, as duas coexistem.

Essa abordagem evita big bang e permite reverter um arquivo de cada vez se algo quebrar.