La vida de un ESM en Node.js – y cómo está cambiando para mejor

Hola, gracias por invitarme hoy. Hoy esta charla trata sobre la vida de un ESM en Node. Así que esta es una charla sobre fundamentos, y una de las cosas más fundamentales en JavaScript son los módulos. Hoy cubriremos qué sucede cuando Node solicita importar un módulo, cómo las diferentes etapas de carga de módulos difieren en los empaquetadores de Node y navegadores, y nuevas características de transpiler o lenguaje de Node que están cambiando estas etapas. También cubriremos algunos malentendidos comunes sobre cómo funciona ESM. Será más útil si trabajas en un framework o herramientas de JavaScript o si deseas maximizar el rendimiento de carga de tus módulos o simplemente cuando necesites depurar algunos errores misteriosos cuando cargas el módulo. Incluso si estás usando IA en estos días, los fundamentos aún pueden ser importantes porque, bueno, la IA puede estar entrenada con datos desactualizados en internet y pueden estar confundidos sobre el estado más reciente de las cosas a menos que lo aclares para ellos.

Así que una rápida auto-presentación. Soy Joy Yi. Trabajo en Gallia y he sido patrocinada por Bloomberg en muchos de mis trabajos de código abierto. Como se mencionó antes, soy miembro de Node.tsc y committer de V8. Recientemente he estado contribuyendo a varias mejoras en la carga de módulos en Node. Puedes encontrarme en GitHub usando este handle y también puedes encontrar las diapositivas de esta charla en mi repositorio de charlas y el código QR aquí.

Así que antes de comenzar, hagamos un rápido cuestionario. Supongamos que tenemos este punto de entrada ESM que tiene estas cuatro declaraciones de importación. Individualmente, todas pueden fallar en la carga del módulo, pero cuando se cargan juntas, ¿cuál golpeará primero? Así que la opción A es cargar un módulo que lanza un error de JavaScript en el nivel superior. B es un módulo que no tiene una exportación nombrada que este módulo está importando. C es un módulo que no existe en disco. Y D es un módulo que contiene un error de sintaxis. ¿Cuál crees que veremos primero si intentamos cargar este módulo? Para ahorrar algo de tiempo, saltemos a la respuesta correcta por ahora. Es la opción C, el módulo que no existe en disco que golpeará primero. Volveremos a esta diapositiva más tarde después de explicar las diferentes fases por las que pasa un ESM en Node, entonces quedará claro por qué este es el que golpea primero.

Así que comencemos con una declaración de importación como esta. Para un poco de complejidad, hablemos de importar un paquete en lugar de solo una ruta. Entonces, ¿qué hará Node cuando ejecutemos el archivo que importa una exportación nombrada, llamada add aquí, de un especificador que es un paquete? Lo primero que va a hacer es la resolución. Así que este es un proceso de resolver el paquete especificador en una URL que identifica un archivo real en disco. Esto es manejado por el embebedor del motor de JavaScript, en este caso Node.

Así que si el módulo puede ser resuelto, por ejemplo si no existe en disco, Node falla con error. Es por eso que vemos que en el fragmento anterior, importar un archivo inexistente fallará primero porque la resolución es el primer paso. Hay varias diferencias en cómo funciona la resolución en diferentes entornos. En Node, si el especificador no es una ruta, busca en la carpeta de módulos de Node recursivamente. También intenta mirar en package.json. Si hay uno, consulta las condiciones de importación o exportación en el package.json. Si el especificador es una ruta, debe ser una ruta exacta porque cuando Node carga ESM a diferencia de common.js, no explora el index.js, por ejemplo en directorios, tampoco explora la extensión .

js si el especificador no deja una extensión. Así que todo esto llevará a errores de resolución para ESM en Node.

Si el especificador es una ruta, a diferencia de en Node, es muy típico que los límites realmente hagan un sondeo al estilo common.js en directorios o prueben diferentes extensiones porque los límites solo necesitan pagar por el costo de búsqueda en tiempo de compilación, no en tiempo de ejecución. Es por eso que esto se llama faux ESM en lugar de ESM real en Node.

