Unverified Commit 05c7df9d authored by Sebastian Markbåge's avatar Sebastian Markbåge Committed by GitHub

Format generated cacheLife() types as overloads with each value (#71544)

This way you can see inline what it really means in terms of numbers
with descriptions.

Also, document inline CacheLife values.

Also fixed a bug where we weren't transferring defaults when a custom
was defined.

<img width="733" alt="Screenshot 2024-10-20 at 8 48 39 PM"
src="https://github.com/user-attachments/assets/420db267-343b-4dc8-9efa-13b0befe8efa">

<img width="700" alt="Screenshot 2024-10-20 at 8 48 48 PM"
src="https://github.com/user-attachments/assets/0628b716-b906-49df-a016-65cd9c0b49bf">
parent b18c027a
...@@ -4,5 +4,140 @@ export { ...@@ -4,5 +4,140 @@ export {
revalidatePath, revalidatePath,
} from 'next/dist/server/web/spec-extension/revalidate' } from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store' export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { cacheLife as unstable_cacheLife } from 'next/dist/server/use-cache/cache-life'
export { cacheTag as unstable_cacheTag } from 'next/dist/server/use-cache/cache-tag' export { cacheTag as unstable_cacheTag } from 'next/dist/server/use-cache/cache-tag'
/**
* Cache this `"use cache"` for a timespan defined by the `"default"` profile.
* ```
* stale: 300 seconds (5 minutes)
* revalidate: 900 seconds (15 minutes)
* expire: never
* ```
*
* This cache may be stale on clients for 5 minutes before checking with the server.
* If the server receives a new request after 15 minutes, start revalidating new values in the background.
* It lives for the maximum age of the server cache. If this entry has no traffic for a while, it may serve an old value the next request.
*/
export function unstable_cacheLife(profile: 'default'): void
/**
* Cache this `"use cache"` for a timespan defined by the `"seconds"` profile.
* ```
* stale: 0 seconds
* revalidate: 1 seconds
* expire: 1 seconds
* ```
*
* This cache may be stale on clients for 0 seconds before checking with the server.
* This cache will expire after 1 seconds. The next request will recompute it.
*/
export function unstable_cacheLife(profile: 'seconds'): void
/**
* Cache this `"use cache"` for a timespan defined by the `"minutes"` profile.
* ```
* stale: 300 seconds (5 minutes)
* revalidate: 60 seconds (1 minute)
* expire: 3600 seconds (1 hour)
* ```
*
* This cache may be stale on clients for 5 minutes before checking with the server.
* If the server receives a new request after 1 minute, start revalidating new values in the background.
* If this entry has no traffic for 1 hour it will expire. The next request will recompute it.
*/
export function unstable_cacheLife(profile: 'minutes'): void
/**
* Cache this `"use cache"` for a timespan defined by the `"hours"` profile.
* ```
* stale: 300 seconds (5 minutes)
* revalidate: 3600 seconds (1 hour)
* expire: 86400 seconds (1 day)
* ```
*
* This cache may be stale on clients for 5 minutes before checking with the server.
* If the server receives a new request after 1 hour, start revalidating new values in the background.
* If this entry has no traffic for 1 day it will expire. The next request will recompute it.
*/
export function unstable_cacheLife(profile: 'hours'): void
/**
* Cache this `"use cache"` for a timespan defined by the `"days"` profile.
* ```
* stale: 300 seconds (5 minutes)
* revalidate: 86400 seconds (1 day)
* expire: 604800 seconds (1 week)
* ```
*
* This cache may be stale on clients for 5 minutes before checking with the server.
* If the server receives a new request after 1 day, start revalidating new values in the background.
* If this entry has no traffic for 1 week it will expire. The next request will recompute it.
*/
export function unstable_cacheLife(profile: 'days'): void
/**
* Cache this `"use cache"` for a timespan defined by the `"weeks"` profile.
* ```
* stale: 300 seconds (5 minutes)
* revalidate: 604800 seconds (1 week)
* expire: 2592000 seconds (30 days)
* ```
*
* This cache may be stale on clients for 5 minutes before checking with the server.
* If the server receives a new request after 1 week, start revalidating new values in the background.
* If this entry has no traffic for 30 days it will expire. The next request will recompute it.
*/
export function unstable_cacheLife(profile: 'weeks'): void
/**
* Cache this `"use cache"` for a timespan defined by the `"max"` profile.
* ```
* stale: 300 seconds (5 minutes)
* revalidate: 2592000 seconds (30 days)
* expire: never
* ```
*
* This cache may be stale on clients for 5 minutes before checking with the server.
* If the server receives a new request after 30 days, start revalidating new values in the background.
* It lives for the maximum age of the server cache. If this entry has no traffic for a while, it may serve an old value the next request.
*/
export function unstable_cacheLife(profile: 'max'): void
/**
* Cache this `"use cache"` using a custom profile "...".
* ```
* stale: ... // seconds
* revalidate: ... // seconds
* expire: ... // seconds
* ```
*
* You can define custom profiles in `next.config.ts`.
*/
export function unstable_cacheLife(profile: string): void
/**
* Cache this `"use cache"` using a custom timespan.
* ```
* stale: ... // seconds
* revalidate: ... // seconds
* expire: ... // seconds
* ```
*
* This is similar to Cache-Control: max-age=`stale`,s-max-age=`revalidate`,stale-while-revalidate=`expire-revalidate`
*
* If a value is left out, the lowest of other cacheLife() calls or the default, is used instead.
*/
export function unstable_cacheLife(profile: {
/**
* This cache may be stale on clients for ... seconds before checking with the server.
*/
stale?: number
/**
* If the server receives a new request after ... seconds, start revalidating new values in the background.
*/
revalidate?: number
/**
* If this entry has no traffic for ... seconds it will expire. The next request will recompute it.
*/
expire?: number
}): void
...@@ -527,19 +527,159 @@ declare module 'next/form' { ...@@ -527,19 +527,159 @@ declare module 'next/form' {
` `
} }
function formatTimespan(seconds: number): string {
if (seconds > 0) {
if (seconds === 18748800) {
return '1 month'
}
if (seconds === 18144000) {
return '1 month'
}
if (seconds === 604800) {
return '1 week'
}
if (seconds === 86400) {
return '1 day'
}
if (seconds === 3600) {
return '1 hour'
}
if (seconds === 60) {
return '1 minute'
}
if (seconds % 18748800 === 0) {
return seconds / 18748800 + ' months'
}
if (seconds % 18144000 === 0) {
return seconds / 18144000 + ' months'
}
if (seconds % 604800 === 0) {
return seconds / 604800 + ' weeks'
}
if (seconds % 86400 === 0) {
return seconds / 86400 + ' days'
}
if (seconds % 3600 === 0) {
return seconds / 3600 + ' hours'
}
if (seconds % 60 === 0) {
return seconds / 60 + ' minutes'
}
}
return seconds + ' seconds'
}
function formatTimespanWithSeconds(seconds: undefined | number): string {
if (seconds === undefined) {
return 'default'
}
if (seconds >= 0xfffffffe) {
return 'never'
}
const text = seconds + ' seconds'
const descriptive = formatTimespan(seconds)
if (descriptive === text) {
return text
}
return text + ' (' + descriptive + ')'
}
function createCustomCacheLifeDefinitions(cacheLife: { function createCustomCacheLifeDefinitions(cacheLife: {
[profile: string]: CacheLife [profile: string]: CacheLife
}) { }) {
const profiles = Object.keys(cacheLife) let overloads = ''
if (!profiles.includes('default')) {
profiles.push('default') const profileNames = Object.keys(cacheLife)
} for (let i = 0; i < profileNames.length; i++) {
for (let i = 0; i < profiles.length; i++) { const profileName = profileNames[i]
profiles[i] = JSON.stringify(profiles[i]) const profile = cacheLife[profileName]
if (typeof profile !== 'object' || profile === null) {
continue
}
let description = ''
if (profile.stale === undefined) {
description += `
* This cache may be stale on clients for the default stale time of the scope before checking with the server.`
} else if (profile.stale >= 0xfffffffe) {
description += `
* This cache may be stale on clients indefinitely before checking with the server.`
} else {
description += `
* This cache may be stale on clients for ${formatTimespan(profile.stale)} before checking with the server.`
}
if (
profile.revalidate !== undefined &&
profile.expire !== undefined &&
profile.revalidate >= profile.expire
) {
description += `
* This cache will expire after ${formatTimespan(profile.expire)}. The next request will recompute it.`
} else {
if (profile.revalidate === undefined) {
description += `
* It will inherit the default revalidate time of its scope since it does not define its own.`
} else if (profile.revalidate >= 0xfffffffe) {
// Nothing to mention.
} else {
description += `
* If the server receives a new request after ${formatTimespan(profile.revalidate)}, start revalidating new values in the background.`
}
if (profile.expire === undefined) {
description += `
* It will inherit the default expiration time of its scope since it does not define its own.`
} else if (profile.expire >= 0xfffffffe) {
description += `
* It lives for the maximum age of the server cache. If this entry has no traffic for a while, it may serve an old value the next request.`
} else {
description += `
* If this entry has no traffic for ${formatTimespan(profile.expire)} it will expire. The next request will recompute it.`
}
}
overloads += `
/**
* Cache this \`"use cache"\` for a timespan defined by the \`${JSON.stringify(profileName)}\` profile.
* \`\`\`
* stale: ${formatTimespanWithSeconds(profile.stale)}
* revalidate: ${formatTimespanWithSeconds(profile.revalidate)}
* expire: ${formatTimespanWithSeconds(profile.expire)}
* \`\`\`
* ${description}
*/
export function unstable_cacheLife(profile: ${JSON.stringify(profileName)}): void
`
} }
// TODO: Annotate each option with their expanded values for IDE support. overloads += `
const profilesEnum = profiles.join(' | ') /**
* Cache this \`"use cache"\` using a custom timespan.
* \`\`\`
* stale: ... // seconds
* revalidate: ... // seconds
* expire: ... // seconds
* \`\`\`
*
* This is similar to Cache-Control: max-age=\`stale\`,s-max-age=\`revalidate\`,stale-while-revalidate=\`expire-revalidate\`
*
* If a value is left out, the lowest of other cacheLife() calls or the default, is used instead.
*/
export function unstable_cacheLife(profile: {
/**
* This cache may be stale on clients for ... seconds before checking with the server.
*/
stale?: number,
/**
* If the server receives a new request after ... seconds, start revalidating new values in the background.
*/
revalidate?: number,
/**
* If this entry has no traffic for ... seconds it will expire. The next request will recompute it.
*/
expire?: number
}): void
`
// Redefine the cacheLife() accepted arguments. // Redefine the cacheLife() accepted arguments.
return `// Type definitions for Next.js cacheLife configs return `// Type definitions for Next.js cacheLife configs
...@@ -552,9 +692,7 @@ declare module 'next/cache' { ...@@ -552,9 +692,7 @@ declare module 'next/cache' {
} from 'next/dist/server/web/spec-extension/revalidate' } from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store' export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
import type { CacheLife } from 'next/dist/server/use-cache/cache-life' ${overloads}
export function unstable_cacheLife(profile: ${profilesEnum} | CacheLife): void
export { cacheTag as unstable_cacheTag } from 'next/dist/server/use-cache/cache-tag' export { cacheTag as unstable_cacheTag } from 'next/dist/server/use-cache/cache-tag'
} }
......
...@@ -810,7 +810,11 @@ function assignDefaults( ...@@ -810,7 +810,11 @@ function assignDefaults(
} }
} }
if (result.experimental?.cacheLife) { if (result.experimental) {
result.experimental.cacheLife = {
...defaultConfig.experimental?.cacheLife,
...result.experimental.cacheLife,
}
const defaultDefault = defaultConfig.experimental?.cacheLife?.['default'] const defaultDefault = defaultConfig.experimental?.cacheLife?.['default']
if ( if (
!defaultDefault || !defaultDefault ||
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment