or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

batch-operations.mderror-handling.mdgraphql-client.mdindex.mdraw-requests.mdstatic-functions.md
tile.json

tessl/npm-graphql-request

Minimal GraphQL client supporting Node and browsers for scripts or simple apps

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/graphql-request@7.2.x

To install, run

npx @tessl/cli install tessl/npm-graphql-request@7.2.0

index.mddocs/

GraphQL Request

GraphQL Request is a minimal and lightweight GraphQL client that supports both Node.js and browser environments for scripts or simple applications. It offers a promise-based API with async/await support, first-class TypeScript integration including TypedDocumentNode, and isomorphic functionality across environments.

Package Information

  • Package Name: graphql-request
  • Package Type: npm (Pure ESM package)
  • Language: TypeScript
  • Installation: npm install graphql-request graphql

Core Imports

import { GraphQLClient, request, gql } from "graphql-request";

Default import:

import request from "graphql-request";

Note: This is a pure ESM package. CommonJS (require()) is not supported. Your project must be configured as ESM with "type": "module" in package.json and use TypeScript moduleResolution "bundler" or "node16"/"nodenext".

Basic Usage

import { gql, request, GraphQLClient } from "graphql-request";

// Static request function
const document = gql`
  {
    users {
      id
      name
      email
    }
  }
`;

const result = await request("https://api.example.com/graphql", document);

// Using GraphQL Client for more control
const client = new GraphQLClient("https://api.example.com/graphql", {
  headers: {
    authorization: "Bearer TOKEN",
  },
});

const data = await client.request(document);

Architecture

GraphQL Request is built around several key components:

  • Static Functions: Simple one-off request functions (request, rawRequest, batchRequests) for basic usage
  • GraphQL Client Class: Stateful client class for advanced scenarios with configuration, headers, and middleware
  • Document Analysis: Automatic operation name extraction and mutation detection from GraphQL documents
  • Error Handling: Custom ClientError class with detailed request context and response information
  • Middleware System: Request and response middleware for custom processing and transformation
  • Isomorphic Design: Works seamlessly in both Node.js and browser environments

Capabilities

Static Request Functions

Simple functions for one-off GraphQL requests without maintaining client state. Perfect for scripts and simple applications where you don't need persistent configuration.

function request<T, V = Variables>(
  url: string,
  document: RequestDocument | TypedDocumentNode<T, V>,
  variables?: V,
  requestHeaders?: HeadersInit
): Promise<T>;

function request<T, V = Variables>(
  options: RequestExtendedOptions<V, T>
): Promise<T>;

Static Functions

GraphQL Client Class

Stateful client class providing advanced configuration options, persistent headers, middleware support, and request management. Ideal for applications requiring consistent GraphQL endpoint interaction.

class GraphQLClient {
  constructor(url: string, requestConfig?: RequestConfig);
  
  request<T, V = Variables>(
    document: RequestDocument | TypedDocumentNode<T, V>,
    variables?: V,
    requestHeaders?: HeadersInit
  ): Promise<T>;
  
  setHeader(key: string, value: string): this;
  setEndpoint(value: string): this;
}

GraphQL Client

Raw Requests

Raw request functionality that returns complete GraphQL response including errors, extensions, and headers. Essential for applications requiring full response introspection.

function rawRequest<T, V = Variables>(
  url: string,
  query: string,
  variables?: V,
  requestHeaders?: HeadersInit
): Promise<GraphQLClientResponse<T>>;

interface GraphQLClientResponse<Data> {
  status: number;
  headers: Headers;
  data: Data;
  extensions?: unknown;
  errors?: GraphQLError[];
}

Raw Requests

Batch Operations

Batch request functionality for sending multiple GraphQL documents in a single HTTP request. Optimizes network usage and enables atomic operations across multiple queries.

function batchRequests<T, V = Variables>(
  url: string,
  documents: BatchRequestDocument<V>[],
  requestHeaders?: HeadersInit
): Promise<T>;

interface BatchRequestDocument<V = Variables> {
  document: RequestDocument;
  variables?: V;
}

Batch Operations

Error Handling

Comprehensive error handling with custom error classes providing detailed context about failed requests and GraphQL errors.

class ClientError extends Error {
  response: GraphQLResponse;
  request: GraphQLRequestContext;
  
  constructor(response: GraphQLResponse, request: GraphQLRequestContext);
}

Error Handling

Core Types

// Base types
type Variables = object;
type RequestDocument = string | DocumentNode;
type ErrorPolicy = "none" | "ignore" | "all";
type HTTPMethodInput = "GET" | "POST" | "get" | "post";

// Configuration types
interface RequestConfig extends Omit<RequestInit, "headers" | "method"> {
  fetch?: Fetch;
  method?: HTTPMethodInput;
  headers?: HeadersInit | (() => HeadersInit);
  requestMiddleware?: RequestMiddleware;
  responseMiddleware?: ResponseMiddleware;
  jsonSerializer?: JsonSerializer;
  excludeOperationName?: boolean;
  errorPolicy?: ErrorPolicy;
}

// Response types  
interface GraphQLResponse<T = unknown> {
  data?: T;
  errors?: GraphQLError[];
  extensions?: unknown;
  status: number;
  [key: string]: unknown;
}

// Request options
interface RequestOptions<V = Variables, T = unknown> {
  document: RequestDocument | TypedDocumentNode<T, V>;
  requestHeaders?: HeadersInit;
  signal?: RequestInit["signal"];
  variables?: V;
}

// Extended request context
interface RequestInitExtended<V = Variables> extends RequestInit {
  url: string;
  operationName?: string;
  variables?: V;
}