Temporal: Fechas y Tiempos Modernos en JavaScript

Hola, mi nombre es Philip Camento. Trabajo como desarrollador de motores de JavaScript en Igalia. Hoy hablaré sobre la propuesta temporal, que añade un manejo moderno de fechas y horas a JavaScript. Soy parte de un grupo que trabaja en esta propuesta, y mi participación es parte de una colaboración entre Igalia y Bloomberg.

En esta presentación, te daré un recorrido por la API y te mostraré lo que puedes hacer con temporal mediante una caminata a través de una tarea de programación fácil, media y complicada. Entonces, si te preguntas qué es temporal, es una API que ha sido propuesta para convertirse en parte de JavaScript. Estará disponible pronto en los navegadores. Y añadirá una biblioteca incorporada para fechas y horas, como ya tienen muchos otros lenguajes de programación.

Entonces, cuando digo que está incorporada, me refiero a que es parte de tu navegador o de tu motor de JavaScript. Eso es importante porque muchos desarrolladores incluyen una dependencia de Moment o alguna biblioteca similar en su aplicación para lograr lo mismo que podrías con temporal. Pero dependiendo de cuánta información local incluyas, eso podría añadir una carga de entre una docena a 200 kilobytes a tu aplicación. Y con incorporado, evitas eso. Temporal está fuertemente tipificado. Eso significa que para diferentes tipos de datos, como una fecha de calendario con o sin una hora asociada, hay diferentes tipos para representarlos, en lugar de un tipo que se ajuste a todo.

Los objetos Temporal son inmutables, y eso significa que no tienes que preocuparte por el código que no posees modificando tus objetos sin tu conocimiento. Y por último, está diseñado para trabajar junto con las facilidades de internacionalización de JavaScript. Y proporciona cosas que muchas otras bibliotecas no, como calendarios no gregorianos.

Entonces, una pregunta justa para cualquier adición al lenguaje JavaScript es, ¿realmente necesitamos esto? Como, ya tenemos el objeto global de fecha. No es perfecto, pero ha funcionado bien durante todos estos años. Y voy a estar en desacuerdo con lo que acabo de decir. De hecho, tenemos una buena lista de deficiencias de fechas. Aquí hay una lista de problemas con las fechas que se identificaron desde el principio que Temporal apunta a resolver.

Puedes leer sobre estos en la publicación del blog que enlacé por Maggie Johnson-Pint, una de las desarrolladoras de Moment y también una de las arquitectas originales de Temporal. Así que, ella enumera estas cosas en su publicación de blog en orden de disgusto relativo, para usar sus palabras. No entraré en todos estos. Algunos de ellos, como las APIs poco manejables, podrían ser arreglados, pero otros como la mutabilidad no pueden ser arreglados sin romper la web, porque hay tanto código por ahí que ya depende del comportamiento existente.

La fecha original de JavaScript se basó en una clase de fecha de Java, que Java desaprobó en 1997 y reemplazó por algo mejor. Y un cuarto de siglo después, ahora estamos haciendo lo mismo en JavaScript. Así que, mencioné la tipificación fuerte. Para las próximas diapositivas, te daré un recorrido por estos tipos que Temporal introduce. El primer tipo que debes conocer es instant. Representa lo que llamamos un tiempo exacto, un punto instantáneo en la línea de tiempo con resolución de nanosegundos. No hay calendario, así que no hay meses, semanas, años, o días, solo zona horaria.

Sin zona horaria, así que no hay ajustes de horario de verano. Solo un número en constante aumento. A continuación, tenemos una familia de tipos llamados los tipos plain. Estos representan una fecha en tu calendario de pared y una hora en tu reloj de pared, a lo que llamamos tiempo de pared para abreviar. Estos representan tu fecha y hora local independientemente de la zona horaria, y por lo tanto no hay ajustes de horario de verano. Pero a diferencia de instant, no son momentos exactos en el tiempo. Un tiempo de pared como el 18 de noviembre de 2024 a las 2.30 ocurre en varios momentos exactos diferentes alrededor del mundo. Así que, esto es solo puramente los números que ves en tu pared. Entonces, ¿por qué tenemos esta familia de tipos plain o tipos de pared con progresivamente menos información? Esto es para que puedas representar correctamente la información que tienes.