Ahora en los navegadores, no tienen concepto de módulos de Node o package.json. Si intentas importar un nombre de paquete, simplemente fallará al resolver porque solo aceptan rutas o URLs. Así que si el especificador es una ruta, debe ser exacta. Además, los navegadores soportan mapas de importación, pero Node no. Bueno, al menos todavía no. Hay un trabajo en progreso, pero las discusiones sobre si los mapas de importación realmente tienen sentido para Node o si Node debería ofrecer una solución diferente son algo inconclusas en este momento.

Así que anteriormente mencionamos que solo los límites sondearían diferentes extensiones al resolver un especificador ESM. Ahora aquí hay un consejo que puede ser útil si trabajas con TypeScript. Así que a partir de 22, Node soporta TypeScript a través de TypeScripting. Con una sugerencia del equipo de TypeScripting, Node solo soporta TypeEraser, por lo que no permite transformaciones como convertir ESM a CommonJS.

Pero para un rendimiento y compatibilidad óptimos, la mejor práctica suele ser usar TypeScripting en tiempo de desarrollo. Pero si el código se distribuirá en un entorno de producción en ejecución donde el tiempo de inicio es importante, es mejor transpilarlo a JavaScript y ejecutarlo en su lugar en producción. Entonces tenemos un problema porque generalmente los transpiladores transpilan archivos .ts a archivos .js en una carpeta diferente. Así que, por ejemplo, aquí, la importación relativa en source slash main.ts está destinada a resolverse a source slash mod.ts. Entonces, cuando esto se transpila a dist main.js, esta importación relativa ya no se resolverá porque en el directorio dist, solo tenemos el mod.js transpilado, no mod.ts. Así que eso todavía estaba en el directorio source.

Algunos usuarios han estado resolviendo dist omitiendo la extensión y luego confiando en un empaquetador para convertir el módulo de ESM a CommonJS que sondea extensiones. Así que, por ejemplo, para el mod sin extensión aquí, podrían contar con empaquetadores para sondear mod.ts durante la resolución en tiempo de compilación y luego contar con el cargador CommonJS de node para sondear mod.js en tiempo de ejecución. Pero si quieren eliminar la dependencia del empaquetador y ejecutarlo directamente con node usando eliminación de tipos, las importaciones sin extensión no funcionan ya que la eliminación de tipos de node deja ESM como ESM y ESM en node no sondea las extensiones. Requiere la ruta exacta.

Así que si el archivo main.ts que importa mod sin una extensión se ejecuta en node, falla en error de resolución. El consejo aquí no se trata realmente de cambiar la configuración de node, se trata de cambiar la configuración del transpilador. Así que desde 5.7, TSC introdujo una opción de reescribir la extensión de importación relativa que reescribe los especificadores .ts en el código fuente a .js en el código generado durante la transpilación. Así que, como aquí, con este archivo que carga mod.ts, lo ejecutamos con node. Durante el tiempo de desarrollo, esto será source main.ts importando source mod.ts. Después de la transpilación, cualquier transpilador que soporte esta opción lo transpilará a este slash main.js importando de este mod.js en ESM. Ambos se resolverán bien en node, así que si todavía estás confiando en un empaquetador o cargador personalizado para ejecutar TypeScript en node debido a este problema específicamente, la configuración de reescribir extensiones de importación relativa puede ayudarte a eliminar la dependencia.

Así que aquí hay otra característica que hace que la resolución de módulos sea más personalizable. Para Node 22 y superiores, tenemos la API de hooks de resolución de módulos que ahora está en versión candidata. Esto te permite personalizar la resolución usando el hook de resolución. Como aquí, podemos registrar una función que redirige todas las importaciones de db.js a db.mark.js. Esto es principalmente útil para herramientas o frameworks que necesitan personalizar la resolución de módulos.

Ahora, después de la resolución, tenemos la URL. Así que vamos a la siguiente etapa, que es obtener el código fuente identificado por la URL de resolución. Esto se denomina más confusamente como carga en los internos de las APIs de Node. En Node, cargar ESM a veces se refiere específicamente al proceso de obtención del código fuente. Y nuevamente, esto también es manejado por Node, no por el motor.

Así que en esta etapa, si no se puede obtener el código fuente, por ejemplo, si el resultado del archivo no es legible debido a la falta de permisos, Node puede lanzar el error del sistema de archivos aquí. Y diferentes entornos cargan el código fuente de manera diferente. Por ejemplo, en Node, típicamente obtiene el código fuente de manera infrarroja y sincrónica para reducir las carreras con el caché de carga requerido. Y también porque en Node, la carga de módulos generalmente se realiza desde el sistema de archivos local o memoria antes de que el código de la aplicación se ejecute.

En este caso, la carga sincrónica suele ser más rápida. Mientras que en los navegadores, esto suele ser fuera del hilo y asincrónico o encadenado porque típicamente cargan a través de la red. En el caso de los empaquetadores, esto varía. Y también en Node, porque los únicos protocolos soportados son file, data, y node, y hay solo regiones opacas. Así que Node se basa en los permisos del sistema de archivos para verificar el acceso. Esto también suele ser el caso para los empaquetadores, empaquetando para Node. Pero en los navegadores, la política de mismo origen se aplica a ESM. Así que si estás intentando cargar el módulo desde un origen diferente en los navegadores, pero no tienes configurada la política de recursos de origen cruzado, entonces la carga fallará en el navegador.

Ahora, similar al hook de resultado, Node también proporciona un hook de carga que se puede usar para personalizar el código fuente de los módulos que se están cargando. Se ejecuta sincrónicamente en el hilo porque también necesita soportar require. Aquí, por ejemplo, puedes implementar un hook de carga que devuelva un código fuente personalizado predefinido si la URL de un módulo usa un protocolo personalizado. Y puede devolver source-true para que Node omita el paso de carga predeterminado y luego lo busque en el disco. Esto permitirá al framework, por ejemplo, virtualizar la carga de módulos o permitir cargadores personalizados para transpilar y soportar módulos en otros lenguajes sobre la marcha.

Así que una vez que tenemos el código fuente listo, la siguiente etapa es el análisis. Ahora, el análisis es mayormente realizado por VA en esta etapa, pero Node también necesita hacer algo de conducción aquí. Así que si el módulo que se está cargando está en ESM, VA verificará su sintaxis y lanzará un error si el módulo objetivo no se analiza. Después del análisis, construye un ASC, al menos para el código de nivel superior. Así que justo antes del análisis, porque Node soporta importar tipos de módulos distintos a ESM, también puede primero detectar el formato del módulo para decidir cómo analizarlo. Esta detección puede basarse en extensiones, el campo type en PackJSON, o comenzando con 20, Node también verifica la sintaxis del archivo si otras señales están ausentes. La detección mejora la experiencia del usuario, pero tiene un costo y puede ser ambigua. Para un máximo rendimiento, siempre es mejor usar extensiones o el campo type explícitamente para evitar el costo de detección. Así que los empaquetadores usualmente tienen una detección similar cuando empaquetan el código para ejecutarse en Node, pero en los navegadores, el tipo del módulo siempre se indica explícitamente, ya sea usando el atributo type en la etiqueta script o el campo type pasado a los workers. Y también en los navegadores, los submódulos transitivos cargados por un ESM siempre se asumirán como ESM, por lo que no se realizará ninguna detección. Así que en Node, el análisis es infrarrojo, no es transmitido porque necesita interoperar con personalizaciones ejecutadas en JavaScript de un solo hilo. Los navegadores típicamente analizan el archivo fuera del hilo y transmiten el análisis. En el caso de los empaquetadores, pueden hacer ambos. Depende del empaquetador que estés usando. Ahora tenemos AST, la siguiente etapa es la compilación.

La mayoría de los navegadores principales tienen una forma de almacenar en caché el bytecode en el disco. La próxima vez que el mismo módulo se cargue nuevamente sin cambios, si el navegador no se actualiza, típicamente solo reutilizará el bytecode leído desde el disco. Al igual que el análisis, la compilación en los navegadores generalmente ocurre fuera del hilo. Además, la mayoría de los motores de JavaScript construidos para navegadores no analizan sus funciones en los módulos al principio, como aquí. La asignación de constantes a nivel superior se analizará y compilará completamente cuando el módulo se cargue, pero la función add no se analizará ni compilará completamente hasta que se invoque por primera vez.

