Incremental Cache

Copyexport class CacheHandler {
  constructor(_ctx: CacheHandlerContext) {}
 
  public async get(
    _cacheKey: string,
    _ctx:
      | GetIncrementalFetchCacheContext
      | GetIncrementalResponseCacheHandlerContext
      | GetIncrementalImageCacheContext
  ): Promise<CacheHandlerValue | null> {
    return {} as any
  }
 
  public async set(
    _cacheKey: string,
    _data: IncrementalCacheValue | null,
    _ctx:
      | SetIncrementalFetchCacheContext
      | SetIncrementalResponseCacheHandlerContext
      | SetIncrementalImageCacheContext
  ): Promise<void> {}
 
  public async revalidateTag(
    _tags: string | string[],
    _durations?: { expire?: number }
  ): Promise<void> {}
 
  public resetRequestCache(): void {}
}

Copy      const incrementalCache = new IncrementalCache({
        fs: (
          require('../lib/node-fs-methods') as typeof import('../lib/node-fs-methods')
        ).nodeFs,
        dev: this.isDev,
        requestHeaders: req.headers,
        allowedRevalidateHeaderKeys:
          nextConfig.experimental.allowedRevalidateHeaderKeys,
        minimalMode: isMinimalMode,
        serverDistDir: `${projectDir}/${this.distDir}/server`,
        fetchCacheKeyPrefix: nextConfig.experimental.fetchCacheKeyPrefix,
        maxMemoryCacheSize: nextConfig.cacheMaxMemorySize,
        flushToDisk: !isMinimalMode && nextConfig.experimental.isrFlushToDisk,
        previewProps,
        prerenderManifest,
        CurCacheHandler: CacheHandler,
        locales: nextConfig.i18n?.locales,
      })
      ;(globalThis as any).__incrementalCache = incrementalCache
      return incrementalCache

Copy      const workUnitStore = workUnitAsyncStorage.getStore()
      const resumeDataCache = workUnitStore
        ? getResumeDataCache(workUnitStore)
        : null
      if (resumeDataCache) {
        const memoryCacheData = resumeDataCache.fetch.get(cacheKey)
        if (memoryCacheData?.kind === CachedRouteKind.FETCH) {
          const workStore = workAsyncStorage.getStore()
          const combinedTags = [...(ctx.tags || []), ...(ctx.softTags || [])]
          const hasRevalidatedTag = combinedTags.some(
            (tag) =>
              this.revalidatedTags?.includes(tag) ||
              workStore?.pendingRevalidatedTags?.some(
                (item) => item.tag === tag
              )
          )
 
          if (hasRevalidatedTag) {
            // Fall through to cacheHandler lookup
          } else {
            return { isStale: false, value: memoryCacheData }
          }
        }
      }

Copy  const memoryCache = new LRUCache<PrivateCacheEntry>(
    maxSize,
    (entry, cacheKey) => entry.size + cacheKey.length
  )
  const pendingSets = new Map<string, Promise<void>>()

Copy  private readonly getBatcher = Batcher.create<
    { key: string; isOnDemandRevalidate: boolean },
    IncrementalResponseCacheResult,
    string
  >({
    cacheKeyFn: ({ key, isOnDemandRevalidate }) =>
      `${key}-${isOnDemandRevalidate ? '1' : '0'}`,
    schedulerFn: scheduleOnNextTick,
  })
 
  private readonly revalidateBatcher = Batcher.create<
    string,
    IncrementalResponseCacheResult
  >({
    schedulerFn: scheduleOnNextTick,
  })

Copy      if (
        previousIncrementalCacheEntry &&
        !context.isOnDemandRevalidate &&
        previousIncrementalCacheEntry.isStale !== -1
      ) {
        resolve(previousIncrementalCacheEntry)
        resolved = true
 
        if (!previousIncrementalCacheEntry.isStale || context.isPrefetch) {
          return previousIncrementalCacheEntry
        }
      }

