Lecciones de Mantenimiento de Bibliotecas de TypeScript

Hola, soy Mark Erickson, y hoy me gustaría hablarles sobre las lecciones que he aprendido al mantener bibliotecas de TypeScript. Un par de cosas rápidas sobre mí. Actualmente soy un Ingeniero Frontend Senior en Replay, donde estamos construyendo un depurador de aplicaciones JavaScript que permite viajar en el tiempo real. 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. Recolecto enlaces interesantes sobre cualquier cosa que parezca potencialmente útil. Escribo publicaciones de blog extremadamente largas sobre React y Redux, y soy un mantenedor de Redux. Además, es posible que también me conozcas como ese chico con el avatar de los Simpsons.

admitir TypeScript, cómo abordar la migración de una biblioteca de JavaScript a TypeScript, los problemas al tratar con los tipos y versiones de la biblioteca, y cómo admitir múltiples versiones de TypeScript. También veremos cómo depurar y probar los tipos, cómo diseñar APIs para su uso con TypeScript, y algunas características que facilitarían el uso de TypeScript con bibliotecas.

Entonces, ¿por qué proporcionamos tipos con una biblioteca de todos modos? Los tipos cumplen varios propósitos. Uno de ellos es la documentación de la API. Los usuarios pueden ver los tipos y comprender qué funciones y tipos existen y cómo pueden usarlos en su aplicación. Otro propósito es la corrección del código del usuario. Pueden aplicar ciertos patrones de uso que los usuarios deben tener en su código fuente de la aplicación real. Junto con eso, está la corrección del código de la biblioteca. Los tipos nos ayudan a asegurarnos de que el código dentro de nuestra biblioteca se comporte como se espera y se trata de la mantenibilidad, poder trabajar en el código real dentro de la biblioteca.

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

Ahora, hay varias formas en que una biblioteca de JavaScript puede proporcionar tipos. El mejor enfoque es si la biblioteca está escrita en TypeScript en sí. Esto garantiza que los tipos coincidan con el comportamiento real de lo que está en el código fuente de la biblioteca y que los tipos se actualicen cada vez que haya una nueva versión de la biblioteca. Otra opción es escribir el código fuente en JavaScript y escribir manualmente las definiciones de tipo e incluirlas en la salida publicada. Esto está bien porque los tipos aún son mantenidos por los propietarios reales de la biblioteca. Pero puedes encontrarte 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 reunir algunos tipos y publicarlos en el repositorio de Definitely Typed propiedad de Microsoft. Esto definitivamente puede causar problemas, pero al menos te brinda una forma de tener tipos, especialmente si los mantenedores de la biblioteca no quieren preocuparse por lidiar con eso ellos mismos. Realmente hemos utilizado todos estos enfoques diferentes con las bibliotecas de Redux a lo largo del tiempo. Pero hemos estado trabajando en tratar de migrar las bibliotecas de Redux a TypeScript, especialmente en los últimos años. El núcleo de Redux se convirtió a TypeScript en 2019. Simplemente nunca llegamos a publicarlo. React Redux versión 8 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 la infraestructura de compilación. Debes asegurarte de compilar realmente los tipos de TypeScript, transformar la salida de la compilación a JavaScript simple y asegurarte de que la configuración de tus pruebas esté configurada para trabajar con TypeScript también.

También debes asegurarte de que los tipos se incluyan directamente en el paquete publicado. Esto significa agregar una clave de tipos a tu archivo package.json. También es una buena idea probar el paquete con código de aplicación TypeScript y asegurarte de que todo funcione como esperas. Me gusta usar una herramienta llamada Yalk para hacer una publicación local de esto.

