GraphQL Code Generator v3: ¡generar tipos GraphQL nunca ha sido tan fácil!

¡Hola a todos y gracias por estar aquí! Estoy feliz de estar aquí para hablar sobre el futuro de GraphQL Code Generator y las nuevas características que hemos agregado recientemente que brindan una experiencia de desarrollo completamente nueva. Así que empecemos. Mi nombre es Charlie. He estado trabajando a tiempo completo en Code Gen durante los últimos seis meses y especialmente en la característica que voy a presentar hoy y en la hoja de ruta próxima para Code Gen. Entonces, antes de ver esta nueva experiencia de desarrollo que Code Gen está trayendo, echemos un vistazo a la historia de Code Gen y cómo pasamos de generar tipos simples a hooks y a la nueva característica que veremos hoy. Code Gen se creó en 2016 para generar inicialmente tipos de esquema, tipos simples de TypeScript y luego, un poco más tarde, en el mismo año, generar tipos de operaciones, tanto para el backend como para el frontend. Pero la primera versión de Code Gen, antes de la 1.0, solo generaba tipos simples de TypeScript. Luego, un poco más tarde, Code Gen comenzó a admitir la generación de tipos para muchos tipos de lenguajes más allá de TypeScript y JavaScript, como Java, C Sharp, pero también Kotlin, etcétera. Y un poco más tarde, nuevamente, debido a la alta demanda en el frontend, Code Gen comenzó a generar complementos específicos del framework, como Apollo Client, Yorkle, Vue, Angular, y así sucesivamente. Code Gen, en la actualidad, es bastante famoso y está presente en la mayoría del stack de GraphQL, especialmente en el lado del cliente, con 7 millones de descargas al mes en NPM.

Y si observamos el uso popular, Code Gen es muy famoso en el lado del cliente, especialmente para el stack de TypeScript, pero también en el lado del servidor, con el stack de TypeScript, pero cualquier tipo de implementación de servidor GraphQL. Y si nos acercamos al lado del cliente, porque este es el tema de hoy, vamos a hablar sobre una nueva experiencia en el lado del cliente, vemos que, en la actualidad, la gente está muy, muy contenta con los hooks y SDK generados.

Entonces, si bien los hooks y SDK generados son muy famosos, dimos un paso atrás y también analizamos las desventajas que vienen con este enfoque en particular. En primer lugar, la limitación de los hooks y SDK generados por Code Gen es la replicación de cambios de firma. Dado que Code Gen ahora es responsable de envolver muchas bibliotecas en el lado del cliente, como React, Query, Apollo, tu llamada en React, pero tu llamada en Vue, Apple Angular, etc. Todas esas bibliotecas tienen su propia vida y cambian con bastante frecuencia y ofrecen diferentes opciones.

Por lo tanto, debemos asegurarnos de que cada vez que envolvemos una biblioteca, estamos proporcionando acceso a las opciones específicas subyacentes de cada biblioteca y estamos alineados con las diferentes versiones principales. Esto lleva a muchas solicitudes de extracción, problemas de implementación que a veces son impulsados por la comunidad y no siguen la evolución de las bibliotecas envueltas. El segundo punto es el número exponencial de opciones. Code Gen en sí mismo tiene muchas opciones para adaptarlo más, hacerlo más configurable y asegurarse de que se ajuste bien a su uso de TypeScript en su stack de GraphQL. Pero dado que estamos envolviendo bibliotecas existentes y debe ser flexible, cada complemento obtiene su propio conjunto de opciones además de las docenas de opciones que ofrecen los paquetes principales de Code Gen. Esto dificulta mucho a largo plazo asegurarse de que cada nueva opción introducida sea compatible con la existente y que la actualización o el cambio de comportamiento de las opciones existentes no traiga nada en ningún tipo de complemento que comience a divergir entre sí. Y finalmente, el último punto es el impacto en el tamaño del paquete.

Estamos en una nueva era de aplicaciones web y de front-end donde el rendimiento del paquete y el impacto en el ancho de banda son muy importantes. Y Code Gen, al generar envoltorios como SDK, pero especialmente al generar hooks, está generando todo este código solo para asegurarse de que reenviamos los tipos correctamente y verificamos los tipos de las variables. Por lo tanto, todas estas versiones llevaron a un experimento muy específico que se llama Type Document Node.

