Skip to content

Commit 02a73c5

Browse files
authored
Rename DYNAMIC_EXPIRE and DYNAMIC_STALE to describe what they gate (#95361)
The `DYNAMIC_EXPIRE` and `DYNAMIC_STALE` constants read as if the value itself is a dynamic expire or stale time, but every comparison is `expire < DYNAMIC_EXPIRE` / `stale < DYNAMIC_STALE`, so the value is the exclusive upper bound of the dynamic range: it is the smallest value that is *not* dynamic, not a dynamic value. The names are backwards at the boundary, which is easy to misread. The two thresholds also gate different things. `expire` gates whether a cache entry is included in the static prerender: below the threshold it becomes a dynamic hole, though a short-`expire` value is still served during a runtime prefetch. `stale` gates whether an entry is included in a runtime prefetch or app shell. This renames them to name that consequence: `MIN_PRERENDERABLE_EXPIRE` and `MIN_PREFETCHABLE_STALE`. It reads correctly both at the comparison sites (`expire < MIN_PRERENDERABLE_EXPIRE` is "below the minimum prerenderable expire", i.e. dynamic) and at the one site that uses the value directly, where private caches force `expire: MIN_PRERENDERABLE_EXPIRE` precisely because it is the shortest expire that stays prerenderable (and so is retained without being reclassified as a short-expire dynamic hole). This is a pure rename with no behavior change. --- <sub>Stack created with <a href="GitHub">https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a href="Give" rel="nofollow">https://gh.io/stacks-feedback">Give Feedback 💬</a></sub>
1 parent a25865f commit 02a73c5

12 files changed

Lines changed: 75 additions & 61 deletions

File tree

‎packages/next/src/server/app-render/work-unit-async-storage.external.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -366,8 +366,8 @@ export interface PublicUseCacheStore extends CommonUseCacheStore {
366366
readonly readRootParamNames: Set<string>
367367
/**
368368
* The first nested public `'use cache'` invocation with a dynamic cache life
369-
* (`revalidate === 0` or `expire < DYNAMIC_EXPIRE`) that propagated up to
370-
* this store. Used as `cause` for the nested-dynamic cache error so the
369+
* (`revalidate === 0` or `expire < MIN_PRERENDERABLE_EXPIRE`) that propagated
370+
* up to this store. Used as `cause` for the nested-dynamic cache error so the
371371
* redbox can point at the inner invocation site, not just the outer one.
372372
*/
373373
dynamicNestedCacheError: Error | undefined

‎packages/next/src/server/resume-data-cache/cache-store.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import {
33
stringToUint8Array,
44
} from '../app-render/encryption-utils'
55
import type { CachedFetchValue } from '../response-cache/types'
6-
import { DYNAMIC_EXPIRE } from '../use-cache/constants'
6+
import { MIN_PRERENDERABLE_EXPIRE } from '../use-cache/constants'
77
import type { CollectedCacheResult } from '../use-cache/use-cache-wrapper'
88

99
/**
@@ -135,7 +135,8 @@ export async function serializeUseCacheCacheStore(
135135
}) => {
136136
if (
137137
isCacheComponentsEnabled &&
138-
(entry.revalidate === 0 || entry.expire < DYNAMIC_EXPIRE)
138+
(entry.revalidate === 0 ||
139+
entry.expire < MIN_PRERENDERABLE_EXPIRE)
139140
) {
140141
// The entry was omitted from the prerender result, and subsequently
141142
// does not need to be included in the serialized RDC.
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
export const DYNAMIC_EXPIRE = 300 // 5 minutes
2-
export const DYNAMIC_STALE = 30 // 30 seconds
1+
export const MIN_PRERENDERABLE_EXPIRE = 300 // 5 minutes
2+
export const MIN_PREFETCHABLE_STALE = 30 // 30 seconds

‎packages/next/src/server/use-cache/use-cache-wrapper.ts‎

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ import {
5959
} from '../app-render/create-error-handler'
6060
import { createDigestWithErrorCode } from '../../lib/error-telemetry-utils'
6161
import stringHash from 'next/dist/compiled/string-hash'
62-
import { DYNAMIC_EXPIRE, DYNAMIC_STALE } from './constants'
62+
import { MIN_PRERENDERABLE_EXPIRE, MIN_PREFETCHABLE_STALE } from './constants'
6363
import { NEXT_CACHE_ROOT_PARAM_TAG_ID } from '../../lib/constants'
6464
import {
6565
getCacheHandler,
@@ -907,7 +907,8 @@ function propagateCacheEntryMetadata(
907907
// cause points at the immediate dynamic child.
908908
if (
909909
cacheContext.dynamicNestedCacheError !== undefined &&
910-
(metadata.revalidate === 0 || metadata.expire < DYNAMIC_EXPIRE)
910+
(metadata.revalidate === 0 ||
911+
metadata.expire < MIN_PRERENDERABLE_EXPIRE)
911912
) {
912913
cacheContext.outerWorkUnitStore.dynamicNestedCacheError ??=
913914
cacheContext.dynamicNestedCacheError
@@ -1085,18 +1086,18 @@ async function collectResult(
10851086
)
10861087

10871088
// In development, force a dynamic cache life (`revalidate: 0`, `expire:
1088-
// DYNAMIC_EXPIRE`) for private caches, which have no real backing handler.
1089-
// The zero revalidate makes every read serve stale-while-revalidate
1090-
// (regenerating a fresh entry in the background), and `DYNAMIC_EXPIRE` (5
1091-
// minutes) caps how long an entry lingers in the dedicated in-memory private
1092-
// handler. It is the shortest `expire` that isn't treated as dynamic; a
1093-
// smaller `expire` would exclude the entry from prerenders. The size-0 case
1094-
// (`cacheMaxMemorySize: 0`) deliberately does NOT force this: it keeps its
1095-
// resolved cache life so that the cache entry can be considered prerenderable
1096-
// instead of being misread as a dynamic hole, and a separate dev revalidation
1097-
// (see the cache-hit path below) keeps its reloads showing a fresh value.
1098-
// Custom kinds keep their real cache life too, since their backing handler
1099-
// owns it.
1089+
// MIN_PRERENDERABLE_EXPIRE`) for private caches, which have no real backing
1090+
// handler. The zero revalidate makes every read serve stale-while-revalidate
1091+
// (regenerating a fresh entry in the background), and
1092+
// `MIN_PRERENDERABLE_EXPIRE` (5 minutes) caps how long an entry lingers in
1093+
// the dedicated in-memory private handler. It is the shortest `expire` that
1094+
// isn't treated as dynamic; a smaller `expire` would exclude the entry from
1095+
// prerenders. The size-0 case (`cacheMaxMemorySize: 0`) deliberately does NOT
1096+
// force this: it keeps its resolved cache life so that the cache entry can be
1097+
// considered prerenderable instead of being misread as a dynamic hole, and a
1098+
// separate dev revalidation (see the cache-hit path below) keeps its reloads
1099+
// showing a fresh value. Custom kinds keep their real cache life too, since
1100+
// their backing handler owns it.
11001101
const forceDynamicCacheLifeInDev = isPrivateCacheInDev
11011102

11021103
// If cacheLife() was used to set an explicit revalidate/expire/stale time we
@@ -1108,7 +1109,7 @@ async function collectResult(
11081109
? innerCacheStore.explicitRevalidate
11091110
: innerCacheStore.revalidate
11101111
const collectedExpire = forceDynamicCacheLifeInDev
1111-
? DYNAMIC_EXPIRE
1112+
? MIN_PRERENDERABLE_EXPIRE
11121113
: innerCacheStore.explicitExpire !== undefined
11131114
? innerCacheStore.explicitExpire
11141115
: innerCacheStore.expire
@@ -2254,7 +2255,7 @@ export async function cache(
22542255
if (rdcResult !== undefined) {
22552256
if (
22562257
rdcResult.entry.revalidate === 0 ||
2257-
rdcResult.entry.expire < DYNAMIC_EXPIRE
2258+
rdcResult.entry.expire < MIN_PRERENDERABLE_EXPIRE
22582259
) {
22592260
switch (workUnitStore.type) {
22602261
case 'prerender':
@@ -2320,8 +2321,8 @@ export async function cache(
23202321
// otherwise silently shorten. A dev private cache's
23212322
// `revalidate` is forced to 0 by us (not by a nested cache), so
23222323
// it's excluded from the first throw to avoid a false positive.
2323-
// Its forced `expire` is exactly DYNAMIC_EXPIRE, so it never
2324-
// trips the second throw and needs no exclusion there.
2324+
// Its forced `expire` is exactly MIN_PRERENDERABLE_EXPIRE, so
2325+
// it never trips the second throw and needs no exclusion there.
23252326
if (
23262327
cacheContext.kind !== 'private' &&
23272328
rdcResult.entry.revalidate === 0 &&
@@ -2334,7 +2335,7 @@ export async function cache(
23342335
)
23352336
}
23362337
if (
2337-
rdcResult.entry.expire < DYNAMIC_EXPIRE &&
2338+
rdcResult.entry.expire < MIN_PRERENDERABLE_EXPIRE &&
23382339
rdcResult.hasExplicitExpire === false
23392340
) {
23402341
throw wrapAsInvalidDynamicUsageError(
@@ -2378,7 +2379,7 @@ export async function cache(
23782379
}
23792380
}
23802381

2381-
if (rdcResult.entry.stale < DYNAMIC_STALE) {
2382+
if (rdcResult.entry.stale < MIN_PREFETCHABLE_STALE) {
23822383
switch (workUnitStore.type) {
23832384
case 'prerender':
23842385
case 'prerender-runtime':
@@ -2826,7 +2827,7 @@ export async function cache(
28262827
const currentTime = performance.timeOrigin + performance.now()
28272828
if (
28282829
entry !== undefined &&
2829-
(entry.revalidate === 0 || entry.expire < DYNAMIC_EXPIRE)
2830+
(entry.revalidate === 0 || entry.expire < MIN_PRERENDERABLE_EXPIRE)
28302831
) {
28312832
switch (workUnitStore.type) {
28322833
case 'prerender':
@@ -2903,7 +2904,7 @@ export async function cache(
29032904
}
29042905
}
29052906

2906-
if (entry !== undefined && entry.stale < DYNAMIC_STALE) {
2907+
if (entry !== undefined && entry.stale < MIN_PREFETCHABLE_STALE) {
29072908
switch (workUnitStore.type) {
29082909
case 'request': {
29092910
// A short stale time excludes the entry from prerenders.

‎test/e2e/app-dir/segment-cache/prefetch-runtime/app/(default)/caches/private-seconds/page.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export default async function Page() {
1313
This page uses a short-lived private cache (with cacheLife("seconds")),
1414
which should not be included in a static prefetch, but should be
1515
included in a runtime prefetch, because it has a long enough stale time
16-
(&ge; DYNAMIC_STALE, 30s)
16+
(&ge; MIN_PREFETCHABLE_STALE, 30s)
1717
</p>
1818
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
1919
<ShortLivedCache />

‎test/e2e/app-dir/segment-cache/prefetch-runtime/app/(default)/caches/private-short-stale/page.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ export default async function Page() {
1111
<DebugRenderKind />
1212
<p id="intro">
1313
This page uses a short-lived private cache (staleTime &lt;
14-
DYNAMIC_STALE, which is 30s), which should not be included in a runtime
15-
prefetch
14+
MIN_PREFETCHABLE_STALE, which is 30s), which should not be included in a
15+
runtime prefetch
1616
</p>
1717
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
1818
<CachedButShortLived />

‎test/e2e/app-dir/segment-cache/prefetch-runtime/app/(default)/caches/public-seconds/page.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export default async function Page() {
1313
This page uses a short-lived public cache (with cacheLife("seconds")),
1414
which should not be included in a static prefetch, but should be
1515
included in a runtime prefetch, because it has a long enough stale time
16-
(&ge; DYNAMIC_STALE, 30s)
16+
(&ge; MIN_PREFETCHABLE_STALE, 30s)
1717
</p>
1818
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
1919
<ShortLivedCache />

‎test/e2e/app-dir/segment-cache/prefetch-runtime/app/(default)/caches/public-short-expire-long-stale/page.tsx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ export default async function Page() {
1010
<main>
1111
<DebugRenderKind />
1212
<p id="intro">
13-
This page uses a short-lived public cache (expire &lt; DYNAMIC_EXPIRE,
14-
5min), which should not be included in a static prefetch, but should be
15-
included in a runtime prefetch, because it has a long enough stale time
16-
(&ge; DYNAMIC_STALE, 30s)
13+
This page uses a short-lived public cache (expire &lt;
14+
MIN_PRERENDERABLE_EXPIRE, 5min), which should not be included in a
15+
static prefetch, but should be included in a runtime prefetch, because
16+
it has a long enough stale time (&ge; MIN_PREFETCHABLE_STALE, 30s)
1717
</p>
1818
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
1919
<ShortLivedCache />
@@ -25,9 +25,9 @@ export default async function Page() {
2525
async function ShortLivedCache() {
2626
'use cache'
2727
cacheLife({
28-
stale: 60, // > DYNAMIC_STALE
28+
stale: 60, // >= MIN_PREFETCHABLE_STALE
2929
revalidate: 2 * 60,
30-
expire: 3 * 60, // < DYNAMIC_EXPIRE
30+
expire: 3 * 60, // < MIN_PRERENDERABLE_EXPIRE
3131
})
3232
await cachedDelay([__filename])
3333

‎test/e2e/app-dir/segment-cache/prefetch-runtime/app/(default)/caches/public-short-expire-short-stale/page.tsx‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,11 @@ export default async function Page() {
1010
<main>
1111
<DebugRenderKind />
1212
<p id="intro">
13-
This page uses a short-lived public cache (expire &lt; DYNAMIC_EXPIRE,
14-
5min), which should not be included in a static prefetch, and should
15-
also not be included in a runtime prefetch, because it has a short
16-
enough stale time (&lt; DYNAMIC_STALE, 30s)
13+
This page uses a short-lived public cache (expire &lt;
14+
MIN_PRERENDERABLE_EXPIRE, 5min), which should not be included in a
15+
static prefetch, and should also not be included in a runtime prefetch,
16+
because it has a short enough stale time (&lt; MIN_PREFETCHABLE_STALE,
17+
30s)
1718
</p>
1819
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
1920
<ShortLivedCache />
@@ -25,9 +26,9 @@ export default async function Page() {
2526
async function ShortLivedCache() {
2627
'use cache'
2728
cacheLife({
28-
stale: 20, // < DYNAMIC_STALE
29+
stale: 20, // < MIN_PREFETCHABLE_STALE
2930
revalidate: 2 * 60,
30-
expire: 3 * 60, // < DYNAMIC_EXPIRE
31+
expire: 3 * 60, // < MIN_PRERENDERABLE_EXPIRE
3132
})
3233
await cachedDelay([__filename])
3334

‎test/e2e/app-dir/segment-cache/prefetch-runtime/prefetch-runtime.test.ts‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -715,25 +715,32 @@ describe('runtime prefetching', () => {
715715
describe('cache stale time handling', () => {
716716
it.each([
717717
{
718-
// If a cache has an expiration time under 5min (DYNAMIC_EXPIRE), we omit it from static prerenders.
719-
// However, it should still be included in a runtime prefetch if its stale time is >=30s. (DYNAMIC_STALE)
718+
// If a cache has an expiration time under 5min
719+
// (MIN_PRERENDERABLE_EXPIRE), we omit it from static prerenders.
720+
// However, it should still be included in a runtime prefetch if its
721+
// stale time is >=30s. (MIN_PREFETCHABLE_STALE)
720722
description:
721723
'includes short-lived public caches with a long enough staleTime',
722724
staticContent: 'This page uses a short-lived public cache',
723725
path: '/caches/public-short-expire-long-stale',
724726
},
725727
{
726-
// If a cache has an expiration time under 5min (DYNAMIC_EXPIRE), we omit it from static prerenders.
727-
// However, it should still be included in a runtime prefetch if its stale time is >=30s. (DYNAMIC_STALE)
728-
// `cacheLife("seconds")` is deliberately set to have a stale time of 30s to stay above this treshold.
728+
// If a cache has an expiration time under 5min
729+
// (MIN_PRERENDERABLE_EXPIRE), we omit it from static prerenders.
730+
// However, it should still be included in a runtime prefetch if its
731+
// stale time is >=30s. (MIN_PREFETCHABLE_STALE) `cacheLife("seconds")`
732+
// is deliberately set to have a stale time of 30s to stay above this
733+
// treshold.
729734
description: 'includes public caches with cacheLife("seconds")',
730735
staticContent: 'This page uses a short-lived public cache',
731736
path: '/caches/public-seconds',
732737
},
733738
{
734739
// A Private cache will always be omitted from static prerenders.
735-
// However, it should still be included in a runtime prefetch if its stale time is >=30s. (DYNAMIC_STALE)
736-
// `cacheLife("seconds")` is deliberately set to have a stale time of 30s to stay above this treshold.
740+
// However, it should still be included in a runtime prefetch if its
741+
// stale time is >=30s. (MIN_PREFETCHABLE_STALE) `cacheLife("seconds")`
742+
// is deliberately set to have a stale time of 30s to stay above this
743+
// treshold.
737744
description: 'includes private caches with cacheLife("seconds")',
738745
staticContent: 'This page uses a short-lived private cache',
739746
path: '/caches/private-seconds',
@@ -777,7 +784,8 @@ describe('runtime prefetching', () => {
777784
})
778785

779786
it('omits short-lived public caches with a short enough staleTime', async () => {
780-
// If a cache has a stale time below 30s (DYNAMIC_STALE), we should omit it from runtime prefetches.
787+
// If a cache has a stale time below 30s (MIN_PREFETCHABLE_STALE), we
788+
// should omit it from runtime prefetches.
781789

782790
let page: Playwright.Page
783791
const browser = await next.browser('/', {
@@ -837,7 +845,8 @@ describe('runtime prefetching', () => {
837845
})
838846

839847
it('omits private caches with a short enough staleTime', async () => {
840-
// If a cache has a stale time below 30s (DYNAMIC_STALE), we should omit it from runtime prefetches.
848+
// If a cache has a stale time below 30s (MIN_PREFETCHABLE_STALE), we
849+
// should omit it from runtime prefetches.
841850

842851
let page: Playwright.Page
843852
const browser = await next.browser('/', {

0 commit comments

Comments
 (0)