Generando TypeScript con TypeScript

Hola a todos. Bienvenidos a mi charla sobre cómo generamos automáticamente definiciones de TypeScript para los workers de CloudFlare usando TypeScript. Como introducción rápida, soy Brendan. Creé MiniFlare, un simulador completamente local para los workers de CloudFlare. Ya mencioné los workers de CloudFlare varias veces, pero ¿qué son? Los workers son una plataforma de funciones como servicio. Escribes un código de manejo de HTTP, lo publicas en nuestra plataforma y te damos una URL a la que puedes acceder para ejecutarlo. Desplegamos tu código en todas las ubicaciones de borde de CloudFlare para que tus usuarios tengan acceso de baja latencia donde sea que estén. Importante, prácticamente no hay tiempo de inicio en frío. Debido a que nuestra plataforma de ejecución se basa en aislamientos de V8, no en contenedores o máquinas virtuales. Además de las API web estándar, proporcionamos API no estándar para almacenamiento de clave-valor. Los puntos clave que tenemos hasta ahora son tiempo de ejecución personalizado basado en V8, como Node o Dino. Implementamos principalmente API web estándar como los navegadores, pero también implementamos algunas API no estándar específicamente para casos de uso en el lado del servidor. Con todo esto en mente, ¿por qué queremos tipos? Queremos verificación de tipos para prevenir errores en tiempo de ejecución y queremos autocompletado en los IDE. Para empezar, cubriremos cómo solíamos hacer tipos escritos a mano hace un par de años, luego veremos nuestro enfoque de generación automática utilizando información de tipo en tiempo de ejecución. Después de eso, veremos algunas transformaciones que podemos hacer para mejorar otros tipos, y luego nos centraremos en cómo permitimos anulaciones de tipo manuales para mejorar la ergonomía del desarrollador. Y finalmente, echaremos un vistazo rápido a las fechas de compatibilidad.

En primer lugar, cómo hacíamos los tipos hace unos años. Al igual que la mayoría de las plataformas de ejecución, teníamos un paquete npm que proporcionaba tipos globales para nuestra plataforma de ejecución. Es importante destacar que este paquete solo incluía API específicas de CloudFlare, como el reescritor de HTML, y no estándares web. Había varios problemas con este enfoque. En primer lugar, estos tipos eran escritos a mano, lo que los hacía propensos a errores al actualizarlos. En segundo lugar, estos tipos no eran actualizados típicamente por el equipo que implementaba la plataforma de ejecución, lo que los hacía lentos para actualizarse con nuevas API. A la derecha, tenemos un ejemplo de un error de tipo al usar una nueva API, aunque ese código debería funcionar bien en Rutgers. Sin embargo, el mayor problema estaba en nuestra dependencia de libwebworker. Esto incluía API como message channel, que no implementamos, lo que significa que el código que pasaba la verificación de tipos no se ejecutaría en nuestra plataforma de ejecución. Y en ese momento, los workers no cumplían completamente con las especificaciones. También nos faltaban API experimentales que habíamos implementado. Así que aquí hay algunos problemas. Ahora que hemos visto todos los problemas, ¿qué debemos hacer al respecto? La plataforma de ejecución de workers proporciona un sistema de información de tipo en tiempo de ejecución. Esto nos permite consultar tipos en tiempo de ejecución y originalmente se usaba para la automatización

fuzz testing. La información de tipo en tiempo de ejecución se codifica como cap y proto, que utilizamos como un formato binario independiente del lenguaje y la plataforma, algo así como los protocol buffers si los has utilizado antes. Básicamente, es una versión tipada de JSON. Este es nuestro esquema cap y proto para la información de tipo. Puedes ver que esto se mapea a los tipos de TypeScript. Lo realmente bueno de cap y proto es que puede generar el código de codificación y decodificacióncode por ti a partir de tu esquema para muchos lenguajes diferentes. Es importante destacar que esto significa que no tenemos que implementar todas las etapas del proceso de generación automática en el mismo lenguaje. Podemos codificar todos los tipos de API en tiempo de ejecución en C++ y realizar un procesamiento adicional en TypeScript. Esto nos permite utilizar la API del compilador de TypeScript para renderizar TypeScript. Lo que queremos hacer es construir el nosotros mismos a partir de la información de tipo en tiempo de ejecución. Intentaremos construir la interfaz que acabamos de ver. Comenzaremos desde la parte inferior del árbol, por lo que comenzaremos con el parámetro clave para el método get, luego construiremos el tipo de retorno del método get y el propio método, luego construiremos la interfaz que contiene el método get, luego crearemos un archivo de origen de marcador de posición y un impresor para que podamos imprimir la interfaz en una cadena y registrarla en la console. Si ejecutamos eso, obtenemos lo que esperábamos. Todo eso por tres líneas de TypeScript, esto es una API muy detallada, pero con un poco más de trabajo para convertir los tipos cap y proto en TypeScript, tenemos tipos generados automáticamente. Esto prácticamente resuelve todos nuestros problemas anteriores. Tenemos exactamente las API que se implementaron en tiempo de ejecución con las diferencias menores de especificación. Pero los tipos aún no son perfectos. Por ejemplo, los iteradores no tienen valores con tipos correctos, no podemos usar funciones o constantes globales y no tenemos sobrecargas de funciones, por lo que TypeScript no puede estrechar los tipos de retorno dados los argumentos. Afortunadamente, toda la información que necesitamos para solucionar estos problemas ya está en los tipos. Lo que necesitamos hacer es transformarlos en una forma que TypeScript reconozca. Comenzaremos arreglando los iteradores. Así es como se ven nuestros tipos en este momento. Queremos usar el tipo de iterador iterable incorporado de TypeScript en su lugar, y la transición se ve algo así. Para solucionar los globales, necesitamos extraer los miembros del ámbito global del servicio de trabajador de servicio en el ámbito global, y esto también deberá incluir superclases. Entonces, nuevamente, necesitamos realizar algo como esto. Entonces, ¿cómo lo hacemos realmente? Veamos un ejemplo más simple. Digamos que queremos reemplazar todas las cadenas por números. Podemos escribir un transformador de TypeScript para esto que visite recursivamente todos los nodos. Si encontramos un token de cadena, lo reemplazamos por un número. Luego podemos usar la API de transformación de TS para aplicar esto a un nodo AST. Comenzamos en la declaración del espacio de nombres KV raíz, y hacemos un recorrido en profundidad

