TypeScript para Autores de Bibliotecas: Aprovechando el Poder de TypeScript para DX

Hola. Es un placer estar aquí hoy, hablando sobre TypeScript para autores de bibliotecas. Es algo que me interesa mucho porque soy egoísta y me encanta usar bibliotecas con una gran experiencia de desarrollo, y estoy seguro de que ustedes también. Mi nombre es Daniel Rowe. Estoy ubicado en el noreste del Reino Unido, y soy parte del equipo principal de Nuxt, y también mantengo algunos otros paquetes de código abierto. Debo decir de antemano, esta es mi perspectiva a medida que nos adentramos en TypeScript para autores de bibliotecas, es posible que tengan otras ideas. Es posible que tengan enfoques mejores, y me encantaría saber de ustedes si ese es el caso. Por favor, contáctenme, ya sea por correo electrónico o Twitter es una excelente manera de ponerse en contacto. Por favor. Me encantaría conectarme más tarde.

Entonces, para empezar, la pregunta que me gustaría plantear es ¿cuál es el punto de TypeScript para autores de bibliotecas, supongo? Y obviamente, incluso si no estuvieran exponiendo sus tipos fuera de su propio proyecto, creo que aún habría beneficios. Ciertamente, yo encontraría eso por mí mismo. Creo que TypeScript ayuda a mejorar el código que producimos. Nos ayuda a cubrir casos límite. Nos ayuda a ver las posibles alternativas y resultados de lo que estamos creando. Y nos ayuda con cosas como la refactorización, asegurándonos de que no hayamos dejado algo fuera. Muchos beneficios enormes para usar TypeScript internamente. Pero creo que al mirar la pregunta de por qué usamos TypeScript para beneficio externo, la razón clave es la verdad. Y creo que hay un par de implicaciones diferentes para esto que espero explicar hoy. Pero creo que todo se reduce a la verdad. Estamos permitiendo a nuestros usuarios una ventana hacia cómo funcionan nuestras bibliotecas. Esa ventana es precisa. Debe ser precisa. Les estamos ofreciendo una alternativa a mirar nuestro código fuente o leer nuestra documentación. Algo que es en realidad una representación realista de lo que está sucediendo. Y eso, creo, es una de las cosas que hace que TypeScript sea tan increíble, cuando lo usas al consumir alguna otra biblioteca. Porque estás obteniendo información a través de él. El popup de tu IDE te está diciendo algo sobre cómo funciona en el fondo. Te está diciendo algo sobre lo que puedes esperar que regrese de eso

llamada a función. Las opciones posibles que puedes pasarle. Ese tipo de cosas. Todo se trata de la verdad para mí. Y la primera implicación es la documentación. Eso también se trata de la verdad, ¿no es así? Entonces, los tipos son parte de tu documentación o tal vez incluso de tu documentación. Ciertamente, los tipos y TS doc, JS doc, usaré los términos indistintamente aunque no sean exactamente iguales. Pero pueden proporcionar la documentación de tu biblioteca. Entonces, si piensas en agregar comentarios inmediatamente antes de cada función, cada interfaz, cada constante que expones de tu biblioteca, puedes describirlo con precisión allí. Mi opinión para hoy es que toda tu API documentación y ejemplos deben estar en tu código. Esto significa que cuando tus usuarios realmente usan tu biblioteca, obtienen información actualizada y precisa sobre la versión que están consumiendo en ese momento. No necesitas tener un sitio web elegante con un menú desplegable que permita a los usuarios seleccionar las versiones principales, si tu documentación está en el propio código. Su editor mostrará la versión correcta para ellos. Puedes agregar enlaces. Puedes agregar ejemplos. Tienes todo el poder de markdown a tu disposición. Puedes agregar valores predeterminados. Puedes agregar la versión en la que se introdujo algo en el proyecto. Cualquier otra cosa que puedas pensar o considerar, jsdoc, son estándares realmente maduros. Y no hay nada mejor que poder ver la documentación de lo que estás usando en tu IDE en lugar de tener que ir a otro lugar o realizar una búsqueda rápida. Incluso puedes alojarlo de esa manera. Echa un vistazo a jsdocs.io. Puedes escribir cualquier paquete y ellos mostrarán la documentación basada en los archivos de declaración de ese proyecto. Incluso puedes considerar algo como unpiped, que es un paquete en la organización onjs.github que te permite tener un esquema de configuración con tipos. Puede que no sea relevante para tu proyecto, lo usamos en Nuxt. Podemos tipar nuestro esquema de configuración y luego exportarlo a json o a código. Podemos hacer cosas con él, como generar documentación de forma programática. Eso es lo que usamos para asegurarnos de que nuestra documentación de configuración de Nuxt sea precisa y esté actualizada en el sitio web. Siempre se basa en el código real y el JSTOC en ese archivo de código. Aquí hay un pequeño ejemplo seleccionado de una biblioteca que mantengo. No es complejo, no es difícil como autor hacer esto.

