Cómo hacer nuestros CLIs más seguros con tipos

Hola a todos, y bienvenidos a esta charla sobre cómo hacer nuestro CLI más seguro con TypeScript. Mi nombre es Mayr Neonaysan. Trabajo en Datadog como parte del equipo de desarrollo front-end, donde estamos construyendo todo tipo de herramientas para asegurarnos de que nuestros ingenieros front-end puedan ser tan eficientes como deseen ser. Puedes encontrarme en Twitter y GitHub como Arkalis, y sí, espero verte allí.

Entonces, primero, sobre esta charla, la vamos a dividir en cuatro partes diferentes. Primero, vamos a hablar sobre qué son los CLIs, cuáles son los problemas que enfrentamos al construir ellos. Luego vamos a ver algunas técnicas que podemos usar en TypeScript para hacer una mejor inferencia sobre el tipo de las opciones. Y finalmente, vamos a repasar algunos de los frameworks que ya hacen eso por nosotros antes de llegar a una conclusión y recapitular todo lo que aprendimos. ¿Suena bien? Entonces, primero, ¿cuáles son los problemas que enfrentamos al construir CLIs? ¿Qué son los CLIs? En su esencia, son solo un conjunto de palabras separadas por espacios.

Son muy simples de leer y muy simples de implementar por lo general. Los utilizamos para parametrizar acciones, que pueden ser tan complicadas como una aplicación CLI completa como YARN, o algo mucho más simple como un script que estás utilizando dentro de tu pipeline de construcción. Lo que tienen en común es que suelen ser muy simples. En comparación con las aplicaciones de UI completas, requieren muy pocas plantillas, lo que los hace muy útiles si solo estás tratando de hacer que un par de comportamientos sean configurables.

Sin embargo, también pueden ser complicados. Por ejemplo, tomemos npm run eslint ____ versión. Si no usas el token ____ para separar eslint y el token de versión, terminarás ejecutando la opción de versión en npm mismo y no en eslint. Sin embargo, si estás ejecutando YARN, no tienes que usar este token ____. Pero para hacer eso, como veremos más adelante, las cosas comienzan a complicarse.

El comando cp parece simple. Sin embargo, a diferencia de muchos comandos donde la cantidad de parámetros o argumentos variádicos está al final del comando, en el caso de cp, está al principio del comando. Tienes slc1, slc2, cualquier número de otras fuentes, pero debes tener un destino al final. Por lo tanto, la posición requerida de los argumentos está al final en lugar de al principio. Tienes el comando arm que tiene la opción preserve-root, pero también tiene la opción "-no-preserve-root". Y si estás implementando algo como esto en tus scripts, generalmente quieres declarar ambas opciones en una sola, para no tener que duplicarlas. Y finalmente, tomemos el caso de vlc-v. Si miras este comando y no sabes nada más al respecto, pensarías que "-v" es en realidad una bandera booleana. Pero no lo es. Si ejecutas vlc-vvv, no obtendrás el mismo comportamiento que si estuvieras ejecutando vlc-v. Porque vvv es en realidad un contador. Cuenta la cantidad de veces que lo pasas al comando.

Ahora, hablemos del CLI de Yarn en sí. Es muy interesante, porque el CLI de Yarn es una de las interfaces de CLI más grandes que todos usamos en el ecosistema de JavaScript. Cada uno tiene más de veinte comandos, y cada uno de ellos acepta opciones, y tenemos algunos comportamientos muy específicos como vimos anteriormente. Al principio, se comenzó a utilizar Commander JS, que es un framework de CLI para JavaScript que admite subcomandos, y eso es algo muy importante para Yarn, porque Yarn add, Yarn remove, Yarn upgrade interactúan contigo, todas esas cosas son comandos de la aplicación principal. Sin embargo, decidimos eventualmente hacer que la palabra clave run fuera opcional, para que pudieras ejecutar Yarn eslint en lugar de Yarn run-eslint, y eso no era algo que Commander JS admitiera de forma nativa. Así que tuvimos que implementar nuestro propio código para admitir eso. Luego, más adelante, decidimos también hacer que el token dash dash fuera opcional, para que si ejecutas Yarn eslint dash dash versión, entonces la versión de dash dash se aplique a eslint y no a Yarn mismo. Eso es muy útil. Sin embargo, requirió implementar algo más encima de Commander JS.

