Trabajo con fechas y horas en TypeScript: guía completa

Trabajo con fechas y horas en TypeScript: desde lo básico hasta técnicas avanzadas

Trabajar con fechas y horas es una de las tareas más comunes en el desarrollo web. TypeScript, como superconjunto de JavaScript, hereda el objeto incorporado Date, pero añade tipado estricto. En este artículo analizaremos cómo trabajar eficientemente con fechas en TypeScript: desde la creación y el formateo hasta manipulaciones complejas con zonas horarias. Aprenderás a evitar errores típicos y a hacer tu código más fiable y legible.

Fundamentos: creación y operaciones básicas con fechas

El objeto Date en TypeScript es el mismo objeto de JavaScript, pero con soporte mejorado de tipos. Veamos las principales formas de crear fechas:

// Fecha y hora actualconst now: Date = new Date();

// Desde una cadena (ISO 8601)const specificDate: Date = new Date('2024-12-25T10:30:00Z');

// Desde componentes (año, mes (0-11), día, horas, minutos, segundos)const customDate: Date = new Date(2024, 11, 25, 10, 30, 0); // 25 de diciembre de 2024

// Desde milisegundos (Unix timestamp)const fromTimestamp: Date = new Date(1703493000000);

Es importante recordar que los meses en JavaScript/TypeScript se numeran desde 0 (enero es 0, diciembre es 11). Esta es una causa frecuente de errores para los principiantes. Para evitar confusiones, se recomienda usar formatos de cadena o bibliotecas.

Métodos básicos para obtener componentes de una fecha:

• getFullYear() — devuelve el año (4 dígitos)
• getMonth() — mes (0-11)
• getDate() — día del mes (1-31)
• getDay() — día de la semana (0 — domingo, 6 — sábado)
• getHours(), getMinutes(), getSeconds() — hora
• getTime() — cantidad de milisegundos desde el 1 de enero de 1970

Ejemplo de uso con tipado:

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"

Formateo y visualización de fechas

Los métodos incorporados de formateo de fechas en TypeScript son limitados. Para tareas simples se puede usar toLocaleDateString() y toLocaleTimeString():

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

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

// Formato completoconsole.log(date.toLocaleString('es-ES', {    year: 'numeric',    month: 'long',    day: 'numeric',    weekday: 'long'})); // "miércoles, 25 de diciembre de 2024"

Sin embargo, para formateo complejo o un control estricto sobre la salida, es mejor usar bibliotecas especializadas. La más popular es date-fns — ligera, modular y completamente compatible con TypeScript.

Instalación:

npm install date-fns

Ejemplo de uso:

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

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

// Formateoconsole.log(format(date, 'dd.MM.yyyy')); // "25.12.2024"console.log(format(date, 'PPP', { locale: es })); // "25 de diciembre de 2024"

// Suma de díasconst futureDate: Date = addDays(date, 10);console.log(format(futureDate, 'dd.MM.yyyy')); // "04.01.2025"

Otras funciones útiles de date-fns: differenceInDays, isBefore, isAfter, startOfMonth, endOfWeek y muchas más. La biblioteca permite escribir código limpio y funcional sin mutar la fuente original.