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

Hola. Gracias por invitarme hoy. La charla de hoy 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 se le pide a Node que importe un módulo, cómo las diferentes etapas de carga de módulos difieren en Node, empaquetadores 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ía más útil si trabajas en un framework de JavaScript o herramientas o si deseas maximizar el rendimiento de carga de tus módulos o simplemente cuando necesites depurar algunos errores misteriosos al cargar 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 colaboradora de VA. Recientemente he estado contribuyendo a varias mejoras de 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 se ejecutará 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 el disco. Y D es un módulo que contiene un error de sintaxis. ¿Cuál crees que verás primero si intentamos cargar este módulo? Bien, para ahorrar algo de tiempo, saltemos a la respuesta correcta por ahora. Es la opción C, el módulo que no existe en el disco que se ejecutará 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 se ejecuta primero.

Así que comencemos con una declaración de importación como esta. Para un poco de complejidad, hablemos sobre la importación de un paquete en lugar de solo una ruta. Entonces, ¿qué haría Node cuando ejecutamos un archivo que importa una exportación nombrada llamada add aquí desde el especificador que es un paquete? Lo primero que va a hacer es la resolución. Así que este es un proceso de resolver el especificador del paquete en una URL que identifica un archivo real en el disco. Esto es manejado por el embebedor del motor de JavaScript, en este caso Node. Así que si el módulo no puede ser resuelto, por ejemplo si no existe en el disco, Node lanza un 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.

Y 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 Node modules recursivamente. También intenta mirar el 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 CommonJS, no sondea el index.js, por ejemplo en directorios. Tampoco sondea 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.

Cuando los límites empaquetan código para Node, imitan la resolución de módulos en Node. También consultan Node modules y package JSON recursivamente. Pueden recoger sus propias condiciones de importación y exportación. Eso varía dependiendo de los límites que uses. Si el especificador es una ruta, a diferencia de Node, es muy típico que los límites realmente hagan un sondeo al estilo CommonJS en directorios o prueben diferentes extensiones porque los límites solo necesitan pagar por las llamadas 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 real ESM en Node. Ahora en los navegadores, no tienen concepto de Node modules o package JSON. Si intentas importar un nombre de paquete, simplemente fallará en 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 no todavía. 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 un poco 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 la versión 22, Node soporta TypeScript a través de la eliminación de tipos. Con una sugerencia del equipo de TypeScript, Node solo soporta la eliminación de tipos, 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 la eliminación de tipos en tiempo de desarrollo. Pero si el código se distribuirá o ejecutará en un entorno de producción donde el tiempo de inicio es importante, es mejor transpilarlos a JavaScript y ejecutar eso en producción. Entonces tenemos un problema porque usualmente 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 en source slash mod.ts. Así que 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.

porque en el directorio dist, solo tenemos el mod.js transpilado, no mod.ts. Así que eso todavía estaba en el directorio fuente. Así que algunos usuarios han estado resolviendo esto omitiendo la extensión y luego confiando en un bounder 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 bounders para sondear mod.

ts durante la resolución en tiempo de construcció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 bounder y ejecutarlo directamente con Node usando eliminación de tipos, las importaciones sin extensión no funcionan ya que la eliminación de tipos 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 es realmente sobre cambiar la configuración de Node, es sobre cambiar la configuración del transpilador. Así que desde la versión 5.7, TSC introdujo una opción de reescritura de 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.