Por ejemplo, en un par de casos cuando trabajaba en Jan, sucedió que en algún momento del desarrollo de una función agregué una opción, trabajé con ella por un tiempo y luego decidí eliminarla antes de gestionar la solicitud de extracción. Sin embargo, puede que haya olvidado eliminar el código en el que se basaba. O podría haber eliminado el código en el que se basaba esta opción, pero olvidé eliminar la opción de la declaración real del comando, lo que significa que alguien que ejecute el comando de ayuda vería que esta opción existe pero en realidad no estaría allí.

Entonces, en 2018, cuando comenzamos con un proyecto a gran escala para reescribir Jan y hacerlo totalmente compatible con TypeScript, decidimos desechar varios de nuestros sistemas heredados, y uno de ellos fue la implementación de la CLI. Así que comenzamos a buscar lo que existía y, desafortunadamente, no encontramos realmente nada que resolviera todos nuestros requisitos. Necesitábamos algo con buena legibilidad porque teníamos muchos colaboradores que se sumarían al código sin conocimiento previo de lo que estábamos usando. Necesitábamos algo que estuviera totalmente verificado por tipos porque queríamos prevenir tantos errores como fuera posible sin tener que depender de revisiones de código manuales, porque notamos que en cada revisión de código siempre hay algo que pasa desapercibido. Y finalmente, queríamos protegernos realmente contra errores. Queríamos que el camino del éxito estuviera allí. Si no estás familiarizado con el concepto, el camino del éxito es que cualquier cosa que hagas, caerás en un comportamiento de comando. Y luego, si puedes mejorarlo más tarde, pero por defecto todo es sensato y funciona como esperas. Y realmente tienes que esforzarte para hacer algo que esté roto.

Entonces hablamos de las CLI en términos abstractos. Y en el caso de YARN, lo que necesitábamos construir. Así que decidimos construir nuestro propio marco y al hacerlo aprendimos muchas cosas. Así que eso es lo que vamos a hacer juntos. Construyamos un marco de CLI totalmente tipado desde cero. Por supuesto, nos vamos a enfocar solo en el aspecto de verificación de tipos y no en la implementación de cómo analizar los argumentos porque eso sería mucho más que una charla de 25 minutos. Pero en cuanto a la verificación de tipos, tenemos tres formas de lograr estos efectos. Primero, podemos usar metacadenas, podemos usar decoradores y podríamos usar lo que llamo la tercera forma. Vamos a dejar esta para el final porque es bastante interesante, pero primero necesitamos repasar las dos primeras para entender mejor por qué es tan bueno. Así que primero hablemos de las metacadenas. Es la más simple, de hecho, es la misma sintaxis que usa Commander.js y eso es algo bueno porque significa que es familiar para cualquiera que solía hacer interfaces de CLI hace un par de años. Tienes un comando y luego declaras las opciones combinando los resultados de la función del comando y una vez que has declarado todas las opciones, puedes declarar qué hace el comando. Y luego el marco de CLI, cuando se llama al comando, analizará las opciones y llamará a la acción pasándole un OptionBug que contiene todas las opciones que se analizaron. Para esta charla, vamos a fingir que las opciones siempre están configuradas porque de lo contrario, todas las cosas como obd.check serían booleanas o indefinidas en lugar de solo booleanas y eso haría que el código fuera más difícil de leer. Pero aquí lo que queremos lograr es un estado en el que obd.check exista y sea un booleano, obd.require exista y sea una cadena y obd.foo sea detectado correctamente por TypeScript como que no existe y eso es lo importante. No podemos tener obd como any. Eso no funcionaría para nosotros. En términos de TypeScript, ¿cuál sería el tipo del valor resultante de la función del comando? Primero, queremos algo que devuelva un comando sin opción, porque no declara ninguna opción.