Por ejemplo, con la antigua fecha, si querías representar una fecha sin una hora, podrías usar medianoche en la zona horaria local del usuario. Pero en realidad hay días en ciertas zonas horarias donde se omite la medianoche debido al horario de verano. Eso puede causar errores difíciles de rastrear cuando intentas poner medianoche para uno de esos días. {{^}}Por ejemplo, la medianoche del 4 de noviembre de 2018 no existió en Brasil. Así que, el 4 de noviembre de 2018 es un dato diferente al 4 de noviembre de 2018 a las 12 a.m.

Así que, aquí están los tipos que tenemos que no llevan toda la información. Plain date es un día sin una hora específica del reloj, lo cual es un caso de uso muy común. Plain time es una hora del reloj no en un día específico. Plain year months es un mes sin un día específico. Así que, podrías pensar en usar eso para referirte a un evento que ocurre ocasionalmente, como tengo aquí la reunión de la junta de noviembre de 2024. También corresponde al tipo de entrada HTML month. Y plain month day es una fecha de calendario pero sin un año específico. Así que, podrías pensar en eso como referirse a un cumpleaños o aniversario o algo así. Como digo, mi cumpleaños es el 15 de diciembre.

Completando la familia de tipos hay otro tipo de tiempo exacto llamado zone date time. Al igual que instant, este tipo representa un momento exacto en el tiempo pero también está acoplado a una ubicación con reglas de zona horaria porque incluye una zona horaria. La zona horaria significa que este tipo sí tiene en cuenta los cambios de horario de verano y otros cambios en la zona horaria. Y también tiene un calendario, lo que significa que a diferencia de instant, tiene un año, mes y día. Así que, es un tiempo exacto, pero también puede darte convenientemente un tiempo completo. Decimos que zone date time representa un evento de calendario que ocurrió o ocurrirá en un lugar en la Tierra.

Así que, un ejemplo de los datos completos es decir que la sesión de la conferencia es el lunes, 18 de noviembre de 2024 a las 11 AM hora estándar del este de EE. UU. Luego hay un tipo más que es parte de temporal y no representa una fecha o una hora. Duration, lo usamos en aritmética con los otros tipos y tiene algunos métodos propios para redondear y convertir entre unidades. Así que, aquí están las relaciones entre todos los tipos. Este diagrama está tomado de la documentación de temporal. Puedes ver que hay dos tipos a la izquierda que conocen el tiempo exacto, instant y zone date time. Y hay otros tipos a la derecha que conocen el tiempo completo.

Ahora que te he presentado a los personajes de Temporal, es hora de mostrar cómo realizar una tarea de programación. Personalmente, siempre he aprendido mejor haciendo. Así que, espero que esto te muestre lo que puedes hacer con cAPI. He elegido tres tareas para recorrer, una fácil, una media y una complicada. Primero, la fácil.

La tarea fácil es obtener la hora actual como el timestamp en milisegundos. Esta es la pregunta número uno más votada para el antiguo objeto de fecha de JavaScript en Stack Overflow. Así que, naturalmente, querremos poder hacer lo mismo en Temporal. Primero, consideramos qué tipo tenemos que usar. Un timestamp representa un tiempo exacto sin tener en cuenta las zonas horarias. Y así, pensamos en los tipos que mencioné. El tipo que corresponde a ese tiempo exacto, sin zona horaria, es instant.

Lo siguiente, tal vez es algo un poco meta para considerar, es si realmente queremos un timestamp en milisegundos, o si el objeto instant funcionará igual de bien. Creo que en el futuro, a medida que Temporal se adopte más ampliamente, esperaría que los timestamps numéricos sean principalmente necesarios para la interoperación con sistemas no JavaScript, no tanto para aplicaciones JavaScript donde simplemente usaremos instant. Pero para el propósito de este ejemplo, digamos que realmente necesitamos un timestamp numérico. Así que, sabemos qué tipo necesitamos. A continuación, necesitamos saber cómo llenarlo con la hora actual.

Hacemos esto con las funciones en el namespace now. Cualquiera de estas funciones te dará la fecha o la hora o la zona horaria actual en forma de una instancia de uno de los tipos de Temporal. El ISO en el nombre significa que la fecha está en el calendario estándar ISO, y hablaré más sobre calendarios y lo que eso significa más adelante. Pero como necesitamos la hora actual como una instancia, usaremos la primera de esta lista, temporal.now.instant. A continuación, necesitamos averiguar cómo obtener un número de milisegundos desde la época Unix del instant.

