feat: add fetchOptions parameter to control fetch() (#291)

* feat: add `fetchOptions` parameter

* test: `fetchOptions`

src/client.ts

@@ -15,6 +15,7 @@ import {
 	FetchLike,
 	HttpRequestLike,
 	ExtractDocumentType,
+	RequestInitLike,
 } from "./types";
 import { ForbiddenError } from "./ForbiddenError";
 import { NotFoundError } from "./NotFoundError";
@@ -164,18 +165,33 @@ export type ClientConfig = {
 	 * Node.js, this function must be provided.
 	 */
 	fetch?: FetchLike;
+
+	/**
+	 * Options provided to the client's `fetch()` on all network requests. These
+	 * options will be merged with internally required options. They can also be
+	 * overriden on a per-query basis using the query's `fetchOptions` parameter.
+	 */
+	fetchOptions?: RequestInitLike;
 };
 
 /**
- * Parameters for any client method that use `fetch()`. Only a subset of
- * `fetch()` parameters are exposed.
+ * Parameters for any client method that use `fetch()`.
  */
 type FetchParams = {
+	/**
+	 * Options provided to the client's `fetch()` on all network requests. These
+	 * options will be merged with internally required options. They can also be
+	 * overriden on a per-query basis using the query's `fetchOptions` parameter.
+	 */
+	fetchOptions?: RequestInitLike;
+
 	/**
 	 * An `AbortSignal` provided by an `AbortController`. This allows the network
 	 * request to be cancelled if necessary.
 	 *
 	 * {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal}
+	 *
+	 * @deprecated Move the `signal` parameter into `fetchOptions.signal`.
 	 */
 	signal?: AbortSignalLike;
 };
@@ -341,6 +357,8 @@ export class Client<
 	 */
 	fetchFn: FetchLike;
 
+	fetchOptions?: RequestInitLike;
+
 	/**
 	 * Default parameters that will be sent with each query. These parameters can
 	 * be overridden on each query if needed.
@@ -404,6 +422,7 @@ export class Client<
 		this.accessToken = options.accessToken;
 		this.routes = options.routes;
 		this.brokenRoute = options.brokenRoute;
+		this.fetchOptions = options.fetchOptions;
 		this.defaultParams = options.defaultParams;
 
 		if (options.ref) {
@@ -1269,12 +1288,15 @@ export class Client<
 	 */
 	async buildQueryURL({
 		signal,
+		fetchOptions,
 		...params
 	}: Partial<BuildQueryURLArgs> & FetchParams = {}): Promise<string> {
-		const ref = params.ref || (await this.getResolvedRefString());
+		const ref =
+			params.ref || (await this.getResolvedRefString({ signal, fetchOptions }));
 		const integrationFieldsRef =
 			params.integrationFieldsRef ||
-			(await this.getCachedRepository({ signal })).integrationFieldsRef ||
+			(await this.getCachedRepository({ signal, fetchOptions }))
+				.integrationFieldsRef ||
 			undefined;
 
 		return buildQueryURL(this.endpoint, {
@@ -1338,9 +1360,10 @@ export class Client<
 
 		if (documentID != null && previewToken != null) {
 			const document = await this.getByID(documentID, {
-				signal: args.signal,
 				ref: previewToken,
 				lang: "*",
+				signal: args.signal,
+				fetchOptions: args.fetchOptions,
 			});
 
 			const url = prismicH.asLink(document, args.linkResolver);
@@ -1688,7 +1711,16 @@ export class Client<
 		// 	: {};
 
 		const res = await this.fetchFn(url, {
-			signal: params.signal,
+			...this.fetchOptions,
+			...params.fetchOptions,
+			headers: {
+				...this.fetchOptions?.headers,
+				...params.fetchOptions?.headers,
+			},
+			signal:
+				params.fetchOptions?.signal ||
+				params.signal ||
+				this.fetchOptions?.signal,
 		});
 
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any

src/types.ts

@@ -72,16 +72,23 @@ export type FetchLike = (
 export type AbortSignalLike = any;
 
 /**
- * The minimum required properties from RequestInit.
+ * A subset of RequestInit properties to configure a `fetch()` request.
  */
-export interface RequestInitLike {
+// Only options relevant to the client are included. Extending from the full
+// RequestInit would cause issues, such as accepting Header objects.
+//
+// An interface is used to allow other libraries to augment the type with
+// environment-specific types.
+export interface RequestInitLike extends Pick<RequestInit, "cache"> {
+	/**
+	 * An object literal to set the `fetch()` request's headers.
+	 */
 	headers?: Record<string, string>;
 
 	/**
-	 * An object that allows you to abort a `fetch()` request if needed via an
-	 * `AbortController` object
+	 * An AbortSignal to set the `fetch()` request's signal.
 	 *
-	 * {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal}
+	 * See: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
 	 */
 	// NOTE: `AbortSignalLike` is `any`! It is left as `AbortSignalLike`
 	// for backwards compatibility (the type is exported) and to signal to

test/__testutils__/testAbortableMethod.ts

@@ -1,21 +1,21 @@
-import { it, expect } from "vitest";
+import { expect, it } from "vitest";
 
-import { mockPrismicRestAPIV2 } from "./mockPrismicRestAPIV2";
 import { createTestClient } from "./createClient";
+import { mockPrismicRestAPIV2 } from "./mockPrismicRestAPIV2";
 
 import * as prismic from "../../src";
 
 type TestAbortableMethodArgs = {
 	run: (
 		client: prismic.Client,
-		signal: prismic.AbortSignalLike,
+		params?: Parameters<prismic.Client["get"]>[0],
 	) => Promise<unknown>;
 };
 
 export const testAbortableMethod = (
 	description: string,
 	args: TestAbortableMethodArgs,
-) => {
+): void => {
 	it.concurrent(description, async (ctx) => {
 		const controller = new AbortController();
 		controller.abort();
@@ -25,7 +25,31 @@ export const testAbortableMethod = (
 		const client = createTestClient();
 
 		await expect(async () => {
-			await args.run(client, controller.signal);
+			await args.run(client, {
+				fetchOptions: {
+					signal: controller.signal,
+				},
+			});
 		}).rejects.toThrow(/aborted/i);
 	});
+
+	// TODO: Remove once the `signal` parameter is removed in favor of
+	// `fetchOptions.signal`.
+	it.concurrent(
+		`${description} (using deprecated \`signal\` param)`,
+		async (ctx) => {
+			const controller = new AbortController();
+			controller.abort();
+
+			mockPrismicRestAPIV2({ ctx });
+
+			const client = createTestClient();
+
+			await expect(async () => {
+				await args.run(client, {
+					signal: controller.signal,
+				});
+			}).rejects.toThrow(/aborted/i);
+		},
+	);
 };

test/__testutils__/testFetchOptions.ts

@@ -0,0 +1,98 @@
+import * as prismic from "../../src";
+import { createTestClient } from "./createClient";
+import { mockPrismicRestAPIV2 } from "./mockPrismicRestAPIV2";
+import fetch from "node-fetch";
+import { expect, it, vi } from "vitest";
+
+type TestFetchOptionsArgs = {
+	run: (
+		client: prismic.Client,
+		params?: Parameters<prismic.Client["get"]>[0],
+	) => Promise<unknown>;
+};
+
+export const testFetchOptions = (
+	description: string,
+	args: TestFetchOptionsArgs,
+): void => {
+	it.concurrent(`${description} (on client)`, async (ctx) => {
+		const abortController = new AbortController();
+
+		const fetchSpy = vi.fn(fetch);
+		const fetchOptions: prismic.RequestInitLike = {
+			cache: "no-store",
+			headers: {
+				foo: "bar",
+			},
+			signal: abortController.signal,
+		};
+
+		const repositoryResponse = ctx.mock.api.repository();
+		const masterRef = ctx.mock.api.ref({ isMasterRef: true });
+		const releaseRef = ctx.mock.api.ref({ isMasterRef: false });
+		releaseRef.id = "id"; // Referenced in ref-related tests.
+		releaseRef.label = "label"; // Referenced in ref-related tests.
+		repositoryResponse.refs = [masterRef, releaseRef];
+
+		mockPrismicRestAPIV2({
+			ctx,
+			repositoryResponse,
+			queryResponse: ctx.mock.api.query({
+				documents: [ctx.mock.value.document()],
+			}),
+		});
+
+		const client = createTestClient({
+			clientConfig: {
+				fetch: fetchSpy,
+				fetchOptions,
+			},
+		});
+
+		await args.run(client);
+
+		for (const [input, init] of fetchSpy.mock.calls) {
+			expect(init, input.toString()).toStrictEqual(fetchOptions);
+		}
+	});
+
+	it.concurrent(`${description} (on method)`, async (ctx) => {
+		const abortController = new AbortController();
+
+		const fetchSpy = vi.fn(fetch);
+		const fetchOptions: prismic.RequestInitLike = {
+			cache: "no-store",
+			headers: {
+				foo: "bar",
+			},
+			signal: abortController.signal,
+		};
+
+		const repositoryResponse = ctx.mock.api.repository();
+		const masterRef = ctx.mock.api.ref({ isMasterRef: true });
+		const releaseRef = ctx.mock.api.ref({ isMasterRef: false });
+		releaseRef.id = "id"; // Referenced in ref-related tests.
+		releaseRef.label = "label"; // Referenced in ref-related tests.
+		repositoryResponse.refs = [masterRef, releaseRef];
+
+		mockPrismicRestAPIV2({
+			ctx,
+			repositoryResponse,
+			queryResponse: ctx.mock.api.query({
+				documents: [ctx.mock.value.document()],
+			}),
+		});
+
+		const client = createTestClient({
+			clientConfig: {
+				fetch: fetchSpy,
+			},
+		});
+
+		await args.run(client, { fetchOptions });
+
+		for (const [input, init] of fetchSpy.mock.calls) {
+			expect(init, input.toString()).toStrictEqual(fetchOptions);
+		}
+	});
+};

test/client-dangerouslyGetAll.test.ts

@@ -7,6 +7,7 @@ import { testAbortableMethod } from "./__testutils__/testAbortableMethod";
 import { testGetAllMethod } from "./__testutils__/testAnyGetMethod";
 
 import { GET_ALL_QUERY_DELAY } from "../src/client";
+import { testFetchOptions } from "./__testutils__/testFetchOptions";
 
 /**
  * Tolerance in number of milliseconds for the duration of a simulated network
@@ -178,6 +179,10 @@ it("does not throttle single page queries", async (ctx) => {
 	).toBe(true);
 });
 
+testFetchOptions("supports fetch options", {
+	run: (client, params) => client.dangerouslyGetAll(params),
+});
+
 testAbortableMethod("is abortable with an AbortController", {
-	run: (client, signal) => client.dangerouslyGetAll({ signal }),
+	run: (client, params) => client.dangerouslyGetAll(params),
 });

test/client-get.test.ts

@@ -1,5 +1,6 @@
 import { testGetMethod } from "./__testutils__/testAnyGetMethod";
 import { testAbortableMethod } from "./__testutils__/testAbortableMethod";
+import { testFetchOptions } from "./__testutils__/testFetchOptions";
 
 testGetMethod("resolves a query", {
 	run: (client) => client.get(),
@@ -52,6 +53,10 @@ testGetMethod("merges params and default params if provided", {
 	},
 });
 
+testFetchOptions("supports fetch options", {
+	run: (client, params) => client.get(params),
+});
+
 testAbortableMethod("is abortable with an AbortController", {
-	run: (client, signal) => client.get({ signal }),
+	run: (client, params) => client.get(params),
 });

test/client-getAllByEveryTag.test.ts

@@ -1,5 +1,6 @@
 import { testGetAllMethod } from "./__testutils__/testAnyGetMethod";
 import { testAbortableMethod } from "./__testutils__/testAbortableMethod";
+import { testFetchOptions } from "./__testutils__/testFetchOptions";
 
 testGetAllMethod("returns all documents by every tag from paginated response", {
 	run: (client) => client.getAllByEveryTag(["foo", "bar"]),
@@ -23,6 +24,10 @@ testGetAllMethod("includes params if provided", {
 	},
 });
 
+testFetchOptions("supports fetch options", {
+	run: (client, params) => client.getAllByEveryTag(["foo", "bar"], params),
+});
+
 testAbortableMethod("is abortable with an AbortController", {
-	run: (client, signal) => client.getAllByEveryTag(["foo", "bar"], { signal }),
+	run: (client, params) => client.getAllByEveryTag(["foo", "bar"], params),
 });

test/client-getAllByIDs.test.ts

@@ -1,5 +1,6 @@
 import { testGetAllMethod } from "./__testutils__/testAnyGetMethod";
 import { testAbortableMethod } from "./__testutils__/testAbortableMethod";
+import { testFetchOptions } from "./__testutils__/testFetchOptions";
 
 testGetAllMethod("returns all documents by IDs from paginated response", {
 	run: (client) => client.getAllByIDs(["id1", "id2"]),
@@ -23,6 +24,10 @@ testGetAllMethod("includes params if provided", {
 	},
 });
 
+testFetchOptions("supports fetch options", {
+	run: (client, params) => client.getAllByIDs(["id1", "id2"], params),
+});
+
 testAbortableMethod("is abortable with an AbortController", {
-	run: (client, signal) => client.getAllByIDs(["id1", "id2"], { signal }),
+	run: (client, params) => client.getAllByIDs(["id1", "id2"], params),
 });

test/client-getAllBySomeTags.test.ts

@@ -1,5 +1,6 @@
 import { testGetAllMethod } from "./__testutils__/testAnyGetMethod";
 import { testAbortableMethod } from "./__testutils__/testAbortableMethod";
+import { testFetchOptions } from "./__testutils__/testFetchOptions";
 
 testGetAllMethod("returns all documents by some tags from paginated response", {
 	run: (client) => client.getAllBySomeTags(["foo", "bar"]),
@@ -23,6 +24,10 @@ testGetAllMethod("includes params if provided", {
 	},
 });
 
+testFetchOptions("supports fetch options", {
+	run: (client, params) => client.getAllBySomeTags(["foo", "bar"], params),
+});
+
 testAbortableMethod("is abortable with an AbortController", {
-	run: (client, signal) => client.getAllBySomeTags(["foo", "bar"], { signal }),
+	run: (client, params) => client.getAllBySomeTags(["foo", "bar"], params),
 });