El Camino hacia TypeScript Nativo

Bienvenidos, a todos. Estoy muy feliz de dar esta masterclass aquí en Node Congress. Hoy hablaré sobre el camino hacia TypeScript nativo, cómo Node.js y TypeScript han trabajado juntos para traer esta nueva integración en Node.js.

Permítanme presentarme. Mi nombre es Marco Ippolito. Soy ingeniero de seguridad senior en Herodas y miembro del Comité de Dirección Técnica de Node.js.

Así que comenzaremos con un poco de historia, cómo y por qué decidimos apoyar TypeScript y qué ha cambiado en los últimos años. Así que comenzaremos con este gráfico. Este es el estado de JS 2016, hace casi 10 años. Y podemos ver que TypeScript estaba justo al principio, no era muy popular. De hecho, el 34% de los encuestados, habían oído de TypeScript, pero no estaban interesados en ello. Y solo una pequeña fracción estaba realmente interesada y lo había usado y lo usaría de nuevo. También podemos ver algunos otros nombres que han desaparecido de la escena del desarrollo web, como CoffeeScript, Elm y ClosureScript, pero eran bastante populares en ese momento. Y ahora podemos ver el estado más reciente de JS, que es el 2023. En este gráfico, podemos ver que casi todos los desarrolladores que respondieron, que son 17,000, usan TypeScript solo el 32%. Y solo el 9% de los encuestados usan JavaScript. Así que la mayoría de los usuarios usan TypeScript en diferentes porcentajes, pero todos lo hacen. Y es una locura pensar que hace 10 años, esto era muy de nicho. Y hoy, como todos usan TypeScript. Es una de las tecnologías más populares. Esta es la encuesta de Stack Overflow 2023. Y podemos ver que TypeScript es el quinto lenguaje de programación más popular. Así que hoy veremos por qué Node.js no lo ha integrado hace años y esto solo ha sucedido ahora. Otro dato muy importante son las descargas de NPM. TypeScript tiene alrededor de 12 millones de descargas por día. Es uno de los paquetes más descargados en NPM. Así que hoy veremos cómo TypeScript es compatible en Node.js.

Pero hablemos un poco sobre la historia. Como mantenedor de Node.js, siempre he visto problemas, discusiones, PRs de usuarios que quieren soporte nativo para TypeScript. Como pueden ver, hay múltiples problemas y ha habido tantas propuestas sobre cómo implementar TypeScript en Node.js, pero nunca sucedió hasta recientemente.

Y hay razones por las cuales la implementación no es sencilla. Uno de los primeros desafíos es que es muy difícil obtener consenso, siendo Node.js un proyecto dirigido por voluntarios y gobernanza abierta. Es muy difícil hacer que todos estén de acuerdo sobre lo que significa soportar TypeScript y cómo debería hacerse. Ha habido intentos en el pasado en 2023, hubo una discusión en la Cumbre de Colaboradores en Bilbao, pero la discusión, eventualmente se desvaneció. Así que no sucedió.

Existen diferentes garantías de estabilidad entre Node.js y TypeScript. TypeScript no sigue SEMVer. Así que significa que cada actualización menor tiene cambios disruptivos mientras que Node.js tiene fuertes garantías de seguridad. Así que hay una nueva, como una versión LTS de Node que dura tres años. Así que no es posible fijar una versión específica de TypeScript durante tres años. Y esta gran diferencia entre los dos, entre Node y TypeScript hace que sea difícil integrarlo. Node.js no soporta un archivo de configuración y por lo tanto no soporta TSConfig. Tener Node soportando TSConfig sería raro. Y es algo que no obtendría consenso porque en primer lugar, Node no tiene su propio archivo de configuración. Así que, ¿por qué debería soportar el archivo de configuración de otro proyecto o dependencia de Node.js, que es la razón por la cual Node no soporta TSConfig?

Es muy difícil elegir una herramienta que funcione de inmediato. Como dijimos, no podemos usar TypeScript como un paquete de NPM. Necesitamos usar algo más. La razón por la cual no podemos usar TypeScript es porque es un paquete de NPM muy grande. Es un paquete de 24 megabytes. Está escrito en JavaScript y sería muy difícil integrarlo y sin mencionar las garantías de estabilidad de las que hablamos antes. Así que no hay una sola herramienta que se ajuste al caso de uso de Node y por lo tanto es muy difícil elegir. En el pasado, hubo muchos problemas entre la interoperabilidad de CommonJS y ESM. Así que hasta que esos se solucionaran, habría sido una característica a medio hacer integrar TypeScript. Pero ahora esos finalmente están solucionados. Y así tuvimos la oportunidad de soportar TypeScript. Los mapas de origen. Así que cada vez que transpiles tu código, cambias la posición de tu código dentro del archivo al transformar TypeScript en JavaScript. Así que necesitarías mapas de origen para poder depurar efectivamente y reconstruir la ubicación de todo en tu código fuente. Pero los mapas de origen añaden mucha sobrecarga.

