feat: replace mode flag with includeQuery

The availability of the documentId on the query already indicated if
we want to do persistent queries vs non persistent queries. With the
flag `includeQuery` we can now always append the query

Author: mvantellingen

.changeset/gentle-plants-rule.md

@@ -0,0 +1,5 @@
+---
+"@labdigital/graphql-fetcher": patch
+---
+
+Replace `mode` flag via simpler `includeQuery` to indicate if the query should be sent even if there is a documentId available

src/client.ts

@@ -6,7 +6,6 @@ import {
 	createRequestBody,
 	createRequestURL,
 	isPersistedQuery,
-	type ModeFlags,
 } from "request";
 import invariant from "tiny-invariant";
 import {
@@ -41,7 +40,10 @@ type Options = {
 	 */
 	defaultHeaders?: Headers | Record<string, string>;
 
-	mode?: ModeFlags;
+	/**
+	 * If the query should always be sent, even if there is a document id
+	 */
+	includeQuery?: boolean;
 
 	/**
 	 * Function to customize creating the documentId from a query
@@ -72,7 +74,7 @@ export const initClientFetcher =
 			persistedQueries = false,
 			defaultTimeout = 30000,
 			defaultHeaders = {},
-			mode = "document",
+			includeQuery = false,
 			createDocumentId = getDocumentId,
 		}: Options = {},
 	): ClientFetcher =>
@@ -96,7 +98,12 @@ export const initClientFetcher =
 
 		const query = isNode(astNode) ? print(astNode) : astNode.toString();
 		const documentId = createDocumentId(astNode);
-		const request = await createRequest(mode, query, variables, documentId);
+		const request = await createRequest(
+			query,
+			variables,
+			documentId,
+			includeQuery,
+		);
 
 		let response: GqlResponse<TResponse> | undefined = undefined;
 		const headers = mergeHeaders({ ...defaultHeaders, ...options.headers });

src/request.test.ts

@@ -1,11 +1,11 @@
 import { createRequestSearchParams, type GraphQLRequest } from "request";
 import { expect, it } from "vitest";
 
-it.each(["both", "document", "persistent"])(
-	"createRequestURL - mode=%s",
-	(mode) => {
+it.each([true, false])(
+	"createRequestSearchParams - includeQuery=%s",
+	(includeQuery) => {
 		const data = createRequestSearchParams({
-			mode: mode,
+			includeQuery: includeQuery,
 			query: "query { hello }",
 			variables: { name: "world" },
 			operationName: "hello",
@@ -23,42 +23,28 @@ it.each(["both", "document", "persistent"])(
 			result[key] = value;
 		});
 
-		switch (mode) {
-			case "both": {
-				expect(result).toStrictEqual({
-					documentId: "123",
-					op: "hello",
-					variables: '{"name":"world"}',
-					extensions: '{"persistedQuery":{"version":1,"sha256Hash":"123"}}',
-				});
-				break;
-			}
-			case "persisted": {
-				expect(result).toStrictEqual({
-					documentId: "123",
-					op: "hello",
-					variables: '{"name":"world"}',
-					extensions: '{"persistedQuery":{"version":1,"sha256Hash":"123"}}',
-				});
-				break;
-			}
-			case "document": {
-				expect(result).toStrictEqual({
-					op: "hello",
-					variables: '{"name":"world"}',
-					extensions: '{"persistedQuery":{"version":1,"sha256Hash":"123"}}',
-				});
-				break;
-			}
+		if (includeQuery) {
+			expect(result).toStrictEqual({
+				documentId: "123",
+				op: "hello",
+				variables: '{"name":"world"}',
+				extensions: '{"persistedQuery":{"version":1,"sha256Hash":"123"}}',
+			});
+		} else {
+			expect(result).toStrictEqual({
+				documentId: "123",
+				op: "hello",
+				variables: '{"name":"world"}',
+			});
 		}
 	},
 );
 
-it.each(["both", "document", "persistent"])(
-	"createRequestURL - minimal mode=%s",
-	(mode) => {
+it.each([true, false])(
+	"createRequestSearchParams - minimal includeQuery=%s",
+	(includeQuery) => {
 		const data = createRequestSearchParams({
-			mode: mode,
+			includeQuery,
 			query: "query { hello }",
 			variables: {},
 			operationName: "hello",
@@ -70,27 +56,16 @@ it.each(["both", "document", "persistent"])(
 			result[key] = value;
 		});
 
-		switch (mode) {
-			case "both": {
-				expect(result).toStrictEqual({
-					documentId: "123",
-					op: "hello",
-				});
-				break;
-			}
-			case "persisted": {
-				expect(result).toStrictEqual({
-					documentId: "123",
-					op: "hello",
-				});
-				break;
-			}
-			case "document": {
-				expect(result).toStrictEqual({
-					op: "hello",
-				});
-				break;
-			}
+		if (includeQuery) {
+			expect(result).toStrictEqual({
+				documentId: "123",
+				op: "hello",
+			});
+		} else {
+			expect(result).toStrictEqual({
+				documentId: "123",
+				op: "hello",
+			});
 		}
 	},
 );

src/request.ts

@@ -1,23 +1,24 @@
 import type { DocumentTypeDecoration } from "@graphql-typed-document-node/core";
 import { createSha256, extractOperationName, pruneObject } from "helpers";
 
-export type ModeFlags = "persisted" | "document" | "both";
-
 export type DocumentIdFn = <TResult, TVariables>(
 	query: DocumentTypeDecoration<TResult, TVariables>,
 ) => string | undefined;
 
 export type GraphQLRequest<TVariables> = {
-	mode: ModeFlags;
 	operationName: string;
 	query: string | undefined;
 	documentId: string | undefined;
 	variables: TVariables | undefined;
 	extensions: Record<string, unknown>;
+	includeQuery: boolean;
 };
 
-export const isPersistedQuery = <T>(request: GraphQLRequest<T>): boolean =>
-	request.mode === "persisted" || request.mode === "both";
+export const isPersistedQuery = <TVariables>(
+	request: GraphQLRequest<TVariables>,
+) => {
+	return request.documentId !== undefined;
+};
 
 export const createRequestSearchParams = <TVariables>(
 	request: GraphQLRequest<TVariables>,
@@ -26,22 +27,18 @@ export const createRequestSearchParams = <TVariables>(
 		op: request.operationName,
 	};
 
-	if (request.mode === "both" || request.mode === "persisted") {
-		if (!request.documentId) {
-			throw new Error("Persisted query mode requires a documentId");
-		}
-		params.documentId = request.documentId;
-	}
-
 	params = {
 		...params,
 		...pruneObject({
+			documentId: request.documentId,
 			variables: isNotEmpty(request.variables)
 				? JSON.stringify(request.variables)
 				: undefined,
-			extensions: isNotEmpty(request.extensions)
-				? JSON.stringify(request.extensions)
-				: undefined,
+			extensions:
+				isNotEmpty(request.extensions) &&
+				(!request.documentId || request.includeQuery)
+					? JSON.stringify(request.extensions)
+					: undefined,
 		}),
 	};
 	return new URLSearchParams(params);
@@ -66,53 +63,40 @@ export const createRequestURL = <TVariables>(
 export const createRequestBody = <TVariables>(
 	request: GraphQLRequest<TVariables>,
 ) => {
-	switch (request.mode) {
-		case "both":
-			return JSON.stringify(
-				pruneObject({
-					documentId: request.documentId,
-					query: request.query,
-					variables: request.variables,
-					extensions: request.extensions,
-				}),
-			);
-		case "document":
-			return JSON.stringify(
-				pruneObject({
-					query: request.query,
-					variables: request.variables,
-					extensions: request.extensions,
-				}),
-			);
-		case "persisted":
-			if (!request.documentId) {
-				throw new Error("Persisted query mode requires a documentId");
-			}
-			return JSON.stringify(
-				pruneObject({
-					documentId: request.documentId,
-					variables: request.variables,
-					extensions: request.extensions,
-				}),
-			);
+	if (!request.documentId || request.includeQuery) {
+		return JSON.stringify(
+			pruneObject({
+				documentId: request.documentId,
+				query: request.query,
+				variables: request.variables,
+				extensions: request.extensions,
+			}),
+		);
 	}
+	return JSON.stringify(
+		pruneObject({
+			documentId: request.documentId,
+			variables: request.variables,
+			extensions: request.extensions,
+		}),
+	);
 };
 
 export const createRequest = async <TVariables>(
-	mode: ModeFlags,
 	query: string,
 	variables: TVariables,
 	documentId?: string,
+	includeQuery?: boolean,
 ): Promise<GraphQLRequest<TVariables>> => {
 	const operationName = extractOperationName(query) || "(GraphQL)";
 
 	const request = {
-		mode,
 		documentId,
 		query,
 		operationName,
 		variables,
 		extensions: {},
+		includeQuery: includeQuery ?? false,
 	};
 
 	/**
@@ -122,7 +106,7 @@ export const createRequest = async <TVariables>(
 	 * Note that these are not the same hashes as the documentId, which is
 	 * used for allowlisting of query documents
 	 */
-	if (mode === "document" || mode === "both") {
+	if (!documentId || request.includeQuery) {
 		request.extensions = {
 			persistedQuery: {
 				version: 1,

src/server.ts

@@ -46,11 +46,9 @@ type Options = {
 	defaultHeaders?: Headers | Record<string, string>;
 
 	/**
-	 * Mode to use for sending requests, persisted means that only the documentId
-	 * will be sent, document means that the full query will be sent and both
-	 * means that the full query and the documentId will be sent
+	 * If the query should always be sent, even if there is a document id
 	 */
-	mode?: "persisted" | "document" | "both";
+	includeQuery?: boolean;
 
 	/**
 	 * Function to customize creating the documentId from a query
@@ -79,7 +77,7 @@ export const initServerFetcher =
 			dangerouslyDisableCache = false,
 			defaultTimeout = 30000,
 			defaultHeaders = {},
-			mode = "document",
+			includeQuery = false,
 			createDocumentId = getDocumentId,
 		}: Options = {},
 	) =>
@@ -94,7 +92,12 @@ export const initServerFetcher =
 		const query = isNode(astNode) ? print(astNode) : astNode.toString();
 
 		const documentId = createDocumentId(astNode);
-		const request = await createRequest(mode, query, variables, documentId);
+		const request = await createRequest(
+			query,
+			variables,
+			documentId,
+			includeQuery,
+		);
 		const requestOptions: RequestOptions = {
 			signal: options.signal ?? AbortSignal.timeout(defaultTimeout),
 			headers: mergeHeaders({ ...defaultHeaders, ...options.headers }),