Así que, este es un buen momento para hablar sobre cómo obtienes información de fecha y hora de tus instancias de tipos de Temporal. Todos los tipos tienen propiedades de solo lectura que podemos usar para obtener este tipo de información. Así que, aquí en esta diapositiva hay una lista completa de estas propiedades. No todos los tipos tienen todas las propiedades, solo las que tienen sentido para ese tipo. Así que, por ejemplo, year solo está en tipos que tienen calendarios y tampoco en plain month-day. Offset solo existe en zone date-time, y los epoch nanoseconds y propiedades similares solo están en los tipos de tiempo exacto en zone date-time. Así que, en nuestro caso, necesitamos la propiedad epoch milliseconds porque ese es el número de milisegundos desde la época Unix del 1 de enero de 1970, medianoche.

Entonces, juntamos toda la información en las diapositivas anteriores en esta línea de código aquí. Obtenemos el resultado de temporal.now.instant y examinamos su propiedad epoch milliseconds para obtener un timestamp Unix en milisegundos.

Y aquí hay una posible salida, dependiendo de cuándo llames al método.

Así que, esa fue la tarea fácil. Ahora para la tarea media. Entonces, la pregunta que tenemos que responder para la tarea media es, ¿cuál es la fecha de un mes a partir de hoy? Así que, ya vimos en la tarea anterior cómo averiguar cuál es la fecha de hoy. Solo usas una función diferente del namespace now. Así que, saltemos eso por el momento, aunque hablaré más sobre cómo interactúa con los calendarios en un momento.

¿Cómo añadimos un mes a una fecha? Este es un buen momento para echar un vistazo a cómo hacer aritmética con fechas y horas en temporal. Mencioné duration hace unas diapositivas, y mencioné métodos aritméticos. Estos son los métodos aritméticos. Tenemos add y subtract para sumar o restar una duración de otro tipo. Y también tenemos since y until que determinan el tiempo transcurrido como una duración entre dos objetos del mismo tipo. Así que, en nuestro caso, usamos el método add. Queremos tomar una fecha y añadir una duración de un mes. Le pasamos un property bag, que se convierte automáticamente en una duración, para que no tengamos que llamar al constructor de duration aquí en esta línea de código.

Entonces, esta variable date, ¿de dónde viene? Ya necesitamos saber que necesitamos usar uno de los métodos now, específicamente now.plain date ISO. Y aquí es donde dije que el tema ISO iba a volver. Así que, un poco sobre calendarios. El calendario ISO se puede considerar como el calendario de la máquina. La forma en que funciona está estandarizada. No tiene dependencia regional o de idioma. Es adecuado para el cálculo. El calendario gregoriano es un calendario humano que se utiliza en gran parte del mundo con variaciones menores, pero es en lo que se basa el calendario ISO. Son lo suficientemente similares como para que puedas cambiar mentalmente entre los dos sin tener que hacer cálculos mentales. Sin embargo, una gran parte del mundo usa el calendario gregoriano, pero eso no significa que todo el mundo lo use. Algunas regiones no lo hacen, y en algunas regiones, las personas usan el calendario gregoriano para fines comerciales y otro calendario para fines religiosos. Así que, ya sin temporal, puedes imprimir un objeto de fecha antiguo de JavaScript en un calendario no gregoriano si el usuario lo desea. Así que, eso es suficiente para algunas aplicaciones, pero no es bueno para responder a esta pregunta, porque cuánto dura un mes depende de qué mes estás hablando en qué calendario. Puedo ilustrar eso.

Aquí tienes un ejemplo de cómo podría salir mal usando el old date. Digamos que la fecha de hoy en el calendario gregoriano es el 9 de octubre. Un mes después es el 9 de noviembre. En el calendario hebreo, estas dos fechas no están separadas por un mes este año. Están separadas por un mes y un día porque los meses tienen longitudes diferentes que en el calendario gregoriano. Así que, no es suficiente solo añadir un mes del calendario ISO y imprimir las fechas en otro calendario. Tienes que considerar realmente el calendario al realizar la adición.

Así que, la conclusión aquí es que cuando trabajas con fechas que el usuario verá, usa el calendario preferido del usuario, no el calendario ISO de la máquina. Así que, si juntamos todo eso, la forma de obtener la fecha de un mes a partir de hoy es, en primer lugar, definir exactamente a qué mes te refieres eligiendo el calendario. Puedes obtener el calendario de las preferencias del usuario en tu aplicación, por ejemplo, o de su configuración regional usando el método resolved options de Intel dot date time format. Aunque eso es una buena aproximación, no siempre corresponde a lo que el usuario realmente quiere. Y luego puedes obtener la fecha de hoy en ese calendario usando now dot plain date ISO, poner el calendario en él usando el método with calendar. Luego puedes añadir un mes usando el método add, y luego puedes formatearlo para el usuario con el método to locale string.