Entonces, tan pronto como llamamos a boolean, esta vez el comando es un genérico con una propiedad check que es un booleano. Y luego, una vez que llamamos a la función string, el comando se devuelve como un genérico con tanto check como require. Y finalmente, cuando tenemos action, simplemente toma una devolución de llamada que acepta la bolsa de opciones como parámetro y devuelve void.

Al hacer eso, permitimos que TypeScript infiera correctamente cuando pasamos la devolución de llamada de acción que el tipo OPITIZ está compuesto por la opción que declaramos anteriormente. Para hacer eso, es muy simple, realmente. Eso es todo lo que necesitamos.

Entonces tenemos nuestra interfaz de comando con su tipo genérico, que se establece en void de forma predeterminada, y declaramos tanto Boolean como string como una función que toma una cadena literal como parámetro. Incluso usamos algún tipo de concatenación de cadenas como tipos, porque una versión reciente de TypeScript lo admite. Y cada vez que llamamos a Boolean o string, devolvemos el mismo tipo de comando, excepto que lo extendemos para incluir la opción recién declarada. Y finalmente, tenemos la función action que, como mencionamos, permite que TypeScript infiera el tipo de OPDs en función del propio genérico.

Este enfoque tiene ventajas y desventajas. Es lo suficientemente fácil de escribir. Claramente, no hay mucho código involucrado, como puedes ver. Se siente un poco como en 2017, porque la mayoría de los marcos de CLI de ese tiempo estaban escritos de esta manera, encadenando funciones, una tras otra. Esto significa que si ya estás familiarizado con este tipo de marco, entonces es exactamente lo que esperarías. Sin embargo, es un poco variable. Tienes que usar muchas funciones para declarar tus opciones. No es muy idiomático. Estás usando el encadenamiento de métodos, algo que no se encuentra en muchas interfaces de JavaScript. Por lo tanto, las personas que ingresen a tu código pueden encontrar esto un poco difícil de leer. Y tiene una integración deficiente con las herramientas. Y este es el principal del que quiero hablarles. Veamos el encadenamiento de métodos aquí. Como puedes ver, estamos declarando un comando con una opción de cadena. Y tenemos una acción aquí, que imprime una cadena con el nombre de la persona que ejecuta el comando. Pero ¿lo hace realmente? En realidad, no, no lo hace. Olvidamos usar opent.name. Pero TypeScript no puede ver eso, porque desde su perspectiva, tal vez la bolsa de opciones que se pasa del parámetro a la acción también se usa en otro lugar. Por lo tanto, no es local. Por lo tanto, la verificación de variables no utilizadas no podrá ver que olvidamos usar eso.

Entonces, eso es a lo que me refiero con la integración de ajuste. Dado que estamos evitando un poco la declaración de variables locales y ese tipo de cosas, no podemos verificar tan fácilmente que nuestro código sea correcto. Tenemos una segunda opción para hacer eso: los decoradores. Los decoradores son interesantes porque utilizan una nueva sintaxis que ha aparecido muy recientemente. Ahora está en la etapa tres. Hasta entonces, era difícil saber si podíamos usarlos o no. Con los decoradores, adjuntas anotaciones sobre cada propiedad de tu clase. Al hacer eso, puedes atribuir metadatos especiales y lógica especial a esas propiedades.

En teoría, podríamos imaginar algo como esto, donde declaramos una clase para nuestro comando. Luego declaramos las opciones. Y luego adjuntamos una anotación que declara si la verificación, por ejemplo, es una opción booleana o una opción de cadena, como require. Y eso es mucho mejor que el encadenamiento de metadatos en términos de integración de ajuste. Porque esta vez, tenemos propiedades de clase regulares, que se declaran como privadas. Por lo tanto, TypeScript sabe que no se van a utilizar en ningún otro lugar de este archivo. Si no se utilizan en este archivo, significa que hay un problema y te advertirá al respecto.

