CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-graphql-request

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/graphql-request@7.2.x
Publish Source
CLI
Badge
tessl/npm-graphql-request badge