Tenemos la API moduleResolutionHooks que ahora es un candidato a lanzamiento. Esto te permite personalizar la resolución usando el gancho de resolución. Como aquí, podemos registrar una función que redirige todas las importaciones de db.js a dbMock.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 de manera algo confusa 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 los diferentes entornos cargan el código fuente de manera diferente. Por ejemplo, en Node, típicamente obtienes el código fuente en infrarrojo y sincrónicamente para reducir las carreras con la caché de carga requerida. También, porque en Node, la carga de módulos generalmente se realiza desde el sistema de archivos local o la 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 asíncrono 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 son solo regiones opacas. Así que Node se basa en los permisos del sistema de archivos en su lugar para verificar el acceso. Esto también suele ser el caso para los empaquetadores que empaquetan 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 gancho de resultado, Node también proporciona un gancho 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 gancho de carga que devuelva un código fuente personalizado predefinido si la URL de un módulo utiliza un protocolo personalizado. Y puede devolver el circuito de fuente verdadero para que Node omita el paso de carga predeterminado y no 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 realizado principalmente por VA en esta etapa porque Node también necesita hacer algo de conducción aquí. Así que si el módulo que se está cargando es un 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 la importación de tipos de módulos distintos de ESM, también puede detectar primero el formato del módulo para decidir cómo analizarlo. Esta detección puede basarse en extensiones, el campo type en Pack.json 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 typefield explícitamente para evitar el costo de detección. 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 typefield pasado a los workers.

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. También en Node, el análisis es infrarrojo, no es stringed, porque necesita interoperar con personalizaciones ejecutadas en JavaScript de un solo hilo. Los navegadores típicamente analizan el archivo fuera del hilo y string en lugar de analizar. En el caso de los empaquetadores, podrían hacer ambos. Depende un poco de los empaquetadores que estés usando.

Ahora tenemos AST, la siguiente etapa es la compilación. En el caso de V8, genera bytecode en la primera compilación. Así que aquí también tenemos algunas diferencias en cómo los navegadores y Node manejan 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 la compilación de análisis en los navegadores típicamente 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 de nivel superior se analizará y compilará completamente cuando se cargue el módulo. Pero la función add no se analizará ni compilará completamente hasta que se invoque por primera vez. Node también ha comenzado a soportar la caché de compilación en disco desde la versión 22, aunque actualmente se actualiza a través de la variable no-compile-cache o la API module enable-compile-cache, o la opción use-code-cache si estás construyendo una aplicación no-sync-code. 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 la compilación de análisis en Node ocurre en el hilo principal. Actualmente, Node también solo pre-analiza sus funciones y no genera código para ellas hasta que se invocan, aunque esto también puede hacerse configurable en el futuro porque Node usualmente proporciona más extensiones de bajo nivel que los navegadores.

Así que después de la compilación, tenemos 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 puede resolverse, cargarse o analizarse, 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 ejecutarás ningún código, incluso si lo colocas antes de las declaraciones de importación, como el primer console log aquí no se ejecutará porque según la especificación 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. Esto es cuando V8 intenta emparejar 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 V8, 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, de un paquete y el paquete no tiene una exportación llamada add. Así que estas referencias se unirán, y el paquete a su vez importa n underscore add de otro paquete, y también importa la exportación predeterminada del módulo incorporado node path. Y estas referencias también se unirán por V8 durante la instanciación. Y en esta etapa, si un módulo importa un nombre de otro módulo que no lo exporta, V8 lanzará un error. Y es por eso que lo llamamos instanciación, porque si es un módulo que no lo exporta, V8 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 de un 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 module.register.hooks en la codificación, 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 module.register.hooks. 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 todavía es 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 y reporte 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 frameworks o herramientas usando la API experimental del módulo 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 se ejecutarán. Como aquí, lanza errores njs lanza, entonces la declaración console.log en main no se ejecutará, incluso si está colocada antes de la importación. Recuerda, las declaraciones de importación se elevan antes que el código ejecutable en el módulo importador. Y en esta etapa, node solo puede iniciar la evaluación del módulo raíz porque VA controla la evaluación de los módulos de suma transitiva. 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. Esta es la razón por la que no hay un gancho de evaluación pre-módulo ESN.

