Lecciones de Mantenimiento de Bibliotecas TypeScript

Hola, soy Mark Erickson, y hoy me gustaría hablarles sobre las lecciones que he aprendido manteniendo TypeScript libraries. Un par de cosas rápidas sobre mí. Actualmente soy un Ingeniero Frontend Senior en Replay, donde estamos construyendo un verdadero depurador de viaje en el tiempo para aplicaciones JavaScript. Si no lo has visto, por favor, échale un vistazo. Soy conocido por varias cosas. Soy un respondedor de preguntas. Con gusto responderé preguntas sobre React y Redux en cualquier lugar donde haya un cuadro de texto en internet. Recojo enlaces interesantes a cualquier cosa que parezca potencialmente útil. Escribo entradas de blog extremadamente largas sobre React y Redux, y soy un mantenedor de Redux. Además, también podrías conocerme como ese tipo con el avatar de los Simpsons.

Hoy vamos a hablar sobre las diferentes formas en que las bibliotecas JavaScript pueden usar y soportar TypeScript, cómo abordar la migración de una biblioteca JavaScript a TypeScript, problemas al tratar con los tipos de biblioteca y la versión, y soportar múltiples versiones de TypeScript también, cómo puedes debug y probar tipos, cómo abordar el diseño de APIs para usar con TypeScript, y potencialmente algunas características que facilitarían el uso de TypeScript con bibliotecas.

Entonces, ¿por qué incluso proporcionamos tipos con una biblioteca? Los tipos sirven para varios propósitos. Uno es la documentación de la API. Los usuarios pueden mirar los tipos y entender qué funciones y tipos existen y cómo puedes usarlos en tu aplicación. Otro es la corrección del código del usuario. Pueden hacer cumplir ciertos patrones de uso que los usuarios deben tener en su aplicación fuente de código. Junto con eso, está la corrección del código de la biblioteca. Los tipos nos ayudan a asegurar que el código dentro de nuestra biblioteca se comporta como se espera, y se trata de mantenibilidad, de poder trabajar en el código real dentro de la biblioteca.

Ahora, diré que creo que hay una diferencia distinta entre los tipos que ves dentro del código de la aplicación y los tipos que ves dentro del código de la biblioteca. Los tipos de aplicación tienden a ser bastante simples. Tienes respuestas de la API, argumentos de funciones, estado con el que estás lidiando, componentes props. Por lo general, no es demasiado complicado, y no ves muchos tipos genéricos allí. Los tipos de biblioteca, por otro lado, son mucho más complicados porque necesitan manejar casos de uso mucho más flexibles. Los tipos de biblioteca tienden a tener un uso mucho más pesado de los genéricos de TypeScript. Y a veces, incluso puedes ver programación a nivel de tipo donde estás haciendo inferencias, lógica condicional, y transformaciones complejas de tipos también.

Ahora, hay varias formas en que una biblioteca JavaScript puede proporcionar tipos. El mejor enfoque es si la biblioteca está realmente escrita en TypeScript. Esto garantiza que los tipos coinciden con el comportamiento real de lo que está en el código fuente de la biblioteca, y que los tipos se actualizan cada vez que hay una nueva versión de la lib. Otra opción es escribir el código fuente en JavaScript y escribir a mano las definiciones de tipo e incluirlas en la salida publicada. Esto está bien porque los tipos todavía son mantenidos por los propios dueños de la biblioteca. Pero puedes terminar en situaciones donde hay diferencias entre lo que los tipos dicen que está en la biblioteca y lo que el código fuente realmente hace. Como último recurso, si los mantenedores de la biblioteca no quieren tener sus propios tipos, entonces la comunidad puede juntar algunos tipos y publicarlos en el repositorio Definitely Typed de Microsoft. Esto puede definitivamente llevar a problemas, pero al menos te da una forma de tener tipos, especialmente si los mantenedores de la biblioteca no quieren preocuparse por tratar con eso ellos mismos. Realmente hemos usado todos estos diferentes enfoques con las bibliotecas Redux a lo largo del tiempo. Pero hemos estado trabajando en tratar de migrar las bibliotecas Redux a TypeScript, especialmente en los últimos años. El núcleo de Redux fue convertido a TypeScript en 2019. Simplemente nunca llegamos a publicarlo. La versión 8 de React Redux finalmente se convirtió a TypeScript, y migramos Reselect el año pasado. Entonces, ¿cómo abordas una de estas migraciones? Bueno, el primer paso es configurar alguna infraestructura de construcción. Necesitas asegurarte de que estás compilando los tipos de TypeScript, transformando la salida de la construcción a JavaScript plano, y quieres asegurarte de que tu configuración de pruebas está configurada para lidiar con TypeScript también.

