Gerador de GraphQL para TypeScript

Gerador de GraphQL para TypeScript

Converta esquemas SDL e consultas GraphQL em tipos, interfaces, enums e resolvers TypeScript. Codegen instantâneo no navegador, sem configurações ou envio ao servidor.

Modelos
Ecossistema Alvo de Codegen
Origem do Esquema GraphQL (SDL / Introspecção JSON)
Mapeamento Rápido de Escalares:
Exportação Pronta para Produção
12Nodes
AST Architecture
Object: 6Interface: 1Enum: 1Input: 1
83%Strict
Nullability Guard

High non-null strictness (safe against unexpected runtime undefined).

AST de Esquema Válido
/**
 * Strongly Typed GraphQL TypeScript Artifacts
 * Generated via ToolsAA In-Browser Codegen Engine [Regime: strict-modern]
 * 100% In-Browser AST synthesis - Zero server upload
 */

type Maybe<T> = T | null;

type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };

/** All Built-In & Custom GraphQL Scalars */
type Scalars = {
  DateTime: string;
};

type Scalars = {
  JSON: Record<string, unknown>;
};

type Scalars = {
  Money: number;
};

type ProductStatus = 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'OUT_OF_STOCK';

type Node = {
  __typename?: string;
  readonly id: string;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type MoneyAmount = {
  __typename?: 'MoneyAmount';
  readonly amount: number;
  readonly currency: string;
};

type ProductVariant = {
  __typename?: 'ProductVariant';
  readonly id: string;
  readonly sku: string;
  readonly title: string;
  readonly price: MoneyAmount;
  readonly inStock: boolean;
  readonly inventoryQuantity: number;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Review = {
  __typename?: 'Review';
  readonly id: string;
  readonly author: string;
  readonly rating: number;
  readonly comment: Maybe<string>;
  readonly metadata: Maybe<Record<string, unknown>>;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Product = {
  __typename?: 'Product';
  readonly id: string;
  readonly title: string;
  readonly slug: string;
  readonly description: Maybe<string>;
  readonly status: ProductStatus;
  readonly price: MoneyAmount;
  readonly variants: ReadonlyArray<ProductVariant>;
  readonly reviews: ReadonlyArray<Review>;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Query = {
  __typename?: 'Query';
  readonly product: Maybe<Product>;
  readonly products: ReadonlyArray<Product>;
};

type Mutation = {
  __typename?: 'Mutation';
  readonly createProduct: Product;
  readonly deleteProduct: boolean;
};

type CreateProductInput = {
  readonly title: string;
  readonly slug: string;
  readonly description?: Maybe<string>;
  readonly price: number;
  readonly currency?: Maybe<String = "USD">;
  readonly status?: Maybe<ProductStatus = DRAFT>;
};
Tipos12
Campos40
Enums1
Uniões0
Escalares3
Tempo de Execução< 1ms
Referência técnica e guia de arquitetura

Gerador GraphQL para TypeScript — Guia de referência

Converta schemas SDL e queries GraphQL em tipos, interfaces, enums e resolvers TypeScript. Codegen instantâneo no navegador sem configuração ou upload para servidores.

Gerador GraphQL para TypeScript — Guia de referência — Arquitetura em memória do lado do cliente e fluxo de dados
Gerador GraphQL para TypeScript — Guia de referência — Arquitetura em memória do lado do cliente e fluxo de dados

Parâmetros-chave e controles

Origem do Schema GraphQL (SDL vs. JSON de Introspecção)Documento de Definição de Schema (Entrada AST)

Texto padrão em GraphQL Schema Definition Language (SDL) ou resposta serializada em JSON da Introspecção (objeto raiz __schema). Compatível com a gramática da especificação oficial GraphQL de outubro de 2021.

Padrão: Schema Definition Language (SDL)
Estratégia de Nulabilidade e OpcionalidadeModo de Nulabilidade do Compilador (Enum)

Mapeia campos GraphQL não nulos (!) e anuláveis para expressões de tipos TypeScript. Controla se campos anuláveis geram 'T | null', 'Maybe<T>' ou propriedades opcionais 'field?: T' sob strictNullChecks do TypeScript.

Padrão: Maybe<T> = T | null | undefined
Paradigma de Declaração de TiposSintaxe de Emissão de Tipos (Enum)

Define se os tipos Object do GraphQL são compilados como type aliases ('type') ou declarações de 'interface' do TypeScript. Type aliases suportam unions e acesso indexado; interfaces viabilizam declaration merging em SDKs extensíveis.

Padrão: type (Type Aliases)
Formato de Compilação de EnumsRepresentação de Enum (Enum)

Controla se enums GraphQL compilam para objetos runtime 'enum' nativos do TypeScript ou uniões de literais de string tree-shakable ('ADMIN' | 'USER') acompanhadas de dicionários const.

Padrão: String Literal Union
Mapeamento de Escalares Customizados (ScalarMappingDictionary)Dicionário (Record<string, string>)

Resolve escalares GraphQL customizados para tipos TypeScript concretos. Mapeamentos padrão: ID para 'string', Int para 'number', Float para 'number', String para 'string', Boolean para 'boolean', DateTime para 'string | Date'.

Padrão: DateTime: string, JSON: Record<string, unknown>
Modificador Imutável / Readonly ArrayFlag de Imutabilidade (Boolean)

Quando ativo, injeta o modificador 'readonly' em cada campo de objeto e envolve arrays em 'ReadonlyArray<T>', impondo imutabilidade em tempo de compilação para stores de estado Redux e Zustand.

Padrão: true

Dicas profissionais e melhores práticas

Armadilha Universal da Nulabilidade: Campos Anuláveis no GraphQL vs. Undefined no TypeScript

No GraphQL, um campo de saída anulável sem exclamação retorna null explícito quando não preenchido, nunca undefined. No TypeScript, declarar 'field?: string' permite undefined, mas rejeita null explícito sob strictNullChecks. Para tipos de resposta no cliente, sempre gere 'field: Maybe<string>' (string | null) em vez de 'field?: string', prevenindo exceções de TypeError em tempo de execução ao acessar payloads do servidor contendo valores null.

Evite Enums Numéricos Nativos: Use Uniões de Literais de String para Zero Overhead de Runtime

O 'enum' nativo do TypeScript gera um objeto JavaScript IIFE de busca bidirecional em tempo de execução que não pode ser eliminado por tree-shaking em bundlers modernos (Vite, Rollup, esbuild). Em aplicações cliente, gerar 'type UserRole = "ADMIN" | "MEMBER"' combinado com um array congelado com 'as const' elimina 100% do overhead no bundle final, mantendo autocompletion idêntico e type narrowing mais estrito.

Mascaramento de Fragmentos com TypedDocumentNode em Vez de Wrappers Genéricos de Query

Em vez de emitir tipos monolíticos de resultado de query e realizar type casting manual nas respostas de fetch, gere instâncias de TypedDocumentNode<ResultType, VariablesType>. Clientes GraphQL modernos (Apollo Client 3.7+, urql e graphql-request) inferem automaticamente a estrutura dos dados retornados e as variáveis obrigatórias diretamente a partir do document node, eliminando type parameters explícitos.

Distinga Tipos de Serialização de Rede de Modelos de Domínio em Memória

Escalares customizados como DateTime, JSON e BigInt trafegam na rede como strings JSON ou números brutos. Se o seu codegen mapear 'DateTime' para 'Date' do JavaScript, buscar dados com o JSON.parse() padrão deixará o campo como string, quebrando chamadas de métodos de data em runtime (por exemplo, date.toISOString() is not a function). Use 'string' para tipos de resposta trafegados na rede e reserve 'Date' para modelos de domínio convertidos por transformers de desserialização.

Armadilhas comuns e solução de problemas

⚠️Erro de Compilação TypeScript TS2322: O tipo 'null' não pode ser atribuído ao tipo 'undefined' em objetos de entrada gerados

Objetos de entrada (input objects) no GraphQL tratam campos omitidos como undefined, enquanto null explícito representa uma limpeza intencional de valor. Habilite exactOptionalPropertyTypes no tsconfig.json e configure a estratégia de input do codegen para emitir 'field?: string | null' em argumentos de entrada, distinguindo a omissão de uma chave do envio explícito de um payload null.

⚠️Profundidade de referência circular excede o limite do compilador TypeScript em schemas recursivos profundos

Estruturas de schema autorreferenciadas (como Comment -> replies: [Comment!]! ou Category -> children: [Category!]!) podem disparar o erro TS2589 de instanciação de tipos infinitamente recursiva. Resolva emitindo as definições de tipo como declarações de 'interface' em vez de aliases 'type' recursivos aninhados, aproveitando a resolução tardia (lazy property resolution) de interfaces do TypeScript.

⚠️Syntax Error: Unexpected token in JSON at position 0 ao colar resultados de Introspecção

Certifique-se de colar o payload JSON completo contendo a chave raiz '__schema' ou 'data.__schema'. Se a query de introspecção foi extraída via curl ou Postman, remova cabeçalhos de resposta HTTP ou retire caracteres de escape de aspas antes de realizar o parsing.

⚠️Diretivas do Apollo Federation (@key, @external, @shareable) causam falhas de parsing por diretiva desconhecida

O parser padrão da especificação GraphQL não inclui as diretivas de schema do Apollo Federation v1/v2 nativamente. O gerador disponibiliza stubs integrados para diretivas do Federation; confirme se a opção 'Habilitar Diretivas do Federation' está ativada ou cole o bloco de definições padrão de diretivas do Federation no topo do seu SDL.

Perguntas frequentes (FAQ)

Como a nulabilidade do GraphQL é mapeada para campos opcionais vs. uniões com null no TypeScript?▼

No GraphQL SDL, os campos são anuláveis por padrão e só se tornam não nulos quando marcados com ponto de exclamação (!). No TypeScript com strictNullChecks ativado, campos não nulos (String!) compilam para 'string', enquanto campos anuláveis (String) compilam para 'string | null' (ou 'Maybe<string>'). Já para objetos de entrada (input objects), campos anuláveis viram propriedades opcionais ('field?: string | null'), pois o GraphQL permite omitir argumentos em queries e mutations.

Enums GraphQL devem ser convertidos em enum do TypeScript ou uniões de literais de string?▼

Uniões de literais de string ('type Status = "ACTIVE" | "INACTIVE"') são altamente recomendadas para aplicações web modernas, pois compilam para zero código JavaScript em runtime, suportam tree-shaking perfeitamente e aceitam strings literais comuns sem necessidade de importar o enum. Enums nativos do TypeScript ('enum Status { Active = "ACTIVE" }') só devem ser adotados quando reflexão de objetos em runtime, busca reversa de chaves ou integração com bibliotecas legadas forem estritamente necessárias.

Qual é a diferença entre codegen de Schema Types e codegen de Client Operation Types?▼

O codegen de Schema Types compila todo o schema backend do GraphQL (todos os tipos, inputs, enums e assinaturas de resolvers) em interfaces TypeScript exaustivas. Já o codegen de Client Operation Types inspeciona os documentos de query específicos do cliente, seleciona apenas os subcampos consultados (aplicando selection sets e fragmentos) e gera tipos de resposta precisos e desaninhados que espelham exatamente o payload JSON retornado por aquela query em particular.

Por que o escalar ID do GraphQL serializa para string ou number em vez de um tipo dedicado no TypeScript?▼

A especificação oficial do GraphQL define o escalar ID como um identificador exclusivo serializado como String, mas permite que clientes enviem strings ou inteiros como entrada. Por consequência, o codegen TypeScript mapeia ID para 'string' (em tipos de saída) ou 'string | number' (em argumentos de entrada). Aplicações que necessitam de type safety estrito entre IDs de entidades distintas devem adotar branded types nominais (por exemplo, 'type UserId = string & { readonly __brand: unique symbol }').

Ferramentas e utilitários relacionados

Todas as ferramentas →