Migrando TypeScript a Módulos: Los Detalles Finales

Hola a todos, soy Jake. Soy un ingeniero de software senior en Microsoft y hoy voy a hablar sobre la migración de TypeScript a módulos. Entonces, primero, ¿de qué estamos hablando? Bueno, en noviembre del año pasado, envié esta PR. Fue la culminación de muchos, muchos meses de trabajo. Fue un cambio enorme, alrededor de un cuarto de millón de líneas de código, y cambió por completo la forma en que el compilador de TypeScript estaba estructurado internamente. Hablamos de esto en detalle en nuestro blog, pero hay muchos detalles de los que no pudimos hablar y eso es de lo que voy a hablar hoy. En resumen, vamos a hablar de qué significa una migración a módulos. Vamos a hablar de por qué fue tan desafiante, pero cómo lo hice menos doloroso. Vamos a hablar de cómo funcionó la migración bajo el capó y vamos a hablar de lo que eso significó para nosotros, cómo fue, y qué sigue para los módulos en TypeScript. Volviendo a lo básico, ¿qué son los módulos? Creo que hay algunas definiciones diferentes que se pueden dar para esto, pero creo que las dos más críticas son la sintaxis en sí misma. Así que eso es importación-exportación y la parte donde se crean múltiples archivos e importarlos entre sí, pero también es el formato de salida. Así que ESM como he escrito a continuación, CommonJS que se utiliza bastante en el ecosistema de Node, y muchos otros formatos menores. Cuando hablo de migrar TypeScript a módulos, me refiero específicamente a esta primera definición. Es decir, cambiar TypeScript para usar la sintaxis de importación y exportación. Ahora eso plantea la pregunta, si TypeScript no era módulos antes, pero no usaba importación-exportación, ¿qué usaba? La respuesta es scripts. Entonces, en TypeScript, todo es un script o un módulo.

explícito. Ahora, todo nuestro código está en diferentes archivos, pero podemos agruparlos usando outfile y prepend. Entonces, puedes ver que dentro de la configuración de tsconfig de tsc, establecemos outfile como tsc.js, y luego le pedimos a tsc que agregue todo el contenido de sus proyectos dependientes. A continuación, puedes ver todo el código que el compilador definió, el comando de ejecución de la línea de comandos definido, todo se coloca en la parte superior del archivo. Y luego todo el código que estaba en el proyecto tsc. Entonces, tsc ha sido efectivamente un paquete todo este tiempo, aunque veremos más adelante que esta opción se eliminará. Ahora, si alguien quiere importarnos, esto es interesante porque somos scripts globales. No hay importaciones ni exportaciones. Pero podemos ser inteligentes aquí. Lo que podemos hacer es decir que si estamos en un contexto de CommonJS, es decir, hay module y module exports, entonces simplemente podemos leer nuestro espacio de nombres ts como un valor y establecerlo en module.exports. Esto significa que si alguien nos carga dentro de un contexto que admite CommonJS, como Node, pero también otros paquetes, verán que este es un módulo de CommonJS y funcionará como la gente espera. Pero si alguien carga esto en su página web simplemente usando una etiqueta de script, obtendrán una variable ts y también funcionará. Los espacios de nombres tienen algunas ventajas. Debido a que estamos usando espacios de nombres, no tenemos que escribir importaciones. Obviamente, estamos hablando de agregar importaciones. Antes no había importaciones en absoluto. Cuando agregamos nuevo código, no tenemos que importarlo. Si es otro archivo, simplemente lo usamos. Si movemos código de un archivo a otro, tampoco tenemos que cambiar las importaciones. También obtenemos el agrupamiento de forma gratuita utilizado por TSC. Pero nadie escribe código así en la actualidad. Esto significa que no podemos probar los módulos. Si queremos probar cosas como la resolución de Node Next, importaciones automáticas, importaciones organizadas, todas esas cosas buenas, no podemos hacerlo en nuestro propio código base. Tampoco podemos usar herramientas externas que solo manejan importaciones y exportaciones. Entonces, si queremos probar ciclos entre archivos, todas esas herramientas esperan tener importaciones presentes y no podemos usarlas. También necesitamos mantener prepend. Resulta que nadie usa esta función excepto TypeScript en sí mismo. Entonces, sería genial eliminarla del producto y dejar de mantenerla. Queremos tener archivos que se exporten e importen explícitamente entre sí. Tenemos el mismo archivo anterior, pero tenemos parser.tsx exportando create source file en el nivel superior. Y luego en program.ts lo importamos por nombre y lo usamos.