También necesitas asegurarte de que los tipos se incluyen en el paquete publicado directamente. Eso significa agregar una clave de tipos a tu paquete JSON. Y es una buena idea probar realmente la publicación del paquete con alguna aplicación code de TypeScript y asegurarte de que las cosas funcionan como esperas. Y me gusta usar una herramienta llamada Yalk para hacer una publicación local de esto.

Cuando estés listo para convertir el code actual, si hay algún typedef existente, como indefinidamente tipado, te sugiero fuertemente que los uses como punto de partida. Hicimos eso para React Redux. Elige algunos archivos, conviértelos a TypeScript y repite. Y realmente recomiendo tener algunos commits que solo renombren los archivos primero antes de que realmente comiences a hacer cambios en ellos para tratar de preservar el historial de Git existente. Además, no olvides convertir todas tus pruebas a TypeScript. Esto ayudará a detectar algunos de los problemas, y veremos un par de otros ejemplos de esto más adelante. Finalmente, asegúrate de que realmente estás exportando tipos de tu archivo índice, no solo las funciones y las estructuras de data en el code.

Entonces, ¿cómo gestionas el versionado para tipos públicos? Esto es un poco complicado. TypeScript en sí mismo no utiliza el semantic versioning. Simplemente utilizan un enfoque de incremento decimal, y eso significa que cualquier nueva versión de TypeScript podría, de hecho, romper el code que se está ejecutando actualmente. Además de eso, diferentes personas pueden tener diferentes configuraciones de TypeScript, y esas pueden llevar a diferencias en el comportamiento. Una de las cosas más grandes que vemos es que las personas desactivan las banderas de comprobación estricta o nula y esto lleva a un comportamiento de compilación claramente diferente. Realmente, cualquier cambio en tus tipos en absoluto, incluyendo para correcciones de errores, podría resultar en que las aplicaciones de los usuarios fallen al compilar.

Entonces, ¿eso significa que cada vez que lanzo una corrección de errores, esto es en realidad algún tipo de versión mayor? El equipo de Ember ha estado trabajando en tratar de establecer un conjunto de reglas para cómo planean manejar TypeScript en el ecosystem de Ember, y publicaron un RFC increíblemente extenso donde intentaron definir qué significa Sember para los tipos de TypeScript, no solo para Ember, sino un enfoque que cualquier biblioteca puede usar. Y lo que concluyeron es que los tipos son APIs. Deberías factorizar los tipos en tu versionado, pero puedes dividirlo en cambios que se consideran rompedores y cambios que se consideran no rompedores. Y hacen algunas excepciones allí para las correcciones de errores y la intención. Es posible que hagan un cambio que introduzca algunos errores en el code del usuario, pero en realidad está previniendo el mal uso de ciertos patterns en el terreno del usuario. Pero ciertamente su objetivo es que si sigues la lista de versiones soportadas de TypeScript, no deberías ver nuevos errores apareciendo en el code del usuario. Otro problema relacionado es cómo apuntas a versiones específicas de TypeScript. TypeScript saca varias versiones nuevas al año y esas pueden tener nuevas características y funcionalidades bastante importantes. Entonces, ¿cuánto tiempo soportas versiones antiguas de TypeScript? ¿Qué tan pronto puedes adoptar nueva sintaxis y características? ¿Y cómo te acercas a las testing contra múltiples versiones de TypeScript? Vale la pena mencionar que el repositorio Definitely Typed en sí mismo intenta soportar aproximadamente 2 años de versiones de TypeScript. Entonces, diferentes bibliotecas abordan esto de diferentes maneras. Ember ha definido su conjunto de planes de adopción donde han dicho que las bibliotecas centrales de Ember usarán una ventana rodante donde intentarán soportar nuevas versiones de TypeScript de inmediato y dejarán de soportar versiones antiguas en versiones de soporte a largo plazo de Ember. Otras bibliotecas de Ember podrían simplemente elegir un par de versiones. Y cada vez que dejan una versión se considera un lanzamiento mayor de esa biblioteca.