Así que Node también ha comenzado a soportar la caché de compilación en disco desde 2022. Actualmente es opcional a través de la variable de entorno no compile cache o la API module enable compile cache o la opción use code cache si estás construyendo una aplicación sincronizable con Node. El bytecode también solo se reutiliza cuando el módulo no ha cambiado y se ejecuta en la misma versión de Node. Y al igual que el análisis, la compilación en Node ocurre en el hilo principal. Además, Node también solo pre-analiza funciones internas y no genera código para ellas hasta que se invocan, aunque esto también se puede hacer configurable en el futuro porque Node generalmente proporciona más extensiones de bajo nivel que los navegadores.

Así que después de la compilación, obtenemos el bytecode de un módulo. ¿Qué sigue? Necesitamos avanzar y manejar sus dependencias, si las hay. Por ejemplo, aquí tenemos un módulo, main.js, que importa un paquete. Ese paquete a su vez carga el módulo incorporado node path y otro módulo utils. Necesitamos iterar a través de estas solicitudes de módulo. Necesitamos resolver sus especificadores a URLs, cargar el código fuente desde las URLs resueltas, analizar y compilar su código y repetir hasta que el gráfico de dependencias se cargue transitivamente. En esta etapa, si alguna de las dependencias transitivas no se puede resolver, cargar o analizar, Node lanzará un error porque cualquier código de módulo en el gráfico antes de que cualquier código de módulo en el gráfico se ejecute.

Como aquí, por ejemplo, si el paquete utils.js no existe, falla al resolver, y node dará un error y no se ejecutará ningún código incluso si lo colocas antes de las declaraciones de importación. El primer console log aquí no se ejecutará, porque según la especificación específica del lenguaje, las declaraciones de importación se elevan y el código ejecutable se ejecutará mucho más tarde antes de que las dependencias se carguen, independientemente de las ubicaciones de origen. Y después de compilar todo el gráfico transitivamente, la siguiente etapa es la instanciación. Es cuando VA intenta hacer coincidir las importaciones y exportaciones, y busca desajustes. En la especificación del lenguaje, esta etapa ha sido renombrada a vinculación. Según la terminología de node y VA, esto todavía se llama instanciación, así que también lo llamamos instanciación por ahora. Aquí, por ejemplo, main.js importa un nombre, add, del paquete, y el paquete no exporta el código add. Entonces, estos dos... que sí tienen un código de exportación add, así que estas referencias se unirán juntas. El paquete, a su vez, importa n underscore add de otro paquete, y también importa la exportación por defecto de node path incorporado. Y estas referencias también se unirán juntas por VA durante la instanciación. Y en esta etapa, si un módulo importa un nombre de otro módulo que no lo exporta, VA lanzará un error.

Y nuevamente, esto sucede antes de que se ejecute cualquier código. Como aquí, si main.js importa el nombre que no se exporta del paquete, la declaración console.log antes de la declaración de importación no se ejecutaría. Así que antes, hablamos sobre el uso de hooks registrados de módulo para personalizar la resolución y carga, pero ¿qué tal personalizar las etapas desde el análisis hasta la instanciación? Estas etapas son más especiales en ESM, y no pueden compartir primitivas con CommonJS a través de la misma API de hooks registrados de módulo. Tenemos la API de módulos VM. Ha sido utilizada por algunos marcos de prueba para aislamiento ligero. Esta fue la razón por la que el soporte de ESM en Jest sigue siendo experimental, porque dependen de esta API que ha sido experimental desde 2017. Resulta que esta API tiene algunos problemas de diseño que llevan a errores y advertencias cuando se usa en el mundo real. Así que para lidiar con estos problemas, estamos renovando esta API con un nuevo diseño que intenta evitar problemas en la gestión de memoria.

