La API Temporal de JavaScript: fechas hechas bien
Por qué la API Temporal corrige décadas de errores de fechas en JavaScript y cómo migrar de Date antes de que rompa tu app.

Date lleva roto desde 1995, y todos hemos aceptado tácitamente trabajar alrededor de eso. Instancias mutables, meses indexados desde cero, un manejo ambiguo de zonas horarias y un parser que acepta entradas basura sin quejarse — todo desarrollador de JavaScript tiene una historia de terror sobre un bug de fechas que solo apareció en producción, normalmente cerca de un límite de zona horaria o una transición de horario de verano (DST). La Temporal API soluciona esto a nivel de lenguaje, y está lo bastante cerca de publicarse como para que la entiendas ahora, no después de que llegue a todos los runtimes.
Por qué Date sigue rompiendo cosas
El problema de fondo no es que Date tenga bugs — es que Date mezcla tres conceptos distintos en un solo objeto mutable: un punto en el tiempo, una fecha de calendario y un instante consciente de zona horaria. Cada operación que haces sobre él tiene que adivinar a cuál de los tres te referías.
// ❌ Date: mutation, implicit UTC/local confusion, no real duration type
const meeting = new Date('2026-03-08T14:00:00');
meeting.setDate(meeting.getDate() + 1); // mutates in place
const duration = new Date(meeting) - new Date(); // subtraction gives ms, not a duration
// Was that +1 day across a DST boundary? Which time zone did the
// constructor assume? setDate() silently rolls over invalid days.
// None of this is visible by reading the code.Date tampoco tiene concepto de una fecha puramente de calendario (un cumpleaños no tiene zona horaria) ni de una hora civil (una reunión recurrente a las "9am hora local" significa algo distinto según dónde estés). Cada solución alternativa — librerías como Moment.js, date-fns o Luxon — existe precisamente porque la primitiva de la plataforma es inadecuada.
Los tipos centrales de Temporal
Temporal divide el único objeto Date en tipos distintos y diseñados para un propósito específico. Este es el mayor cambio mental: eliges el tipo que coincide con lo que realmente estás modelando, en lugar de forzarlo todo a través de un objeto ambiguo.
| Tipo | Representa | Caso de uso de ejemplo |
|---|---|---|
Temporal.PlainDate | Fecha de calendario, sin hora | Cumpleaños, fecha de vencimiento de una factura |
Temporal.PlainTime | Hora de reloj, sin fecha | Hora de apertura de una tienda |
Temporal.ZonedDateTime | Instante + zona horaria | Reunión programada en una ciudad específica |
Temporal.Instant | Punto exacto en la línea de tiempo UTC | Timestamp de un log de servidor |
// ✅ Temporal: immutable, explicit, type matches intent
const meeting = Temporal.PlainDate.from('2026-03-08');
const tomorrow = meeting.add({ days: 1 }); // returns a new instance
const zoned = Temporal.ZonedDateTime.from(
'2026-03-08T14:00:00-05:00[America/New_York]'
);
const inTokyo = zoned.withTimeZone('Asia/Tokyo');
console.log(inTokyo.toString());
// 2026-03-09T04:00:00+09:00[Asia/Tokyo]Todo objeto de Temporal es inmutable. add(), subtract() y with() devuelven siempre nuevas instancias, lo que elimina toda una categoría de bugs de "acción a distancia" causados por referencias de fecha mutables compartidas.
Temporal está definido por la propuesta TC39 en Stage 3, el mismo organismo de estandarización responsable de la especificación ECMAScript. Está implementado de forma nativa en Firefox y llega progresivamente al resto de runtimes, con polyfills cubriendo el hueco mientras tanto.
Las duraciones son un tipo de primera clase
Uno de los bugs de fechas más comunes es tratar una duración como un entero de milisegundos, perdiendo el significado semántico de "1 mes" frente a "30 días" — no son lo mismo, y la aritmética de Date no tiene forma de expresar esa diferencia.
// ❌ Millisecond math breaks across month/DST boundaries
const ONE_MONTH_MS = 30 * 24 * 60 * 60 * 1000;
const renewalDate = new Date(subscriptionStart.getTime() + ONE_MONTH_MS);
// Off by a day or more depending on the actual month length.
// ✅ Temporal.Duration carries calendar semantics
const subscriptionStart = Temporal.PlainDate.from('2026-01-31');
const renewalDate = subscriptionStart.add({ months: 1 });
console.log(renewalDate.toString()); // '2026-02-28' — correctly clampedTemporal.Duration también admite aritmética balanceada entre dos puntos:
const start = Temporal.PlainDateTime.from('2026-01-01T09:00:00');
const end = Temporal.PlainDateTime.from('2026-03-15T17:30:00');
const elapsed = start.until(end, {
largestUnit: 'months',
smallestUnit: 'minutes',
});
console.log(elapsed.toString()); // P2M14DT8H30MEsa cadena de duración ISO 8601 es directamente interoperable con cualquier sistema que lea el estándar ISO 8601, lo que incluye la mayoría de los pipelines de logging, contratos de API y formatos de serialización de bases de datos ya en uso.
Zonas horarias sin librerías externas
El manejo de zonas horarias es donde la mayoría de las librerías de fechas se ganan el sueldo, porque la única primitiva nativa del navegador consciente de zonas horarias solía ser Intl.DateTimeFormat, que formatea pero no te permite hacer aritmética. Temporal cierra esa brecha directamente.
function nextBusinessDayInZone(
date: Temporal.PlainDate,
timeZone: string
): Temporal.ZonedDateTime {
let candidate = date.toZonedDateTime({
timeZone,
plainTime: Temporal.PlainTime.from('09:00:00'),
});
do {
candidate = candidate.add({ days: 1 });
} while (
candidate.dayOfWeek === 6 ||
candidate.dayOfWeek === 7
);
return candidate;
}
const result = nextBusinessDayInZone(
Temporal.PlainDate.from('2026-11-13'), // a Friday
'Europe/Madrid'
);
console.log(result.toString());
// 2026-11-16T09:00:00+01:00[Europe/Madrid] — correctly skips the weekendFíjate en que no hay ambigüedad sobre si 09:00 significa hora local o UTC — ZonedDateTime lleva consigo el identificador de zona IANA, y cada operación respeta automáticamente las transiciones de horario de verano en esa zona específica.
Migrar sin una reescritura de golpe
No necesitas arrancar de raíz cada llamada a Date de una sola vez. El camino práctico es convertir primero en los límites de tu sistema — respuestas de API, lecturas de base de datos, entradas de formularios — y dejar que Temporal gobierne toda la lógica interna.
// Boundary: convert incoming Date/string to Temporal immediately
function parseApiTimestamp(iso: string): Temporal.Instant {
return Temporal.Instant.from(iso);
}
// Internal logic works exclusively with Temporal types
function isWithinSla(
receivedAt: Temporal.Instant,
resolvedAt: Temporal.Instant,
slaHours: number
): boolean {
const elapsed = receivedAt.until(resolvedAt, { largestUnit: 'hours' });
return elapsed.hours <= slaHours;
}
// Boundary: convert back only when an API or legacy library demands Date
function toLegacyDate(instant: Temporal.Instant): Date {
return new Date(instant.epochMilliseconds);
}Esto refleja cómo los equipos migraron de moment a date-fns o luxon hace años: aislar la conversión en los bordes, mantener la lógica de negocio sobre la mejor primitiva, y eliminar el tipo heredado una vez que todos los puntos de llamada se hayan migrado.
Puntos clave
Datemezcla instantes, fechas de calendario y horas civiles en un solo objeto mutable — la mayoría de los bugs de fechas vienen de esa mezcla, no de errores de aritmética.- Temporal te da tipos distintos (
PlainDate,PlainTime,ZonedDateTime,Instant) de modo que la firma de tipo documenta lo que el valor realmente representa. - Todo objeto de Temporal es inmutable —
add()ywith()devuelven nuevas instancias, lo que elimina los bugs por referencias compartidas. Temporal.Durationentiende la semántica de calendario ("1 mes" no es un número fijo de milisegundos), algo que la aritmética deDateno puede expresar.- La aritmética de zonas horarias es nativa — ya no necesitas una librería solo para sumar un día correctamente a través de un límite de horario de verano.
- Migra primero en los límites del sistema (parseo de API, lecturas de base de datos) y deja que Temporal gobierne la lógica interna antes de tocar cada punto de llamada.
Comprueba el soporte antes de comprometer código de producción con esto — consulta las tablas de compatibilidad en la referencia de Temporal en MDN y recurre al polyfill oficial en entornos donde todavía no haya soporte nativo. Pero diseña hoy tu lógica de manejo de fechas según el modelo de Temporal, incluso detrás de un polyfill — es la forma hacia la que converge el lenguaje, y el código escrito contra PlainDate y ZonedDateTime sobrevivirá a cualquier librería de fechas ad hoc a la que recurrirías de otro modo.


