GraphQL in HyperFetch 10
GraphQL in HyperFetch 10
Typed documents, persisted queries and subscriptions.
const getUser = client.createRequest()({
endpoint: GetUserDocument, // typed by graphql-codegen or gql.tada
options: { persistedQueries: true },
});
const { data } = await getUser.send({ payload: { id: "1" } });
Your GraphQL documents already know their result and variables types. HyperFetch 10 reads them straight from the
document, sends hashes instead of full queries, keeps partial data when you want it, refetches every variant of an
operation after a mutation, and listens to subscriptions over graphql-ws.
This post covers HyperFetch 10. Read the release overview for the rest of the series.
- Typed documents: a
TypedDocumentNodeor gql.tada document types the request without generics. - Error policy:
errorPolicy: "all"keeps partial data as a success, with the errors inextra.errors. - Persisted queries:
persistedQueriessends the SHA-256 hash of the query instead of the text. - Operation refetch:
matchGqlOperationinvalidates every variant of an operation at once. - Subscriptions:
GraphqlWsAdapterspeaksgraphql-transport-wson the shared reconnection engine. - Spec alignment:
operationName, the GraphQL over HTTPAcceptheader and the right content type. - Separate cache keys: other variables or other selections never share a cache entry or a request.
Typed documents
With graphql-codegen or gql.tada every document carries its types, but a request still needed them written again as
generics, and the two could drift apart. createRequest now reads them from the __apiType decoration of the
endpoint.
import { createClient } from "@hyper-fetch/core";
import { GraphqlAdapter, type GraphqlErrorType } from "@hyper-fetch/graphql";
import { GetUserDocument, GetUsersDocument } from "./gql/graphql"; // generated
export const client = createClient<{ error: GraphqlErrorType }>({
url: "http://localhost:4000/graphql",
}).setAdapter(GraphqlAdapter());
export const getUser = client.createRequest()({ endpoint: GetUserDocument });
const { data } = await getUser.send({ payload: { id: "1" } }); // data and payload typed by the document
// A document without variables needs no payload
await client.createRequest()({ endpoint: GetUsersDocument }).send();
- Generics you declare win over the document.
createRequest<{ response: UserView }>()keeps the variables of the document and uses your response type. - Core reads the decoration structurally and has no GraphQL dependency. Any adapter whose endpoint carries
__apiTypegets the same inference. - An untyped
DocumentNodeor string keeps theundefinedresponse and payload, so declare them with generics.
When the document goes in the document option, the endpoint is a URL path. Read the types with
GraphqlDocumentTypes then:
import { type GraphqlDocumentTypes } from "@hyper-fetch/graphql";
const getUserByPath = client.createRequest<
GraphqlDocumentTypes<typeof GetUserDocument>
>()({
endpoint: "/User",
document: GetUserDocument,
});
Error policy
A GraphQL response can hold both data and errors when only some fields failed. A dashboard with one broken widget
should still show the other widgets. The errorPolicy adapter option decides what such a response resolves to.
const getDashboard = client.createRequest()({
endpoint: GetDashboardDocument,
options: { errorPolicy: "all" },
});
const { data, extra } = await getDashboard.send();
if (extra?.errors) {
// Show the data, and mark the fields listed in extra.errors[].path as unavailable
}
"none"(default) fails the request:dataisnullanderrorholds the errors. This is the behavior of 9."all"succeeds with the partialdata. A response withoutdata, or with a 4xx or 5xx status, still fails.- The server errors are in
extra.errorswith both policies, whenever the response has any.
Set it for every request with GraphqlAdapter().setAdapterDefaults(() => ({ errorPolicy: "all" })). The request
options still win.
Automatic persisted queries
Large queries make every request heavy, and GET requests with the full query in the URL are too long for many CDNs to
cache. With persistedQueries, the request sends the SHA-256 hash of the query in extensions.persistedQuery instead.
import { GraphqlMethod } from "@hyper-fetch/graphql";
const getUser = client.createRequest()({
endpoint: GetUserDocument,
method: GraphqlMethod.GET, // short hashed urls, so a CDN can cache the response
options: { persistedQueries: true },
});
- When the server answers
PersistedQueryNotFound, the request is sent again with the query, so the server stores it. You get the response of that second request. - When the server answers
PersistedQueryNotSupported, the request is sent again with the query, and the adapter sends full queries from then on. - Without Web Crypto (
crypto.subtleis missing on insecure origins) the full query is sent. - One
timeoutcovers the hashed request and the one that registers the query.
Turn it on for every request with GraphqlAdapter().setAdapterDefaults(() => ({ persistedQueries: true })). Without
the option nothing changes: the request flow, the timeout and the progress events are the same as before.
Refetch every variant of an operation
After UpdateUser, every GetUser in the cache may be stale: id: 1, id: 2, and whatever else the app loaded.
cache.invalidate(request) reaches only one combination of variables. matchGqlOperation returns a RegExp that matches
the cache keys of every request of a document, like refetchQueries in Apollo.
import { matchGqlOperation } from "@hyper-fetch/graphql";
const updateUser = client.createRequest()({ endpoint: UpdateUserDocument });
const { success } = await updateUser.send({
payload: { id: "1", name: "Ann" },
});
if (success) {
client.cache.invalidate(matchGqlOperation(GetUserDocument));
}
- It matches any variables, params, query params and method. A document matches its requests on every URL path of the
documentoption, a request only on its own path. - Documents with the same operation name but other selections are other operations, so they are not matched.
invalidatetakes a list, so one mutation can refetch several operations.
Subscriptions over graphql-ws
Queries and mutations had a home in HyperFetch, subscriptions did not. GraphqlWsAdapter connects a Socket to
GraphQL subscriptions over WebSocket. It speaks graphql-transport-ws, the protocol of the graphql-ws library that
Apollo Server, GraphQL Yoga, Mercurius, Hot Chocolate and Hasura support.
import { Socket } from "@hyper-fetch/sockets";
import { GraphqlWsAdapter } from "@hyper-fetch/graphql";
import { OnMessageDocument } from "./gql/graphql";
const socket = new Socket({
url: "wss://api.example.com/graphql",
adapter: GraphqlWsAdapter(),
// A function runs on every connection attempt, so a reconnect sends a fresh token
adapterOptions: {
connectionParams: async () => ({ token: await auth.getFreshToken() }),
},
});
export const onMessage = socket.createListener()({
topic: "OnMessage",
options: { document: OnMessageDocument },
});
onMessage
.setPayload({ room: "general" })
.listen(({ data }) => console.log(data.onMessage.text));
The typed document types the data and makes the variables a required payload, the same way it types requests. In React,
useListener(onMessage.setPayload({ room })) subscribes again when the room changes and reports status and error.
- One subscription per document and variables. Listeners with the same variables share it, and the last one to stop
sends
complete. - Ready after the acknowledgement. The connection counts as open once the server acknowledged
connection_init, soconnectionTimeoutcovers the whole handshake. Subscriptions started before wait for it. - Restarted after a reconnect. Every running subscription is sent again with a new id. Close codes a retry can't
fix, like
4400or4401, stay closed, like in thegraphql-wsclient.shouldReconnectGraphqlWskeeps those rules in a customshouldReconnect. - Two kinds of errors. Errors of one event arrive in
extra.errorsand the subscription goes on. Anerrormessage ends the listener with aGraphqlSubscriptionErrorinonEnd. - Connection control. The adapter answers the server's
ping.keepAlivepings a quiet connection to notice one that died behind a proxy, andlazyholds a connection only while there are subscriptions.
The adapter runs on the reconnection engine every socket adapter shares, with typed payloads and the listener lifecycle
from the sockets post. Listener delivery strategies work too, so batch delivers arrays
of the document's data.
What goes over the wire
Each operation follows the GraphQL over HTTP format more closely:
- The body, or the query string for
GET, holdsoperationName, the name of the first operation in the document. - The
Acceptheader asks forapplication/graphql-response+jsonwithapplication/jsonas the fallback, so servers that follow the spec answer invalid requests with a 4xx status. AnAcceptheader you set wins. POSTrequests always sendContent-Type: application/json, also without variables.GETrequests send none, since the header only triggered a CORS preflight. A content type you set wins.- Cache and query keys contain the operation name, a fingerprint of the document and the variables.
Reliability fixes
GetUser(id: 1)andGetUser(id: 2)no longer share a cache entry or get deduplicated into one request. The variables are part of the cache and query keys.- Two documents with one operation name but other selections no longer share a cache entry. A deduplicated request used to hand the second caller the data of the first.
- Queries without variables are sent as JSON. They went out as
text/plain, and servers answered 415. - A string document like
mutation DeleteUser($id: ID!) { ... }no longer asks for a URL param named after the text after the colon, sosend({ payload })compiles. - An empty
errorslist is no longer a failure. - Network, abort and timeout failures arrive as a list with one
Error, like every other GraphQL error, soGraphqlErrorTypecovers them all. - The upload of a request is reported as finished only once the body was sent.
Upgrading
graphqlis a peer dependency now, and@hyper-fetch/socketsis one too, forGraphqlWsAdapter. Install both next to@hyper-fetch/graphql:
npm install @hyper-fetch/core @hyper-fetch/sockets @hyper-fetch/graphql graphql
- Cache keys of GraphQL requests contain the document fingerprint and the variables. Data persisted in cache storage under the keys of earlier versions is not read again, so the first requests after the upgrade go to the network.
- If you wrote the response and payload generics only to mirror a typed document, you can delete them. Keeping them still works, since declared generics win.