Otra limitación de ESN es que mientras los espacios de nombres ESN pueden reflejar mutaciones desde dentro del exportador, no se pueden mutar 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 cinco desde el módulo principal, la mutación es una operación nula porque el espacio de nombres es inmutable según el lenguaje. Pero si invocamos el método ink, que muta el count desde dentro del módulo, esto se reflejará en el objeto del espacio de nombres del módulo. Y también en este caso, el embebedor no puede controlar la mutabilidad del espacio de nombres. Así que si quieres hacer alguna personalización del espacio de nombres, tiene que hacerse modificando el código fuente en el gancho de carga. También tenemos algunas nuevas características del lenguaje que cambian cómo se realiza la evaluación.

Por ejemplo, desde la versión 24, Node soporta la propuesta de importación basada en fuente de etapa 3 que permite a los usuarios personalizar una evaluación Wazen en ESM usando la API de WebAssembly. Otra característica de etapa 3 próxima 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 mucha inicialización para ejecutar, o si simplemente tiene un enorme gráfico de dependencias que contiene muchas bibliotecas que no usas, o 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 utilizados para que solo se evalúen bajo demanda cuando se acceda 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 sobre la importación de ESM en Node. Ahora volviendo al cuestionario inicial, creo que ahora estará claro lo que está sucediendo aquí. En el 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. Luego nos encontraremos 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 ESM 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, si tenemos un módulo con estado que exporta algo que muta su estado interno, y en otro módulo, podemos cargar y liberar, y después de alguna 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 se vuelve a cargar, todavía necesita mantener el estado original. Así que como puedes imaginar, para lograr esto, Node necesita mantener varios cachés internos. Estas referencias internas pueden hacer que herramientas y frameworks apunten a fugas cuando implementan, por ejemplo, recarga en caliente de ESM en Node. Para abordar este problema, se está trabajando actualmente en una API de limpieza de caché de módulos. Esto no limpiará todos los cachés por ahora, pero permitirá a los frameworks mutar el único caché que anteriormente no se podía limpiar y puede hacer que la descarga a ESM 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 como la forma en que ESM se carga es diferente de CommonJS, especialmente para personas que vienen de un entorno más antiguo, como sin experiencia en CommonJS. Porque para CommonJS, cargas el módulo uno por uno, y 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 ESM, intenta cargar todo el gráfico, analizarlo, compilarlo, y luego puede resolver la ejecución del gráfico. Así que es como si hubiera dos fases. Entonces, 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 ESM versus CommonJS.

Correcto, bien, 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, 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á del caché. Si, por ejemplo, uno de los cargadores encuentra un error, como que temporalmente almacenas algo en el caché. Si hay un error, simplemente lo sacará. Así es como se realiza la carga. Para la evaluación, cuando tienes una dependencia circular, según la especificación del lenguaje, tienes como una especie de marcador de posición, por lo que no puedes acceder realmente a él durante la evaluación cuando todavía estás en el ciclo. Si haces eso, encontrarás TDC, como típico, como si haces let o cons antes de que se inicialice, encontrarás un TDC. Así que es el mismo TDC en dependencias circulares en la evaluación en ESM.

Bien, genial. Y sobre el tipo de futuro de esto, tengo uno aquí que trata sobre la bandera en TypeScript. ¿Sabes si eso se convertirá en algo predeterminado o algo así? Supongo que eso es más una pregunta de TypeScript. Sí, esa es una pregunta para TypeScript. Sí. 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 a nuestro rendimiento porque si el código de tu aplicación no se va a ejecutar antes de la carga del módulo, tienes como 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 la asincronía y su sincronicidad, ya sabes, en realidad tiene mucho overhead, porque necesita hacer muchas cosas, especialmente cuando tienes como coordinación de hilos, ese tipo de cosas. Así que esa es una de las cosas. Y la otra cosa es como la caché de compilación de la que hablé antes, que simplemente elimina el overhead de carga porque solo estás deserializando cosas. Ya no estás realmente analizando. Correcto.

Bien. 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érquense a ella en una de las sesiones después. Gracias de nuevo, Joy.