Primero, buscamos hasta encontrar una cadena. Cuando lo hacemos, lo reemplazamos por un número, y seguimos hasta que todos los nodos hayan sido reemplazados. Aplicar esta técnica a nuestras otras transformaciones nos permite solucionar los dos primeros problemas, por lo que los iteradores ahora tienen el tipo correcto y podemos usar funciones y constantes globales. Para las sobrecargas, necesitamos algo un poco más complicado. Lo que queremos en nuestros tipos de TypeScript es algo como esto, donde tenemos una correspondencia entre los tipos de entrada y salida. Por ejemplo, cuando especificamos texto, esperamos una cadena. Cuando especificamos un búfer de rayos, esperamos un búfer de matriz, y así sucesivamente. El problema es que en el código C++ para los espacios de nombres KV, no hay correspondencia entre el tipo de entrada y el resultado de salida. ¿Cómo sabemos qué generar? Necesitamos aportes adicionales de los humanos aquí. Hay otros lugares donde también necesitamos aportes humanos, para mejorar la ergonomía del desarrollador. Como ya hemos visto, necesitamos esta función para las sobrecargas de funciones. También necesitamos aportes adicionales para agregar parámetros de tipo. A veces quieres renombrar los tipos para que sean menos verbosos, a veces quieres reemplazar la definición generada automáticamente con algo diferente, y a veces quieres ocultar el tipo porque no debería ser expuesto a los usuarios finales. Resolvemos esto permitiendo que se inserte código TypeScript parcial junto con el código C++. Esto se codifica con la información de tipo en tiempo de ejecución en cap y proto, y fusionamos esto con la definición generada. Podemos usar esto para todos los casos que hemos resaltado, y debido a que estamos colocando las anulaciones junto con el código C++, es mucho más fácil para los desarrolladores de tiempo de ejecución agregarlos y mantenerlos actualizados. Con eso, hemos resuelto todos los problemas anteriores y tenemos un conjunto sólido de definiciones de tipo para los workers. Pero hay una cosa más que podemos hacer para mejorarlos aún más. A veces las personas cometen errores. Los desarrolladores no son diferentes y a veces introducimos errores en nuestro código. A veces, corregir esos errores introduciría cambios de comportamiento disruptivos, pero no queremos romper el código existente implementado. Entonces, cuando cargas tu código de worker, debes especificar una fecha de compatibilidad. Ponemos los cambios disruptivos detrás de una bandera de compatibilidad que tiene una fecha en la que se habilitan de forma predeterminada. Si la fecha de compatibilidad de tu worker es posterior a la fecha predeterminada de una bandera, entonces esa bandera se habilitará. El problema es que algunas banderas cambian la superficie de la API pública y, por lo tanto, los tipos de TypeScript. Por ejemplo, la bandera global navigator agrega una nueva constante navigator al ámbito global. Actualmente hay 41 banderas de compatibilidad, aunque no todas ellas cambian la superficie de los tipos, pero si generamos una versión de los tipos para todas las combinaciones posibles de banderas, terminamos con 2 billones de archivos de definición de tipo, lo cual es inviable. En su lugar, nuestra solución en este momento es generar un punto de entrada de los tipos para cada fecha de compatibilidad que cambie la superficie de la API pública. Esto no resuelve completamente el problema, ya que los usuarios aún pueden habilitar y deshabilitar selectivamente las banderas. Lo que estamos planeando hacer es construir Types as a Service, que será un worker de Cloudflare que genera dinámicamente paquetes NPM que contienen archivos de definición de TypeScript basados en la fecha de compatibilidad y las banderas seleccionadas. Así que te animo a probar los workers de Cloudflare si aún no lo has hecho. Puedes encontrar todos los scripts de TypeJet Reclamation en el repositorio de GitHub de Cloudflare WorkerD y encontrarme en GitHub y Twitter. Muchas gracias por escuchar.