Cuando estés listo para convertir el código real, si existen definiciones de tipo existentes, como DefinitelyTyped, te sugiero que las utilices como punto de partida. Lo hicimos para React Redux. Elige algunos archivos, conviértelos a TypeScript y repite. También recomiendo hacer algunos commits que simplemente cambien el nombre de los archivos antes de comenzar a realizar cambios en ellos para preservar el historial de Git existente. Además, no olvides convertir todas tus pruebas a TypeScript. Esto ayudará a detectar algunos problemas, y veremos algunos ejemplos más adelante. Por último, asegúrate de exportar tipos desde tu archivo de índice, no solo las funciones y las estructuras de datos en el código.

Entonces, ¿cómo gestionas la versión de los tipos públicos? Esto es un poco complicado. TypeScript en sí no utiliza la versión semántica. Simplemente utilizan un enfoque de incremento decimal, lo que significa que cualquier nueva versión de TypeScript podría romper el código que se está ejecutando actualmente. Además, diferentes personas pueden tener diferentes configuraciones de TypeScript, lo que puede llevar a diferencias en el comportamiento. Una de las cosas más importantes que vemos es que las personas desactivan las banderas de verificación estricta o de verificación estricta de nulos, lo que conduce a un comportamiento de compilación claramente diferente. En realidad, cualquier cambio en tus tipos, incluidas las correcciones de errores, podría hacer que las aplicaciones de los usuarios no se puedan compilar.

Entonces, ¿eso significa que cada vez que lanzo una corrección de errores, en realidad es una especie de versión importante? El equipo de Ember ha estado trabajando en tratar de establecer un conjunto de reglas sobre cómo planean manejar TypeScript en el ecosistema de Ember, y publicaron un RFC increíblemente extenso donde intentaron definir lo que Sember significa para los tipos de TypeScript, no solo para Ember, sino también como un enfoque que cualquier biblioteca puede utilizar. Y lo que concluyeron es que los tipos son APIs. Debes tener en cuenta los tipos en tu versión, pero puedes dividirlos en cambios que se consideran rompedores y cambios que no se consideran rompedores. Y hacen algunas excepciones para correcciones de errores e intenciones. Es posible que realicen un cambio que introduzca algunos errores en el código de los usuarios, pero que en realidad esté evitando el uso incorrecto de ciertos patrones en el código del usuario. Pero su objetivo es que si sigues la lista de versiones de TypeScript admitidas, no deberías ver nuevos errores en el código de los usuarios. Otro problema relacionado es cómo apuntar a versiones específicas de TypeScript. TypeScript lanza varias versiones nuevas al año y estas pueden tener nuevas características y funcionalidades bastante importantes. Entonces, ¿cuánto tiempo admites versiones antiguas de TypeScript? ¿Qué tan pronto puedes adoptar nueva sintaxis y características? ¿Cómo abordas las pruebas con múltiples versiones de TypeScript? Vale la pena señalar que el repositorio Definitely Typed intenta admitir aproximadamente 2 años de versiones de TypeScript. Diferentes bibliotecas abordan esto de diferentes maneras. Ember ha definido su conjunto de planes de adopción donde han dicho que las bibliotecas principales de Ember utilizarán una ventana móvil donde intentarán admitir nuevas versiones de TypeScript de inmediato y dejarán de admitir versiones antiguas en las versiones de soporte a largo plazo de Ember. Otras bibliotecas de Ember pueden elegir solo un par de versiones. Y cada vez que eliminan una versión, se considera un lanzamiento importante de esa biblioteca.

Por otro lado, el grupo Stately ha dicho que nos reservamos el derecho de realizar cambios en nuestro soporte de TypeScript a medida que nuestra comprensión de TypeScript y su comportamiento evolucione con el tiempo. Entonces, ¿cómo puedes admitir múltiples versiones de TypeScript? Lo más importante que veo aquí es configurar tu CI para compilar tus pruebas y tu aplicación y probarlas con múltiples versiones de TypeScript al mismo tiempo. Esto se puede hacer utilizando algo como el soporte de Matriz en GitHub Actions. También puede ser útil utilizar una versión anterior de TypeScript mientras desarrollas la biblioteca, ya que esto te obliga a restringirte a la sintaxis que

en realidad se puede usar mientras trabajas en el código. TypeScript tiene soporte incorporado para usar múltiples copias de definiciones de tipos según la versión de TypeScript que el usuario tenga en su aplicación. Si defines un campo de versiones de tipos, puedes indicarle a TypeScript una comparación y otros archivos de definiciones de tipos específicos, y los utilizará en su lugar si es una versión anterior de TypeScript. También es posible compilar hacia atrás algunos tipos de definiciones para que funcionen en versiones anteriores de TypeScript. Sin embargo, en la práctica, sugiero utilizar las versiones de tipos como último recurso. Idealmente, tus tipos principales deberían admitir varias versiones a la vez. Entonces, ¿cómo manejamos esto con las bibliotecas 3DX? En realidad, no tenemos una política de versionado específica que hayamos redactado. En general, intentamos hacer un esfuerzo de buena fe para intentar admitir varias versiones de TypeScript a la vez. Y tenemos en cuenta la intención al realizar cambios en los tipos. Por ejemplo, si hago un cambio que técnicamente introduce subrayados rojos nuevos, pero mi intención era solucionar un error, entonces lo lanzaría como una versión de parche en lugar de una versión principal. Ha habido un par de veces en las que hemos realizado cambios que técnicamente rompen la compatibilidad, pero solo lo hicimos después de buscar el uso de código público y ver que nadie realmente está utilizando este tipo en la práctica. Tampoco tenemos una definición estrictamente definida para cuántas versiones de TypeScript admitimos. En la práctica, tiende a ser las últimas cuatro o cinco versiones, es decir, aproximadamente un año de lanzamientos de TypeScript. Realmente depende de las características que necesitemos. TypeScript 4.1 en particular fue muy importante porque introdujo muchas características nuevas de cadenas. Dependemos de eso para cosas como las API de los hooks de consulta de RTK. Francamente, tampoco hacemos un buen trabajo documentando qué versiones de TypeScript admitimos actualmente, y eso es algo en lo que podríamos mejorar. Aunque al menos he intentado listar cuándo dejamos de admitir una versión en las notas de lanzamiento.

Entonces, dado que los tipos son código, eso significa que tienen errores, y los usuarios informarán 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 entornos. Como mínimo, necesitas saber qué versión de TypeScript estás utilizando y cómo lo tienen configurado, y esto realmente significa que los usuarios deben proporcionar ejemplos o repositorios de GitHub o enlaces de TypeScript Playground que muestren este tipo de error. Uno de los mayores problemas que vemos es cuando las personas desactivan las banderas de estricto o nulo, y esto realmente introduce diferencias en cómo se comportan nuestros tipos. En este punto, les decimos a los usuarios que si lo desactivan, ese es su problema, no el nuestro.