No necesitas escribir todos los tipos, TypeScript te respalda en ese sentido. Puedes agregar solo el valor que se requiere. Un ejemplo de cómo se podría usar algo, una explicación adicional de qué podría ser un parámetro en particular, luego obviamente alguna declaración general, y solo mira cómo se muestra. ¿No es hermoso? ¿No muestra algo que podría ser realmente útil como usuario de ese código?

Entonces ahí lo tienes, los tipos como documentación. Pero creo que otro punto de este concepto de verdad es que no solo estamos exponiendo nuestro código en tiempo de ejecución, también estamos exponiendo nuestros tipos como una biblioteca. Eso también es nuestro código, lo que significa que la implicación número uno es que debemos probarlos. Me gusta especialmente expect type como biblioteca, y eso es lo que estás viendo aquí, pero test también es una gran herramienta que he usado en otros proyectos. Entonces, en realidad, puedes probar tus tipos junto con tus pruebas unitarias normales con algo como expect type. Así puedes reducir el enfoque en un valor de retorno específico y realmente esperar que ese valor sea el tipo que deseas. Para que esto funcione, solo necesitas ejecutar ESC y noemit en tus archivos de prueba, además de ejecutarlos con tu ejecutor de pruebas, vtest o simplemente o lo que sea. Y no olvides el hecho de que TypeScript en sí mismo también puede ayudarnos. Es particularmente útil tsexpect error, que lanzará un error si no hay un error en la línea siguiente. Es un gran ejemplo de decir que esto debería generar la línea ondulada roja cuando mis usuarios hacen algo como esto porque no debería permitirse. Entonces, entre expect typeof, que viene con una gran cantidad de funciones auxiliares que se pueden encadenar a partir de él, y tsexpect error, puedes tipificar tu código de manera bastante precisa, crear una interfaz de tipo para tus usuarios. Creo que eso es absolutamente esencial para un autor de biblioteca. También recomendaría como seguimiento de eso probar tus archivos compilados porque a veces puedes tener una situación en la que los archivos fuente están bien desde el punto de vista de la tipificación. No es hasta que se construyen las cosas que surge algún tipo de problema. Y para ayudar con eso, existen herramientas como Unbuild y otras que te permiten tener un modo de simulación para que tus archivos dist en desarrollo apunten efectivamente a tus archivos fuente. Unbuild escribe stubs que funcionan en node, por lo que puedes usarlo en desarrollo. Pero también significa que obtienes los archivos compilados precisos cuando realmente construyes tu proyecto. Siempre y cuando en tus pruebas importes desde tu biblioteca compilada. Solo escribe el nombre completo de tu proyecto y asegúrate de tener una entrada en tsconfig o hayas configurado un alias en tu ejecutor de pruebas y de esa manera siempre puedes probar tus archivos compilados en tus pruebas de tipo. Otra implicación si los tipos son código, versionarlos. Adhiérete a semver si puedes. Por ejemplo, podrías lanzar una mejora en tu proyecto. Normalmente, una mejora no desencadenaría un cambio que no rompa la compatibilidad. Pero si cambia tu tipo de manera que algo se rompa para tus usuarios o la compilación se rompa en ese proyecto, entonces es un cambio que rompe la compatibilidad. Un ejemplo sería, tengo que admitirlo aquí, hice un PRN a definitely types para cambiar el tipo de end y algunos otros tipos relacionados con stream, y parece que había una pequeña discrepancia entre la realidad y los tipos de node. Res end devuelve esto, no void, así que queríamos corregir eso. Pero solo mirando las implicaciones de

