GraphQL SDL

TypeScript

Qué hace este conversor

Tienes un esquema GraphQL. Tu frontend está en TypeScript. En algún punto necesitas un conjunto de tipos que coincidan con el esquema campo a campo, y los necesitas ya — no después de un build de codegen de cinco minutos, no después de cablear graphql-code-generator en un proyecto nuevo, no después de explicarle a un junior qué plugin instalar. Pega el GraphQL SDL en el panel izquierdo y el panel derecho devuelve TypeScript idiomático: interface para tipos object e input, enum para enums, alias type simples para uniones y scalars.

El mapeo sigue las reglas que la mayoría del código TypeScript espera. Los scalars integrados se alinean con sus equivalentes primitivos en TypeScript: String e ID se vuelven string, Int y Float se vuelven number, Boolean se vuelve boolean. Los scalars personalizados como DateTime caen por defecto en string con un marcador // custom scalar para que recuerdes ampliarlos después. Los campos non-null (name: String!) se emiten como propiedades obligatorias; los nullable se emiten con el modificador ?. Los tipos lista [Order!]! se convierten en Order[]. type Order implements Node se convierte en interface Order extends Node — la relación de interface en GraphQL mapea limpiamente a la extensión estructural de TS.

Sin subidas, sin red, sin IA. La conversión ocurre en el cliente con un tokenizador SDL hecho a mano — tu esquema nunca sale de la página, que es lo que quieres cuando el esquema es interno o pre-release.

Cómo usarlo

Tres pasos. La conversión es automática — no hay botón Convertir.

Pega, sube o carga el ejemplo

Suelta tu SDL en el panel izquierdo GraphQL SDL. En cuanto dejas de escribir, el panel derecho se actualiza. Pulsa Subir para un archivo .graphql / .graphqls / .gql, o Ejemplo para cargar un esquema realista de e-commerce. Un fragmento de SDL se ve así:

type Order implements Node { id: ID! placedAt: DateTime! status: OrderStatus! items: [OrderItem!]! } enum OrderStatus { PENDING PAID SHIPPED DELIVERED CANCELLED }

Funcionan tanto los esquemas estilo servidor (con extend type Query) como las definiciones de tipos sueltas. Las descripciones en block-string ("""...""") se detectan y se emiten como comentarios JSDoc encima del tipo generado, que es la convención que documenta la implementación de referencia de GraphQL.

Lee el TypeScript generado

El panel derecho emite los tipos agrupados por clase: primero scalars, luego enums, uniones, interfaces, tipos input, y por último tipos object. Dentro de cada grupo, las definiciones se mantienen en el orden del fuente para que el diff contra tus tipos escritos a mano sea lo más pequeño posible. Si el SDL tiene un error de parseo (llaves desbalanceadas, un block-string sin cerrar, etc.) el panel de salida muestra un único comentario // Invalid GraphQL: ... en lugar de lanzar — el mismo patrón que Apollo Server usa cuando su parseo de arranque falla.

Copia o descarga

Pulsa Copiar para pegar los tipos directamente en un archivo schema.types.ts de tu proyecto. Pulsa Descargar para guardarlos como archivo .ts. La salida es texto plano — sin imports de módulo, sin código en runtime — así que entra en cualquier proyecto TS, frontend o backend.

Cuándo lo usarías de verdad

Tipos rápidos sin montar codegen

Estás prototipando un frontend contra un endpoint GraphQL existente y no quieres levantar todo un pipeline de codegen solo para tener tipos para tres queries. Pega el esquema, copia la salida en types.ts, despliega el prototipo. Ya pondrás un pipeline de codegen como Dios manda cuando el proyecto sea real.

Verifica qué emitirá codegen

Antes de añadir un nuevo tipo al esquema, pega el SDL propuesto aquí para ver qué forma tendrán tus llamadores en TypeScript. A veces un campo que se lee bien en SDL produce TS incómodo — una lista opcional de nullables, un enum con un valor que choca con una palabra reservada de TS — y es mucho más barato encontrarlo aquí que después de mergear el PR.

Documentar un esquema para un equipo TypeScript

¿Onboarding de un equipo TS-first a una API GraphQL? Pega el esquema, copia los tipos generados al wiki. Los ingenieros que piensan en interfaces TS captan el esquema más rápido desde una vista TS que desde SDL crudo — las formas de los datos son las mismas, la sintaxis es solo una que ya leen con fluidez todos los días.

Scripts desechables que pegan a un endpoint GraphQL

Una herramienta CLI puntual, un script de Node, una tarea de admin — cualquier cosa donde quieras tipos alrededor de la respuesta sin comprometerte con un setup completo de codegen. Pega, copia, tipa la respuesta, corre el script. Desechable, pero con tipos suficientes para no quedar mal.

Preguntas frecuentes

¿Genera tipos de operación (Query / Mutation), o solo tipos del esquema?

Solo tipos del esquema — los tipos declarados en el SDL. Los tipos de resultado de operación dependen del query o mutation concreto que un cliente ejecute, y eso es exactamente para lo que está hecho graphql-code-generator con el plugin typed-document-node. Esta página cubre la mitad del esquema: cada type, interface, enum, input, union y scalar de tu SDL se vuelve una declaración TS.

¿Cómo se manejan los campos nullable vs non-null?

Los campos non-null (name: String!) se emiten como propiedades TS obligatorias, no opcionales: name: string;. Los campos nullable (name: String) se emiten como opcionales: name?: string;. La salida queda limpia — sin uniones | null por todos lados — que es lo que la mayoría de consumidores quiere. Si prefieres strict null checks, corre un find-and-replace sobre la salida.

¿Y los tipos lista como [Order] o [Order!]!?

Las listas se vuelven arrays de TS. [Order!]! se emite como Order[] en un campo obligatorio. [Order] se emite como Order[] en un campo opcional. La nullability a nivel de elemento se colapsa por legibilidad — si necesitas preservarla puedes cambiar a mano un T[] generado a (T | null)[], pero en la práctica casi ningún codebase real lee la nullability interna por separado.

¿Cómo se manejan los scalars personalizados?

Los scalars personalizados (cualquiera que no sea ID, String, Int, Float o Boolean) caen por defecto en string con un marcador // custom scalar para que sean fáciles de encontrar y ampliar. Para un scalar DateTime podrías ampliar a string | Date; para un scalar JSON podrías ampliar a unknown o a una forma tipada. El default string coincide con lo que la mayoría de servidores envían por la red como JSON.

¿Mi esquema se envía a un servidor?

No. La conversión corre enteramente en tu navegador — el SDL se tokeniza en el cliente y la salida TypeScript se renderiza directamente en el panel derecho. No se sube nada, no se loguea nada. Es seguro pegar esquemas internos o no liberados.

¿La salida hace round-trip de vuelta al mismo SDL?

No — y no es la idea. La salida es TypeScript, que es otro lenguaje. Pegar la salida TS de vuelta en el panel SDL producirá un error de parseo. Si quieres formatear tu SDL de GraphQL, usa el GraphQL Formatter enlazado abajo; está hecho para eso.

Otras herramientas GraphQL

Generar tipos es una pieza. Estas herramientas cubren el resto del flujo de GraphQL:

GraphQL Schema a TypeScript