or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-graphql-typed-document-node--core

TypeScript type definitions for GraphQL DocumentNode operations with full type safety

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@graphql-typed-document-node/core@3.2.x

To install, run

npx @tessl/cli install tessl/npm-graphql-typed-document-node--core@3.2.0

index.mddocs/

GraphQL Typed Document Node Core

GraphQL 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.

Package Information

  • Package Name: @graphql-typed-document-node/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @graphql-typed-document-node/core

Core Imports

import { TypedDocumentNode, ResultOf, VariablesOf } from "@graphql-typed-document-node/core";

For CommonJS:

const { TypedDocumentNode, ResultOf, VariablesOf } = require("@graphql-typed-document-node/core");

Basic Usage

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 } }

Architecture

This package provides a foundational type system for GraphQL TypeScript integration:

  • TypedDocumentNode Interface: Extends GraphQL's DocumentNode with generic type parameters for type-safe operations
  • Type Inference System: Uses TypeScript's conditional types to extract result and variable types
  • Zero Runtime Impact: Contains only TypeScript type definitions with no runtime code
  • Client Library Integration: Designed to work seamlessly with GraphQL clients that support TypedDocumentNode

Capabilities

TypedDocumentNode Interface

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.

ResultOf Utility Type

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 }> }

VariablesOf Utility Type

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 } }

Error Handling

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:

  • Using ResultOf or VariablesOf with non-TypedDocumentNode types will result in never type
  • Type mismatches between expected and actual GraphQL operation types will be caught by TypeScript

Dependencies

  • Peer Dependencies: graphql (versions ^0.8.0 through ^17.0.0)
  • Runtime Dependencies: None (TypeScript types only)

Supported GraphQL Client Libraries

This package is designed to work with GraphQL client libraries that support TypedDocumentNode:

  • Apollo Client (v3.2.0+, v4+)
  • urql and related packages (v1.11.0+)
  • graphql-request (v5.0.0+)
  • apollo-angular (v2.6.0+)
  • villus (v1.0.0-beta.8+)
  • @vue/apollo-composable (v4.0.0-alpha.13+)
  • And others that implement TypedDocumentNode support