que lo cambian fue enorme. De repente, los flujos que se estaban pasando no podían ser pasados a funciones que esperaban el antiguo tipo de flujo. Así que hacer ese cambio fue un cambio que rompió para mucha, mucha gente. Probablemente aún tenía que hacerse, pero tienes que tener mucho cuidado al respecto. Y requiere mucho esfuerzo asegurarse de que versiones tus tipos correctamente. Considero una herramienta como API Extractor. Es increíblemente completa. Es un poco compleja de configurar, pero puede ayudar a garantizar que tus contratos de tipo no cambien, que puedas cumplir cuando estás lanzando nuevos cambios a los tipos. Y obviamente, hay cosas que puedes hacer cuando estás haciendo cambios para asegurarte de que no sean cambios completos, sino que las cosas sean un poco más suaves. Por ejemplo, puedes simplemente deprecar un tipo si lo estás renombrando. Así, los usuarios tienen algo de tiempo para cambiar su uso. Y puedes hacer algo similar, con funciones, en lugar de simplemente cambiar el tipo de la función. Nuevamente, esto puede que no sea necesario. Pero en algunos casos, podría serlo. Puedes agregar una sobrecarga, para que la función continúe teniendo la firma anterior, pero también tenga una nueva firma y maneje ambas. Entonces, hay algunas cosas que puedes hacer, creo, para reducir el impacto en ti como mantenedor de biblioteca al tener que lanzar nuevas versiones menores o mayores cuando estás cambiando tus tipos.

También vale la pena decir que si tus tipos son tu código, si los consideras como tu API y un contrato con tus usuarios, es realmente importante que solo expongas los tipos que pretendes. Habrá muchos tipos internos, tipos que estás utilizando con fines de utilidad. Puede haber código de utilidad que sea solo interno. Por defecto, TypeScript hace algo que encuentro incomprensible, y es que obviamente representa la estructura completa de tu proyecto en archivos de declaración. Entonces, los usuarios pueden, agregando la ruta a tus archivos fuente, acceder a los tipos y las declaraciones de cada función y tipo que se exporta en cualquiera de tus archivos fuente, incluso si no se exporta desde tu punto de entrada y paquete final. Entonces, usar algo como rollup-plugin-dts o dts-bundle-generator significa que puedes agruparlo para que no sea accesible desde tu index.d.ts final. Eso es algo muy útil en conjunto con todo lo demás de lo que he estado hablando en términos de pruebas y versionado de tus tipos. Ya existen muchas herramientas de compilación que hacen esto por ti, incluido Unbuild, que mencioné anteriormente. Y finalmente, no solo se trata de tipos como documentación o tipos como código, sino que llegamos al punto real, los tipos como verdad. Perdona el punto filosófico o epistemológico. Creo que de eso se trata los tipos. Se trata de exponer la realidad del proyecto, de tu biblioteca, de cómo funciona y qué hace. Y la consecuencia es que debemos evitar la oportunidad de mentirnos a nosotros mismos y a nuestros usuarios. Porque hacemos esto todo el tiempo, y yo soy muy propenso a esto, es muy fácil poner un as o escribir algo como any. Es muy posible desactivar las comprobaciones estrictas de nulos y simplemente disfrutar de

