Skip to main content
Version: v8.0.0

GraphQL Adapter

Read the API Reference »

The Hyper Fetch GraphQL Adapter provides a seamless way to integrate GraphQL with Hyper Fetch, enabling you to make queries and mutations with ease.

Purpose
  1. Simplify GraphQL integration in both server and browser environments.
  2. Provide a type-safe way to handle GraphQL operations.
  3. Offer seamless integration with the Hyper Fetch ecosystem.
  4. Support both queries and mutations with a consistent API.

Installation​

To get started, you need to install the @hyper-fetch/graphql package. You will also need graphql and graphql-tag as recommended companion packages.

npm install @hyper-fetch/graphql graphql graphql-tag

Getting Started​

Whether you're developing a server-side GraphQL API or a client-side application that consumes GraphQL data, you can use Hyper Fetch GraphQL to interact with it. The setup process is simple and straightforward.

import { Client } from "@hyper-fetch/core";
import { GraphqlAdapter } from "@hyper-fetch/graphql";
import gql from "graphql-tag";

// 1. Create a client
const client = new Client({ url: "http://localhost:3000/graphql" }).setAdapter(GraphqlAdapter());

// 2. Define an interface for your data
interface User {
user: {
username: string;
firstName: string;
};
}

// 3. Create a request
const getUser = client.createRequest<User>()({
endpoint: gql`
query GetUser {
user {
username
firstName
}
}
`,
});

// 4. Send the request and get the response
const { data, error } = await getUser.send();

Queries​

To perform a query, create a request with the gql tag and your GraphQL query string.

import { Client } from "@hyper-fetch/core";
import { GraphqlAdapter } from "@hyper-fetch/graphql";
import gql from "graphql-tag";

const client = new Client({ url: "http://localhost:3000/graphql" }).setAdapter(GraphqlAdapter());

const getUsers = client.createRequest<any[]>()({
endpoint: gql`
query GetUsers {
users {
id
name
}
}
`,
});

Mutations​

Mutations work just like queries. Define your mutation string and use it in a request.

import { Client } from "@hyper-fetch/core";
import { GraphqlAdapter } from "@hyper-fetch/graphql";
import gql from "graphql-tag";

const client = new Client({ url: "http://localhost:3000/graphql" }).setAdapter(GraphqlAdapter());

const addUser = client.createRequest<any>()({
endpoint: gql`
mutation AddUser($name: String!) {
addUser(name: $name) {
id
name
}
}
`,
});

Variables​

You can pass variables to your queries and mutations using the data option in the send method.

const { data, error } = await addUser.send({
data: {
variables: { name: "John Doe" },
},
});

This will pass the name variable to the AddUser mutation.


URL path per operation​

By default, endpoint holds the GraphQL document and every operation goes to client.url. When gateways, WAF/CDN rules, APM or access logs group the traffic by URL, pass the document separately with the document option. The endpoint then becomes a URL path appended to client.url, the same way as in the HttpAdapter.

const getUser = client.createRequest<{ response: User; payload: { id: number } }>()({
endpoint: "/User", // URL path, supports params like "/tenant/:tenantId/User"
document: gql`
query User($id: ID!) {
user(id: $id) {
username
}
}
`, // string | DocumentNode, sent as `query`
});

await getUser.send({ payload: { id: 1 } });
// POST {client.url}/User
// body: { query, variables: { id: 1 } }
  • Without document nothing changes: endpoint is the document and the URL is client.url.
  • The cache, query and abort keys contain the operation name from document and the path from endpoint, so the same operation sent to two paths is not shared in the cache.
  • Devtools display the operation name from document.
  • Variables are typed with the payload generic, the same as without the document option.

Query params​

Query params are appended to the URL, with or without the document option. This lets access logs and APM filter requests without parsing the body.

await getUser.setQueryParams({ source: "app", build: "1.2.3" }).send({ payload: { id: 1 } });
// POST {client.url}/User?source=app&build=1.2.3
// body: { query, variables: { id: 1 } }

For the GET method they are merged with query and variables in the query string. If a key collides, query and variables take precedence.

They go through the query params mapper of the adapter, so you can change the format with the mapper config or replace the mapper. It can return a query string or an object.

import { stringifyDefaultOptions } from "@hyper-fetch/core";

// The config replaces the defaults, so spread them to keep the encoding
const adapter = GraphqlAdapter().setQueryParamsMapperConfig({ ...stringifyDefaultOptions, arrayFormat: "comma" });

Next Steps​

Now that you have a basic understanding of the GraphQL adapter, you can explore more advanced topics:

Queries
Learn more about fetching data with GraphQL queries.
Mutations
Discover how to modify data with GraphQL mutations.
GraphQL Tag
Understand how to use the gql tag for your GraphQL operations.