Temporal | Typescript

• Temporal | Typescript

---

Namespace Temporal no JavaScript

sidebar_position: 1
tags:
  - javascript
  - temporal
  - date
  - ecmascript

O que é o Temporal

O Temporal é a nova API moderna do JavaScript para trabalhar com datas, horários, duração, fuso horário e calendário.

Ele vem para resolver vários problemas históricos do Date, como:

Problema do Date	Como o Temporal melhora
API confusa	Tipos separados para cada caso de uso
Objeto mutável	Objetos do Temporal são imutáveis
Fuso horário difícil	Suporte explícito a time zones
Parsing inconsistente	Parsing mais previsível
Mistura data, hora e timezone	Cada conceito tem seu próprio tipo
Trabalhar só com data é ruim	Existe Temporal.PlainDate
Trabalhar só com hora é ruim	Existe Temporal.PlainTime

O Temporal é exposto como um namespace global, parecido com Math ou Intl.

Temporal.Now.plainDateISO();
Temporal.PlainDate.from("2026-05-19");
Temporal.Duration.from({ days: 3 });

Ele não é um construtor direto.

new Temporal(); 
// TypeError: Temporal is not a constructor

A documentação da TC39 descreve o Temporal justamente como um objeto global que atua como um namespace de alto nível, semelhante ao Math. A MDN também o descreve como substituto moderno do Date, embora ainda marque suporte como limitado em alguns ambientes. (TC39)

Estrutura do namespace

Dentro de Temporal, existem vários tipos especializados:

Temporal.Now
Temporal.Instant
Temporal.PlainDate
Temporal.PlainTime
Temporal.PlainDateTime
Temporal.ZonedDateTime
Temporal.Duration
Temporal.PlainYearMonth
Temporal.PlainMonthDay

Principais tipos

Tipo	Quando usar
Temporal.Now	Pegar data/hora atual
Temporal.Instant	Representar um ponto exato no tempo
Temporal.PlainDate	Trabalhar apenas com data
Temporal.PlainTime	Trabalhar apenas com hora
Temporal.PlainDateTime	Data e hora sem fuso horário
Temporal.ZonedDateTime	Data e hora com fuso horário
Temporal.Duration	Representar duração
Temporal.PlainYearMonth	Trabalhar com ano e mês
Temporal.PlainMonthDay	Trabalhar com mês e dia

Temporal.Now

Usado para obter valores atuais.

const hoje = Temporal.Now.plainDateISO();

console.log(hoje.toString());
// "2026-05-19"

Com horário:

const agora = Temporal.Now.plainDateTimeISO();

console.log(agora.toString());

Com timezone:

const agoraEmSaoPaulo = Temporal.Now.zonedDateTimeISO("America/Sao_Paulo");

console.log(agoraEmSaoPaulo.toString());

Temporal.PlainDate

Use quando você precisa representar apenas uma data, sem hora e sem timezone.

const data = Temporal.PlainDate.from("2026-05-19");

console.log(data.year); 
console.log(data.month); 
console.log(data.day);

Adicionar dias:

const vencimento = Temporal.PlainDate
  .from("2026-05-19")
  .add({ days: 10 });

console.log(vencimento.toString());
// "2026-05-29"

Subtrair meses:

const data = Temporal.PlainDate
  .from("2026-05-19")
  .subtract({ months: 1 });

console.log(data.toString());
// "2026-04-19"

Temporal.PlainTime

Use quando você precisa representar somente horário.

const hora = Temporal.PlainTime.from("14:30:00");

console.log(hora.hour);
// 14

Adicionar tempo:

const novaHora = Temporal.PlainTime
  .from("14:30")
  .add({ hours: 2, minutes: 15 });

console.log(novaHora.toString());
// "16:45:00"

Temporal.PlainDateTime

Use quando você precisa de data e hora, mas sem fuso horário.

const dataHora = Temporal.PlainDateTime.from("2026-05-19T14:30:00");

console.log(dataHora.toString());
// "2026-05-19T14:30:00"

Esse tipo é bom para representar algo como:

Consulta marcada para 19/05/2026 às 14:30

Mas ele não representa sozinho um instante global, porque não tem timezone.

Temporal.ZonedDateTime

Use quando o fuso horário importa.

const dataHora = Temporal.ZonedDateTime.from({
  year: 2026,
  month: 5,
  day: 19,
  hour: 14,
  minute: 30,
  timeZone: "America/Sao_Paulo"
});

console.log(dataHora.toString());

Esse é o tipo ideal para eventos reais em calendário, agendamento, job scheduler, expiração de token, vencimento com timezone e sistemas distribuídos.

Temporal.Instant

Representa um ponto exato na linha do tempo.

const instant = Temporal.Instant.from("2026-05-19T17:30:00Z");

console.log(instant.toString());
// "2026-05-19T17:30:00Z"

Comparação com Date:

const date = new Date("2026-05-19T17:30:00Z");
const instant = Temporal.Instant.from("2026-05-19T17:30:00Z");

O Instant é mais explícito: ele representa um instante absoluto, normalmente em UTC.

Temporal.Duration

Representa uma duração.

const duracao = Temporal.Duration.from({
  days: 2,
  hours: 3,
  minutes: 30
});