Así que, aquí tienes un ejemplo de cómo se ve eso en mi configuración regional. Aquí en el ejemplo de salida 2024-12-18. Muy bien, esa fue la tarea complicada. O ahora esa fue la tarea media. Ahora para la tarea complicada. Para esta tarea, necesitamos responder a la pregunta usando la información en este sitio web de la conferencia. ¿A qué horas ocurren estas sesiones para mí? ¿A qué sesiones puedo asistir cuando no estoy dormido? Así que, algo curioso, me hubiera encantado usar el sitio web de JS Nation US para esto, pero convenientemente ya pone las sesiones en la zona horaria local de tu navegador. Así que, bien hecho en eso. Tuve que elegir un sitio web de conferencia diferente que no hiciera eso. Pero vamos a pretender que estas son sesiones de JS Nation US. Así que, esta pregunta resulta ser sorprendentemente difícil de responder si no usamos una computadora, porque requiere muchas acrobacias mentales con las zonas horarias y restar o añadir horas.

Así que, la mayoría de las personas, incluyéndome a mí, simplemente, ya sabes, si queremos saber qué hora es 11 en punto AEST en mi zona horaria, simplemente lo pondré en un motor de búsqueda y esperaré que el motor de búsqueda corrija la suposición de lo que quiero. Pero el enfoque fuertemente tipado que tenemos en Temporal es perfecto para resolver este problema, porque puedes determinar el tipo basado en los datos que tienes, y luego puedes determinar a qué tipo convertirlo basado en los datos que necesitas.

Así que, aquí están los hechos que conocemos. Sabemos por el sitio web las dos fechas del calendario de la conferencia, 23 y 30 de julio. Obtuve la captura de pantalla de una conferencia pasada, pero digamos para este ejemplo, que las fechas son en 2025. Luego hay tres sesiones en cada día de conferencia. Conocemos las horas de inicio locales de cada una de las tres sesiones y en qué zonas horarias se dan esas horas de inicio locales. Así que, son las 11 a.m. AEST, mediodía BST, y 1 p.m. EDT. Luego también conozco mi zona horaria, y conozco las horas en mi zona horaria local durante las cuales estoy dispuesto a estar en línea viendo una conferencia.

Así que, aquí hay una expresión en pseudocódigo de lo que necesitamos hacer. Para cada fecha y cada sesión, conocemos la hora de pared y la zona horaria, lo que nos permite averiguar la hora exacta en que la sesión comienza y termina. Luego necesitamos ir de esa hora exacta de regreso a la hora de pared en mi zona horaria local para verificar si estoy despierto o no. Si estoy despierto, entonces imprimimos esa sesión. Aquí está la primera parte del código donde configuramos las cosas. Tenemos las fechas del calendario, las zonas horarias de las sesiones, y las horas de inicio. Tenemos la duración de las sesiones, y tenemos mi zona horaria. Así que, mi zona horaria la obtenemos de otro método now. La duración de la sesión es una duración. Y las fechas son fechas simples. Así que, para este cálculo, está bien usar el calendario ISO para las fechas porque estoy calculando mis tiempos de vigilia en el calendario ISO también. Ahora, hay algunas cosas que explicar aquí. Una de ellas es cómo determino estos nombres de zonas horarias. Estaba mencionando las abreviaturas como AEST y BST en la diapositiva anterior. En el sitio web, teníamos los nombres completos, Australia, Eastern Standard Time, British Summer Time, y Eastern Daylight Time con América del Norte implícita en el último. Esos son nombres humanos, no identificadores de máquina. Estas cadenas con las barras aquí en esta diapositiva, como Australia slash Brisbane, esos son los identificadores oficiales de la base de datos de zonas horarias de IANA. Así es como te refieres a las zonas horarias en Temporal. Si no conoces el identificador de una zona horaria en particular, generalmente puedes encontrar en Wikipedia o consultar la base de datos.

A veces, las abreviaturas humanas son ambiguas. Pero los identificadores son siempre precisos. Así que, la siguiente pregunta es, ¿por qué estamos usando from para crear estos objetos? Este es un buen momento para hablar sobre cómo crear un objeto Temporal. Podrías esperar que también puedas usar un constructor para crear una instancia de un tipo Temporal. Los constructores están destinados para uso de bajo nivel donde tienes todos los datos exactamente en el formato correcto, como en estos ejemplos. Luego, por otro lado, están estos métodos de fábrica llamados from. Son de alto nivel. Aceptan muchos más tipos de datos y los convierten.

