Client

Configuration and methods.

src/client.ts

import { Client } from "@zoontek/gql-client";
import schemaConfig from "./schemaConfig.json";
 
export const client = new Client({
  url: "https://api.example.com/graphql",
  schemaConfig,
});

Configuration

type ClientConfig = {
  url: string;
  schemaConfig: SchemaConfig;
  timeout?: number;
  transformRequest?: (request: Request) => Request | Promise<Request>;
};
 
new Client(config: ClientConfig): Client;

Option	Description
`url`	Required. The GraphQL endpoint. Every request is sent here as an HTTP `POST`.
`schemaConfig`	Required. The interface-to-types map generated by `gql-schema-config`.
`timeout`	Optional. Request timeout in milliseconds. Defaults to `10_000`. Set `Infinity` to disable it.
`transformRequest`	Optional. Returns the request to send instead of the one the client built, see Request transforms.

transformRequest

The client builds a POST request to url, with Accept and Content-Type set to application/json, cache set to no-store, and the GraphQL payload as its JSON body. transformRequest receives that request and returns the one to send, sync or async. Use it to set headers, credentials, or any other fetch option, and to read or replace the body.

If the function throws or rejects, or returns a request whose body has been consumed, the request fails with a ClientError whose reason is "transform".

Methods

Most apps only need the hooks. These methods are what the hooks call under the hood; use them directly for one-off requests outside a component, or for the SSR and refetch flows.

query

query<Data, Variables>(
  document: TypedDocumentNode<Data, Variables>,
  variables: Variables,
  options?: { refresh?: boolean },
): Promise<Data>;

Sends document, writes the response into the cache, and resolves with the response data. Throws a ClientError on failure.

Calls for the same document and variables share one promise: a call made while a request is in flight joins it, and a call after success reuses the settled result. Pass refresh: true to replace a settled result with a fresh request. A rejected promise is dropped, so the next call retries.

mutate

mutate<Data, Variables>(
  document: TypedDocumentNode<Data, Variables>,
  variables: Variables,
  config?: { connectionUpdates?: GetConnectionUpdate<Data, Variables>[] },
): Promise<Data>;

Same as query, but never deduplicated, and accepts connection updates.

refetch

refetch(): Promise<void>;

Re-sends every mounted query and writes the fresh responses into the cache. Resolves once every request has settled; never rejects. See Refetching.

purge

purge(): void;

Drops every cache entry, then notifies all subscribers so mounted queries fetch fresh data. Useful on logout.

extract

extract(): string;

Serializes the cache to script-safe JSON text (every < escaped). See Server-side rendering.

restore

restore(data: SerializedCache | string): void;

Replaces the cache content with data produced by extract(), then notifies subscribers. Call it before rendering, on a client that hasn't fetched anything yet.

Suggest changes to this page