Y si los habilitas, los habilitas globalmente, lo que significa que también estarían habilitados para tu JavaScript. Este es un gran problema porque sería un cambio disruptivo. Y finalmente, no hay campeón. Significa que nadie quería hacer este trabajo de tener, como implementar la característica y hacer que todos estuvieran de acuerdo. Bueno, yo sí defendí esta iniciativa, así que comencé a trabajar en esto en julio de 2024 y la forma en que elegí implementar TypeScript se llama TypeStripping.

Así que la forma en que implementé TypeScript es no hacer verificación de tipos, solo transpilación. La razón es que la verificación de tipos es la parte más inestable de TypeScript y no hay especificación. Así que la única forma de realizar la verificación de tipos es a través del paquete NPM de TypeScript. Así que esperamos que los usuarios descarguen este paquete de forma independiente para que puedan actualizar sus versiones de forma independiente. Ellos pueden configurar su TSConfig sin que el tiempo de ejecución proporcione valores predeterminados. Y el problema también es que la verificación de tipos no es algo que quieras. No es algo que hagas durante tu ciclo de desarrollo. Solo lo haces durante CI o cada vez que terminas de desarrollar tu característica. Así que ya tienes tu IDE que te muestra cada vez que hay errores en los tipos. Así que esto no era algo que quisiéramos proporcionar como un tiempo de ejecución.

Además, dado que no queremos soportar un TSConfig, esta técnica de TypeStripping no involucra TSConfig. TypeStripping, lo que hace es básicamente eliminar todo de TypeScript que no sea JavaScript. Y si el resultado es JavaScript válido, lo ejecutará. No necesita un TSConfig porque todas las características de TypeScript son eliminadas. Y esto es exactamente lo que hace. Elimina tipos en línea. No todo es un tipo en línea, así que veremos eso un poco más tarde, cómo funciona y cuáles son los problemas que surgen de TypeStripping. Pero imagina que defines una variable que es una cadena. Esa pequeña parte de cadena se puede eliminar de forma segura porque no afecta al tiempo de ejecución. No requiere mapas de origen. Usamos un pequeño truco mágico para evitar cambiar la ubicación dentro del archivo durante la transpilación. Así que esta solución no requiere mapas de origen, lo que significa que la posición en el archivo es uno a uno con donde escribes, se ejecutará. Y TypeStripping es estable a través de las versiones de TypeScript porque la verificación de tipos es altamente inestable, pero la transpilación es bastante estable. No cambia mucho. TypeScript no ha añadido nuevas palabras clave en un tiempo, así que es bastante seguro.

Hablamos con el equipo de TypeScript y nos aseguraron de esta estabilidad. Así que ¿cómo funciona TypeStripping? Podemos imaginar que este es un código de TypeScript, podemos simplemente tomar una goma y borrar todo. Así que las interfaces no son parte de JavaScript. Podemos borrarlas. Este es un tipo en línea. Podemos borrarlo porque no es parte de JavaScript. Así que el resultado final se ve así. Este es JavaScript válido. Así que esto es algo que node puede ejecutar.

El problema es que esto requiere mapas de origen porque hemos cambiado la posición dentro del archivo. Pero si reemplazamos la sintaxis que hemos eliminado con espacios en blanco, ¿es posible preservar la ubicación original? Así que cada vez que eliminamos tipos en línea, los reemplazamos con espacio en blanco y por lo tanto no necesitamos mapas de origen. Así que para lograr esto, usamos una variante de SWC. SWC estaba en TypeScript. Es un paquete NPM que libera un WASM web assembly. Así que Node.js construye para muchas plataformas diferentes y tener WASMs nos permite soportar todas las diferentes plataformas que de otro modo un proyecto de Rust no soportaría porque Rust se construye en diferentes plataformas que Node.js.

