JavaScript Date y zonas horarias: cuando un mes no es una fecha

04-11-2026

Hace unas semanas estaba trabajando en un pet project personal y quería añadir una funcionalidad bastante inocente: poder preparar información para el mes siguiente antes de que empezara.

Nada especialmente raro. Agosto, septiembre, octubre… meses.

El modelo ya soportaba varios periodos, así que pensaba que el trabajo iba a estar principalmente en la UI. Hasta que apareció uno de esos bugs que te hacen mirar el código durante un rato pensando:

Esto no puede estar pasando.

En determinadas zonas horarias, durante las primeras horas del día 1, una parte de la aplicación podía pensar que estábamos en un mes y otra parte en el anterior.

  • El servidor decía agosto.
  • El navegador decía septiembre.

Los dos tenían razón, y ahí estaba precisamente el problema.

Porque había cometido un error bastante sencillo: estaba utilizando Date para representar algo que no era una fecha ni un instante. Era un mes.

Date responde a una pregunta diferente

Cuando hacemos esto:

 

const now = new Date();

parece que tenemos “la fecha actual”, pero conceptualmente no es exactamente eso.

Un Date de JavaScript representa un instante concreto en el tiempo. Internamente tenemos un timestamp, una cantidad de milisegundos desde el epoch.

Después podemos interpretar ese instante desde UTC o desde la zona horaria de la máquina, y aquí empieza la fiesta.

Imagina este instante:

 

const instant = new Date("2026-08-31T22:30:00.000Z");

Si nuestro proceso está ejecutándose en una zona como Europe/Madrid, localmente ya es 1 de septiembre.

Por tanto:

 

instant.getFullYear(); // 2026 instant.getMonth() + 1; // 9 -> septiembre

Mientras que:

 

instant.getUTCFullYear(); // 2026 instant.getUTCMonth() + 1; // 8 -> agosto

Mismo objeto, mismo timestamp, dos meses diferentes.

Y no hay ningún bug en JavaScript, el bug está en nuestra interpretación.

Entonces… ¿en qué mes estamos?

Esta pregunta parece trivial hasta que intentas responderla correctamente.

¿En qué mes estamos?

Depende.

Si estás procesando un evento financiero ocurrido a las 2026-08-31T22:30:00Z, quizá pertenezca a agosto.

Si lo que quieres es enseñar a un usuario de Madrid su presupuesto actual, para esa persona ya es septiembre.

Si estás cerrando un periodo contable definido siempre en UTC, sigue siendo agosto.

El tiempo necesita contexto. Y cuando ese contexto no aparece en nuestros tipos, normalmente acaba escondido en llamadas a getMonth(), getUTCMonth() o new Date() repartidas por el código. Eso era exactamente lo que me había pasado.

Tenía código parecido a esto:

 

function monthKeyOf(date: Date): number { return date.getFullYear() * 12 + date.getMonth(); }

Y en otra zona del sistema:

 

function monthKeyOf(date: Date): number { return date.getUTCFullYear() * 12 + date.getUTCMonth(); }

Las dos funciones parecen razonables, el problema es que representan dos reglas de negocio diferentes con exactamente el mismo tipo.

Un Date tiene demasiada información

Supongamos que nuestro dominio necesita representar:

Septiembre de 2026.

¿Qué información necesitamos?

  • Año: 2026
  • Mes: 9

Eso es todo.

No necesitamos:

  • día;
  • hora;
  • minutos;
  • segundos;
  • milisegundos;
  • offset;
  • zona horaria.

Sin embargo, solemos hacer algo como:

 

const september = new Date(2026, 8, 1);

Para representar un mes acabamos inventándonos:

  • el día 1;
  • la hora 00:00;
  • una zona horaria implícita.

Hemos añadido información ficticia simplemente porque nuestro tipo nos obliga a hacerlo, y esa información que no necesitábamos puede terminar afectando al comportamiento. Es una señal bastante buena de que el modelo no está representando correctamente el concepto.

