Trabalhando com datas e horas em TypeScript: guia completo

Trabalhando com Datas e Horários em TypeScript: do Básico às Técnicas Avançadas

Trabalhar com datas e horários é uma das tarefas mais comuns no desenvolvimento web. TypeScript, sendo uma extensão do JavaScript, herda o objeto nativo Date, mas adiciona a ele uma tipagem estrita. Neste artigo, vamos explorar como trabalhar eficientemente com datas em TypeScript: desde a criação e formatação até manipulações complexas com fusos horários. Você aprenderá como evitar erros típicos e tornar o código mais confiável e legível.

Fundamentos: criação e operações básicas com datas

O objeto Date em TypeScript é o mesmo objeto JavaScript, mas com suporte aprimorado a tipos. Vamos considerar as principais formas de criar datas:

// Data e hora atuaisconst now: Date = new Date();

// A partir de uma string (ISO 8601)const specificDate: Date = new Date('2024-12-25T10:30:00Z');

// A partir de componentes (ano, mês (0-11), dia, horas, minutos, segundos)const customDate: Date = new Date(2024, 11, 25, 10, 30, 0); // 25 de dezembro de 2024

// A partir de milissegundos (Unix timestamp)const fromTimestamp: Date = new Date(1703493000000);

É importante lembrar que os meses em JavaScript/TypeScript são numerados a partir de 0 (janeiro é 0, dezembro é 11). Esta é uma causa frequente de erros para iniciantes. Para evitar confusão, recomenda-se usar formatos de string ou bibliotecas.

Métodos básicos para obter componentes da data:

• getFullYear() — retorna o ano (4 dígitos)
• getMonth() — mês (0-11)
• getDate() — dia do mês (1-31)
• getDay() — dia da semana (0 — domingo, 6 — sábado)
• getHours(), getMinutes(), getSeconds() — horário
• getTime() — quantidade de milissegundos desde 1º de janeiro de 1970

Exemplo de uso com tipagem:

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

const today: Date = new Date();console.log(formatDate(today)); // "2024-12-25"

Formatação e exibição de datas

Os métodos nativos de formatação de datas em TypeScript são limitados. Para tarefas simples, você pode usar toLocaleDateString() e toLocaleTimeString():

const date: Date = new Date('2024-12-25T10:30:00');

// Formato localizadoconsole.log(date.toLocaleDateString('pt-BR')); // "25/12/2024"console.log(date.toLocaleTimeString('pt-BR')); // "10:30:00"

// Formato completoconsole.log(date.toLocaleString('pt-BR', {    year: 'numeric',    month: 'long',    day: 'numeric',    weekday: 'long'})); // "quarta-feira, 25 de dezembro de 2024"

No entanto, para formatação complexa ou controle rigoroso sobre a saída, é melhor usar bibliotecas especializadas. A mais popular é date-fns — leve, modular e totalmente compatível com TypeScript.

Instalação:

npm install date-fns

Exemplo de uso:

import { format, addDays, parseISO } from 'date-fns';import { ptBR } from 'date-fns/locale';

const date: Date = parseISO('2024-12-25T10:30:00');

// Formataçãoconsole.log(format(date, 'dd.MM.yyyy')); // "25.12.2024"console.log(format(date, 'PPP', { locale: ptBR })); // "25 de dezembro de 2024"

// Adição de diasconst futureDate: Date = addDays(date, 10);console.log(format(futureDate, 'dd.MM.yyyy')); // "04.01.2025"

Outras funções úteis do date-fns: differenceInDays, isBefore, isAfter, startOfMonth, endOfWeek e muitas outras. A biblioteca permite escrever código funcional e limpo sem mutação da fonte original.