Copy             if (entry?.value && entry.value.kind === CachedRouteKind.FETCH) {
               // If the consumer will persist this result in a server cache,
               // wait for fresh data so it doesn't persist a stale value.
               if (willConsumerServerCache(workUnitStore) && entry.isStale) {
                 isForegroundRevalidate = true
               } else {
                 if (entry.isStale) {
                   workStore.pendingRevalidates ??= {}
                   if (!workStore.pendingRevalidates[cacheKey]) {
                     const pendingRevalidate = doOriginalFetch(true)
                       .then(async (response) => ({
                         body: await response.arrayBuffer(),
                         headers: response.headers,
                         status: response.status,
                         statusText: response.statusText,
                       }))
                       .finally(() => {
                         workStore.pendingRevalidates ??= {}
                         delete workStore.pendingRevalidates[cacheKey || '']
                       })
 
                     pendingRevalidate.catch(console.error)
 
                     workStore.pendingRevalidates[cacheKey] = pendingRevalidate
                   }
                 }
 
                 cachedFetchData = entry.value.data
               }
             }

Copy              if (cacheEntry.isStale) {
                if (!workStore.pendingRevalidates) {
                  workStore.pendingRevalidates = {}
                }
 
                if (!workStore.pendingRevalidates[invocationKey]) {
                  const revalidationPromise = workUnitAsyncStorage
                    .run(innerCacheStore, cb, ...args)
                    .then(async (result) => {
                      await cacheNewResult(
                        result,
                        incrementalCache,
                        cacheKey,
                        tags,
                        revalidate,
                        fetchIdx,
                        fetchUrl
                      )
                      return result
                    })
                    .catch((err) => {
                      console.error(
                        `revalidating cache with key: ${invocationKey}`,
                        err
                      )
                      return cachedResponse
                    })
 
                  if (willConsumerServerCache(workUnitStore)) {
                    revalidationPromise.catch(() => {})
                  }
 
                  workStore.pendingRevalidates[invocationKey] =
                    revalidationPromise
                }
 
                if (willConsumerServerCache(workUnitStore)) {
                  return await workStore.pendingRevalidates[invocationKey]
                }
                return cachedResponse
              }

