refactor: improve support for persistent queries

Author: mvantellingen

.changeset/warm-tomatoes-wonder.md

@@ -0,0 +1,5 @@
+---
+"@labdigital/graphql-fetcher": major
+---
+
+Internal refactor to better support persisted operations / trusted documents

package.json

@@ -59,6 +59,7 @@
 		"@vitest/coverage-v8": "3.0.2",
 		"tsup": "8.3.5",
 		"typescript": "5.7.3",
+		"vite-tsconfig-paths": "5.1.4",
 		"vitest": "3.0.2",
 		"vitest-fetch-mock": "^0.2.2"
 	},

pnpm-lock.yaml

@@ -10,6 +10,7 @@ import {
 import createFetchMock from "vitest-fetch-mock";
 import { initClientFetcher } from "./client";
 import { TypedDocumentString } from "./testing";
+import { createSha256 } from "helpers";
 
 const query = new TypedDocumentString(/* GraphQL */ `
 	query myQuery {
@@ -52,14 +53,21 @@ describe("gqlClientFetch", () => {
 			"https://localhost/graphql?op=myQuery",
 			{
 				// This exact body should be sent:
-				body: '{"query":"\\n\\tquery myQuery {\\n\\t\\tfoo\\n\\t\\tbar\\n\\t}\\n","variables":{"myVar":"baz"},"extensions":{}}',
+				body: JSON.stringify({
+					query: query,
+					variables: { myVar: "baz" },
+					extensions: { persistedQuery: {
+						version: 1,
+						sha256Hash: await createSha256(query.toString()),
+					}},
+				}),
 				// Method was post:
 				method: "POST",
 				// These exact headers should be set:
 				credentials: "include",
-				headers: {
+				headers: new Headers({
 					"content-type": "application/json",
-				},
+				}),
 				signal: expect.any(AbortSignal),
 			},
 		);
@@ -75,15 +83,15 @@ describe("gqlClientFetch", () => {
 		expect(gqlResponse).toEqual(response);
 		expect(mockedFetch).toHaveBeenCalledWith(
 			// When persisted queries are enabled, we suffix all the variables and extensions as search parameters
-			"https://localhost/graphql?op=myQuery&extensions=%7B%22persistedQuery%22%3A%7B%22version%22%3A1%2C%22sha256Hash%22%3A%22e5276e0694f661ef818210402d06d249625ef169a1c2b60383acb2c42d45f7ae%22%7D%7D&variables=%7B%22myVar%22%3A%22baz%22%7D",
+			"https://localhost/graphql?op=myQuery&variables=%7B%22myVar%22%3A%22baz%22%7D&extensions=%7B%22persistedQuery%22%3A%7B%22version%22%3A1%2C%22sha256Hash%22%3A%22e5276e0694f661ef818210402d06d249625ef169a1c2b60383acb2c42d45f7ae%22%7D%7D",
 			{
 				// Query is persisted, uses GET to be cached by CDN
 				method: "GET",
 				// These exact headers should be set:
 				credentials: "include",
-				headers: {
+				headers: new Headers({
 					"content-type": "application/json",
-				},
+				}),
 				signal: expect.any(AbortSignal),
 			},
 		);
@@ -196,7 +204,7 @@ describe("gqlClientFetch", () => {
 			{
 				myVar: "baz",
 			},
-			controller.signal,
+			{ signal: controller.signal },
 		);
 
 		expect(fetchMock).toHaveBeenCalledWith(
@@ -231,15 +239,22 @@ describe("gqlClientFetch", () => {
 			"https://localhost/graphql?op=myQuery",
 			{
 				// This exact body should be sent:
-				body: '{"query":"\\n\\tquery myQuery {\\n\\t\\tfoo\\n\\t\\tbar\\n\\t}\\n","variables":{"myVar":"baz"},"extensions":{}}',
+				body: JSON.stringify({
+					query: query,
+					variables: { myVar: "baz" },
+					extensions: { persistedQuery: {
+						version: 1,
+						sha256Hash: await createSha256(query.toString()),
+					}},
+				}),
 				// Method was post:
 				method: "POST",
 				// These exact headers should be set:
 				credentials: "include",
-				headers: {
-					"content-type": "application/json",
-					"x-extra-header": "foo",
-				},
+				headers: new Headers({
+					"Content-Type": "application/json",
+					"X-extra-header": "foo",
+				}),
 				signal: expect.any(AbortSignal),
 			},
 		);

src/client.test.ts

@@ -1,22 +1,32 @@
 import type { DocumentTypeDecoration } from "@graphql-typed-document-node/core";
+import { print } from "graphql";
+import { isNode } from "graphql/language/ast.js";
+import {
+	createRequest,
+	createRequestBody,
+	createRequestURL,
+	isPersistedQuery,
+	type ModeFlags,
+} from "request";
 import invariant from "tiny-invariant";
-import { getDocumentId, type GqlResponse } from "./helpers";
 import {
-	createSha256,
 	errorMessage,
-	extractOperationName,
+	getDocumentId,
 	getQueryType,
 	hasPersistedQueryError,
 	mergeHeaders,
+	type GqlResponse,
 } from "./helpers";
-import { print } from "graphql";
-import { isNode } from "graphql/language/ast.js";
 
 type Options = {
 	/**
-	 * Enable use of persisted queries, this will always add a extra roundtrip to the server if queries aren't cacheable
+	 * Enable use of automated persisted queries, this will always add a extra
+	 * roundtrip to the server if queries aren't cacheable
 	 * @default false
 	 */
+	apq?: boolean;
+
+	/** Deprecated: use `apq: <boolean>` */
 	persistedQueries?: boolean;
 
 	/**
@@ -31,6 +41,8 @@ type Options = {
 	 */
 	defaultHeaders?: Headers | Record<string, string>;
 
+	mode?: ModeFlags
+
 	/**
 	 * Function to customize creating the documentId from a query
 	 *
@@ -49,98 +61,78 @@ type RequestOptions = {
 export type ClientFetcher = <TResponse, TVariables>(
 	astNode: DocumentTypeDecoration<TResponse, TVariables>,
 	variables?: TVariables,
-	options?: RequestOptions | AbortSignal, // Backwards compatibility
+	options?: RequestOptions,
 ) => Promise<GqlResponse<TResponse>>;
 
 export const initClientFetcher =
 	(
 		endpoint: string,
 		{
+			apq = false,
 			persistedQueries = false,
 			defaultTimeout = 30000,
 			defaultHeaders = {},
-			createDocumentId = <TResult, TVariables>(
-				query: DocumentTypeDecoration<TResult, TVariables>,
-			): string | undefined => getDocumentId(query),
+			mode = "document",
+			createDocumentId = getDocumentId,
 		}: Options = {},
 	): ClientFetcher =>
 	/**
 	 * Executes a GraphQL query post request on the client.
 	 *
-	 * This is the only fetcher that uses user information in the call since all user information is only
-	 * used after rendering the page for caching reasons.
+	 * This is the only fetcher that uses user information in the call since all
+	 * user information is only used after rendering the page for caching reasons.
 	 */
 	async <TResponse, TVariables>(
 		astNode: DocumentTypeDecoration<TResponse, TVariables>,
 		variables?: TVariables,
-		optionsOrSignal: RequestOptions | AbortSignal = {
+		options: RequestOptions = {
 			signal: AbortSignal.timeout(defaultTimeout),
-		} satisfies RequestOptions,
+		},
 	): Promise<GqlResponse<TResponse>> => {
-		// For backwards compatibility, when options is an AbortSignal we transform
-		// it into a RequestOptions object
-		const options: RequestOptions = {};
-		if (optionsOrSignal instanceof AbortSignal) {
-			options.signal = optionsOrSignal;
-		} else {
-			Object.assign(options, optionsOrSignal);
-		}
-
 		// Make sure that we always have a default signal set
 		if (!options.signal) {
 			options.signal = AbortSignal.timeout(defaultTimeout);
 		}
 
 		const query = isNode(astNode) ? print(astNode) : astNode.toString();
-
-		const operationName = extractOperationName(query);
 		const documentId = createDocumentId(astNode);
-
-		let extensions = {};
-		if (persistedQueries) {
-			const hash = await createSha256(query);
-
-			extensions = {
-				persistedQuery: {
-					version: 1,
-					sha256Hash: hash,
-				},
-			};
-		}
-
-		const url = new URL(endpoint);
-		url.searchParams.set("op", operationName ?? "");
+		const request = await createRequest(mode, query, variables, documentId);
 
 		let response: GqlResponse<TResponse> | undefined = undefined;
-
 		const headers = mergeHeaders({ ...defaultHeaders, ...options.headers });
 
+		const queryType = getQueryType(query);
+
+		apq = apq || persistedQueries;
+
 		// For queries we can use GET requests if persisted queries are enabled
-		if (persistedQueries && getQueryType(query) === "query") {
-			url.searchParams.set("extensions", JSON.stringify(extensions));
-			if (variables) {
-				url.searchParams.set("variables", JSON.stringify(variables));
-			}
-			if (documentId) {
-				url.searchParams.set("documentId", documentId);
-			}
+		if (queryType === "query" && (apq || isPersistedQuery(request))) {
+			const url = createRequestURL(endpoint, request);
 			response = await parseResponse<GqlResponse<TResponse>>(() =>
 				fetch(url.toString(), {
-					headers: Object.fromEntries(headers.entries()),
+					headers: headers,
 					method: "GET",
 					credentials: "include",
 					signal: options.signal,
 				}),
 			);
 		}
 
-		if (!response || hasPersistedQueryError(response)) {
-			// Persisted query not used or found, fall back to POST request and include extension to cache the query on the server
+		// For failed APQ calls or mutations we need to fall back to POST requests
+		if (
+			!response ||
+			(!isPersistedQuery(request) && hasPersistedQueryError(response))
+		) {
+			const url = new URL(endpoint);
+			url.searchParams.append("op", request.operationName);
+
+			// Persisted query not used or found, fall back to POST request and
+			// include extension to cache the query on the server
 			response = await parseResponse<GqlResponse<TResponse>>(() =>
 				fetch(url.toString(), {
-					headers: Object.fromEntries(headers.entries()),
+					headers: headers,
 					method: "POST",
-					body: JSON.stringify({ documentId, query, variables, extensions }),
+					body: createRequestBody(request),
 					credentials: "include",
 					signal: options.signal,
 				}),

src/client.ts

@@ -28,7 +28,7 @@ export const mergeHeaders = (
 	return result;
 };
 
-export const getQueryType = (query: string) =>
+export const getQueryType = (query: string): "query" | "mutation" =>
 	query.trim().startsWith("query") ? "query" : "mutation";
 
 export const getDocumentId = <TResult, TVariables>(
@@ -55,8 +55,17 @@ export interface NextFetchRequestConfig {
 	tags?: string[];
 }
 
-export const pruneObject = <T>(object: T): Partial<T> =>
-	JSON.parse(JSON.stringify(object ?? null));
+export const pruneObject = <T>(object: T): Partial<T> => {
+	const data: Record<string, unknown> = {}
+	for (const key in object) {
+		if (isNotEmpty(object[key])) {
+			data[key] = object[key];
+		}
+	}
+	return JSON.parse(JSON.stringify(data ?? null));
+}
+
+const isNotEmpty = (value: unknown) => value && Object.keys(value).length > 0;
 
 // createSha256 creates a sha256 hash from a message with the same algorithm as
 // Apollo Server, so we know for certain the same hash is used for automatic