Desafortunadamente, realmente no hay una forma fácil de depurar tipos. No puedes poner un punto de interrupción en medio de una definición de tipo y detenerte a ver qué está calculando TypeScript en ese momento. Además, si pasas el cursor sobre las variables en VS Code, muchas veces limita el tamaño de la salida de forma predeterminada. Hay un par de formas en las que puedes ajustar esto. Puedes cambiar la bandera de truncamiento de errores en tu archivo de configuración de TypeScript, o puedes sumergirte en el código de TypeScript y modificar el valor codificado para la cantidad de salida que muestra al pasar el cursor en VS Code. Una sugerencia es que si tienes tipos complejos, los recrees paso a paso y los asignes a variables de tipos separadas para ver qué está haciendo en cada paso del proceso. También hay un tipo en la biblioteca TS Tool Build llamado Any.compute que puede realizar una expansión recursiva de tipos. Es muy importante que pruebes los tipos en tu biblioteca, y tenemos archivos de prueba de tipos en las bibliotecas Redux. Y esto es simplemente código de TypeScript que debe compilarse correctamente y tener algunas afirmaciones que indiquen que esperas que esta variable sea de un cierto tipo. Puedes escribir estos archivos de prueba como archivos de prueba normales que se ejecutan a través de TSC. Puedes tenerlos como pruebas omitidas en un conjunto de pruebas. Pero la idea es saber si este código se compila correctamente. Hemos creado muchas utilidades en las bibliotecas Redux para cosas como esperar que ciertos tipos existan. Entonces, cuando se trata de diseñar API, el problema es que JavaScript es un lenguaje muy dinámico. Y TypeScript intenta capturar ese comportamiento y no siempre funciona muy bien. En general, TypeScript nos empuja a diseñar API mucho más simples. 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, funciones o nulos. Es increíblemente complicada y las diferencias de tipo para esto son francamente extrañas. Y nuestra API de Hooks es mucho más simple. UseSelector es simplemente una función que toma una entrada conocida y devuelve un resultado. Es más fácil de escribir. Es más fácil de usar. Intentamos diseñar las API de React Redux y Redux Toolkit para que puedan inferir la mayor cantidad posible de información. Queremos que nuestros usuarios tengan que proporcionar la menor cantidad posible de información para obtener

El comportamiento correcto del tipo. Eso significa que nuestros tipos son más complicados como resultado, pero facilita la vida de nuestros usuarios. A veces no puedes saber realmente los tipos finales que un usuario va a necesitar proporcionar en la función principal o en las definiciones de tipo. Por lo tanto, a veces es necesario proporcionar un tipo que un usuario pueda importar, anular y pasar valores como el estado final de Redux en su aplicación. Tener estos tipos predefinidos que pueden usar con su código puede ser muy útil.

Entonces veamos algunos consejos y trucos de las diversas bibliotecas de Redux. Verás muchos tipos condicionales y los tipos condicionales son básicamente comparaciones a nivel de tipos y operadores ternarios. Y verás muchos x extends y, que es tanto una comparación como una coincidencia de tipo. Al igual que en el código real, puedes anidar estas declaraciones ternarias. Un buen ejemplo de esto es el middleware de thunk para el tipo de Configure Store de Redux Toolkit, donde intentamos determinar qué tipo se debe incluir para el middleware de thunk en la configuración de la tienda en función de las opciones que el usuario ha proporcionado. Entonces, si dijeron que el middleware de thunk debería estar desactivado, entonces no queremos incluir un tipo para el middleware en absoluto. Si incluyeron un valor de argumento adicional, necesitamos usar eso. De lo contrario, se utiliza el tipo predeterminado. O el tipo de acción de carga útil, donde sabemos que queremos comenzar con un campo de carga útil y un campo de tipo, pero también podría haber un campo de meta o un campo de error, dependiendo de cómo se haya definido el creador de acciones. Ahora, es cierto que las ternarias pueden ser difíciles de leer. Personalmente, nunca me han gustado las ternarias anidadas. Y desafortunadamente, en TypeScript, a veces tienes que hacer lo que tienes que hacer. Y sí, esto puede volverse un poco complicado. Este tipo representa todas las formas posibles en que se podría definir un creador de acciones de Redux Toolkit con todos los diversos campos opcionales y que se pueden pasar. De acuerdo. Sí. A veces esto realmente se vuelve ridículo. Como este tipo que representa un creador de acciones createAsyncThunk. Si crees que esto es realmente difícil de leer, sí, estoy completamente de acuerdo. Ahora, un truco que usamos en createAsyncThunk es proporcionar algunos valores predeterminados para varios tipos opcionales y dar a los usuarios una forma de anularlos. 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 eso y dejar los otros campos como dispatch y extra sin cambios. En reselect, tenemos un tipo increíblemente complejo que realiza una serie de mapeos y extracciones a nivel de tipos. Me llevó semanas crear este tipo y tuve que recibir mucha ayuda de otras personas, pero esto nos ahorró más de 3000 líneas de tipos definidos múltiples para manejar de 1 a 12 entradas variádicas. Esto requirió muchos trucos, como usar valores predeterminados para los genéricos para precalcular algunas variables o mapear sobre una tupla y asegurarse de que solo usemos campos numéricos. Entonces, ¿qué tipo de cosas ayudarían a los mantenedores en el futuro? Sin duda, lo más importante es