Type Document Node es un experimento que comenzó en 2020 y comenzó con una pregunta simple. ¿Qué pasaría si pudiéramos tipificar las operaciones de GraphQL sin usar hooks? ¿Qué pasaría si pudiéramos ofrecer la misma increíble experiencia de desarrollo que a todos les gusta alrededor del uso de hooks que son similares a React pero sin generar realmente hooks y usando solo tipos?

Entonces, esta es una consulta a la izquierda que devuelve una tasa, por ejemplo, para un producto, en una moneda determinada. A la derecha, este es el código que se genera mediante CodeGen cuando se utiliza el complemento TypeDocumentNode. Como puedes ver, es muy similar a los primeros días de CodeGen. Muy similar a lo que generan los complementos TypeScript y TypeScript operations. La única diferencia es que aquí usamos un TypeDocumentNode y TypeDocumentNode es un superset del objeto DocumentNode y del tipo de la biblioteca GraphQL.js y TypeDocumentNode, a diferencia de DocumentNode, está correctamente tipado al llevar el tipo de la consulta y el tipo de las variables. Y esto permite tener una integración perfecta con tu cliente. Aquí, en este ejemplo, puedes ver que simplemente importamos nuestro documento, como lo haces en cualquier aplicación, importas tu documento y lo pasas directamente a la consulta de uso de Apollo. Y de inmediato, obtienes verificación de tipos en la variable y obtienes el tipo de resultado. Entonces aquí, los datos están correctamente tipados con el tipo de consulta correcto de TypeScript operations y lo mismo con las subpropiedades. Esto ha sido posible porque Dotan y otras personas de la comunidad han estado trabajando muy duro para asegurarse de que TypeDocumentNode, esta nueva versión de tipo de DocumentNode de GraphQL.js, sea compatible con todos los clientes de GraphQL en el ecosistema de TypeScript.

A lo largo de los años, todo el trabajo realizado condujo a una integración perfecta en el ecosistema de front-end de GraphQL y TypeScript. Ya puedes usar TypeDocumentNode con Apollo Client, ReoCall, Preact, React Query, incluso en VR. Y también puedes usarlo en Svelte, Vue, etcétera.

Entonces aquí podemos ver que la visión que trajo es que primero se creó CodeGen para, ya sabes, generar tipos de TypeScript y luego se agregó soporte para otros lenguajes, lo cual sigue siendo cierto hoy en día. Pero luego comenzó a tener un enfoque muy específico inspirado en los hooks de React para generar una mejor y, ya sabes, brindar una mejor experiencia para los desarrolladores al generar más que tipos y generar código. Y ahora estamos cerrando el ciclo con una nueva experiencia para los desarrolladores que te mostraré ahora mismo. Y esto no es Type Document Node. Type Document Node es una forma estable de usarlo, pero ahora estamos trayendo una versión mejorada de Type Document Node que fue desarrollada primero como un experimento por Lauren de la Guild y ahora se ha lanzado como un complemento estable de CodeGen. Y esta nueva característica se llama el Cliente Preset.

Esta es una implementación de consulta GraphQL con Apollo Client que utiliza el nuevo Cliente Preset, la nueva experiencia para los desarrolladores de CodeGen. Aquí puedes ver que no importamos ningún tipo, no importamos ningún documento, lo único que importamos es la función GraphQL que ha sido generada para ti por CodeGen de la misma manera que importas GQL cuando estás usando Urql o Apollo Client. Y lo que sucede aquí es que esta función GraphQL que te proporcionamos va a devolver el tipo de nodo de documento adecuado a tu variable, dependiendo de la consulta que le pases. Lo que significa que, como se muestra aquí con ese nodo de documento, simplemente usando esta función GraphQL para definir tu operación, esta variable de documento va a tener un tipo, va a llevar el tipo de la consulta y la variable, y está perfectamente integrada con Apollo Client y todos los demás clientes, como se muestra. Entonces tus datos van a tener tipos y tus variables van a ser verificadas. Lo bueno de este enfoque es que ya no necesitas importar documentos o tipos. Cuando usas GraphQL en modo de observación, tus operaciones GraphQL se tipifican a medida que escribes, y finalmente el impacto en el paquete es muy ligero porque aquí solo estamos generando una función que se utiliza en todas partes y no estamos generando un gancho por consulta y solo estamos generando tipos. Entonces, todos los tipos se eliminan en tiempo de ejecución y lo único que queda es en realidad la consulta GraphQL. Si realmente quieres tener un impacto en el paquete de cero con este nuevo cliente preset, puedes usar el complemento de Babel que proporcionamos y que está documentado, que eliminará la función GraphQL en tiempo de ejecución, lo que significa que tendrás una experiencia de operación con tipos de extremo a extremo sin ningún impacto en el tiempo de ejecución.