Es parecido a utilizar un string para representar un email. Sí, funciona, pero "patata" también es un string. Los tipos primitivos pueden contener nuestros conceptos de dominio, pero no necesariamente los representan.

Modelando el concepto real: MonthKey

La solución que terminé aplicando fue bastante sencilla: introducir un concepto explícito para representar un mes.

Por ejemplo:

 

export class MonthKey { private constructor( readonly year: number, readonly month: number, ) {} static of(year: number, month: number): MonthKey { if (!Number.isInteger(year)) { throw new Error("Year must be an integer"); } if (!Number.isInteger(month) || month < 1 || month > 12) { throw new Error("Month must be between 1 and 12"); } return new MonthKey(year, month); } equals(other: MonthKey): boolean { return this.year === other.year && this.month === other.month; } isBefore(other: MonthKey): boolean { if (this.year !== other.year) { return this.year < other.year; } return this.month < other.month; } next(): MonthKey { if (this.month === 12) { return MonthKey.of(this.year + 1, 1); } return MonthKey.of(this.year, this.month + 1); } toString(): string { return `${this.year}-${String(this.month).padStart(2, "0")}`; } }

Ahora septiembre de 2026 es simplemente:

 

const september = MonthKey.of(2026, 9);

Y serializado:

 

2026-09

Sin días falsos, sin medianoches, sin timezone escondida, sin tener que recordar que Date#getMonth() empieza en cero porque, por algún motivo, enero decidió ser 0 :rofl:.

Pero lo más interesante no es haber creado una clase, lo importante es que el dominio ahora tiene una palabra para algo que antes estaba implícito.

Elegir UTC tampoco arregla mágicamente el problema

Cuando aparece un bug de timezone hay una reacción bastante habitual:

Vale, pues usamos UTC para todo.

Y, ojo, en muchísimos sistemas es una decisión estupenda, de hecho, en mi caso decidí normalizar la identidad de los periodos utilizando UTC.

Pero utilizar UTC no elimina la necesidad de pensar, lo importante no es “usar UTC”. Lo importante es definir:

¿Qué significa un mes dentro de mi dominio?

Si trabajas con movimientos bancarios, quizá quieras almacenar el instante original y posteriormente asignarlo al periodo correspondiente, si haces planificación financiera, puede tener sentido que tus meses tengan una identidad independiente de una zona horaria.S estás construyendo un calendario de reservas para restaurantes, probablemente la zona local del establecimiento sea importantísima.

UTC es una herramienta, no es una regla de negocio universal.

Lo peligroso aparece cuando unas partes del sistema usan UTC y otras el reloj local sin que esa decisión sea explícita.

La conversión debería ocurrir en la frontera

Una vez tenemos MonthKey, podemos dejar Date donde realmente tiene sentido: en los bordes del sistema.

Por ejemplo:

 

export function monthKeyFromUtc(date: Date): MonthKey { return MonthKey.of( date.getUTCFullYear(), date.getUTCMonth() + 1, ); }

Nuestro dominio puede trabajar a partir de ahí exclusivamente con:

 

MonthKey

En vez de transportar un Date por diez capas esperando que todo el mundo recuerde cómo debe interpretarlo.

Esto tiene una ventaja enorme.

Antes podías escribir:

 

date.getMonth()

o:

 

date.getUTCMonth()

o incluso:

 

new Date(date).setMonth(...)

Cada llamante podía decidir cómo interpretar el tiempo.

Ahora, si tienes:

 

MonthKey.of(2026, 9)

hay muchas menos decisiones posibles.

Y reducir decisiones accidentales es una de las cosas que más me gustan de un buen modelo de dominio.

new Date() también es una dependencia

Después de arreglar el problema de los meses me di cuenta de que todavía quedaba otra cosa que me olía regular. Había new Date() por todas partes.