el hecho de que no tengas que... simplemente asumes que se establecerá. Pero creo que la disciplina para los autores de bibliotecas es ser lo más estrictos posible, para que lo que estamos generando y declarando a nuestros usuarios sea confiable según su criterio. No deberían tener que probarlo por nosotros. Deberíamos haberlo probado completamente para que nuestros tipos sean precisos. En la medida de lo posible, me gusta el paradigma llamado fuente de verdad, donde efectivamente tienes la fuente de verdad proveniente de donde algo es... del código real que procesa lo que se ejecuta en una función. En lugar de tener una función y declarar manualmente el tipo de retorno. Sé que las personas tienen diferentes puntos de vista. Prefiero permitir que TypeScript infiera ese tipo de retorno. Pero luego probarlo, como he estado diciendo. Para asegurarnos de que lo que estamos obteniendo no cambie inesperadamente, no se convierta en any, no tenga un void inesperado. Pero en lugar de escribirlo manualmente, o peor aún, usar as para hablar sobre el tipo de retorno, simplemente nos aseguramos de que lo que TypeScript está inferiendo es lo que pretendemos analizar. Eso significa que no estrechamos inesperadamente un tipo, por ejemplo. O no convertimos inesperadamente algo en un tipo cuando no teníamos la intención de hacerlo. Y luego, creo, probablemente el cambio de paradigma más significativo como autor de bibliotecas es pasar de lo que podríamos llamar un uso superficial de tipos a tipos que realmente penetren en el núcleo de tu biblioteca. Entonces, no solo describir algo. Puede que tengas un parámetro que sea una cadena. Describirlo como una cadena puede que no sea tan útil. Pasa de una cadena a un literal de cadena ya es mucho mejor porque estás diciendo que se pueden pasar estos valores específicos a mi biblioteca. Eso te permite hacer algo mucho más útil para tu usuario final. Toma este fragmento de código como ejemplo. Esto se toma y se simplifica ligeramente de una biblioteca llamada OhMyFetch. Es una capa conveniente sobre la API fetch. Una de las cosas que te permite hacer es pasar como opción qué tipo de respuesta te gustaría recibir. ¿Quieres obtener una respuesta JSON? Bueno, ese es el valor predeterminado. Pero es posible que desees acceder a un búfer de matriz o a un blob o simplemente a la cadena que se devuelve. Y queremos poder configurarlo. Pero obviamente, eso cambiará el tipo de la respuesta. Si dices que quieres un búfer de matriz, el tipo que obtienes debería ser una matriz

búfer. No debería ser otra cosa. No debería permitirte anular ese tipo con algún tipo personalizado. Y acabamos de implementar esto de manera bastante sencilla con un mapa, que a menudo es un buen patrón en TypeScript. En lugar de una cadena de extensiones, en realidad solo puedes tener un mapa y escribir un solo extends y devolver lo que deseas. Extends, por cierto, es una de las herramientas más poderosas para este tipo de personalización del que estamos hablando aquí. Y este código en particular define esas utilidades para nosotros. Entonces, aquí está el mapa entre la cadena de texto blob búfer de matriz y el tipo real que va a regresar. Luego permitimos JSON, que es un poco comodín en este caso particular, porque realmente puede ser cualquier cosa. Queremos que el usuario pueda proporcionar una anulación que coincida con lo que realmente está regresando. Y luego tenemos esta magia del tipo mapeado, que nos permite devolver si el usuario pasa, supongo que somos los consumidores de eso. Pasamos texto o búfer de matriz, va a devolver el tipo real que coincide con esa cadena. Y así, luego podemos juntarlo todo en la interfaz para fetch allí, que es lo que sea que sean esas opciones, si el tipo de respuesta es texto, obtenemos una cadena promesa. Si es un búfer de matriz, obtenemos una promesa de búfer de matriz. Y si es JSON, entonces devolvemos desconocido o permitimos que el usuario anule eso. Y así, obtenemos un conjunto predeterminado de respuestas completamente tipadas. Eso es a lo que me refiero con adentrarse en el núcleo de la biblioteca. Y estoy seguro de que eso se podría mejorar mucho. Pon un PRN si quieres. Pero ese tipo de movimiento de decir, no solo quiero devolver el tipo búfer de matriz o blob o cadena o desconocido. En realidad, quiero asegurarme de que lo que estoy devolviendo coincida de manera muy precisa, tanto como sea posible, con la cosa real que regresará dado ese conjunto de entradas a eso

función. Entonces, algunos tips, creo, para lograr eso. Entonces, uno, es un patrón muy común ahora, y creo que es necesario. Para acceder a toda la información que pueda necesitar para devolver una respuesta específica según lo que el usuario le está proporcionando, a menudo es necesario utilizar la inferencia de tipos, que es realmente utilizable a través de funciones. Entonces, una función sin operaciones que dice, bueno, el usuario está pasando algo, y no sé exactamente qué es, pero debería coincidir con el paradigma de opciones. Pero no solo diciendo que es esta interfaz de opciones, sino que la extiende, podemos hacer cosas mucho más interesantes con ella más adelante. Como decir, si esta opción es este valor, vamos a devolver esto. O si esa opción es este valor, entonces esta otra opción debe coincidir de esta manera. Entonces, es posible que necesite utilizar ese tipo de función auxiliar sin operaciones y tener una configuración definida o opciones definidas o una interfaz definida, un esquema definido. Lo que sea que esté produciendo, tener este tipo de paso intermedio donde el usuario proporciona algún tipo de entrada y lo normaliza, pero lo hace accesible para sí mismo con fines de tipo.