Y también en la abortación e informes de errores, esto sigue siendo un borrador temprano. Solo escuchando aquí para darte una idea de cómo se ve. Así que si estás construyendo marcos o herramientas usando la API experimental de módulos VM, por favor revisa este problema y ayúdanos a encontrar un diseño que sea adecuado para la estabilización. Así que nos detuvimos por última vez en la instanciación. Si el gráfico se instancia correctamente, finalmente podemos entrar en la evaluación o ejecución. En esta etapa, las dependencias se ejecutan antes que los módulos dependientes. Así que si las dependencias lanzan un error a nivel superior, los módulos dependientes no serán ejecutados. Y si la dependencia aquí lanza errores en JS, entonces la declaración console.log en main no se ejecutará, incluso si está colocada antes de la importación. Recuerda que las declaraciones de importación se elevan antes que el código ejecutable en el módulo importador. Y en esta etapa, Node solo llega a iniciar la evaluación del módulo raíz, porque VA controla la evaluación de los submódulos transitivos.

Como aquí, Node puede hacer algo antes de que se ejecute todo el gráfico de módulos, pero no puede hacer nada entre ejecutar el código en el paquete y ejecutar el código en el módulo dependiente. Como aquí, no puede insertar nada antes de la llamada console.log en main, porque la evaluación interna está completamente controlada por VA. Es por eso que no hay un hook de evaluación pre-módulo ESN. Otra limitación de ESN es que, aunque los namespaces de ESN pueden reflejar mutaciones desde dentro del exportador, no pueden ser mutados desde el importador. La mutabilidad está mandatada por el lenguaje y controlada por el motor de JavaScript, no por el embebedor del motor de JavaScript. Así que, por ejemplo, aquí tenemos un módulo que muta la variable count. Si intentamos actualizar el count a 5 desde el módulo principal, la mutación no tiene efecto, porque el namespace es inmutable según el lenguaje. Pero si invocamos el método ink, que muta el count desde dentro de ese módulo, esto se reflejará en el objeto namespace del módulo.

Además, en este caso, el embebedor no puede controlar la mutabilidad del namespace. Si deseas hacer alguna personalización del namespace, debe hacerse modificando el código fuente en el hook de carga. También tenemos algunas nuevas características del lenguaje que cambian cómo se realizan las evaluaciones. Por ejemplo, desde 2004, Node soporta la propuesta de importación basada en fuente de Stage 3 que permite a los usuarios personalizar la evaluación de Wazen en ESN usando la API de WebAssembly. Otra característica próxima de Stage 3 es la evaluación diferida. Esto se está integrando actualmente en Node detrás de una bandera de V8. Así que si tienes un módulo como HeavyJS aquí, que tiene muchas inicializaciones para ejecutar, o simplemente tiene un gran gráfico de dependencias que contiene muchas bibliotecas que no usas, si sus exportaciones solo serán realmente necesarias cuando se llame a la función, puedes usar la palabra clave defer para diferir la evaluación de los módulos menos usados para que solo se evalúen bajo demanda cuando se accede a la propiedad. Con esto puedes reducir el tiempo de inicio del código y mantener el uso de memoria bajo.

Así que eso fue un recorrido por la importación de ESN en Node. Volviendo al cuestionario inicial, creo que ahora estará claro lo que está sucediendo aquí. En un fragmento, primero encontraremos el error de resolución porque ese es el primer paso. Si solucionamos la resolución, Node comenzará a intentar cargar el código y analizar las dependencias y el módulo con error de sintaxis fallará a continuación. Después de eso, si solucionamos eso, pasamos a la instanciación, nos encontramos con el error de la exportación no coincidente. Finalmente, encontraremos el error de la dependencia del módulo porque la evaluación ocurre en la última etapa. Así que una última cosa, hablamos sobre cómo ESN cobra vida en Node, pero ¿qué lo mantiene vivo? ¿Cuándo desaparecerá? En este caso, la mayor parte de la complejidad proviene de este requisito de idempotencia en la especificación del lenguaje. Cuando la solicitud del módulo es la misma, el módulo devuelto por el embebedor debe ser el mismo. Por ejemplo, aquí si tenemos un módulo con estado que exporta algo que muta su estado interno y en otro módulo lo cargamos y lo liberamos. Después de cierta recolección de basura, el estado debería haber desaparecido. Pero en realidad, según la especificación, algún tiempo después, incluso si la variable original parece desaparecer, cuando regresa, al ser cargada nuevamente, todavía necesita mantener el estado original. Así que como puedes imaginar, para lograr esto, Node necesita mantener varios cachés internos. Y estas referencias internas pueden hacer que las herramientas y los marcos apunten a fugas cuando implementan, por ejemplo, recarga en caliente de ESN en Node. Así que para abordar este problema, hay una API de limpieza de caché de módulos que se está trabajando actualmente.