Entonces, sabemos lo que queremos, pero necesitamos descubrir cómo podemos hacer el cambio manteniendo el mismo comportamiento y la API compatible. Por supuesto, esto es un desafío. TypeScript es enorme. Entonces, hay más de un cuarto de millón de líneas de código. Y recordarás de antes, un cuarto de millón de líneas de código se cambiaron en mi PR. Y todo esto tendrá que cambiar. También tenemos archivos enormes en general. Entonces, checker.ts tiene casi 50,000 líneas. Entonces, cualquier cosa que tengamos que hacer, cualquier cosa que tengamos necesita poder soportar archivos grandes. Además, TypeScript cambia muy a menudo. Entonces, en el tiempo que me llevó cambiar, trabajar en la migración en sí, hubo más de mil commits en main. Estos no son como fusiones fusionadas o algo así, son ramas de las personas. Estos son literalmente mil y 100 PR que se fusionaron en main. Y cualquiera de estos cambios invalida el cambio completo. Eso es un promedio de cinco commits todos los días laborables. Entonces, lo que sea que hagamos también necesita poder manejar cambios frecuentes y permitirnos iterar y trabajar en el problema. Obviamente, no vamos a hacer este cambio a mano. Vamos a automatizar tanto como sea posible. Eso significa usar la transformación de código siempre que sea posible. También vamos a usar git para almacenar cambios manuales. Y vamos a hacer todo en pasos. Esto nos ayudará a depurar cada paso individualmente. Podremos revisarlos, lo cual es importante cuando estás cambiando mucho código. Y también podremos mantener el git blame funcionando, lo cual es realmente importante para nosotros, ya que nos gusta retroceder y descubrir cuándo cambió algo. La herramienta de migración en sí parece ser TS Morph para la transformación de código. Esta es una gran envoltura de API de TypeScript hecha por David Sherratt. Es genial para hacer transformaciones de TS a TS. Cuando comencé, estaba usando el propio sistema de transformación de TypeScript. Pero es realmente bueno. Es más adecuado para

emitiendo archivos JS o archivos DTS. No necesariamente conserva cosas como el formato, la indentación, etc. Y así, la biblioteca TS Morph, a costa de un poco de rendimiento, pudo capturar todas esas cosas y permitirnos realizar la transformación sin romper todo nuestro formato. También vamos a almacenar todos nuestros cambios manuales en archivos de parche. Entonces, git, obviamente, es realmente bueno para gestionar cambios. Y así, podemos hacer los cambios en el árbol y luego volcarlos al disco. Luego, más tarde, cuando queramos traerlos de vuelta, simplemente podemos usar git am. Y debido a que am es como un rebase, si uno de los parches no se aplica, se

pausa, y podemos solucionar el problema y guardar los cambios para más tarde. Ahora, si quieres ver una demostración de cómo se veía la migración del módulo en sí en el momento en que la ejecuté en el día, hay una demostración a continuación. Tarda unos cinco minutos aproximadamente. Pero vamos a echar un vistazo al código de transformación real en sí. El primer paso es un poco tonto. Pero si lo piensas, cuando escribes código usando modules, todo tu código está en el nivel superior. Pero cuando escribes tu código usando espacios de nombres, todo tu código está dentro del bloque de espacio de nombres en sí. Eventualmente, tendremos que sacar todo el código de nuestro espacio de nombres TS y llevarlo al nivel superior. Entonces, cualquier cambio que haga eso básicamente cambiará todo el espacio en blanco de todas las líneas de código. Si lo hacemos temprano, Git entenderá lo que hemos hecho. También facilitará la revisión de los cambios. Así que el primer paso que vamos a dar es simplemente hacer que el estilo se vea mal, tomar nuestro código, desindentarlo en un nivel y pegarlo al principio.

El siguiente paso es hacer todos nuestros accesos al espacio de nombres explícitos. Así que, como vimos antes, cuando queríamos acceder al espacio de nombres TS pero en un archivo diferente potencialmente, no teníamos que agregar 'TS punto' a nuestros accesos, pero este paso agrega el 'TS punto'. Más adelante verás por qué esto es importante, pero podremos ver más fácilmente dónde se utilizan todos nuestros espacios de nombres dentro del archivo si lo hacemos ahora. El tercer paso es el más importante. Este es el que realmente saca todo el código de los espacios de nombres y lo coloca en el ámbito externo, y luego agrega importaciones. Dado nuestro código, que se ve así ahora, que está desindentado, tiene el 'TS punto', vamos a sacar todo el código del bloque y pegarlo en el nivel superior y luego agregar una importación, y verás que si agregamos una diferencia aquí, los únicos cambios en el archivo son exactamente esos, solo agregar la nueva importación y eliminar el espacio de nombres.