Además, sí, ese es el ejemplo al que me refería. Si no estás usando name, entonces TypeScript emitirá un error. Sin embargo, los decoradores tienen un par de problemas de los que debemos hablar. En primer lugar, tienen una historia complicada. Hay dos tipos diferentes de decoradores: los decoradores antiguos y los decoradores nuevos, porque los decoradores han pasado por varias etapas y tienen varios diseños. Por lo tanto, si tienes una biblioteca que depende de decoradores antiguos en tu código base, entonces no puedes usar los decoradores nuevos. Y si tienes una biblioteca que utiliza los decoradores nuevos, entonces no puedes usar bibliotecas con soporte para todos los decoradores. También significa que necesitas tener pasos de transpilación compatibles. Como vimos, hay pasos de transpilación antiguos y pasos de transpilación nuevos. Por lo tanto, es un poco difícil conciliarlos. Y quizás el mayor problema es que no pueden afectar a los tipos. Si tomamos nuevamente el ejemplo que escribimos aquí, tenemos la opción check que es un booleano y la opción string y la opción require que son de tipo cadena.

Sin embargo, TypeScript no puede inferir que el tipo de check es booleano y el tipo de require es cadena, a pesar de la anotación. Lo que debemos hacer es establecer explícitamente que check es un booleano y require es una cadena. Esto significa que tenemos cierta duplicación, ya que tenemos que escribir booleano dos veces, cadena dos veces. No es ideal. Además, ¿qué sucede si cometemos un error y establecemos booleano en lugar de cadena al declarar la opción require? Resulta que tenemos alguna forma de evitar eso, pero aún existe el problema de duplicación. Y requiere mucho código solo para asegurarnos de que TypeScript esté satisfecho.

Idealmente, querríamos algo donde no tengamos que duplicar tanto la declaración como los tipos. ¿Cómo podemos hacer esto? Eso es lo que llamo la tercera forma. Con la tercera forma, en lugar de asignar la anotación como decoradores, simplemente los asignamos a la propiedad. Entonces aquí, tenemos nuestra clase de comando. Tenemos nuestras opciones de check y require. Y para cada una de ellas, simplemente asignamos el resultado de un valor booleano y una cadena. Y una vez que se llama a la acción, es mágico. Todo funciona perfectamente. TypeScript es capaz de inferir el tipo de check y require, y nunca tuviste que declararlos tú mismo. Parece lo mejor de ambos mundos, ¿verdad? Esto es cómo se vería en términos de configuración.

Entonces tendrías tu array argv, instanciarías tu comando, inyectarías opciones en el comando, y luego simplemente funciona. Puedes llamar al método de acción como quieras. Pero ¿cómo funciona realmente, verdad? Porque parece demasiado bueno para ser verdad. No hay una transpilación compleja. Está directamente en el AST, por lo que cosas como TypeScript o ESLint pueden operar muy fácilmente en él y verificar que todo coincida con tus requisitos. Y no tienes duplicación de tipos como vemos en los decoradores. Eso es extraño.

Ahora vamos a profundizar un poco para entender cómo es posible. Primero, nos vamos a centrar en la implementación de las funciones Boolean y String. ¿Cómo se ven? Bueno, son muy simples, son solo funciones que devuelven un Boolean y un String. ¿Pero lo son? No, en realidad son funciones que devuelven un conjunto de metadatos que se hacen pasar por el tipo que queremos al final. Por ejemplo, aquí tenemos Boolean que devuelve el objeto de tipo Boolean. Pero eso le dice a TypeScript, no, en realidad es un Boolean, te lo prometo. Usamos as any para aligerarlo para el comprobador de tipos. Eso puede parecer extraño.

No, en el código de configuración, en el código de configuración, lo siento, vimos que tenemos una función inject options into command. ¿Cómo funciona? Este es el código general de esta función. Para cada argumento, vamos a eliminar las dobles barras y vamos a recuperar los metadatos que están asociados a la opción. Como vimos anteriormente cuando hacemos check igual a Boolean o require igual a string, estamos asignando un objeto que contiene una propiedad de tipo. Aquí, simplemente estamos recuperando este objeto. Dado que hemos tipado el comando como any dentro del parámetro de inject options into command, TypeScript nos permitirá hacer esto. Y ahora que tenemos el tipo, todo lo que tenemos que hacer es asignar el valor real a la opción, que coincide con el tipo que los metadatos prometieron que sería. Y al hacer eso, funciona. En otras palabras, le mentimos al comprobador de tipos, pero es por una buena causa, así que está bien. Incluso nos permite hacer cosas más complejas, como la validación de formato. Tomemos una función de opción que devuelve un string, al igual que la anotación de string que declaramos anteriormente. También podemos agregar sobrecarga para que acepte validadores. En TypeScript, tienes diferentes validadores que te permiten verificar en tiempo de ejecución que un valor específico tenga un tipo específico, y luego para el resto de tu código, tratarlo como el tipo correcto que validas. Tienes dos bibliotecas que hacen eso. Entonces tienes Tpanion y Zod que son compatibles con TypeScript.

