Datas em JavaScript: new Date, formatação e comparação

O objeto Date é um instante no tempo

No JavaScript, um Date representa um único instante no tempo — por baixo dos panos, nada mais é do que um número de milissegundos contados desde 1º de janeiro de 1970 UTC (a famosa "época Unix"). Todo o resto — ano, mês, dia, fuso horário, formatação — é só uma forma de enxergar esse número.

now.getTime() devolve a contagem bruta em milissegundos. Tudo que um Date faz — comparar, somar dias, formatar — no fundo é manipular esse número e depois reinterpretá-lo.

Guarde esse modelo mental. Um Date não é "14 de março em Paris". É um instante universal que pode ser exibido como 14 de março em Paris, ou como 13 de março em Los Angeles, dependendo do fuso horário pelo qual você olha.

Como criar datas em JavaScript

Existem quatro formas principais de construir um Date:

Dois detalhes importantes para prestar atenção:

• O construtor por partes usa meses indexados em zero. O 2 representa março, e janeiro é 0. Essa é uma fonte constante de bugs de off-by-one — no resto da API os meses também começam em 0, então pelo menos é consistente consigo mesmo.
• new Date("2026-03-14") (sem horário) é interpretado como meia-noite em UTC. Já new Date("2026-03-14T09:30") (sem o Z) é interpretado como horário local. Essa assimetria é uma pegadinha clássica.

Para pegar o "agora" como número, prefira Date.now() — ele evita a alocação do objeto:

Date.now() é a ferramenta certa para medir tempo decorrido, timeouts e qualquer coisa em que você não precisa fazer conta com calendário.

Extraindo partes de uma data

Depois que você tem um Date, dá pra pegar cada componente usando os getters. Cada um tem duas versões: uma no horário local e outra em UTC.

As versões locais dependem da máquina em que o código está rodando. Se você armazena ou compara datas entre usuários e servidores, escolha UTC explicitamente — senão vai caçar bugs fantasmas. Regra geral: use os getters em UTC para qualquer coisa que vai para o banco de dados ou para um log; use os getters locais só quando o valor for exibido para uma pessoa.

Não use getYear(). É um método legado que retorna ano - 1900 e existe apenas por compatibilidade. Vá sempre de getFullYear().

Formatando datas para humanos

Evite date.toString() para qualquer coisa que importe — a saída depende do locale e da engine. Existem dois formatadores que vale a pena conhecer.

Para uma string padronizada, legível por máquina, use toISOString():

Esse é o formato ideal para logs, armazenar em JSON ou trafegar pela rede. É sempre UTC e não deixa margem para ambiguidade.

Já para exibir ao usuário, use Intl.DateTimeFormat ou os métodos toLocale*, que são atalhos para ele:

Intl.DateTimeFormat dá conta de locales, fusos horários e qualquer combinação de campos que você precisar. Prefira ele antes de sair montando ${year}-${month}-${day} na mão — é justamente nesse tipo de string manual que moram aqueles bugs chatos de mês errado por um.

Comparando datas em JavaScript

Dois objetos Date que representam o mesmo instante não são iguais com === — o === verifica identidade de objeto, não o valor. O jeito certo é comparar os timestamps:

Na hora de ordenar, os operadores de comparação funcionam direto, já que eles fazem a coerção para número:

A subtração devolve a diferença em milissegundos. Para obter dias, basta dividir por 1000 * 60 * 60 * 24. Deixe essa constante escrita por extenso na primeira vez — com o tempo, você vai bater o olho em 86_400_000 e já saber do que se trata.

Aritmética de datas em JavaScript

Não existe um método addDays. O jeito idiomático é usar setDate, setMonth e afins — eles aceitam valores fora do intervalo e fazem o ajuste certinho, virando mês ou ano quando preciso:

Dois pontos que merecem destaque:

• new Date(date) cria uma cópia da data. Como setDate é mutável, sempre copie antes — senão você acaba alterando o valor de quem chamou a função.
• Chamar setDate(35) num mês de 31 dias avança automaticamente para o mês seguinte. O mesmo vale para setMonth(14), que pula para o próximo ano. Isso deixa a aritmética com datas bem menos dolorida do que parece.

Para qualquer coisa mais complexa — dias úteis, eventos recorrentes, durações que levam meses em conta — use uma biblioteca (date-fns, Luxon ou a futura API Temporal). Implementar cálculos de calendário na mão, além de "somar alguns dias", é cair num poço sem fundo.

Fuso horário em JavaScript: hora de encarar a realidade

Fuso horário é, disparado, a maior fonte de bugs envolvendo datas. As regras que valem a pena gravar:

• Um Date guarda um instante em UTC. O fuso só entra em cena quando você lê partes da data ou formata ela.
• O fuso usado por getHours(), getDate() e companhia é o fuso local da máquina que está rodando o código. E servidor e navegador costumam discordar.
• new Date("2026-03-14") (só a data) é interpretado como UTC. Já new Date("2026-03-14T00:00") (com hora, sem fuso) é interpretado como local. E new Date(2026, 2, 14) (por partes) também é local.

Quando você precisa exibir uma data em um fuso horário específico, passe timeZone para o Intl.DateTimeFormat:

Mesmo instante, duas visualizações. O objeto Date em si não mudou.

Um pequeno exemplo prático

Juntando tudo — uma função que formata há quanto tempo algo aconteceu:

Timestamps na entrada, string legível na saída. Essa é a cara de 90% do código que lida com datas no mundo real: subtrai dois instantes, divide pela unidade, arredonda e formata.

O que fica desta aula

• Um Date é um instante em UTC. O fuso horário só entra em cena quando você lê ou formata esse valor.
• Use Date.now() para timestamps e new Date() quando precisar trabalhar com o calendário.
• Use toISOString() para armazenar e logar, e Intl.DateTimeFormat para exibir ao usuário.
• Compare com getTime() ou com </>. Nunca use ===.
• Meses começam em 0. E cuidado com a armadilha do parsing de strings que só têm a data.
• Para contas sérias com datas, use uma biblioteca.

A seguir: URLs e query strings

Datas aparecem muito em URLs — filtrar por intervalo de datas, mandar um timestamp como parâmetro na query, esse tipo de coisa. Montar e fazer parse de URL na mão dá tanto nó na cabeça quanto formatar data na mão, e a linguagem já traz um objeto URL pronto que resolve isso sem dor. É o nosso próximo tema.