Copyexport function createDefaultCacheHandler(maxSize: number): CacheHandler {
  // If the max size is 0, return a cache handler that doesn't cache anything,
  // this avoids an unnecessary LRUCache instance and potential memory
  // allocation.
  if (maxSize === 0) {
    return {
      get: () => Promise.resolve(undefined),
      set: () => Promise.resolve(),
      refreshTags: () => Promise.resolve(),
      getExpiration: () => Promise.resolve(0),
      updateTags: () => Promise.resolve(),
    }
  }
 
  const memoryCache = new LRUCache<PrivateCacheEntry>(
    maxSize,
    (entry, cacheKey) => entry.size + cacheKey.length
  )
  const pendingSets = new Map<string, Promise<void>>()
 
  const debug = process.env.NEXT_PRIVATE_DEBUG_CACHE
    ? console.debug.bind(console, 'DefaultCacheHandler:')
    : undefined
 

Copyclass SharedCacheEntry {
  private stream: ReadableStream<Uint8Array>
 
  /**
   * Resolves when collection finishes, without waiting for handler writes.
   */
  public readonly pendingMetadata: Promise<CacheResultMetadata>
 
  /**
   * Resolves with collected metadata after any handler writes settle. Write
   * failures do not discard the metadata. Collection failures still reject this
   * promise.
   */
  public readonly pendingCompletion: Promise<CacheResultMetadata>
 
  constructor(
    stream: ReadableStream<Uint8Array>,
    pendingMetadata: Promise<CacheResultMetadata>,
    pendingWrite: Promise<void> | undefined
  ) {
    this.stream = stream
    this.pendingMetadata = pendingMetadata
    this.pendingCompletion =
      pendingWrite === undefined
        ? pendingMetadata
        : pendingWrite.then(
            () => pendingMetadata,
            () => pendingMetadata
          )
  }
 
  /**
   * Tee the stream: returns a copy for the caller, replaces the internal stream
   * with the remaining branch for future callers. Both the leader and joiners
   * call this — everyone gets a fork.
   */
  fork(): ReadableStream<Uint8Array> {
    const [forked, remaining] = this.stream.tee()
    this.stream = remaining
    return forked
  }
}

Copyclass ResolvableSharedCacheResult {
  private readonly deferred = createPromiseWithResolvers<SharedCacheResult>()
 
  private readonly registrations: Array<{
    map: Map<string, Promise<SharedCacheResult>>
    key: string
    /**
     * Where to move the entry once the invocation completes, instead of
     * dropping it. Only set for the request-scoped map, and only for kinds
     * whose entries are worth retaining; the module-scope cross-request map
     * must never retain, since its entries would outlive the request that
     * produced them.
     */
    retentionMap?: Map<string, Promise<SharedCacheResult>>
  }> = []
 
  registerIn(
    map: Map<string, Promise<SharedCacheResult>>,
    key: string,
    retentionMap?: Map<string, Promise<SharedCacheResult>>
  ): void {
    map.set(key, this.deferred.promise)
    this.registrations.push({ map, key, retentionMap })
  }

Copyexport const areTagsExpired = (tags: string[], timestamp: Timestamp) => {
  for (const tag of tags) {
    const entry = tagsManifest.get(tag)
    const expiredAt = entry?.expired
 
    if (typeof expiredAt === 'number') {
      const now = performance.timeOrigin + performance.now()
      // For immediate expiration (expiredAt <= now) and tag was invalidated after entry was created
      // OR for future expiration that has now passed (expiredAt > timestamp && expiredAt <= now)
      const isImmediatelyExpired = expiredAt <= now && expiredAt > timestamp
 
      if (isImmediatelyExpired) {
        return true
      }
    }
  }
 
  return false
}
 
export const areTagsStale = (tags: string[], timestamp: Timestamp) => {
  for (const tag of tags) {
    const entry = tagsManifest.get(tag)
    const staleAt = entry?.stale ?? 0
 
    if (typeof staleAt === 'number' && staleAt > timestamp) {
      return true
    }
  }
 
  return false

Copyexport async function withExecuteRevalidates<T>(
  store: WorkStore | undefined,
  callback: () => Promise<T>
): Promise<T> {
  if (!store) {
    return callback()
  }
  // If we executed any revalidates during the request, then we don't want to execute them again.
  // save the state so we can check if anything changed after we're done running callbacks.
  const savedRevalidationState = cloneRevalidationState(store)
  try {
    return await callback()
  } finally {
    // Check if we have any new revalidates, and if so, wait until they are all resolved.
    const newRevalidates = diffRevalidationState(
      savedRevalidationState,
      cloneRevalidationState(store)
    )
    await executeRevalidates(store, newRevalidates)
  }
}

Copyasync function revalidateTags(
  tagsWithProfile: Array<{
    tag: string
    profile?: string | { expire?: number }
  }>,
  incrementalCache: IncrementalCache | undefined,
  workStore?: WorkStore
): Promise<void> {
  if (tagsWithProfile.length === 0) {
    return
  }
 
  const handlers = getCacheHandlers() ?? []
  const promises: Promise<void>[] = []
 
  // Group tags by profile for batch processing
  const tagsByProfile = new Map<
    | string
    | { stale?: number; revalidate?: number; expire?: number }
    | undefined,
    string[]
  >()
 
  for (const item of tagsWithProfile) {
    const profile = item.profile
    // Find existing profile by comparing values
    let existingKey = undefined
    for (const [key] of tagsByProfile) {
      if (
        typeof key === 'string' &&
        typeof profile === 'string' &&
        key === profile
      ) {
        existingKey = key
        break
      }
      if (
        typeof key === 'object' &&
        typeof profile === 'object' &&
        JSON.stringify(key) === JSON.stringify(profile)
      ) {
        existingKey = key
        break
      }
      if (key === profile) {
        existingKey = key
        break
      }
    }
 
    const profileKey = existingKey || profile
    if (!tagsByProfile.has(profileKey)) {
      tagsByProfile.set(profileKey, [])
    }
    tagsByProfile.get(profileKey)!.push(item.tag)
  }
 
  // Process each profile group
  for (const [profile, tagsForProfile] of tagsByProfile) {
    // Look up the cache profile from workStore if available
    let durations: { expire?: number } | undefined
 
    if (profile) {
      let cacheLife:
        | { stale?: number; revalidate?: number; expire?: number }
        | undefined
 
      if (typeof profile === 'object') {
        // Profile is already a cacheLife configuration object
        cacheLife = profile
      } else if (typeof profile === 'string') {
        // Profile is a string key, look it up in workStore
        cacheLife = workStore?.cacheLifeProfiles[profile]
 
        if (!cacheLife) {
          throw new Error(
            `Invalid profile provided "${profile}" must be configured under cacheLife in next.config or be "max"`
          )
        }
      }