genéricos opcionales o con nombre. Esto nos facilitaría mucho la vida si pudiéramos simplemente especificar uno o dos genéricos en lugar de todos a la vez. Además, sería útil contar con mejores formas de depurar o visualizar tipos a medida que fluyen a través del sistema de tipos. También podría ser útil especificar mensajes de error para los tipos, de modo que cuando los usuarios tengan una entrada incorrecta específica, podamos definir cuáles deberían ser los mensajes de error. Sería útil contar con algunas comparaciones de tipos incorporadas, y francamente el compilador de TypeScript necesita mostrar mejores mensajes de error. Y ha habido propuestas de parte de miembros del equipo de TypeScript sobre formas en que podrían hacer esto. Espero que esto les dé algunas ideas de cómo es mantener una biblioteca de TypeScript y algunos de los consejos y trucos con los que tratamos para manejar ejemplos del mundo real. Si tienen alguna pregunta al respecto, no duden en hablar con nosotros en el chat después o pasar por los canales de Redux en el Discord de Reactiflix.

Gracias y que tengan un buen día. Hola Mark, bienvenido. Vamos a discutir los resultados de la encuesta. Básicamente, el 32 por ciento utiliza TypeScript entre el 51 y el 90 por ciento. Luego, el 30 por ciento de los encuestados utiliza TypeScript el 100 por ciento del tiempo, el 24 por ciento solo un poco entre el 1 y el 50 por ciento. Y me sorprende mucho descubrir que el 14 por ciento de todos los que respondieron no utiliza TypeScript en absoluto, lo cual es bastante interesante porque es una conferencia de TypeScript. Pensaría que todos nosotros tendríamos algún uso y nos moveríamos un poco. Pero no, hay un 14 por ciento que tiene 0. Tal vez solo quieran aprender. ¿Qué opinas sobre estos resultados de la encuesta en general? Creo que tiene sentido. Quiero decir, dado que es una conferencia de TypeScript, se esperaría que muchas personas estén utilizando una buena cantidad de código TypeScript real. Pero creo que esto habla de la naturaleza muy transicional de nuestras aplicaciones. La mayoría de nosotros no estamos en una posición en la que podamos escribir una base de código completamente nueva de TypeScript todo el tiempo desde cero. Muchos de nosotros estamos lidiando con aplicaciones que, en muchos casos, han estado presentes durante años. Y así que tienes, ya sabes, personas que intentan migrar sus bases de código de manera incremental. He hecho una cantidad significativa de eso a lo largo de mi carrera. Así que estoy muy familiarizado con esa idea.

