feat: add fetchOptions parameter to control fetch()

[angeloashmore]

Types of changes

• Chore (a non-breaking change which is related to package maintenance)
• Bug fix (a non-breaking change which fixes an issue)
• New feature (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR adds a new fetchOptions parameter to createClient() and all client methods that make network requests.

The parameter allows for customizing how fetch() is called.

// Set `fetch()` options for every request.
const client = createClient("example-prismic-repo", {
  fetchOptions: {
    cache: "force-cache",
  },
});

// Set or override `fetch()` options for individual queries.
const page = await client.getByUID("page", "home", {
  fetchOptions: {
    cache: "no-store",
  },
});

Supported options

The TypeScript types support a subset of the global RequestInit type:

• headers (only plain objects are supported)
• cache
• signal

These three parameters have known real-world use cases, while others, like credentials, currently do not.

If we learn that other parameters are needed, we can add support for them in the future.

Adding support for project-specific options

@prismicio/client's type for fetchOptions can be augmented on a per-project basis using module augmentation.

This is useful if a project needs to add support for a RequestInit property that is not supported by default. It is also useful if projects have project-specific RequestInit features that need to be added, like Next.js' next parameter.

// Adds `credentials` support.
declare module "@prismicio/client" {
  interface RequestInitLike {
    credentials?: RequestInit["credentials"];
  }
}

const client = createClient("example-prismic-repo", {
  fetchOptions: {
    credentials: "same-origin",
  },
});

Deprecating signal parameter in favor of fetchOptions.signal

The signal parameter has been replaced by the more apt fetchOptions.signal.

const controller = new AbortSignal();
const client = createClient("example-prismic-repo");

// New
await client.getByUID("page", "home", {
  fetchOptions: {
    signal: controller.signal,
  },
});

// Old
await client.getByUID("page", "home", {
  signal: controller.signal,
});

signal will continue to be supported, but has been marked as deprecated. Please migrate to fetchOptions.signal.

Checklist:

• My change requires an update to the official documentation.
• All TSDoc comments are up-to-date and new ones have been added where necessary.
• All new and existing tests are passing.

🐕

[codecov-commenter]

Codecov Report

Merging #289 (ec3e0d9) into v7 (f1e6f9a) will increase coverage by 0.00%.
The diff coverage is 100.00%.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@           Coverage Diff           @@
##               v7     #289   +/-   ##
=======================================
  Coverage   99.94%   99.94%           
=======================================
  Files          49       49           
  Lines        5650     5698   +48     
  Branches      299      302    +3     
=======================================
+ Hits         5647     5695   +48     
  Misses          3        3           

Impacted Files	Coverage Δ
src/createClient.ts	100.00% <100.00%> (ø)

[lihbr]

Looking sharp 👌