El grupo Stately, por otro lado, ha dicho que nos reservamos el derecho de hacer cambios en nuestro soporte para TypeScript a medida que nuestra comprensión de TypeScript y su comportamiento evoluciona con el tiempo. Entonces, ¿cómo puedes soportar múltiples versiones de TypeScript? Lo más importante que veo aquí es configurar tu CI para construir tus pruebas y tu aplicación y probarlas contra múltiples versiones de TypeScript a la vez. Esto se puede hacer utilizando algo como el soporte de Matrix en GitHub Actions. También podría ser útil usar una versión más antigua de TypeScript mientras realmente estás desarrollando en la biblioteca porque esto te obliga a restringirte a qué sintaxis puedes usar.

Como los tipos son code, eso significa que tienen errores, y los usuarios informarán muchos y muchos problemas con los tipos de TypeScript. Y eso significa que necesitamos que los usuarios proporcionen reproducciones de esos problemas, y esto es especialmente cierto porque diferentes usuarios pueden tener diferentes configuraciones y diferentes configuraciones. Así que, como mínimo, necesitas saber qué versión de TypeScript estás usando y cómo la tienen configurada, y esto realmente significa que los usuarios necesitan suministrar cajas de arena o repositorios de GitHub o enlaces al patio de recreo de TypeScript que muestren este tipo de error ocurriendo. Uno de los mayores problemas que vemos es casos en los que la gente ha desactivado las banderas estrictas o de verificación nula, y esto realmente introduce diferencias en cómo se comportan nuestros tipos. Así que en este punto, les decimos a los usuarios, si estableces eso en falso, ese es tu problema, no el nuestro.

Desafortunadamente, realmente no hay una buena manera de debug los tipos muy fácilmente. No puedes poner un punto de interrupción en medio de una definición de tipo y detenerte a ver qué está calculando actualmente TypeScript. Además, si estás pasando el ratón sobre las variables en VS Code, muchas veces limita el tamaño de salida por defecto. Hay un par de formas de ajustar esto. Puedes cambiar la bandera de no truncamiento de errores en tu configuración de TS, o puedes sumergirte en el code de TypeScript y alterar el valor codificado para cuánta salida muestra en el hover en VS Code. Una sugerencia es que si tienes algunos tipos complejos, recrea esos paso a paso y asígnalos a variables de tipos separadas e intenta ver qué está haciendo en cada paso del camino. También hay un tipo en la biblioteca TS Tool Build llamado Any.compute que puede hacer algunas expansiones recursivas de tipos. Es muy importante que intentes probar los tipos en tu biblioteca y tenemos archivos de prueba de tipos en las bibliotecas de Redux. Y esto es realmente solo code de TypeScript que necesita compilar limpiamente y tiene algunas afirmaciones en allí que dice que espero que esta variable sea un cierto tipo. Puedes escribir estos como archivos de prueba simples que se ejecutan a través de TSC. Puedes tenerlos como pruebas omitidas en una suite de pruebas. Pero la idea es que quiero saber ¿este code compila limpiamente? Y hemos creado muchas utilidades en las bibliotecas de Redux para cosas como esperar que ciertos tipos existan. Así que cuando se trata de diseñar APIs, el problema es que JavaScript es un lenguaje muy dinámico. Y TypeScript intenta capturar ese comportamiento y no siempre funciona bien. Así que en general, TypeScript nos empuja a design APIs que son mucho más simples. Y un buen ejemplo de esto es React Redux. La API Connect original es muy dinámica. Toma cuatro parámetros diferentes, todos muy opcionales, algunos de los cuales pueden ser objetos o funciones o nulos. Es increíblemente complicado y las diferencias de tipo para esto son extrañas, francamente. Y nuestra API de Hooks es mucho más simple. UseSelector es solo una función que toma una entrada conocida y devuelve un resultado. Es más simple de escribir. Es más simple para la gente usar. Intentamos design las APIs de React Redux y Redux toolkit de manera que puedan inferir tanto como sea posible. Queremos que nuestros usuarios tengan que suministrar la menor cantidad posible de información para obtener