console.log(duracao.toString());
// "P2DT3H30M"

Somando duração a uma data:

const data = Temporal.PlainDate.from("2026-05-19");

const novaData = data.add({
  days: 5
});

console.log(novaData.toString());
// "2026-05-24"

Diferença entre os principais tipos

Situação	Tipo recomendado
Data de nascimento	Temporal.PlainDate
Horário de abertura	Temporal.PlainTime
Agendamento sem timezone definido	Temporal.PlainDateTime
Agendamento com timezone	Temporal.ZonedDateTime
Timestamp absoluto	Temporal.Instant
Intervalo de tempo	Temporal.Duration

Exemplo comparando com Date

Com Date:

const date = new Date("2026-05-19");

date.setDate(date.getDate() + 10);

console.log(date);

Problemas:

muta o objeto original
pode sofrer influência do timezone local
API pouco expressiva

Com Temporal:

const data = Temporal.PlainDate.from("2026-05-19");

const novaData = data.add({ days: 10 });

console.log(data.toString());
// "2026-05-19"

console.log(novaData.toString());
// "2026-05-29"

Aqui o objeto original não é alterado.

Imutabilidade

Os objetos do Temporal são imutáveis.

const data = Temporal.PlainDate.from("2026-05-19");

const novaData = data.add({ days: 1 });

console.log(data.toString());
// "2026-05-19"

console.log(novaData.toString());
// "2026-05-20"

Isso evita bugs comuns com Date, onde métodos como setDate, setMonth e setHours alteram o próprio objeto.

Trabalhando com diferença entre datas

const inicio = Temporal.PlainDate.from("2026-05-01");
const fim = Temporal.PlainDate.from("2026-05-19");

const diff = inicio.until(fim);

console.log(diff.toString());
// "P18D"

Com unidade explícita:

const diff = inicio.until(fim, {
  largestUnit: "days"
});

console.log(diff.days);
// 18

Comparando datas

const dataA = Temporal.PlainDate.from("2026-05-19");
const dataB = Temporal.PlainDate.from("2026-05-20");

const resultado = Temporal.PlainDate.compare(dataA, dataB);

console.log(resultado);
// -1

Resultado:

Valor	Significado
-1	primeira data é menor
0	datas iguais
1	primeira data é maior

Convertendo Date para Temporal

const date = new Date();

const instant = Temporal.Instant.from(date.toISOString());

Convertendo Temporal.Instant para Date:

const instant = Temporal.Now.instant();

const date = new Date(instant.epochMilliseconds);

Quando usar cada tipo no dia a dia

Data sem hora

const aniversario = Temporal.PlainDate.from("1995-08-10");

Hora sem data

const horarioAbertura = Temporal.PlainTime.from("08:00");

Data e hora sem timezone

const agendamento = Temporal.PlainDateTime.from("2026-05-19T14:30");

Data e hora com timezone

const evento = Temporal.ZonedDateTime.from({
  year: 2026,
  month: 5,
  day: 19,
  hour: 14,
  minute: 30,
  timeZone: "America/Sao_Paulo"
});

Timestamp absoluto

const criadoEm = Temporal.Now.instant();

Suporte nos ambientes

O Temporal já está avançado no processo de padronização e começou a aparecer em engines modernas, mas a disponibilidade ainda pode variar por navegador, runtime e versão. A MDN ainda marca o recurso como de disponibilidade limitada, então em produção é importante validar suporte ou usar polyfill. (MDN Web Docs)

Para projetos atuais, uma abordagem segura é:

npm install @js-temporal/polyfill

Uso:

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

const hoje = Temporal.Now.plainDateISO();

console.log(hoje.toString());

Exemplo prático em aplicação

Imagine uma regra de vencimento de boleto em 3 dias:

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

function calcularVencimento(dataBase) {
  return Temporal.PlainDate
    .from(dataBase)
    .add({ days: 3 })
    .toString();
}

console.log(calcularVencimento("2026-05-19"));
// "2026-05-22"

Exemplo com timezone

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

const agora = Temporal.Now.zonedDateTimeISO("America/Sao_Paulo");

console.log(agora.toString());

Exemplo para expiração

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

const agora = Temporal.Now.instant();

const expiracao = agora.add({
  minutes: 30
});

console.log(expiracao.toString());

Regra prática

Preciso de...	Use
Dia, mês e ano	Temporal.PlainDate
Hora, minuto e segundo	Temporal.PlainTime
Data + hora sem timezone	Temporal.PlainDateTime
Data + hora com timezone	Temporal.ZonedDateTime
Momento absoluto em UTC	Temporal.Instant
Período de tempo	Temporal.Duration

Resumo direto

Temporal é o novo namespace global do JavaScript para lidar com data e hora de forma mais correta que Date.

Ele melhora principalmente:

imutabilidade
clareza
timezone
datas sem hora
horas sem data
durações
comparações
aritmética de datas

Em código moderno, a tendência é usar:

Temporal.PlainDate
Temporal.PlainTime
Temporal.PlainDateTime
Temporal.ZonedDateTime
Temporal.Instant
Temporal.Duration

em vez de concentrar tudo em Date.

---

---