Algo parecido a:

 

function canRegisterMovement(month: MonthKey): boolean { const now = new Date(); const currentMonth = monthKeyFromUtc(now); return !currentMonth.isBefore(month); }

A simple vista no parece grave, pero esta función tiene una dependencia que no aparece en su firma:

el reloj del sistema.

Su resultado cambia dependiendo del momento en el que la ejecutemos. Y eso se vuelve especialmente divertido cuando escribes tests cerca del cambio de día, de mes o de año.

La solución fue tratar el tiempo igual que trataría cualquier otra dependencia externa.

 

export interface Clock { now(): Date; }

La implementación real:

 

export class SystemClock implements Clock { now(): Date { return new Date(); } }

Y para los tests:

 

export class FixedClock implements Clock { constructor(private readonly value: Date) {} now(): Date { return this.value; } }

Nuestro código queda entonces así:

 

export class MovementRegistrationPolicy { constructor(private readonly clock: Clock) {} canRegister(month: MonthKey): boolean { const currentMonth = monthKeyFromUtc( this.clock.now(), ); return !currentMonth.isBefore(month); } }

Y el test deja de depender del día en el que alguien ejecute la suite:

 

it("does not allow movements in a future month", () => { const clock = new FixedClock( new Date("2026-08-31T23:30:00.000Z"), ); const policy = new MovementRegistrationPolicy(clock); expect( policy.canRegister(MonthKey.of(2026, 9)), ).toBe(false); });

Esto puede parecer overengineering para una llamada a new Date().

Hasta que tienes una suite que pasa durante 29 días al mes y falla misteriosamente el día 1 :roll_eyes: .

Los tests de timezone son sorprendentemente útiles

Otra cosa que me llevé de esta historia fue empezar a ejecutar determinadas pruebas con zonas horarias diferentes.

Por ejemplo, en Node puedes ejecutar una suite cambiando el timezone del proceso:

 

TZ=UTC pnpm test

 

TZ=America/New_York pnpm test

 

TZ=Asia/Tokyo pnpm test

Si tu lógica debería ser independiente de la zona horaria y los resultados cambian, probablemente hayas encontrado algo interesante.

Especialmente útiles son los instantes cercanos a los límites:

 

new Date("2026-08-31T23:59:59.999Z");

 

new Date("2026-09-01T00:00:00.000Z");

O finales de año:

 

new Date("2026-12-31T23:59:59.999Z");

Los tests felices de:

 

new Date("2026-05-15T12:00:00Z");

son muy majos.

Pero a las doce del mediodía de un día cualquiera casi todos los bugs temporales están durmiendo la siesta. Los problemas viven en los bordes.

Otro pequeño regalo de Date

Hay además comportamientos de Date que hacen que estos problemas sean todavía menos evidentes.

Estas dos construcciones parecen conceptualmente muy parecidas:

 

new Date("2026-09-01");

 

new Date(2026, 8, 1);

Pero no tienen exactamente la misma semántica.

La cadena ISO que contiene únicamente la fecha se interpreta utilizando UTC, mientras que el constructor que recibe año, mes y día utiliza la zona horaria local.

Es decir, incluso antes de empezar a utilizar nuestro Date, la forma en la que lo construimos puede introducir una decisión temporal distinta.

No creo que la conclusión sea “JavaScript Date es horrible y nunca debes usarlo”.

Date hace perfectamente el trabajo para el que fue diseñado: representar instantes y convertirlos a diferentes componentes temporales.

El problema aparece cuando le pedimos que represente cosas que no son instantes.

¿Y Temporal?

Aquí es donde resulta curioso mirar hacia Temporal.

Una de las cosas que más me gustan de su diseño es precisamente que no intenta meter todos los conceptos relacionados con el tiempo dentro del mismo objeto. Tenemos conceptos distintos para cosas distintas.

Un instante:

 

Temporal.Instant