es a menudo realmente, realmente crucial. Muy importante. En algunos casos, vale la pena destacarlo. Los tipos pueden hacer todo el trabajo por ti. Esto puede ser donde proviene el beneficio real de tu biblioteca. Por ejemplo, tienes un objeto pasado. TypeScript es capaz de puedes escribir tipos que transmitan el comportamiento que deseas. Y luego puedes tener algo como un proxy que haga el trabajo real. Entonces, tal vez estés mapeando valores del objeto a algo más y usando una notación de puntos anidados. En realidad, puedes permitir que el tipo sea la guía para el usuario. Entonces, solo pueden escribir los tipos de cosas que coinciden con el objeto fuente. Y luego en tu código, tienes un proxy que solo observa qué valores realmente accede el usuario. Qué propiedades de el objeto a las que acceden. Y luego realmente puedes generar el código y hacer lo que ellos pretenden hacer de esa manera. Creo que eso es bastante divertido, cuando mueves el trabajo del tiempo de ejecución a la escritura de tipos. Aquí tienes un ejemplo de lo que hemos hecho en Nuxt. Entonces, en Nuxt, hemos intentado que la escritura de tipos coincida lo más posible con la realidad para el usuario. Entonces, tenemos el concepto de componentes que son accesibles en cualquier lugar de la aplicación. Entonces, mi componente debería ser accesible aquí. Y de hecho, lo es. Tenemos el tipo generado aquí automáticamente, para que el usuario pueda ir directamente a él con el complemento Vue que recomendamos. Los complementos mismos pueden inyectar valores en la instancia de la aplicación Nuxt y en la instancia de Vue para que puedan ser accedidos en la plantilla. Y nuevamente, admitimos la detección automática de tipos para eso. Entonces, el usuario puede decir, estoy inyectando Fu, y en la plantilla, lo tenemos disponible para el usuario como una propiedad que ha sido inyectada. TypeScript es un poco más inteligente cuando estás escribiendo una función. Puedes ver el valor específico que se devuelve al final, debería ser world. Lo cual, creo, es bastante genial. También tenemos rutas de API tipadas. Cuando estás definiendo un controlador de eventos en el lado del servidor de tu aplicación. Este es solo un ejemplo bastante simple con una cadena. Pero puedes tener algo

eso es mucho más complejo. Y en realidad, podemos decir, bueno, en realidad sabemos qué será el valor de retorno. Entonces, cuando obtienes ese punto final, sabemos que su respuesta será esa cadena simple. Muchos otros ejemplos. Los componibles podrían ser útiles. Tenemos un concepto de componibles importados automáticamente en toda tu aplicación. Entonces, nuevamente, hacemos que ese tipo esté disponible globalmente en toda la aplicación. Entonces, si el usuario simplemente escribe `úsame en cualquier lugar`, obtendrán la respuesta del componible real. Entonces, nuevamente, en la medida de lo posible, lo que estamos tratando de hacer es brindar ayuda y soporte para el entorno real con el que están interactuando. En este caso, su entorno, nuxt, importará automáticamente estas cosas y las pondrá a su disposición en cualquier lugar. Por lo tanto, el usuario no debería tener que hacer nada adicional para eso. Y si estás interesado en saber cómo funciona nuxt, básicamente está escribiendo declaraciones de tipo en segundo plano y exponiéndolas al editor para que el editor pueda brindar el tipo correcto de soporte mientras escribes. Lo cual creo que es bastante genial. Me encantaría responder cualquier pregunta que puedas tener al respecto más adelante. Bueno, si estás interesado en algo de lo que he estado hablando, ya sea la integración de nuxt o algunas de las herramientas que tenemos a nuestra disposición en TypeScript para brindar a los usuarios una gran experiencia al usar nuestras bibliotecas, no dudes en escribirme, seguirme en Twitter, y especialmente si estás interesado en nuxt, consulta la documentación, mira algunas de las cosas que hemos hecho con los tipos. Me encantaría explicarte eso. Síguenos en Twitter o únete a Discord y no dudes en enviarme un mensaje directo con cualquier pregunta que puedas tener. Ha sido un verdadero placer y espero que tengas un excelente resto de tu conferencia.