TypeScript type definitions for GraphQL DocumentNode operations with full type safety
npx @tessl/cli install tessl/npm-graphql-typed-document-node--core@3.2.0GraphQL Typed Document Node Core provides TypeScript type definitions for creating fully typed GraphQL DocumentNode objects. It enables type safety for GraphQL operations by extending the standard DocumentNode interface with generic type parameters for operation results and variables, providing automatic type inference and compile-time type checking without any runtime dependencies.
npm install @graphql-typed-document-node/coreimport { TypedDocumentNode, ResultOf, VariablesOf } from "@graphql-typed-document-node/core";For CommonJS:
const { TypedDocumentNode, ResultOf, VariablesOf } = require("@graphql-typed-document-node/core");import { TypedDocumentNode, ResultOf, VariablesOf } from "@graphql-typed-document-node/core";
// Define a typed document node (typically generated by GraphQL Code Generator)
const GetUserQuery: TypedDocumentNode<
{ user: { id: string; name: string; email: string } },
{ id: string }
> = {
kind: "Document",
definitions: [
// ... GraphQL AST definitions
]
};
// Extract types from the typed document
type UserQueryResult = ResultOf<typeof GetUserQuery>;
// Result: { user: { id: string; name: string; email: string } }
type UserQueryVariables = VariablesOf<typeof GetUserQuery>;
// Result: { id: string }
// Use with GraphQL client libraries that support TypedDocumentNode
const result = await client.query({
query: GetUserQuery,
variables: { id: "123" } // Fully typed!
});
// result.data is typed as { user: { id: string; name: string; email: string } }This package provides a foundational type system for GraphQL TypeScript integration:
Core interface that extends GraphQL DocumentNode with type parameters for result and variables.
interface TypedDocumentNode<
TResult = { [key: string]: any },
TVariables = { [key: string]: any }
> extends DocumentNode, DocumentTypeDecoration<TResult, TVariables> {}
interface DocumentTypeDecoration<TResult, TVariables> {
/**
* This type is used to ensure that the variables you pass in to the query are assignable to Variables
* and that the Result is assignable to whatever you pass your result to. The method is never actually
* implemented, but the type is valid because we list it as optional
*/
__apiType?: (variables: TVariables) => TResult;
}Type Parameters:
TResult - The expected result type of the GraphQL operation (defaults to generic object)TVariables - The expected variables type for the GraphQL operation (defaults to generic object)Usage: Typically used by GraphQL Code Generator or similar tools to create typed GraphQL operations.
Helper type for extracting the result type from a TypedDocumentNode.
/**
* Helper for extracting a TypeScript type for operation result from a TypedDocumentNode and TypedDocumentString.
* @example
* const myQuery = { ... }; // TypedDocumentNode<R, V>
* type ResultType = ResultOf<typeof myQuery>; // Now it's R
*/
type ResultOf<T> = T extends DocumentTypeDecoration<infer ResultType, infer VariablesType>
? ResultType
: never;Usage Example:
const GetUsersQuery: TypedDocumentNode<
{ users: Array<{ id: string; name: string }> },
{ limit: number }
> = /* ... */;
type UsersResult = ResultOf<typeof GetUsersQuery>;
// Result: { users: Array<{ id: string; name: string }> }Helper type for extracting the variables type from a TypedDocumentNode.
/**
* Helper for extracting a TypeScript type for operation variables from a TypedDocumentNode and TypedDocumentString.
* @example
* const myQuery = { ... }; // TypedDocumentNode<R, V>
* type VariablesType = VariablesOf<typeof myQuery>; // Now it's V
*/
type VariablesOf<T> = T extends DocumentTypeDecoration<infer ResultType, infer VariablesType>
? VariablesType
: never;Usage Example:
const CreateUserMutation: TypedDocumentNode<
{ createUser: { id: string; success: boolean } },
{ input: { name: string; email: string } }
> = /* ... */;
type CreateUserVariables = VariablesOf<typeof CreateUserMutation>;
// Result: { input: { name: string; email: string } }This package contains only TypeScript type definitions and does not throw any runtime errors. Type checking occurs at compile time through TypeScript's type system.
Common compile-time scenarios:
ResultOf or VariablesOf with non-TypedDocumentNode types will result in never typegraphql (versions ^0.8.0 through ^17.0.0)This package is designed to work with GraphQL client libraries that support TypedDocumentNode: