Trabalhando com datas e horas em JavaScript: guia completo para Node.js

Trabalhando com Datas e Horários em JavaScript (Node.js): do Básico às Técnicas Avançadas

Trabalhar com datas e horários é uma das tarefas mais comuns no desenvolvimento web. Seja para registro de eventos, processamento de dados do usuário, agendamento de tarefas ou exibição de timestamps — não há como evitar o gerenciamento de datas em JavaScript. Neste artigo, abordaremos todos os aspectos essenciais do trabalho com datas no ambiente Node.js: desde a criação e formatação até manipulações complexas com fusos horários e o uso de bibliotecas populares.

Fundamentos: o objeto Date em JavaScript

O objeto nativo Date é a base para trabalhar com datas. Ele armazena o número de milissegundos desde 1º de janeiro de 1970 (época Unix).

Criando uma data

Existem várias maneiras de criar uma instância de Date:

// Data e hora atuaisconst now = new Date();console.log(now); // 2025-03-15T10:30:00.000Z

// A partir de milissegundos (Unix timestamp)const fromTimestamp = new Date(1742025000000);console.log(fromTimestamp); // 2025-03-15T10:30:00.000Z

// A partir de uma string (ISO 8601)const fromString = new Date('2025-03-15T10:30:00');console.log(fromString);

// A partir de componentes (ano, mês, dia, hora, minuto, segundo, milissegundo)const fromComponents = new Date(2025, 2, 15, 10, 30, 0, 0); // Meses: 0-11console.log(fromComponents); // March 15, 2025 10:30:00

Importante: os meses em JavaScript são numerados de 0 (janeiro é 0, dezembro é 11).

Obtendo componentes da data

Métodos para extrair partes individuais da data:

const date = new Date('2025-03-15T10:30:45.123Z');

console.log(date.getFullYear());    // 2025console.log(date.getMonth());       // 2 (março)console.log(date.getDate());        // 15console.log(date.getDay());         // 6 (sábado, 0 - domingo)console.log(date.getHours());       // 10console.log(date.getMinutes());     // 30console.log(date.getSeconds());     // 45console.log(date.getMilliseconds());// 123console.log(date.getTime());        // milissegundos desde a época

Formatação de datas em Node.js

O Date padrão oferece capacidades limitadas de formatação. Para exibição legível, use toLocaleDateString() e toLocaleString().

const date = new Date('2025-03-15T10:30:00');

// Formatação localizadaconsole.log(date.toLocaleDateString('pt-BR')); // 15/03/2025console.log(date.toLocaleTimeString('pt-BR')); // 10:30:00console.log(date.toLocaleString('pt-BR'));     // 15/03/2025, 10:30:00

// Com opçõesconst options = {  year: 'numeric',  month: 'long',  day: 'numeric',  weekday: 'long',  hour: '2-digit',  minute: '2-digit'};console.log(date.toLocaleString('pt-BR', options)); // sábado, 15 de março de 2025, 10:30

Formatação personalizada

Para controle total, escreva uma função simples:

function formatDate(date, format = 'YYYY-MM-DD HH:mm:ss') {  const map = {    YYYY: date.getFullYear(),    MM: String(date.getMonth() + 1).padStart(2, '0'),    DD: String(date.getDate()).padStart(2, '0'),    HH: String(date.getHours()).padStart(2, '0'),    mm: String(date.getMinutes()).padStart(2, '0'),    ss: String(date.getSeconds()).padStart(2, '0'),  };  return format.replace(/YYYY|MM|DD|HH|mm|ss/g, match => map[match]);}

console.log(formatDate(new Date(), 'DD.MM.YYYY')); // 15.03.2025console.log(formatDate(new Date(), 'HH:mm:ss'));   // 10:30:00

Manipulação de datas: adição, subtração, comparação

As datas podem ser alteradas diretamente através dos métodos set* ou trabalhando com milissegundos.

Adicionando e subtraindo tempo

const date = new Date('2025-03-15T10:30:00');

// Adicionar 5 diasdate.setDate(date.getDate() + 5);console.log(date); // 2025-03-20T10:30:00

// Adicionar
```