Saltar al contenido

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.

5 min de lectura
Editor de código mostrando el uso de la API Temporal de JavaScript para cálculos de fecha y hora

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.

jsjavascript
// ❌ 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.

TipoRepresentaCaso de uso de ejemplo
Temporal.PlainDateFecha de calendario, sin horaCumpleaños, fecha de vencimiento de una factura
Temporal.PlainTimeHora de reloj, sin fechaHora de apertura de una tienda
Temporal.ZonedDateTimeInstante + zona horariaReunión programada en una ciudad específica
Temporal.InstantPunto exacto en la línea de tiempo UTCTimestamp de un log de servidor
jsjavascript
// ✅ 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.

i

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.

jsjavascript
// ❌ 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 clamped

Temporal.Duration también admite aritmética balanceada entre dos puntos:

jsjavascript
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()); // P2M14DT8H30M

Esa 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.

tstypescript
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 weekend

Fí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.

tstypescript
// 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

  1. Date mezcla 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.
  2. Temporal te da tipos distintos (PlainDate, PlainTime, ZonedDateTime, Instant) de modo que la firma de tipo documenta lo que el valor realmente representa.
  3. Todo objeto de Temporal es inmutable — add() y with() devuelven nuevas instancias, lo que elimina los bugs por referencias compartidas.
  4. Temporal.Duration entiende la semántica de calendario ("1 mes" no es un número fijo de milisegundos), algo que la aritmética de Date no puede expresar.
  5. 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.
  6. 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.

Wilfredo Rujel

Wilfredo Rujel

Ingeniero de Software Full Stack

Compartir esta publicaciónX