Ahora, probablemente te estés preguntando qué es esto de los espacios de nombres. Esto es una forma de emular nuestra antigua API. El truco es que dentro de un módulo, digamos, TS punto TS, podemos exportar todos los archivos que solían exportar el espacio de nombres TS. Y luego, cuando alguien importa ese módulo, la vista en el archivo que ven es exactamente lo que esos archivos solían declarar antes para el espacio de nombres TS. En el mundo de JS, esto se conoce comúnmente como un módulo de barril. Así que simplemente voy a llamar a estos barriles de espacio de nombres barriles para mantener la consistencia. Ahora, los barriles de espacio de nombres pueden emular todos los comportamientos que solían tener los espacios de nombres. Por ejemplo, si queremos declarar un espacio de nombres anidado, por ejemplo, hay TS punto performance, podemos crear un archivo que contenga las exportaciones del espacio de nombres TS performance y luego volver a exportarlas a través del barril de espacio de nombres TS. Si queremos combinar muchos barriles de espacio de nombres diferentes como lo haría prepend, eso es lo mismo que exportar todos ellos a través de un solo módulo. Y luego, más tarde, cuando queramos exportar nuestro código, simplemente podemos importar ese barril de espacio de nombres TS y luego exportarlo como nuestra API pública. Es exactamente la misma API. En resumen, después del tercer paso, nos quedan estas importaciones de espacios de nombres. Así que puedes ver que importamos TS desde el espacio de nombres TS, y nuestro código contiene el 'TS punto'.

Lo que este último paso hará es tomar todos esos nombres explícitos de TS con puntos y convertirlos en importaciones con nombre. Entonces, esto se acerca mucho más a lo que realmente queremos al final del día. De hecho, si tomas el código y lo comparas con el estado original, lo único que habrá cambiado es la línea de importación en sí. El código a continuación es idéntico.

En este punto, el trabajo tedioso está hecho. Pero aún no hemos terminado, porque hay muchos cambios manuales que debemos hacer después de la transformación masiva. De hecho, hubo 29 commits. Obviamente, esto es un poco preocupante, ¿verdad? Porque cualquier cambio aguas arriba podría romper cualquiera de nuestras correcciones y tendríamos problemas. Pero afortunadamente, estábamos utilizando Git para gestionar esto. Entonces, cuando le pedimos a Git que aplique todos estos parches, nos dirá que el parche no se aplicó, ¿puedes solucionar el problema? Y luego continuamos con el rebase. Y luego le pedimos que muestre los parches. Los parches se almacenan con la herramienta de transformación, por lo que cuando llegue el momento, podemos ejecutar la herramienta y funciona.

Ahora, obviamente hay 29 cambios manuales, así que no puedo revisarlos todos. Pero hay algunos realmente interesantes. Primero que nada, estamos agrupando TypeScript usando ESBuild. Por diversas razones, TypeScript todavía quería enviar todo su código como estos grandes archivos agrupados. Antes, vimos que se producía mediante outfile y prepend, así que si queremos recrear esos mismos archivos en el nuevo TypeScript con módulos, necesitamos usar algún tipo de agrupador. Hay muchos agrupadores disponibles, no voy a intentar enumerarlos todos, pero elegí ESBuild. Obviamente, es muy, muy rápido, por lo que 200 milisegundos para construir TSC es realmente bueno. También tiene muchas características realmente geniales, como scope hoisting, que saca todo el código de los módulos de las personas y los lleva al nivel superior para que no tengas que hacerlo indirectamente. Hay tree shaking, que elimina el código muerto, y luego enum inlining. Entonces, cuando declaramos nuestros enums en nuestro compilador, se inyectan y se propagan por todo el código para que sea más rápido y no tenga que pasar por una búsqueda de objetos.

Ahora, obviamente, dependemos de un proyecto externo para agrupar nuestro código, y solo para asegurarnos de que aún podamos ejecutarnos en el trabajo, nuestra compilación tiene un modo alternativo llamado nobundle, y nos aseguramos de que podamos emitir todo nuestro código como common.js y que siga funcionando. Ahora, debido a que estamos utilizando esbuild para agrupar, no hay nadie que pueda agrupar los archivos DTS. Así que terminé creando mi propio agrupador DTS. Son alrededor de 400 líneas de código. Hay muchos otros agrupadores DTS disponibles, API extractor, TS up, rollup plugins, etc. Y todos son buenos a su manera, pero para nosotros, solo necesitábamos un subconjunto muy pequeño de las características. Específicamente, debido a que estábamos utilizando espacios de nombres, no teníamos conflictos de nombres. Por lo tanto, pudimos usar nuestro propio agrupador personalizado para ir un poco más rápido, pero también producir una salida que se parece mucho a nuestra salida anterior.

