Function Caching | blade47/next.js Wiki | doc0

Public

Function Caching | blade47/next.js Wiki | doc0

Work Unit Store Type	Public `'use cache'` Behavior	Private `'use cache: private'` Behavior
`prerender`	Executes render tracking and static generation	Returns hanging promise via `makeHangingPromise`
`prerender-ppr`	Postpones execution via dynamic tracking	Postpones execution via `postponeWithTracking`
`prerender-legacy`	Throws interrupt static generation	Throws via `throwToInterruptStaticGeneration`
`prerender-client` / `validation-client`	Throws `InvariantError` (forbidden in client components)	Throws `InvariantError` (forbidden in client components)
`cache`	Creates nested dynamic cache error context	Throws invalid dynamic usage error
`unstable_cache`	Allowed / standard nesting	Throws invalid dynamic usage error
`request` / `prerender-runtime` / `private-cache`	Standard cache context creation	Standard private cache context creation

Design Choice	Benefit	Cost
Global symbol storage for cache handlers (`@next/cache-handlers`)	Shares cache handler instances across distinct module copies and boundary boundaries	Relies on global singleton state which complicates isolated unit testing
Teeing streams on cache hit (`entry.value.tee()`)	Allows concurrent readers to consume independent clones of the cached `ReadableStream`	Increases memory overhead by buffering chunks until both branches are consumed
Pending promise deduplication map (`pendingSets`)	Prevents cache stampedes and duplicate concurrent writes for the same cache key	Holds promises in memory until concurrent set operations settle

Symbol Name	Global Key	Purpose
`handlersSymbol`	`@next/cache-handlers`	Stores raw pre-existing `RemoteCache` or `DefaultCache` references on `globalThis`
`handlersMapSymbol`	`@next/cache-handlers-map`	Maps string kinds (such as `'default'` and `'remote'`) to active `CacheHandler` instances
`handlersSetSymbol`	`@next/cache-handlers-set`	Maintains a unique `Set` of all active `CacheHandler` instances
`privateHandlerSymbol`	`@next/cache-handlers-private`	Dev-only dedicated in-memory cache handler for private cache entries

Design Choice	Benefit	Cost
Gating private cache initialization on `process.env.__NEXT_DEV_SERVER`	Avoids persisting request-derived private cache data to shared production stores	Increases dev-mode memory footprint by maintaining a separate LRU instance
Dynamic ESM imports via `dynamicImportEsmDefault` and `formatDynamicImportPath`	Supports flexible path resolution and interop wrapping for custom user cache handlers	Introduces asynchronous module loading overhead during server preparation
Bypassing cache initialization when `cacheMaxMemorySize` equals `0`	Eliminates unnecessary LRU cache instantiation and memory allocation	Disables local memory caching entirely for that handler instance

Property	Type	Purpose
`page`	`string`	The route page pathname being wrapped
`cacheHandlers`	`Record<string, CacheHandler>`	Optional custom cache handlers bound during edge request initialization
`incrementalCacheHandler`	`typeof IncrementalCacheHandler`	Optional incremental cache handler class reference passed to the edge adapter

Method	Parameters	Return Type	Purpose
`get`	`cacheKey: string`	`Promise<CacheEntry \| undefined>`	Retrieves a cached entry if present, valid, and unexpired, teeing its stream value.
`set`	`cacheKey: string, pendingEntry: Promise<CacheEntry>`	`Promise<void>`	Awaits entry resolution, calculates stream byte size, and stores it in the LRU cache.
`refreshTags`	`tags: string[], soft?: boolean`	`Promise<void>`	No-op method for in-memory cache handlers.
`getExpiration`	`tags: string[]`	`Promise<number>`	Calculates the most recent expiration timestamp across the provided tags manifest entries.
`updateTags`	`tags: string[], durations?: { expire?: number }`	`Promise<void>`	Marks specified tags as stale and updates expiration durations in the tags manifest.

Option / Parameter	Type	Meaning / Purpose
`maxRetries`	`number`	Set to `0` to prevent automatic worker retries upon failure.
`numWorkers`	`number`	Fixed at `4` concurrent workers to absorb parallel cache fill probes.
`enableWorkerThreads`	`boolean`	Controlled by `nextConfig.experimental.workerThreads` to toggle worker threads versus child processes.
`exposedMethods`	`string[]`	Explicitly lists `['probeUseCache']` to bypass parent-process discovery overhead.
`timeoutMs`	`number`	Configured timeout threshold triggering the deadlock probe.

Design Choice	Benefit	Cost
Isolated `jest-worker` pool	Prevents deadlocked cache fills from freezing the main dev server request thread.	Fixed worker memory footprint and serialization overhead for arguments.
Base64 blob encoding	Ensures binary payload survival across child-process JSON fallback transports and worker threads.	Additional CPU overhead and memory allocation during argument serialization.
Coarse pool teardown on HMR	Guarantees absolute freshness of user modules and module manifests without path-level tracking.	Discards warm worker caches on every file invalidation event.