feat(next-drupal): next revalidate options

[MontiMarco92]

Adds next revalidate options to resource-methods and custom fetch.

This pull request is for: (mark with an "x")

• examples/*
• modules/next
• packages/next-drupal
• starters/basic-starter
• starters/graphql-starter
• starters/pages-starter
• Other

GitHub Issue: #761

• I need help adding tests. (mark with an "x")
  Code changes need test coverage. If you don't know
  how to make tests, check this box to ask for help.

Describe your changes

I've extended the custom fetch function to accept the next revalidation options.

• fetch("https://...", { next: { revalidate: false | 0 | number } })
• fetch("https://...", { next: { tags: ['node:1', 'tag:2'] } })

I've added the next option to the following resource-methods:

getResource
getResourceByPath
getResourceCollection
getResourceCollectionPathSegments
translatePath
getIndex
getMenu
getView
getSearchIndex

It might be necessary to add it to CRUD methods or others, but I'll wait for feedback first.

I've added some unitary tests as well but might need refinement.

Contribution

Sponsored by @brainsum

[vercel]

Someone is attempting to deploy a commit to the Chapter Three Team on Vercel.

A member of the Team first needs to authorize it.

[backlineint]

Popping in on this one based on my ongoing review of #787 Specifically: https://github.com/chapter-three/next-drupal/pull/787/files#diff-5b898e58a9c454bff499b9401f4794981861fc3d8870905f57e8082c4e24b6f5

The notes about NextFetchRequestConfig caused me to take a closer look at the types to confirm that this would actually be possible in the state of the codebase that the Docs PR is in. I believe it is possible to pass options like next: { revalidate: 3600 } - our FetchOptions interface extends Next's RequestInit which does have the next property that accepts options for revalidate and tags. That was a mouthful. Here's what the types look like:

Our fetch options:

export interface FetchOptions extends RequestInit {
  withAuth?: boolean | NextDrupalAuth
}

Next Types:

interface RequestInit {
  next?: NextFetchRequestConfig | undefined
}`

interface NextFetchRequestConfig {
  revalidate?: number | false
  tags?: string[]
}

Based on reading that code, I'd expect this to already be supported without this JsonApiWithNextFetchOptions type. But my guess is that you saw otherwise when actually working with this.

[robdecker]

Thanks for bring this up @backlineint. Looking at this again, I noticed that in "our" functions (getResource, createResource, etc) the options parameter is of type JsonApiOptions and not FetchOptions. JsonApiOptions doesn't contain many of the properties that FetchOptions has. We should take a closer look at this and probably rework JsonApiOptions to include all/some of FetchOptions.

[davidwhthomas]

It's becoming a bit problematic not being able to pass cache options with next-drupal API requests.

For example:

• We can't specify Next fetch cache time-based options such as revalidate.
• We can't include Drupal cache-tags and use granular revalidateTag cache tag invalidation.
• Next v15, now RC, no longer caches by default so it becomes more important to be able to pass cache options with the fetch requests.

What needs doing to progress this feature?

[backlineint]

Agreed @davidwhthomas - working on setting some time aside this week to try to help move this one forward.

While I'm here, one thing that either needs to be added here, or handled in a follow up issue is adding the api route for tag invalidation to the basic (app router) starter.

[backlineint]

Thanks for bring this up @backlineint. Looking at this again, I noticed that in "our" functions (getResource, createResource, etc) the options parameter is of type JsonApiOptions and not FetchOptions. JsonApiOptions doesn't contain many of the properties that FetchOptions has. We should take a closer look at this and probably rework JsonApiOptions to include all/some of FetchOptions.

Took another look at this, and I think the problem is that the next-drupal-pages class also uses JsonApiOptions. Adding fetchOptions to JsonApiOptions won't make sense for the pages router. Don't doubt that we could still refine these types, but also don't see an easy path to that in this PR.

[backlineint]

Tested this locally and both the revalidation and tags options seem to work great. I think we can merge this (ideally after accepting the small type related suggestion)

There are two things I think we need to do to complete this story on the front end, which I'll create follow up tickets for:

• Update api/revalidate/route.ts in all three starters to accept a tags param that will then be used to call revalidateTag.
• Update one of the Options types to accept a cache option - https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data. As @davidwhthomas mentioned, I think we get away with this now because Next 13/14 set this to force-cache by default, but next 15 will use no-cache instead by default. Without this, I don't think it will be possible to use the revalidate option in Next 15.

[backlineint]

Suggested change

	export interface FetchOptions extends RequestInit, JsonApiWithNextFetchOptions {
	export interface FetchOptions extends RequestInit {

I tested locally and confirmed that we don't need to add JsonApiWithNextFetchOptions here.

[MontiMarco92]

You're right. I removed this from the FetchOptions type.

[backlineint]

Thanks for bring this up @backlineint. Looking at this again, I noticed that in "our" functions (getResource, createResource, etc) the options parameter is of type JsonApiOptions and not FetchOptions. JsonApiOptions doesn't contain many of the properties that FetchOptions has. We should take a closer look at this and probably rework JsonApiOptions to include all/some of FetchOptions.

Took another look at this, and I think the problem is that the next-drupal-pages class also uses JsonApiOptions. Adding fetchOptions to JsonApiOptions won't make sense for the pages router. Don't doubt that we could still refine these types, but also don't see an easy path to that in this PR.

[MontiMarco92]

@backlineint I've made the correction to the FetchOptions interface. So it would be ready to merge. As you commented, there are a few steps to follow in further tickets:

• Update starters
• Add cache option to methods to follow the next js fetch options.
• Check if it's relevant to extend this next: {revalidate} option to another CRUD methods. See main PR description to check which methods support revalidate options for now.
• Update the docs again to add information to the corresponding methods about the new allowed parameter.

Thanks!