y así las personas no sabrán que algo ha cambiado, pero las cosas funcionarán exactamente como antes. Esta también fue una gran oportunidad para cambiar por completo nuestra compilación.

Entonces, anteriormente, nuestra antigua compilación era Gulp. Creo que hace muchos, muchos años, era Jake. Pero se había vuelto algo complicada, diría yo. Y cuando estamos usando modules, todos nuestros pasos de compilación son completamente diferentes. Y, por lo tanto, fue realmente difícil para mí tratar de superponer la nueva compilación sobre la antigua y hacer que funcione nuevamente.

Entonces, al igual que con lo anterior, creé mi propio gestor de tareas. Este tiene alrededor de 500 líneas de código. Simplemente funciona en base a funciones normales, exportaciones. Y se ejecuta todo en paralelo si es posible. Tiene dependencias explícitas, como make. Y ayuda a que nuestra compilación sea más rápida con menos dependencias. Si quieres buscarlo, se llama Hereby. No creo que debas usarlo. Está completo en cuanto a características en este punto. Pero algunas personas audaces lo han utilizado. Así que puedes echarle un vistazo si quieres.

Lo logramos. ¿Cómo resultó? Bueno, fue genial. Para los usuarios de TypeScript, hubo muchos beneficios importantes. Vimos una mejora de velocidad del 10% al 20% solo con el scope hoisting de ESBuild. Eso es realmente genial. Algunas personas instalaron TypeScript 5.0 y obtuvieron un 20% más de velocidad sin hacer nada. También obtuvimos una gran reducción en el tamaño del paquete proveniente de diversas fuentes diferentes. Pudimos eliminar el paquete de servicios de TypeScript de nuestro paquete. ESBuild también eliminó código muerto en algunos de nuestros paquetes. Y curiosamente, ESBuild tiene una sangría de dos espacios codificada, mientras que TypeScript tiene una sangría de cuatro espacios codificada. Y esa sangría de dos espacios tiene un impacto significativo en el tamaño en disco. Además, el cambio no tuvo ningún impacto en la API para los usuarios finales.

Ahora, para el equipo de TypeScript, obtuvimos un gran impulso en el ciclo de desarrollo. Porque estamos usando ESBuild, lo que podemos hacer es ejecutar el paso de ESBuild y luego depurar una prueba al instante. Además, pudimos realizar pruebas internas, que era la razón original por la que queríamos hacer este cambio en primer lugar. Así que encontramos de inmediato algunos errores de autoimportación y los corregimos. También ha surgido un esfuerzo para intentar mejorar la organización de importaciones de TS, más similar a las herramientas del ecosistema. También hemos podido desaprobar la función pre-penned, que se eliminará en TS 5.5. Así que hay muchas cosas emocionantes de las que hablar para el futuro. Pero aquí hay algunos aspectos destacados que creo que son interesantes. Aún tenemos los barriles de espacios de nombres, sería bueno deshacernos de ellos de alguna manera. Ayudan a solucionar los ciclos en nuestro código base, pero tenemos algunas solicitudes de extracción que ayudarán a solucionar esos ciclos también. Y sería bueno poder limpiar eso. También estamos investigando formas en las que podamos enviar ESM. Por ejemplo, estoy bastante seguro de que podemos hacer esto para nuestros ejecutables. Entonces, TSC y TS-server, nadie los importa. Entonces, si se convierten en ESM, probablemente sea lo mismo. Y si hacemos eso, también podríamos ofrecer una API de ESM de forma gratuita porque todo el código está cubierto por esos dos binarios. También nos gustaría desenredar las cosas. Sabemos que hay una gran demanda de personas que solo quieren nuestro analizador, por ejemplo. Y así, las personas tienen que hacer cosas divertidas para tratar de eliminar todo el código muerto de nuestro paquete. Y podríamos hacer eso si pudiéramos limpiar nuestro código y eliminar los ciclos, tal vez hacer una API de ESM. También hemos pensado en hacer minificación u otras optimizaciones. Aunque eso es bastante desafiante porque tenemos personas que nos parchean aguas abajo. Por ejemplo, Yarn o TSPatch. Pero tenemos la esperanza de que tal vez haya una forma de hacerlo. En cualquier caso, hay muchas cosas emocionantes por delante. Con eso, gracias por ver. Siéntete libre de visitar mi sitio web, jakebailey.dev. Si quieres ver las diapositivas, tengo un enlace a continuación junto con un montón de otros enlaces a otras cosas geniales de migración. Gracias. Adiós.