GraphQL Adapter
The Hyper Fetch GraphQL Adapter provides a seamless way to integrate GraphQL with Hyper Fetch, enabling you to make queries and mutations with ease.
- Simplify GraphQL integration in both server and browser environments.
- Provide a type-safe way to handle GraphQL operations.
- Offer seamless integration with the Hyper Fetch ecosystem.
- 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
documentnothing changes:endpointis the document and the URL isclient.url. - The cache, query and abort keys contain the operation name from
documentand the path fromendpoint, 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
payloadgeneric, the same as without thedocumentoption.
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:

