Unverified Commit 8c0737d7 authored by Wyatt Johnson's avatar Wyatt Johnson Committed by GitHub

perf(router): replace LRU cache with optimized doubly-linked list implementation (#82633)

### What?

Replace LRU cache implementation with an optimized doubly-linked list
algorithm and move from server-only to shared library location.

### Why?

The previous Map-based LRU cache had suboptimal eviction performance for
route matching operations under high load. Route matching is a critical
performance path in Next.js that benefits significantly from true O(1)
cache operations.

### How?

- Implement doubly-linked list with sentinel nodes for true O(1)
get/set/delete operations
- Add comprehensive test coverage including size-based eviction
scenarios
- Update import paths across 14 files throughout the codebase
- Add defensive null checking for edge cases discovered during static
analysis
- Replace deprecated `keys()` iteration with modern `Symbol.iterator`
pattern
parent 2c2c86f5
...@@ -778,5 +778,6 @@ ...@@ -778,5 +778,6 @@
"777": "Invariant: failed to find source route %s for prerender %s", "777": "Invariant: failed to find source route %s for prerender %s",
"778": "`prerenderAndAbortInSequentialTasksWithStages` should not be called in edge runtime.", "778": "`prerenderAndAbortInSequentialTasksWithStages` should not be called in edge runtime.",
"779": "Route %s used \"searchParams\" inside \"use cache\". Accessing dynamic request data inside a cache scope is not supported. If you need some search params inside a cached function await \"searchParams\" outside of the cached function and pass only the required search params as arguments to the cached function. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache", "779": "Route %s used \"searchParams\" inside \"use cache\". Accessing dynamic request data inside a cache scope is not supported. If you need some search params inside a cached function await \"searchParams\" outside of the cached function and pass only the required search params as arguments to the cached function. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache",
"780": "Invariant: failed to find parent dynamic route for notFound route %s" "780": "Invariant: failed to find parent dynamic route for notFound route %s",
"781": "No LRU node to remove"
} }
...@@ -416,7 +416,7 @@ function warnAboutExperimentalEdge(apiRoute: string | null) { ...@@ -416,7 +416,7 @@ function warnAboutExperimentalEdge(apiRoute: string | null) {
return return
} }
if (apiRouteWarnings.has(apiRoute)) { if (apiRoute && apiRouteWarnings.has(apiRoute)) {
return return
} }
...@@ -425,7 +425,10 @@ function warnAboutExperimentalEdge(apiRoute: string | null) { ...@@ -425,7 +425,10 @@ function warnAboutExperimentalEdge(apiRoute: string | null) {
? `${apiRoute} provided runtime 'experimental-edge'. It can be updated to 'edge' instead.` ? `${apiRoute} provided runtime 'experimental-edge'. It can be updated to 'edge' instead.`
: `You are using an experimental edge runtime, the API might change.` : `You are using an experimental edge runtime, the API might change.`
) )
if (apiRoute) {
apiRouteWarnings.set(apiRoute, 1) apiRouteWarnings.set(apiRoute, 1)
}
} }
let hadUnsupportedValue = false let hadUnsupportedValue = false
......
...@@ -11,7 +11,7 @@ import { HMR_ACTIONS_SENT_TO_BROWSER } from '../dev/hot-reloader-types' ...@@ -11,7 +11,7 @@ import { HMR_ACTIONS_SENT_TO_BROWSER } from '../dev/hot-reloader-types'
* bundler while in development. * bundler while in development.
*/ */
export class DevBundlerService { export class DevBundlerService {
public appIsrManifestInner: InstanceType<typeof LRUCache> public appIsrManifestInner: InstanceType<typeof LRUCache<boolean>>
constructor( constructor(
private readonly bundler: DevBundler, private readonly bundler: DevBundler,
...@@ -87,9 +87,10 @@ export class DevBundlerService { ...@@ -87,9 +87,10 @@ export class DevBundlerService {
public get appIsrManifest() { public get appIsrManifest() {
const serializableManifest: Record<string, boolean> = {} const serializableManifest: Record<string, boolean> = {}
for (const key of this.appIsrManifestInner.keys() as string[]) { for (const [key, value] of this.appIsrManifestInner) {
serializableManifest[key] = this.appIsrManifestInner.get(key) as boolean serializableManifest[key] = value
} }
return serializableManifest return serializableManifest
} }
......
import { LRUCache } from './lru-cache'
describe('LRUCache', () => {
describe('Basic Operations', () => {
let cache: LRUCache<string>
beforeEach(() => {
cache = new LRUCache<string>(3)
})
it('should set and get values', () => {
cache.set('key1', 'value1')
expect(cache.get('key1')).toBe('value1')
})
it('should return undefined for non-existent keys', () => {
expect(cache.get('nonexistent')).toBeUndefined()
})
it('should check if key exists with has()', () => {
cache.set('key1', 'value1')
expect(cache.has('key1')).toBe(true)
expect(cache.has('nonexistent')).toBe(false)
})
it('should update existing keys', () => {
cache.set('key1', 'value1')
cache.set('key1', 'value2')
expect(cache.get('key1')).toBe('value2')
expect(cache.size).toBe(1)
})
it('should track cache size correctly', () => {
expect(cache.size).toBe(0)
cache.set('key1', 'value1')
expect(cache.size).toBe(1)
cache.set('key2', 'value2')
expect(cache.size).toBe(2)
})
})
describe('LRU Eviction Behavior', () => {
let cache: LRUCache<string>
beforeEach(() => {
cache = new LRUCache<string>(3)
})
it('should evict least recently used item when capacity exceeded', () => {
cache.set('key1', 'value1')
cache.set('key2', 'value2')
cache.set('key3', 'value3')
cache.set('key4', 'value4') // should evict key1
expect(cache.has('key1')).toBe(false)
expect(cache.has('key2')).toBe(true)
expect(cache.has('key3')).toBe(true)
expect(cache.has('key4')).toBe(true)
expect(cache.size).toBe(3)
})
it('should update LRU order when accessing items', () => {
cache.set('key1', 'value1')
cache.set('key2', 'value2')
cache.set('key3', 'value3')
cache.get('key1') // key1 becomes most recently used
cache.set('key4', 'value4') // should evict key2 (least recently used)
expect(cache.has('key1')).toBe(true)
expect(cache.has('key2')).toBe(false)
expect(cache.has('key3')).toBe(true)
expect(cache.has('key4')).toBe(true)
})
it('should maintain correct order with mixed operations', () => {
cache.set('a', '1')
cache.set('b', '2')
cache.set('c', '3')
cache.get('a') // a becomes most recent
cache.get('b') // b becomes most recent
cache.set('d', '4') // should evict c
expect(cache.has('a')).toBe(true)
expect(cache.has('b')).toBe(true)
expect(cache.has('c')).toBe(false)
expect(cache.has('d')).toBe(true)
})
})
describe('Size-based Eviction', () => {
it('should use custom size calculation', () => {
const cache = new LRUCache<string>(10, (value) => value.length)
cache.set('key1', 'abc') // size 3
cache.set('key2', 'defgh') // size 5
cache.set('key3', 'ij') // size 2, total = 10
cache.set('key4', 'k') // size 1, total = 11, should evict key1
expect(cache.has('key1')).toBe(false)
expect(cache.has('key2')).toBe(true)
expect(cache.has('key3')).toBe(true)
expect(cache.has('key4')).toBe(true)
expect(cache.currentSize).toBe(8) // 5 + 2 + 1
})
it('should handle items larger than max size', () => {
const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
const cache = new LRUCache<string>(5, (value) => value.length)
cache.set('key1', 'toolarge') // size 8 > maxSize 5
expect(cache.has('key1')).toBe(false)
expect(cache.size).toBe(0)
expect(consoleSpy).toHaveBeenCalledWith(
'Single item size exceeds maxSize'
)
consoleSpy.mockRestore()
})
it('should update size when overwriting existing keys', () => {
const cache = new LRUCache<string>(10, (value) => value.length)
cache.set('key1', 'abc') // size 3
expect(cache.currentSize).toBe(3)
cache.set('key1', 'defghij') // size 7
expect(cache.currentSize).toBe(7)
expect(cache.size).toBe(1)
})
it('should evict multiple items if necessary', () => {
const cache = new LRUCache<string>(10, (value) => value.length)
cache.set('key1', 'ab') // size 2
cache.set('key2', 'cd') // size 2
cache.set('key3', 'ef') // size 2, total = 6
cache.set('key4', 'ghijklmno') // size 9, should evict key1, key2, key3
expect(cache.has('key1')).toBe(false)
expect(cache.has('key2')).toBe(false)
expect(cache.has('key3')).toBe(false)
expect(cache.has('key4')).toBe(true)
expect(cache.currentSize).toBe(9)
expect(cache.size).toBe(1)
})
})
describe('Cache Management', () => {
let cache: LRUCache<string>
beforeEach(() => {
cache = new LRUCache<string>(3)
cache.set('key1', 'value1')
cache.set('key2', 'value2')
})
it('should remove specific keys', () => {
cache.remove('key1')
expect(cache.has('key1')).toBe(false)
expect(cache.has('key2')).toBe(true)
expect(cache.size).toBe(1)
})
it('should handle removing non-existent keys', () => {
cache.remove('nonexistent')
expect(cache.size).toBe(2)
})
it('should track current size correctly after operations', () => {
const sizeCache = new LRUCache<string>(10, (value) => value.length)
sizeCache.set('key1', 'abc') // size 3
sizeCache.set('key2', 'de') // size 2
expect(sizeCache.currentSize).toBe(5)
sizeCache.remove('key1')
expect(sizeCache.currentSize).toBe(2)
})
})
describe('Edge Cases', () => {
it('should handle zero max size', () => {
const cache = new LRUCache<string>(0)
cache.set('key1', 'value1')
expect(cache.has('key1')).toBe(false)
expect(cache.size).toBe(0)
})
it('should handle single item capacity', () => {
const cache = new LRUCache<string>(1)
cache.set('key1', 'value1')
expect(cache.has('key1')).toBe(true)
cache.set('key2', 'value2')
expect(cache.has('key1')).toBe(false)
expect(cache.has('key2')).toBe(true)
expect(cache.size).toBe(1)
})
it('should work with different value types', () => {
const numberCache = new LRUCache<number>(2)
const objectCache = new LRUCache<{ id: number }>(2)
numberCache.set('num', 42)
expect(numberCache.get('num')).toBe(42)
const obj = { id: 1 }
objectCache.set('obj', obj)
expect(objectCache.get('obj')).toBe(obj)
})
it('should maintain integrity with rapid operations', () => {
const cache = new LRUCache<number>(100)
// Rapid insertions
for (let i = 0; i < 150; i++) {
cache.set(`key${i}`, i)
}
expect(cache.size).toBe(100)
expect(cache.has('key0')).toBe(false) // early keys evicted
expect(cache.has('key149')).toBe(true) // recent keys retained
})
})
})
export class LRUCache<T> { /**
private cache: Map<string, T> * Node in the doubly-linked list used for LRU tracking.
private sizes: Map<string, number> * Each node represents a cache entry with bidirectional pointers.
private totalSize: number */
private maxSize: number class LRUNode<T> {
private calculateSize: (value: T) => number public readonly key: string
public data: T
constructor(maxSize: number, calculateSize?: (value: T) => number) { public size: number
this.cache = new Map() public prev: LRUNode<T> | SentinelNode<T> | null = null
this.sizes = new Map() public next: LRUNode<T> | SentinelNode<T> | null = null
this.totalSize = 0
this.maxSize = maxSize constructor(key: string, data: T, size: number) {
this.calculateSize = calculateSize || (() => 1) this.key = key
this.data = data
this.size = size
} }
}
set(key?: string | null, value?: T): void { /**
if (!key || !value) return * Sentinel node used for head/tail boundaries.
* These nodes don't contain actual cache data but simplify list operations.
*/
class SentinelNode<T> {
public prev: LRUNode<T> | SentinelNode<T> | null = null
public next: LRUNode<T> | SentinelNode<T> | null = null
}
const size = this.calculateSize(value) /**
* LRU (Least Recently Used) Cache implementation using a doubly-linked list
* and hash map for O(1) operations.
*
* Algorithm:
* - Uses a doubly-linked list to maintain access order (most recent at head)
* - Hash map provides O(1) key-to-node lookup
* - Sentinel head/tail nodes simplify edge case handling
* - Size-based eviction supports custom size calculation functions
*
* Data Structure Layout:
* HEAD <-> [most recent] <-> ... <-> [least recent] <-> TAIL
*
* Operations:
* - get(): Move accessed node to head (mark as most recent)
* - set(): Add new node at head, evict from tail if over capacity
* - Eviction: Remove least recent node (tail.prev) when size exceeds limit
*/
export class LRUCache<T> {
private readonly cache: Map<string, LRUNode<T>> = new Map()
private readonly head: SentinelNode<T>
private readonly tail: SentinelNode<T>
private totalSize: number = 0
private readonly maxSize: number
private readonly calculateSize: ((value: T) => number) | undefined
constructor(maxSize: number, calculateSize?: (value: T) => number) {
this.maxSize = maxSize
this.calculateSize = calculateSize
// Create sentinel nodes to simplify doubly-linked list operations
// HEAD <-> TAIL (empty list)
this.head = new SentinelNode<T>()
this.tail = new SentinelNode<T>()
this.head.next = this.tail
this.tail.prev = this.head
}
/**
* Adds a node immediately after the head (marks as most recently used).
* Used when inserting new items or when an item is accessed.
* PRECONDITION: node must be disconnected (prev/next should be null)
*/
private addToHead(node: LRUNode<T>): void {
node.prev = this.head
node.next = this.head.next
// head.next is always non-null (points to tail or another node)
this.head.next!.prev = node
this.head.next = node
}
/**
* Removes a node from its current position in the doubly-linked list.
* Updates the prev/next pointers of adjacent nodes to maintain list integrity.
* PRECONDITION: node must be connected (prev/next are non-null)
*/
private removeNode(node: LRUNode<T>): void {
// Connected nodes always have non-null prev/next
node.prev!.next = node.next
node.next!.prev = node.prev
}
/**
* Moves an existing node to the head position (marks as most recently used).
* This is the core LRU operation - accessed items become most recent.
*/
private moveToHead(node: LRUNode<T>): void {
this.removeNode(node)
this.addToHead(node)
}
/**
* Removes and returns the least recently used node (the one before tail).
* This is called during eviction when the cache exceeds capacity.
* PRECONDITION: cache is not empty (ensured by caller)
*/
private removeTail(): LRUNode<T> {
const lastNode = this.tail.prev as LRUNode<T>
// tail.prev is always non-null and always LRUNode when cache is not empty
this.removeNode(lastNode)
return lastNode
}
/**
* Sets a key-value pair in the cache.
* If the key exists, updates the value and moves to head.
* If new, adds at head and evicts from tail if necessary.
*
* Time Complexity:
* - O(1) for uniform item sizes
* - O(k) where k is the number of items evicted (can be O(N) for variable sizes)
*/
public set(key: string, value: T): void {
const size = this.calculateSize?.(value) ?? 1
if (size > this.maxSize) { if (size > this.maxSize) {
console.warn('Single item size exceeds maxSize') console.warn('Single item size exceeds maxSize')
return return
} }
if (this.cache.has(key)) { const existing = this.cache.get(key)
this.totalSize -= this.sizes.get(key) || 0 if (existing) {
} // Update existing node: adjust size and move to head (most recent)
existing.data = value
this.cache.set(key, value) this.totalSize = this.totalSize - existing.size + size
this.sizes.set(key, size) existing.size = size
this.moveToHead(existing)
} else {
// Add new node at head (most recent position)
const newNode = new LRUNode(key, value, size)
this.cache.set(key, newNode)
this.addToHead(newNode)
this.totalSize += size this.totalSize += size
this.touch(key)
}
has(key?: string | null): boolean {
if (!key) return false
this.touch(key)
return Boolean(this.cache.get(key))
} }
get(key?: string | null): T | undefined { // Evict least recently used items until under capacity
if (!key) return
const value = this.cache.get(key)
if (value === undefined) {
return undefined
}
this.touch(key)
return value
}
private touch(key: string): void {
const value = this.cache.get(key)
if (value !== undefined) {
this.cache.delete(key)
this.cache.set(key, value)
this.evictIfNecessary()
}
}
private evictIfNecessary(): void {
while (this.totalSize > this.maxSize && this.cache.size > 0) { while (this.totalSize > this.maxSize && this.cache.size > 0) {
this.evictLeastRecentlyUsed() const tail = this.removeTail()
} this.cache.delete(tail.key)
} this.totalSize -= tail.size
}
private evictLeastRecentlyUsed(): void { }
const lruKey = this.cache.keys().next().value
if (lruKey !== undefined) { /**
const lruSize = this.sizes.get(lruKey) || 0 * Checks if a key exists in the cache.
this.totalSize -= lruSize * This is a pure query operation - does NOT update LRU order.
this.cache.delete(lruKey) *
this.sizes.delete(lruKey) * Time Complexity: O(1)
} */
} public has(key: string): boolean {
return this.cache.has(key)
reset() { }
this.cache.clear()
this.sizes.clear() /**
this.totalSize = 0 * Retrieves a value by key and marks it as most recently used.
} * Moving to head maintains the LRU property for future evictions.
*
keys() { * Time Complexity: O(1)
return [...this.cache.keys()] */
} public get(key: string): T | undefined {
const node = this.cache.get(key)
remove(key: string): void { if (!node) return undefined
if (this.cache.has(key)) {
this.totalSize -= this.sizes.get(key) || 0 // Mark as most recently used by moving to head
this.moveToHead(node)
return node.data
}
/**
* Returns an iterator over the cache entries. The order is outputted in the
* order of most recently used to least recently used.
*/
public *[Symbol.iterator](): IterableIterator<[string, T]> {
let current = this.head.next
while (current && current !== this.tail) {
// Between head and tail, current is always LRUNode
const node = current as LRUNode<T>
yield [node.key, node.data]
current = current.next
}
}
/**
* Removes a specific key from the cache.
* Updates both the hash map and doubly-linked list.
*
* Time Complexity: O(1)
*/
public remove(key: string): void {
const node = this.cache.get(key)
if (!node) return
this.removeNode(node)
this.cache.delete(key) this.cache.delete(key)
this.sizes.delete(key) this.totalSize -= node.size
}
}
clear(): void {
this.cache.clear()
this.sizes.clear()
this.totalSize = 0
} }
get size(): number { /**
* Returns the number of items in the cache.
*/
public get size(): number {
return this.cache.size return this.cache.size
} }
get currentSize(): number { /**
* Returns the current total size of all cached items.
* This uses the custom size calculation if provided.
*/
public get currentSize(): number {
return this.totalSize return this.totalSize
} }
} }
...@@ -33,6 +33,8 @@ let argv = require('yargs/yargs')(process.argv.slice(2)) ...@@ -33,6 +33,8 @@ let argv = require('yargs/yargs')(process.argv.slice(2))
.number('c') .number('c')
.boolean('related') .boolean('related')
.boolean('dry') .boolean('dry')
.boolean('print-tests')
.describe('print-tests', 'Prints the test files that will be run')
.boolean('local') .boolean('local')
.alias('r', 'related') .alias('r', 'related')
.alias('c', 'concurrency').argv .alias('c', 'concurrency').argv
...@@ -74,15 +76,9 @@ const TIMINGS_API_HEADERS = { ...@@ -74,15 +76,9 @@ const TIMINGS_API_HEADERS = {
} }
const testFilters = { const testFilters = {
development: new RegExp( development: new RegExp('^(test/(development|e2e))'),
'^(test/(development|e2e)|packages/.*/src/.*|packages/next-codemod/.*)/.*\\.test\\.(js|jsx|ts|tsx)$' production: new RegExp('^(test/(production|e2e))'),
), unit: new RegExp('^(test/unit|packages/.*/src|packages/next-codemod)'),
production: new RegExp(
'^(test/(production|e2e))/.*\\.test\\.(js|jsx|ts|tsx)$'
),
unit: new RegExp(
'^test/unit|packages/.*/src/.*/.*\\.test\\.(js|jsx|ts|tsx)$'
),
examples: 'examples/', examples: 'examples/',
integration: 'test/integration/', integration: 'test/integration/',
e2e: 'test/e2e/', e2e: 'test/e2e/',
...@@ -217,6 +213,7 @@ async function main() { ...@@ -217,6 +213,7 @@ async function main() {
retries: argv.retries ?? DEFAULT_NUM_RETRIES, retries: argv.retries ?? DEFAULT_NUM_RETRIES,
dry: argv.dry ?? false, dry: argv.dry ?? false,
local: argv.local ?? false, local: argv.local ?? false,
printTests: argv.printTests ?? false,
} }
let numRetries = options.retries let numRetries = options.retries
const hideOutput = !options.debug && !options.dry const hideOutput = !options.debug && !options.dry
...@@ -301,6 +298,8 @@ async function main() { ...@@ -301,6 +298,8 @@ async function main() {
file, file,
excludedCases: [], excludedCases: [],
})) }))
//
} }
if (options.timings && options.group) { if (options.timings && options.group) {
...@@ -406,6 +405,10 @@ ${tests.map((t) => t.file).join('\n')} ...@@ -406,6 +405,10 @@ ${tests.map((t) => t.file).join('\n')}
${ENDGROUP}`) ${ENDGROUP}`)
console.log(`total: ${tests.length}`) console.log(`total: ${tests.length}`)
if (options.printTests) {
await cleanUpAndExit(0)
}
if ( if (
!options.dry && !options.dry &&
process.env.NEXT_TEST_MODE !== 'deploy' && process.env.NEXT_TEST_MODE !== 'deploy' &&
......
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