Entonces, hablemos ahora de otra cosa que está siendo introducida por el cliente preset, que es el fragment masking. En el Guild y en todos los proyectos que mantenemos, tratamos de llevar las mejores prácticas al ecosistema y no solo lo que creemos que es lo mejor para nosotros. Estamos tratando de mostrarles cuál es la mejor manera de trabajar con GraphQL en términos de manejo de errores y también de tipificación. Y aquí, el fragment masking no es una práctica muy conocida en el ecosistema de GraphQL y creemos que debería recibir más atención y reconocimiento del ecosistema. Por lo tanto, esta nueva función de Codegen está tratando de brindarte una forma de usar el fragment masking de manera muy sencilla. Así que hablemos de los fragmentos en GraphQL. La mayoría de nosotros usamos fragmentos para descomponer las consultas en modelos de datos. Básicamente, tomamos un tipo y creamos subtipos del tipo existente para poder usarlos en nuestros componentes, etc. La cuestión es que al hacerlo, aquí realmente no sabemos, tenemos una interfaz de usuario a la derecha que muestra un documento y el título es parte del componente principal, pero el acini es un componente y las etiquetas también son un componente independiente, y aquí, al mirar la consulta, no está muy claro qué parte de los datos va a ser utilizada por qué componente. Lo que dificulta saber qué datos utiliza un componente simplemente mirando un componente sin ver todo el árbol de componentes o al menos mirar el componente principal que carga los datos. Esto es exactamente lo que ofrece el fragment masking. El fragment masking es un concepto introducido por el equipo de Relay, el creador inicial de GraphQL, que dice que los fragmentos no deben usarse para descomponer las consultas en modelos de datos. Deberíamos usar fragmentos para representar las diferentes vistas de nuestra aplicación y, por vistas, nos referimos a componentes. Entonces, cada fragmento debe representar qué datos utiliza un componente. Pongamos eso en práctica. Aquí tenemos la misma consulta pero la hemos cambiado. Dado que tenemos un componente para el documento, vamos a crear un fragmento superior para nuestro componente principal y este componente principal solo necesita el título y el id para las diferentes acciones. Entonces, aquí el fragmento principal para la vista del documento va a tener el título, luego el asignado, y este componente está instanciando dos componentes, uno para el asignado y otro para las etiquetas, por lo que vamos a tener dos fragmentos que realmente expresan cuáles son las dependencias de datos de nuestro componente secundario. Sí, tenemos la vista del documento que instancia el asignado, mostramos el título, instanciamos el asignado y las etiquetas, y cada subcomponente tiene su propio fragmento que está colocado junto con el componente en sí. Veamos un ejemplo concreto porque es muy teórico. Aquí tenemos nuestros ajustes preestablecidos del cliente con una nueva configuración de TypeScript de CodeJam, tenemos un esquema que es local porque este es un ejemplo, obtenemos todos los documentos de TypeScript y usamos un nuevo cliente preestablecido. Aquí tenemos nuestra aplicación, que es una aplicación ficticia con solo el propósito de mostrar el concepto de fragment masking. Aquí tenemos nuestra consulta de documento, nuestro fragmento de vista de documento porque estamos en los componentes de documento. Y aquí, dado que este es el componente principal, será el que realice la consulta. Hacemos la consulta y, como te dije, aquí con los ajustes preestablecidos del cliente, obtenemos la verificación de etiquetas de inmediato. Aquí se queja de que el número no se está asignando correctamente a una cadena. Y como puedes ver, no estamos importando ningún tipo de documento o tipo. Solo estamos importando la función GraphQL en todas partes. Luego decimos, está bien, estamos en la vista del documento, por lo que usamos una función especial expuesta generada por GraphQL code gen para extraer los datos.