Estos no limpiarán todos los cachés por ahora, pero permitirás que los frameworks muten el único caché que anteriormente no se podía limpiar y puede hacer que la descarga a ESN sea más fácil de usar en el futuro. Bien, eso es todo. Espero que esto sea útil. Gracias por acompañarme.

Así que el que he destacado hasta ahora es, ¿cuál es el mayor error de concepto de ESM que ves con los ingenieros senior con los que hablas? Creo que el mayor error de concepto sería la forma en que se carga ESM es diferente de CommonJS, especialmente para personas que vienen de un entorno más antiguo de Node CommonJS. Porque para CommonJS, cargas el módulo uno por uno, y luego justo después de cargar el código fuente, lo ejecutas. Así que si el primero falla al ejecutar, bloquea la ejecución subsiguiente. Pero en ESN, intenta cargar todo el gráfico, analizarlo, compilarlo, y luego se lleva a cabo la ejecución del gráfico. Así que es como si hubiera dos fases. Así que si algún módulo no se resuelve, no se analiza o algo, no se ejecuta. Ese es el mayor error de concepto para las personas que miran ESN frente a CommonJS. Bien, de acuerdo, así que la carga de todo el gráfico de una vez, sí.

¿Y qué hay de las dependencias circulares? Así que alguien estaba preguntando cómo el sistema de módulos maneja las dependencias circulares. Así que para la carga, la dependencia circular se maneja mediante un caché. Así que cuando intentas cargar el primer módulo y luego a su vez carga otros módulos, el cargador volverá a visitar el caché, y lo recogerás del caché. Si, por ejemplo, una de las cargas encuentra un error, temporalmente almacenarás algo en el caché. Si hay un error, simplemente lo sacarás. Así es como se realiza la carga. Para la evaluación, cuando tienes una dependencia circular, según la especificación del lenguaje, tendrás una especie de marcador de posición. Así que no puedes acceder realmente a él durante la evaluación cuando todavía estás en el ciclo. Si haces eso, encontrarás tdz, como típico, si haces let o cons antes de que se inicialice, encontrarás un tdz. Así que es el mismo tdz en dependencias circulares en la evaluación en ESN. Bien, genial.

Sobre el futuro de esto, tengo uno aquí que trata sobre la bandera en TypeScript. ¿Sabes si eso se convertirá en predeterminado o algo así? Supongo que eso es más una pregunta de TypeScript. Sí, esa es una pregunta para TypeScript. También hay otra sobre cómo históricamente la carga ha sido un poco menos eficiente. Así que históricamente ha sido menos eficiente. ¿Hay algo que se esté haciendo para reducir un poco ese costo de inicio, o hay algún trabajo que aún necesite hacerse allí? Así que una de las cosas de las que hablé antes, como hacer que la carga sea sincrónica, en realidad está ayudando al rendimiento. Porque si el código de tu aplicación no se va a ejecutar antes de la carga del módulo, tienes un gran bloque de tiempo que se gasta solo en la carga del módulo. Y en realidad, en ese bloque de tiempo, es más rápido ejecutar las cosas de manera sincrónica porque asincrónico y asincrónico en Node en realidad tiene mucho overhead porque necesita hacer muchas cosas, especialmente cuando tienes threading, coordinación, ese tipo de cosas. Así que eso es una cosa. Y la otra cosa es el caché de compilación del que hablé antes que simplemente elimina la sobrecarga de carga porque solo estás deserializando cosas. Ya no estás realmente analizando. Bien, de acuerdo. Así que sí, genial. Desafortunadamente, se nos acabó el tiempo. Me encantaría hacer más preguntas aquí. Pero, por supuesto, Joy, tal vez acércate a ella en una de las sesiones posteriores. Gracias de nuevo, Joy.