En particular, a menudo son más legibles. Como una bolsa de propiedades con el año 2019, mes 6, eso me parece más legible que solo una cadena de números. Así que, en la mayoría de los casos, recomendaría usar from para crear un objeto Temporal. Pero si tienes los datos exactos en el formato correcto, puedes usar el constructor. La otra pieza de datos que mencioné que conocemos es qué horas estoy dispuesto a estar en línea para una conferencia. Quiero escribir una pequeña función que tome una hora de reloj de pared y devuelva verdadero si la hora está dentro de mis horas en línea.

Así que, para eso, tenemos que hacer comparaciones. Cada tipo tiene un método estático compare que usamos para esto. Es un método estático, por lo que puedes no necesitas una instancia. Puedes usarlo como argumento para el método sort de arrays. Si en cambio, solo quieres el caso común de verificar si dos objetos son iguales, usa el método equals. Así que, volviendo a escribir código. Aquí está la función que te dice si puedo estar en línea. Estamos usando plain time.compare para implementarlo. Aquí estoy aprovechando el hecho de que mis horas en línea no cruzan la medianoche. Tendríamos que ser un poco más complicados para soportar el caso en que lo hicieran. Pero esto es suficiente para este ejemplo. Ahora, este código es cómo funciona el cálculo real. Anteriormente lo describí en pseudocódigo. Recorremos cada fecha de la conferencia y la información de cada sesión, y la convertimos a la hora exacta llamada inicio de sesión como un zone date time. Luego usamos el método with time zone para obtener un nuevo objeto zone date time para el inicio de la sesión en mi zona horaria en lugar de la zona horaria de la sesión de la conferencia. Luego agregamos la duración de la sesión usando el método add que conocemos para obtener el final de la sesión en mi zona horaria.

Estos los pasamos a nuestra función de comparación, y si están durante mis horarios en línea, imprimimos el inicio y el final de la sesión usando format range. Si estás viendo una grabación de esta charla, siéntete libre de pausarla para examinar el código con más detalle si lo deseas.

Entonces, conversión. El método two zone date time que vimos es un ejemplo de uno de los métodos para la conversión entre tipos. Para convertir de un tipo a otro, necesitas agregar información o eliminar información. Si eliminas información como el año cuando pasas de plain date a plain Wednesday, el método no toma ningún argumento. Si necesitas agregar información como la hora del reloj, el método tomará la información requerida como argumento. En nuestro caso, convertimos de plain date a zone date time, por lo que tuvimos que agregar tanto una zona horaria como una hora, que el método two zone date time toma en una bolsa de propiedades.

El otro nuevo método que viste fue with time zone, así que este es un buen momento para entrar en cómo modificar un objeto temporal. Técnicamente, no puedes modificarlos. Son inmutables, como hablamos al principio de la presentación, pero puedes obtener un nuevo objeto del mismo tipo con uno o más componentes reemplazados, y para esto es el método with. Eso toma una bolsa de propiedades con uno o más componentes para reemplazar y devuelve un nuevo objeto. Y luego tenemos métodos separados para with calendar. Ya lo viste antes durante la tarea media y with time zone, que viste en esta tarea, porque esos dos no pueden proporcionarse al mismo tiempo que cualquier otra propiedad porque sería ambiguo qué propiedad tienes que reemplazar primero.

Así que, toma ese código, ponlo todo junto, ejecútalo, y aquí está la respuesta bien formateada. Esta es la respuesta en mi zona horaria con mi formato de configuración regional con estilo de fecha completo y estilo de hora corto, y tu respuesta probablemente será diferente si vives en una zona horaria diferente o tienes una configuración regional diferente. Así que, esta es una pregunta aparentemente simple respondida en más líneas de código de las que podrías esperar, pero en serio, ni siquiera habría querido intentar escribir este código con el antiguo objeto date. Habría sido posible asegurándome cuidadosamente de que las fechas estuvieran todas en UTC y convirtiendo en consecuencia al agregar o restar manualmente el número correcto de horas, pero sería realmente susceptible a errores. Y con este, estoy bastante seguro de que obtuve la respuesta correcta. Así que, espero que hayas encontrado útil este recorrido por Temporal, y si tienes el antiguo objeto date en tu base de código, espero que estés emocionado de reemplazarlo con Temporal. Puedes consultar la documentación en este enlace aquí, y en algún momento la documentación se graduará y podrás encontrarla en MDN en su lugar, junto con el resto de los elementos integrados de JavaScript. Gracias por tu atención.