Trabalhando com datas e horas em JavaScript: do A ao Z para Node.js

Introdução: Por que trabalhar com datas em JavaScript é um desafio para o desenvolvedor

Trabalhar com datas e horas é uma das tarefas mais comuns e, ao mesmo tempo, traiçoeiras no desenvolvimento web. Parece que poderia ser mais simples do que obter a data atual ou calcular a diferença entre dois eventos? No entanto, na prática, os desenvolvedores em JavaScript (Node.js) enfrentam várias armadilhas: fusos horários, formato ISO, comportamento não óbvio do método getMonth() e bibliotecas desatualizadas. Neste artigo, abordaremos o trabalho com datas desde os princípios básicos até técnicas avançadas, usando apenas o objeto padrão Date e a biblioteca moderna date-fns.

1. Fundamentos do objeto Date no Node.js

O objeto embutido Date é a base para trabalhar com tempo. Ele armazena o número de milissegundos desde 1º de janeiro de 1970 (época Unix). Vamos ver as operações principais.

Criação e obtenção da hora atual

A maneira mais simples de criar um objeto de data é chamar new Date() sem argumentos. Isso retorna a data e hora atuais no servidor.

// Data e hora atuais (no fuso horário do servidor)const now = new Date();console.log(now); // Exemplo: 2024-05-20T14:30:00.000Z

// Criação a partir de uma string ISOconst specificDate = new Date('2024-12-25T10:00:00');console.log(specificDate); // 2024-12-25T10:00:00.000Z

// Criação a partir de componentes (ano, mês, dia, horas, minutos, segundos)const birthday = new Date(1990, 5, 15); // Atenção: mês 5 = Junho!console.log(birthday); // 1990-06-15T00:00:00.000Z

Observação importante: Os meses em JavaScript são numerados a partir de 0 (Janeiro é 0, Dezembro é 11). Esta é uma causa frequente de bugs.

Métodos para obter componentes da data

Para extrair partes individuais da data, usamos os getters. Lembre-se de que eles retornam valores no fuso horário local do servidor.

const date = new Date('2024-03-15T12:30:45');

console.log(date.getFullYear());   // 2024console.log(date.getMonth());      // 2 (Março, pois a contagem começa em 0)console.log(date.getDate());       // 15console.log(date.getDay());        // 5 (Sexta-feira, 0 - Domingo)console.log(date.getHours());      // 12console.log(date.getMinutes());    // 30console.log(date.getSeconds());    // 45

Para trabalhar em UTC (Tempo Universal Coordenado), use os métodos com o prefixo getUTC..., por exemplo getUTCHours().

2. Formatação e exibição de datas

No Node.js, não há formatação embutida conveniente de datas em um formato de string arbitrário (por exemplo, "15 de março de 2024"). Existem duas maneiras: montar a string manualmente ou usar bibliotecas.

Formatação manual (sem bibliotecas externas)

Se você precisar exibir uma data em um formato simples, pode escrever uma pequena função.

function formatDate(date) {  const day = String(date.getDate()).padStart(2, '0');  const month = String(date.getMonth() + 1).padStart(2, '0');  const year = date.getFullYear();  return `${day}.${month}.${year}`;}

const today = new Date();console.log(formatDate(today)); // Exemplo: "20.05.2024"

Solução moderna: biblioteca date-fns

A biblioteca date-fns é uma alternativa moderna, modular e leve ao desatualizado moment.js. Ela é ideal para Node.js.

// Instalação: npm install date-fns

const { format, addDays, differenceInDays } = require('date-fns');const { ptBR } = require('date-fns/locale'); // Localização

const date = new Date();

// Formatação com localizaçãoconsole.log(format(date, "dd 'de' MMMM 'de' yyyy", { locale: ptBR }));// Exemplo: "20 de maio de 2024"

// Adicionar diasconst nextWeek = addDays(date, 7);console.log(format(nextWeek, 'yyyy-MM-dd')); // "2024-05-27"

// Diferença em diasconst start = new Date(2024, 0, 1);const end = new Date(2024, 11, 31);co