Una fecha sin zona horaria:

 

Temporal.PlainDate

Una fecha y hora sin timezone:

 

Temporal.PlainDateTime

Y, exactamente para el problema de este artículo:

 

Temporal.PlainYearMonth

Por ejemplo:

 

const month = Temporal.PlainYearMonth.from("2026-09"); month.toString(); // "2026-09" month.add({ months: 1 }).toString(); // "2026-10"

Es prácticamente la representación que terminamos construyendo con nuestro MonthKey. Y eso me parece una señal interesante.

El concepto existía, simplemente Date no tenía una forma específica de expresarlo.

A día de hoy el soporte nativo de Temporal todavía no es universal, por lo que dependiendo de dónde ejecutes tu aplicación tendrás que comprobar compatibilidad o utilizar alternativas.

Pero incluso aunque no lo uses, su diseño deja una lección bastante buena:

instante, fecha, hora, mes y fecha con timezone no son la misma cosa.

¿Por qué iban a compartir siempre el mismo tipo?

Los Value Objects no son solo para Email y Money

Cuando hablamos de Value Objects solemos utilizar los ejemplos de siempre:

 

Email Money PhoneNumber Address

Y tienen sentido.

Pero muchas veces los conceptos más interesantes están escondidos en primitivas que usamos todos los días sin cuestionarlas.

Por ejemplo:

 

string // ¿un email? ¿un id? ¿una moneda? number // ¿euros? ¿porcentaje? ¿mes? Date // ¿instante? ¿día? ¿mes? ¿deadline?

Crear un Value Object no consiste únicamente en encapsular validaciones, también consiste en reducir interpretaciones posibles.

Si recibes esto:

 

Date

necesitas contexto para saber qué significa.

Si recibes esto:

 

MonthKey

la conversación cambia, el código ya te está contando parte de la historia.

Una pequeña regla que intento seguir ahora

Después de pelearme con todo esto, intento hacerme una pregunta cada vez que aparece un Date en el dominio:

¿De verdad necesito representar un instante?

Si la respuesta es sí, perfecto.

Date puede ser exactamente lo que necesito.

Pero si la respuesta es:

Necesito saber el mes.

Entonces modelo un mes.

Si necesito:

El día en el que vence algo.

Modelo una fecha.

Si necesito:

El momento exacto en el que ocurrió una operación.

Modelo un instante.

Y si la decisión depende de dónde está el usuario:

La zona horaria tiene que aparecer en algún sitio.

Parece una diferencia semántica pequeña.

Pero precisamente esas pequeñas diferencias son las que evitan que un sistema descubra el 1 de septiembre que todavía cree que vive en agosto.

Lo que me llevo de este bug

El bug original terminó siendo relativamente fácil de arreglar, lo interesante fue todo lo que apareció al tirar del hilo.

Me quedo principalmente con estas ideas:

  • Un instante no es una fecha y una fecha no es un mes. Que todos estén relacionados con el tiempo no significa que deban compartir representación.
  • UTC es una decisión, no una solución mágica. Lo importante es definir cuál es la semántica temporal del dominio y aplicarla de forma consistente.
  • new Date() es una dependencia. Si una regla de negocio depende del momento actual, merece la pena que el reloj sea explícito, especialmente para poder testear los límites.
  • Los bugs temporales viven en los bordes. Cambios de día, de mes, de año y de timezone son escenarios que merece la pena probar expresamente.
  • Los tipos pueden eliminar decisiones. MonthKey no hizo el código más sofisticado. Hizo que hubiera menos formas de usarlo mal.

Desde entonces miro los Date con un poquito más de desconfianza :sweat_smile:. No porque sean malos, sino porque ahora intento preguntarme antes qué concepto estoy modelando realmente.

A veces será un instante.

A veces será una fecha.

Y, de vez en cuando, será simplemente septiembre.

Y septiembre no necesita saber qué hora es.