Entonces tienes un Tpanion y Zod que son compatibles con TypeScript. Y podemos integrarlos con la sintaxis que describimos. Dado que ambas bibliotecas ofrecen un tipo que tiene un genérico en el tipo que ha sido verificado por el tipo, todo lo que tienes que hacer es decirle a TypeScript que tu función de opción acepta un validador que devuelve algo. Y a cambio, una vez que se analiza la opción, será este mismo tipo y simplemente funcionará. Por ejemplo, aquí con T-Banyon, estamos declarando una opción que tiene un validador que verifica que el argumento sea un número. Y luego, dentro de la acción, TypeScript infiere correctamente que count es un número.

Esta tercera forma tiene pros y contras como las otras. En primer lugar, no requiere ninguna sintaxis especial. Son solo clases y propiedades, por lo que requiere lo mínimo de las características de ES. También admite genéricos como vimos. Es bastante fácil escribir código que infiere el tipo resultante en función del parámetro proporcionado a la anotación. Funciona muy bien con ESLint y Prettier. La sintaxis es agradable de leer. Y finalmente, toda la complejidad está completamente oculta dentro del núcleo. No tienes que lidiar con nada especial para entender cómo estás declarando tus opciones de CLI. No tienes que preocuparte por nada, incluso si algo es requerido. Por ejemplo, si quieres declarar un argumento posicional requerido, eso es algo que se abstrae dentro de la declaración de los argumentos posicionales, pero los usuarios no tendrán que preocuparse por ello para que el tipo funcione de inmediato.

La desventaja es que nos estamos alineando un poco con TypeScript, por lo que puede sorprender a las personas que son usuarios avanzados de TypeScript y pueden esperar algo y no entender por qué no funciona como esperaban. Además, la composición es un poco más difícil porque luego tienes que envolver la anotación dentro de otra. Pero por lo general, en mi experiencia, la composición es bastante rara en las CLI, por lo que esto nunca ha sido un problema en la CLI en la que trabajé.

Entonces, ahora hablemos de las opciones que tienes al escribir herramientas de CLI. Cuando hablo de YARN y digo que lo mejoramos, terminamos escribiendo nuestro propio marco de CLI. Así que primero, voy a hablarles de este. Es ClipAnion y te permite hacer algo muy similar a la tercera forma que describí anteriormente. Tienes una clase de comando, tienes un espacio de nombres de opciones que contiene un montón de anotaciones, y tienes la función runExit() que te permite ejecutar tu programa real. Aquí estás declarando un comando que contiene un par de opciones, check y require. Y los estás asignando a una opción que es un booleano o una cadena, con todos los nombres de opciones que desees. Y finalmente, TypeScript es capaz de inferir sus tipos gracias a todas las sobrecargas que ClipAllian declara y asegurarse de que se sigan durante el análisis de la CLI. De hecho, aquí puedes ver que esta vez agregamos el or-undefined() porque una opción puede estar configurada o no estar configurada. Si no está configurada, entonces debe ser un booleano, en caso de que esté configurada, o indefinido.