Entonces, veamos algunos tips y trucos diferentes de las diversas bibliotecas Redux. Verás muchos tipos condicionales allí, y los tipos condicionales son básicamente comparaciones a nivel de tipos y operadores ternarios. Y verás mucho de x extends y allí, y esto es tanto una comparación como una comprobación de si este tipo cumple con este criterio. Puedes, al igual que el verdadero code, anidar estas declaraciones ternarias. Un buen ejemplo de esto es el middleware de thunk para el tipo de la tienda de configuración de Redux Toolkit, donde estamos intentando averiguar qué tipo debe incluirse para el middleware de thunk en la configuración de la tienda basada en las opciones que el usuario ha proporcionado. Así que si dijeron que el middleware de thunk debería estar apagado, entonces no queremos incluir un tipo para el middleware en absoluto. Si incluyeron un argumento extra, necesitamos usar eso. De lo contrario, se recurre al tipo predeterminado. O el tipo de acción de carga, donde sabemos que queremos empezar con un campo de carga y un tipo de campo, pero también podría haber un campo meta o un campo de error, dependiendo de cómo se definió el creador de la acción. Ahora, es cierto que las ternarias pueden ser difíciles de leer. Nunca he sido un fan de las ternarias anidadas. Y desafortunadamente, en TypeScript, a veces tienes que hacer lo que tienes que hacer. Y sí, esto puede salirse un poco de las manos. Este tipo representa todas las posibles formas en que un creador de acciones de Redux Toolkit podría ser definido con todos los campos opcionales y que pueden ser pasados a través. Bueno. Sí. A veces esto realmente se pone ridículo. Como este tipo que representa un creador de acciones createAsyncThunk. Si piensas que esto es realmente difícil de leer, sí, estoy completamente de acuerdo. Ahora, un truco que sí utilizamos en createAsyncThunk es proporcionar algunos valores predeterminados para varios tipos opcionales y dar a los usuarios una forma de anular estos. Idealmente, todo lo que hacen es proporcionar un tipo para el argumento de entrada y el tipo de retorno. Todo se infiere a partir de ahí. Si necesitas anular algo como el valor del estado para usar con getState, entonces puedes anular condicionalmente solo ese y dejar los otros campos como dispatch y extra solos. En reselect, tenemos un tipo increíblemente complejo que hace un montón de mapeo a nivel de tipos y transposición y extracción. Me llevó semanas llegar a este tipo y tuve que obtener mucha ayuda de otras personas, pero esto nos ahorró más de 3000 líneas de tipos definidos múltiples veces para manejar de 1 a 12 entradas variadas. Esto requirió muchos trucos como usar valores predeterminados para genéricos para básicamente precalcular algunas variables o mapear sobre tuplas y asegurarse de que solo usamos campos numéricos. Entonces, ¿qué tipo de cosas ayudarían a los mantenedores en el futuro? De lejos, la cosa más grande es