GraphQL Query to TypeScript Typed Document Node Generator
Compile GraphQL queries and schemas directly into strongly-typed TypeScript interfaces, variables, and TypedDocumentNode definitions online.
/*
* Generated by TwisterTools 2.0 - TypedDocumentNode Generator
* Target: typed-document-node | Mode: strict-null
* Safe, deterministic, zero-runtime overhead.
*/
import { type TypedDocumentNode } from "@graphql-typed-document-node/core";
// GraphQL Enums
export type Role =
| "USER"
| "ADMIN"
| "EDITOR";
export type GetUserProfileVariables = {
readonly userId: string;
};
export type GetUserProfileData = {
readonly userById: {
readonly id: unknown;
readonly name: unknown;
readonly email: unknown;
readonly role: unknown;
};
};
export const GetUserProfileDocument: TypedDocumentNode<GetUserProfileData, GetUserProfileVariables> = {
kind: "Document",
definitions: [
/* Ast definitions pre-parsed for zero runtime cost */
{ kind: "OperationDefinition", operation: "query", name: { kind: "Name", value: "GetUserProfile" } }
]
} as unknown as TypedDocumentNode<GetUserProfileData, GetUserProfileVariables>;The Architecture of TypedDocumentNode in Modern GraphQL Clients
GraphQL operations are fundamentally dynamic text queries transformed into AST objects at runtime. Traditionally, linking query responses and variable parameters to TypeScript types required repetitive manual generic typing or complex build-step watchers. TypedDocumentNode solves this by embedding return types directly into the AST structure itself.
Exact Return Typing
By typing both the response payload and variable definitions within the AST token, hooks like Apollo's useQuery(document) infer shape without explicit generics.
Compile-Time Safety
Invalid variable arguments or access to unselected GraphQL fields are caught instantly during tsc compilation rather than bubbling into production runtime errors.
Zero Runtime Overhead
Because TypedDocumentNode uses Phantom Types (types that only exist at compile time), the compiled JavaScript footprint is identical to a standard document AST.
Comparative Analysis: Client-Side Typing Strategies
| Method | Type Safety | Build Setup | Developer Ergonomics | Ideal Scenario |
|---|---|---|---|---|
| TypedDocumentNode | Comprehensive | Zero / Minimal | Automatic inference in hooks | Modern React, Next.js, and SSR microfrontends |
| Manual Generic Hooks | Partial / Error-prone | None | High repetition (userQuery<T, V>) | Legacy prototypes or rapid proofs of concept |
| CLI Codegen (Watchers) | Comprehensive | Heavy (Node CLI + Plugins) | Full schema synchronization | Massive monorepos with hundreds of fragments |
Frequently Asked Questions (FAQ)
What is TypedDocumentNode and how does it improve type safety?
TypedDocumentNode is a TypeScript type wrapper around standard GraphQL AST DocumentNode objects. By pairing the document node with generic parameters for query results and variables (<TResult, TVariables>), client libraries like Apollo Client, Urql, and GraphQL-Request automatically infer returned data structures and variable requirements without manually typing hook or client calls.
Why should teams prefer client-side type generation over heavyweight build-step codegen?
While large CLI tools like GraphQL Code Generator are excellent for enterprise CI/CD pipelines, lightweight browser-based generators enable instant prototyping, micro-service mocking, and quick script writing without configuring extensive YAML configs, plugins, and dependencies.
How does this generator handle custom scalars like DateTime or JSON?
Custom scalars can be mapped through the custom scalars configuration panel. By standardizing unknown GraphQL scalar strings into defined TypeScript types (such as string, Date, or Record<string, unknown>), your downstream code preserves full semantic safety.
Does this utility support mutation and subscription operations?
Yes. The parser identifies query, mutation, and subscription declarations. It automatically maps the selection tree back to the corresponding root schema type (Mutation or Subscription) and formats variables accordingly.
What is the advantage of using readonly and immutable TypeScript properties?
Applying readonly modifiers prevents inadvertent mutations to cache entries, query results, and UI parameters. Modern state managers like Apollo In-Memory Cache and Urql normalize entities immutably; readonly types guarantee compile-time enforcement of cache integrity.
Is my GraphQL schema or query uploaded to an external server?
No. All parsing, schema traversal, and TypeScript token synthesis are performed entirely within your browser using modern client-side execution. No proprietary schemas or query documents ever touch an external network.
Related & Complementary Utilities
Explore more privacy-first client-side web tools.
URL Encoder / Decoder & URI Sanitizer
Encode special characters into percent-encoded URI strings or decode encoded URLs back to human-readable paths in real time. 100% client-side web utility.
Regex Tester, Explainer & Cheat Sheet
Test, debug, and explain regular expressions in real-time with native JavaScript RegExp engine, flag toggles, match highlighting, group captures, and a comprehensive syntax cheat sheet — 100% client-side.
Diff Checker & Text Comparison Tool
Compare text differences with precision — line-by-line or character-by-character. Split and unified views with real-time performance metrics.