Así que necesitábamos algo compatible con todo. Es probado en batalla porque es utilizado por muchos proyectos populares en el ecosistema, RSpark, Deno y tantos proyectos usan SWC. Soporta el stripping de tipos. Así que nos permite hacer lo que hablamos antes. Es muy rápido y los mantenedores son increíbles. Ellos nos ayudaron mucho. Ellos pudieron enviar estas versiones personalizadas de SWC en días desde que comenzamos a trabajar en TypeScript y esto nos ayudó mucho. Así que un gran saludo a los mantenedores de SWC. Decidimos envolver SWC en un paquete llamado Amaro. Así que esto permite a los usuarios actualizar sus versiones de TypeScript y Spiler de forma independiente. Así que puedes usar Amaro como un cargador externo y esto te permite no estar atascado en una versión de TypeScript. Pero si TypeScript lanza nuevas características, Amaro será actualizado. Puedes usar Amaro independientemente de la versión utilizada dentro de Node. Así que esta es la razón por la que envolvimos en un paquete. Así que en julio del año pasado, abrí este PR para soportar tipos de stripping experimentales.

Este PR se completó en 20 días, lo cual es muy rápido considerando el tiempo de Node.js, lo que fue genial. Así que en Node 22.6, lanzamos esta nueva bandera experimental llamada Experimental Strip Types. Tiene algunas limitaciones. Así que solo podemos soportar características que pueden ser borradas. No todas las características de TypeScript pueden ser borradas. Algunas de ellas, por ejemplo, los namespaces y enums requieren ser transformados en JavaScript porque sí afectan el tiempo de ejecución. Por ejemplo, este es un namespace y exporta una función, los enums exportan algunos valores. Estos no son solo tipos. Estos son valores y no pueden ser borrados. Así que si tu namespace exporta solo tipos desde Node 23.8, pueden ser soportados. Pero si exportan valores que afectan los tiempos de ejecución, no pueden ser soportados. Ellos lanzarán un error durante la traducción. Pero para superar este obstáculo, creamos una nueva bandera llamada Experimental Transform Types. Esto te permite consumir toda la sintaxis de TypeScript. Así que esto requiere que los mapas de origen estén habilitados, pero puedes usar enums, puedes usar namespaces, puedes usar toda la sintaxis de TypeScript que desees a costa de tener los mapas de origen habilitados.

Por ejemplo, esto es lo que namespace y enum lucen en JavaScript. Así que hay una generación de código desde TypeScript a JavaScript. Y por defecto, queremos evitar este tipo de generaciones de código. Además, las rutas personalizadas no son soportadas. Porque requiere configuración de TS, pero puedes usar importaciones de subruta de Node.js que son soportadas y hacen exactamente lo mismo. Así que puedes usarlas para aliasar una ruta específica dentro de tu proyecto.

Así que la primera limitación, como dije, son las características que requieren transformación. No realizamos degradación, lo que significa que si es una sintaxis que va a ser soportada por el motor de JavaScript, por ejemplo, decoradores o gestión de recursos explícita, el compilador de TypeScript no realizará la transpilación de esos porque eventualmente serán soportados en una nueva versión de Node.js. Así que el keyword using, no será transpilado, no será degradado a JavaScript que sea compatible. Así que se quedará ahí. Y si el motor de JavaScript lo soporta, será posible ejecutarlo. De lo contrario, lanzará un error de sintaxis. Lo mismo para los decoradores. Ellos llegarán pronto al lenguaje. Así que no había razón para polyfill el comportamiento de los decoradores.

Otra limitación es que debes ser explícito cuando importas un archivo. Si es un archivo de TypeScript, necesitas usar la extensión .ts. De lo contrario, necesitas usar la .js extensión. En el pasado en TypeScript, siempre teníamos que usar la extensión .javascript al importar un archivo porque ese archivo sería transpilado a JavaScript. Pero en tiempo de ejecución, ese archivo es un archivo de TypeScript. Así que necesitamos ser explícitos. En el pasado, ya podías usar la extensión .ts en TypeScript, pero no podías transpilarlo. Solo podías usarlo en combinación con la bandera noemit. Este comportamiento ha cambiado desde TypeScript 5.7. Una nueva característica llamada reescritura de rutas para rutas relativas fue desarrollada por el equipo de TypeScript específicamente para soportar los tipos de stripping experimentales de Node.js. Así que con esta nueva bandera, durante la transpilación, reescribirá las extensiones para que coincidan con el destino. Así que cada vez que transpiles un archivo .ts, se convertirá en un archivo .js, y eso coincidirá. Pero ¿qué pasa con el código fuente existente? Así que es posible con un modo de código migrar la base de código existente para soportar este comportamiento que Node.js impone. Puedes usar este modo de código llamado correct-yes-specifiers por Jacob, uno de los colaboradores de Node.js. Transformará toda la sintaxis, todas las importaciones que no son soportadas en importaciones que son soportadas.

Este es un trabajo en progreso, así que puedes leer más sobre esto en NPM.

Otra limitación importante es que se requiere la palabra clave type para las importaciones de tipo. Así que cada vez que importes un tipo, necesitas especificar que eso es un tipo. Por ejemplo, en el primer caso, importamos type 1 y 2. Usamos la palabra clave type. Si no la usamos, Node.js pensará que eso es un valor y no un tipo, así que no lo borrará. Mientras que si es un tipo, se puede borrar de forma segura, y causará un error en tiempo de ejecución.

Además, una limitación importante es que no es posible ejecutar archivos TypeScript en módulos de Node. Esto es para evitar interrumpir el ecosistema porque al publicar TypeScript, crearía muchas incompatibilidades. Así que si alguna vez intentas ejecutar un archivo TypeScript dentro de los módulos de Node, lanzamos un error llamado módulos de Node no soportados TypeScript. La razón por la cual esto fue específicamente impuesto por el equipo de TypeScript es porque causaría muchas versiones de compatibilidad, y tu IDE realizaría verificaciones de tipo en los módulos de Node y sabemos cuán grandes son los módulos de Node, así que no queremos hacer esto. En Node 23.6, habilitamos tipos de strip experimentales por defecto. Así que puedes ejecutar Node file.ts por defecto sin pasar ninguna bandera.

Además, hemos trabajado en la detección de sintaxis de TypeScript en Eval. Este es un tema muy interesante. Así que esto es, por ejemplo, podemos ver import util from util, y cost foo es un valor de cadena una palabra. Esta es una cadena ESM de TypeScript. Así que Node.js intenta evaluar si la sintaxis es un módulo común JS, que no lo es. Intentará de nuevo como un módulo ES, pero no lo es porque es TypeScript. Así que eso fallará. Si falla, intentará eliminar los tipos, así que intentará transpilar, como eliminar la cadena de esto, el tipo de cadena de punto de esta cadena. Así que foo ahora, esto es JavaScript puro, y esto es JavaScript puro ESM. Así que si esto falla, significa que tienes un error de sintaxis, o la sintaxis no es soportada. Así que lanzará el error del paso dos, más el mensaje del compilador de TypeScript. Esto es para evitar cambios drásticos en el error que se lanza. Y volverá a intentar ejecutar la cadena como un JS común, pero sabemos que es ESM, así que fallará. Y finalmente intentará de nuevo como un módulo ESM que es correcto. Así que puedes ver que la detección de sintaxis es muy complicada. Pero puedes omitir todo este sobrecosto especificando qué tipo de sintaxis es. Así que puedes usar la bandera guion guion input type para decir que este es un módulo TypeScript, o TypeScript común JS, y Node sabrá exactamente qué hacer.

decir que este es un módulo TypeScript, o TypeScript común JS, y Node sabrá exactamente qué hacer. Hay alguna sintaxis que es ambigua. Por ejemplo, fetch object. Esto parece TypeScript, pero esto es válido JavaScript. Si intentas ejecutarlo en Node, devolverá falso. Y si lo intentas en el navegador, también devolvería falso. Esto se debe a que el angular se detecta como menor. Así que es una sintaxis válida de JavaScript. Y hay ambigüedad porque si intentas ejecutar esto en el playground de TS, esto se ejecutará como un fetch. Así que en realidad realizará una llamada HTTP. Si intentas ejecutarlo en Node con el tipo de entrada como TypeScript común JS también realizará un fetch. Así que como puedes ver, la misma sintaxis, si es JavaScript o TypeScript, cambia el comportamiento.

Así que este es un gran problema. TypeScript, en la última versión, anunció una nueva bandera llamada sintaxis solo borrable. Esto coincidirá con el comportamiento de Node.js, así que toda la sintaxis que no es soportada por Node.js lanzará un error en TypeScript cuando verifiques los tipos. Esto es muy bueno porque ahora puedes verificar los tipos y asegurarte de que la sintaxis que estás escribiendo puede ser ejecutada por Node. Esta es la configuración de TypeScript que sugerimos a nuestros usuarios.

Así que todas las banderas de las que hablamos antes. ¿Y cuáles son los próximos pasos? Seguiré corrigiendo errores, trabajaré en hacerlo más rápido y estoy trabajando en marcarlo en Node 22, y espero hacerlo estable en Node 24 que viene en muy pronto. Así que si lo pruebas, puedes unirte a nosotros en el repositorio de Node.js TypeScript. Tenemos reuniones, puedes consultar el calendario de Node.js y eso es todo.