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

Note: This PR backports #289 from v7 to v6. It is being backported to support existing Next.js projects that want to upgrade to App Router, but can't yet upgrade @prismicio/client to v7.

The following description is copied from #289, originally written for v7.

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.

🐈‍⬛

[github-actions]

size-limit report 📦

Path	Size
dist/index.js	3.92 KB (+2.17% 🔺)
dist/index.cjs	8.95 KB (+1% 🔺)

[lihbr]

LGTM 👌