API de fecha y hora: la sintaxis más peculiar de JavaScript

Al finalizar este tema

Conocerás las principales dificultades del objeto Date de JavaScript y comprenderás por qué es necesaria la API temporal.

Enero es 0

Creemos una fecha en JavaScript:

const date = new Date(2026, 6, 7);
console.log(date);
// Tue Jul 07 2026 ...

Para crear el 7 de julio, debes ingresar 6 en el campo del mes. Esto se debe a que en JavaScript, los meses se numeran a partir de 0: enero = 0, febrero = 1, ..., diciembre = 11.

Este problema surgió cuando JavaScript copió directamente la clase Date de Java en 1995. Aunque Java lo corrigió posteriormente, JavaScript no ha podido solucionarlo en 27 años debido a problemas de compatibilidad.

Otras peculiaridades

No es solo que los meses comiencen en 0:

new Date("2026-07-07");
// UTC → si se ejecuta en Corea, 07 de julio 09:00 (KST)

new Date("07/07/2026");
// según la zona horaria local → 07 de julio 00:00 (KST)

Aunque sea la misma fecha, la interpretación de la zona horaria varía según el formato de la cadena. Si se usa un guion (-), se interpreta como UTC; si se usa una barra (/), se interpreta como la hora local. Nadie pretendía que fuera así.

La comparación de fechas tampoco es intuitiva:

const a = new Date("2026-07-07");
const b = new Date("2026-07-07");
console.log(a === b);  // false
console.log(a == b);   // false

Date es un objeto, por lo que se compara por referencia. Para realizar la comparación, debes obtener el valor en milisegundos mediante a.getTime() === b.getTime().

Además, los objetos Date no son inmutables:

const date = new Date("2026-07-07");
date.setMonth(11);
// date cambia a diciembre — el original se modifica

Si pasas un objeto Date a una función y esa función llama a setMonth, tu fecha original se modifica.

Por eso se utilizan bibliotecas

Hay tantas desventajas con Date que, en la práctica, casi siempre se recurre a bibliotecas externas.

moment.js — Fue durante mucho tiempo el estándar, pero tiene un tamaño de paquete grande (72KB) y utiliza objetos mutables, por lo que repite los mismos problemas. En 2020, se declaró oficialmente que "ya no debe usarse en nuevos proyectos".

day.js — Surgió como alternativa a moment.js. Ofrece la misma API, pero con solo 2KB. Utiliza objetos inmutables, por lo que el objeto original no se modifica. Actualmente, es la biblioteca de fechas más utilizada.

import dayjs from "dayjs";

dayjs("2026-07-07").add(1, "month").format("YYYY-MM-DD");
// "2026-08-07"

date-fns: Enfoque funcional. Permite importar solo las funciones necesarias, lo que facilita la optimización mediante tree-shaking.

API Temporal: Solución definitiva

Las bibliotecas son soluciones provisionales. JavaScript debería proporcionar una API de fechas y horas adecuada directamente en el lenguaje. Esa es la API Temporal.

const date = Temporal.PlainDate.from("2026-07-07");
date.month;      // 7 (¡no es cero!)
date.dayOfWeek;  // 2 (martes)

const next = date.add({ months: 1 });
// date permanece igual, next solo cambia a 7 de agosto — ¡inmutable!

Temporal se ha rediseñado por completo:

Los meses comienzan en 1. Enero = 1, diciembre = 12. Esto se alinea con la lógica humana.

Es inmutable. Métodos como .add() y .subtract() devuelven un nuevo objeto. El objeto original nunca se modifica.

Maneja explícitamente las zonas horarias. Se diferencia entre PlainDate (solo fecha), PlainTime (solo hora) y ZonedDateTime (con zona horaria). Esto previene de forma estructural los errores causados por las zonas horarias.

const meeting = Temporal.ZonedDateTime.from({
  timeZone: "Asia/Seoul",
  year: 2026,
  month: 7,
  day: 7,
  hour: 14,
  minute: 0,
});

meeting.withTimeZone("America/New_York").toString();
// conversión automática a hora de Nueva York

¿Se puede usar ahora?

La API Temporal es una propuesta de TC39 en la etapa 3. Aún tomará tiempo hasta que se implemente por completo en los navegadores. Si se utiliza un polyfill (@js-temporal/polyfill), se puede usar ahora, pero day.js sigue siendo la opción más realista para producción.

Sin embargo, una vez que Temporal se adopte oficialmente, será posible manejar fechas y horas de forma segura solo con JavaScript, sin necesidad de bibliotecas externas.

Aspectos clave

El objeto Date de JavaScript tiene el problema de que los meses comienzan en 0, es mutable y tiene una interpretación inconsistente de las zonas horarias. En la práctica, se utilizan bibliotecas como day.js para evitar estos problemas. La API Temporal es un estándar de nueva generación que busca resolver este problema a nivel del lenguaje.