También admite validadores a través de ClipAllian, a través, perdón, a través de TipAllian, que es el validador de tipos, el validador de tipos en tiempo de ejecución que mencioné antes. Entonces, si tienes una opción de cadena, también puedes validar que su formato sea realmente un número, en cuyo caso TypeScript refinará correctamente el número para que sea un número en lugar de una cadena. ClipAllian admite muchas cosas. Es el marco que estamos utilizando en la CLI de Yarn, que hace muchas cosas diferentes. Admite argumentos posicionales opcionales, argumentos posicionales requeridos, argumentos posicionales de tarjeta. Por ejemplo, cuando ejecutas Yarn ESLint y aceptas opciones, eso es una tarjeta porque estamos aceptando cualquier cosa. Admite booleanos, cadenas, matrices, tablas, contadores. Implementa el análisis de los tokens de la CLI a través de una máquina de estados, lo cual es algo muy único. Significa que simplemente estamos generando una máquina de estados completa con poco margen para errores. Muchos marcos de CLI en la actualidad intentan analizar los tokens uno por uno a través de un bucle for, básicamente. Pero corres el riesgo de tener muchos errores. También nos permite admitir sobrecargas. Por ejemplo, puedes tener comandos diferentes con la misma ruta pero opciones o requisitos diferentes. ClipAllian podrá determinar cuál es el que debe usar, dependiendo de lo que el usuario haya proporcionado. Manejo de errores nativo, anulación de tiempo de ejecución baja y, por supuesto, es completamente seguro en cuanto a tipos. Por ejemplo, dada la siguiente declaración de comando, podrá refinar correctamente los tipos según lo que declares. Por supuesto, hay una opción regular que es booleana, que es booleana o indefinida. Pero también puedes asignar un valor predeterminado, en cuyo caso ClipAllian verá que, dado que hay un valor predeterminado, ya no puede ser indefinido. También puedes declarar una opción opcional que acepta una cadena como argumento, en cuyo caso será una cadena o indefinida, pero también puedes marcarlas como requeridas, en cuyo caso serán una cadena, porque son requeridas y si no están presentes, ClipAllian lanzará un error. También puedes declarar tuplas usando la opción ret. Tienes muchas opciones diferentes y cada vez ClipAllian hace lo correcto y realiza una comprobación de tipos adecuada. Pero también tienes otras herramientas que hacen lo mismo con sintaxis ligeramente diferentes. Primero, tienes Common.js, por supuesto, que es el más antiguo y realmente admite muy bien los tipos utilizando el paquete de typings adicionales. Funciona igual que la metacadena que vimos anteriormente. Y también tienes Oclif que tal vez sea un poco más verboso pero funciona de manera similar a ClipAllian. Eso es casi todo. ¿Qué debes recordar de esta charla? Quiero que recuerdes un par de cosas. Primero, TypeScript es una gran herramienta para los autores de CLI, incluso para las CLI internas. Cuando estás escribiendo CLI, escribiendo una aplicación dentro de una empresa, es posible que te tientes a usar TypeScript para todo lo relacionado con tu plataforma web, pero noté que muchos scripts comienzan escribiendo JavaScript, porque no se necesita transmutación. Sin embargo, si estás utilizando herramientas como TS Node, esto ya no es un problema. Puedes ejecutar tu código directamente desde las fuentes de TS sin tener que transpilarlo antes y eso es algo genial porque significa que podemos tipar correctamente el script de construcción que estamos utilizando en nuestra infraestructura. A través de un mecanismo como el que discutimos con ClipAllian, con Oclif, este tipo de cosas, significa que también puedes asegurarte de que tus scripts estén bien escritos y acepten las opciones adecuadas que esperas. La próxima vez que escribas una CLI interna, considera usar TypeScript para eso y considera usar un marco de CLI porque realmente facilitan mucho tu trabajo y evitan que cometas errores. Tienes diferentes sintaxis que puedes elegir según tus preferencias en términos de sintaxis. Vimos la metacadena, los decoradores y la tercera forma. Las nuevas características aún no están completamente listas por las razones que mencioné antes, especialmente en cuanto a la necesidad de duplicar tus tipos tanto en la anotación como en el tipo de TypeScript, pero creo que mejorarán en los próximos años, así que eso también es algo que debes tener en cuenta para el futuro. Finalmente, recuerda que ClipAllian está ahí, ha estado en producción durante muchos años, y pruébalo para tu próxima CLI. Gracias a todos, puse el enlace en la pantalla, siéntanse libres de revisar todo lo que hice para esta charla, y estoy aquí para responder sus preguntas. ¡Que tengan un buen día!