Genial. Gracias. Así que tenemos un par de preguntas para ti. Anil Polt, está preguntando si estoy creando la versión de TypeScript como un proyecto que no es una biblioteca, ¿sería fácil simplemente actualizar y buscar un nuevo script rojo que pueda aparecer si el servidor de lenguaje está funcionando correctamente, verdad? Perdón, repíteme eso una vez más. Sí, por supuesto. Si actualizar la versión de TypeScript es un proyecto que no es una biblioteca, ¿sería fácil simplemente actualizar y buscar un nuevo script rojo que pueda aparecer si el servicio de lenguaje está funcionando correctamente? Veamos. Creo que en general, en su mayor parte, deberías poder actualizar TypeScript. He encontrado que como regla general tanto en el desarrollo de aplicaciones como en el desarrollo de bibliotecas, definitivamente hay momentos en los que tengo que usar el comando de VS code para reiniciar el servidor de TypeScript o simplemente volver a cargar toda la ventana, es la vieja historia de reiniciarlo y ver qué pasa y ver si funciona mejor para asegurarme de que TypeScript esté analizando correctamente las cosas, especialmente si estás haciendo algo como actualizar la versión de TypeScript o a veces modificar otras versiones de bibliotecas que tienes en la aplicación. Pero en general, actualizar esas cosas y posiblemente reiniciar debería ser suficiente para que VS code y el servidor de lenguaje comiencen a hacer algún reprocesamiento. Ahora, como observación general, también he visto que como VS code está limitado generalmente a los archivos que tienes abiertos y hay muchos archivos que en realidad no tienes abiertos. Así que mirar las cosas en el editor ayuda, pero también vas a querer volver a ejecutar un paso de compilación y hacer que intente compilar todo el proyecto para ver si realmente funciona como crees que debería funcionar. De acuerdo, gracias. ¿Cuál es la etiqueta de TypeScript más complicada en la que has trabajado? Eso probablemente sería la que está en la penúltima diapositiva que hice en mi presentación de Reselect 4.1. Para hacer una comparación, creo que mencioné esto en la charla, las definiciones anteriores de Reselect tenían definiciones escritas a mano para cubrir casos de 1 a 12 entradas como argumentos separados o un array de argumentos, y eso sumaba más de 3,000 líneas solo de tipos. Así que cuando estaba, las definiciones en Reselect 4.1 comenzaron como una solicitud de extracción de otra persona. Así que no escribí todo desde cero, pero hice el trabajo de tratar de integrarlas y luego evolucionarlas. Y ese último tipo que viste allí, donde se está haciendo una operación de mapeo a nivel de tipo, eso fue realmente difícil. Y me atribuyo la mayor parte de ello. Vi más o menos lo que quería hacer a nivel de tipos. Pero también es cierto que había varios lugares donde realmente no sabía cómo hacer que los tipos hicieran lo que me gusta. Puedo ver lo que necesita hacer. Si esto fuera código JavaScript, podría hacer que suceda. ¿Cómo hago esto como una operación a nivel de tipos? Y afortunadamente, había algunas personas que eran mucho mejores en TypeScript que yo, que pudieron ayudarme a superar esos problemas. Eso fue realmente difícil de trabajar. Gracias por compartir tu experiencia. Y si alguien de la audiencia quiere compartir su experiencia con el tipo más difícil que ha encontrado, puede usar el hashtag TSCongress en Twitter. Y otra pregunta es, ¿cuál es el problema más común que ves cuando los usuarios presentan problemas relacionados con TS? Diría que tiene que ver con las personas que no tienen la opción de configuración estricta de TypeScript o la opción de verificación estricta de nulos activada. Hemos tenido varios casos en los diversos repositorios relacionados con Redux donde alguien presenta un problema diciendo que la biblioteca no funciona correctamente en su aplicación. Y siempre, como mantenedores, siempre pedimos a alguien que nos muestre una reproducción del problema en un código sandbox o un repositorio de GitHub. Pero esto es especialmente cierto cuando se trata de un problema de TypeScript porque hay tantas opciones de configuración diferentes que podrían haber configurado de manera diferente. Y hemos visto varios casos en los que resulta que el usuario no tenía activada la verificación estricta de nulos, y eso significa que los tipos que hemos escrito en nuestra biblioteca se comportan de manera diferente a cómo los probamos y esperamos que funcionen. Y en ese caso, les decimos, mira, francamente, desde nuestra perspectiva, la configuración de tu aplicación está configurada incorrectamente. Por favor, activa la verificación estricta de nulos y eso solucionará el problema real que estás viendo. De acuerdo. Gracias. Eso fue genial. Ahora vamos a unirnos a Mark en la sala de oradores en Discord. El enlace para unirse está en la línea de tiempo. Gracias, Mark. Gracias. Lo aprecio.