LRU Cache Implementation from Scratch

Overview

This implementation uses a doubly linked list combined with a hash map to achieve O(1) time complexity for both get and put operations.

• Doubly Linked List: Tracks access order (most recent → least recent)
• Hash Map: Provides O(1) key lookups

"""
LRU Cache Implementation

Architecture:
- Doubly Linked List maintains access order
- Dictionary maps keys to nodes for O(1) lookup
- HEAD <-> [most recent] <-> ... <-> [least recent] <-> TAIL

Time Complexity:  O(1) for get and put
Space Complexity: O(capacity)
"""

from typing import Optional, Any


class Node:
    """
    A node in the doubly linked list.
    
    Each node stores a key-value pair and maintains
    pointers to adjacent nodes in the list.
    """

    def __init__(self, key: Any = None, value: Any = None):
        self.key = key
        self.value = value
        self.prev: Optional["Node"] = None
        self.next: Optional["Node"] = None

    def __repr__(self) -> str:
        return f"Node(key={self.key!r}, value={self.value!r})"


class LRUCache:
    """
    Least-Recently-Used (LRU) Cache.

    Evicts the least recently used item when capacity is exceeded.
    Supports O(1) get and put operations.

    Args:
        capacity (int): Maximum number of items the cache can hold.

    Raises:
        ValueError: If capacity is less than 1.

    Example:
        >>> cache = LRUCache(2)
        >>> cache.put("a", 1)
        >>> cache.put("b", 2)
        >>> cache.get("a")   # Returns 1, makes "a" most recent
        1
        >>> cache.put("c", 3)  # Evicts "b" (least recently used)
        >>> cache.get("b")   # Returns None ("b" was evicted)
        
    """

    def __init__(self, capacity: int):
        if not isinstance(capacity, int) or isinstance(capacity, bool):
            raise TypeError(f"Capacity must be an integer, got {type(capacity).__name__}")
        if capacity < 1:
            raise ValueError(f"Capacity must be at least 1, got {capacity}")

        self.capacity = capacity
        self._size = 0

        # Sentinel nodes eliminate edge cases for empty list / boundary operations
        # Layout: HEAD <-> [nodes...] <-> TAIL
        self._head = Node()  # Dummy head — next is most recently used
        self._tail = Node()  # Dummy tail — prev is least recently used
        self._head.next = self._tail
        self._tail.prev = self._head

        # Maps key → Node for O(1) access
        self._cache: dict[Any, Node] = {}

    # ------------------------------------------------------------------
    # Public API
    # ------------------------------------------------------------------

    def get(self, key: Any) -> Optional[Any]:
        """
        Retrieve the value associated with a key.

        Marks the accessed item as most recently used.

        Args:
            key: The key to look up.

        Returns:
            The cached value, or None if the key is not present.

        Time Complexity: O(1)
        """
        if key not in self._cache:
            return None

        node = self._cache[key]
        self._move_to_front(node)  # Mark as most recently used
        return node.value

    def put(self, key: Any, value: Any) -> None:
        """
        Insert or update a key-value pair in the cache.

        - If the key exists, updates its value and marks it as most recently used.
        - If the cache is full, evicts the least recently used item first.

        Args:
            key:   The key to insert or update.
            value: The value to associate with the key.

        Time Complexity: O(1)
        """
        if key in self._cache:
            # Update existing node and promote it
            node = self._cache[key]
            node.value = value
            self._move_to_front(node)
        else:
            # Evict LRU item if at capacity
            if self._size == self.capacity:
                self._evict_lru()

            # Insert new node at the front (most recently used position)
            new_node = Node(key, value)
            self._cache[key] = new_node
            self._insert_at_front(new_node)
            self._size += 1

    def delete(self, key: Any) -> bool:
        """
        Explicitly remove a key from the cache.

        Args:
            key: The key to remove.

        Returns:
            True if the key was present and removed, False otherwise.

        Time Complexity: O(1)
        """
        if key not in self._cache:
            return False

        node = self._cache.pop(key)
        self._remove_node(node)
        self._size -= 1
        return True

    def clear(self) -> None:
        """
        Remove all items from the cache and reset its state.

        Time Complexity: O(1)
        """
        self._cache.clear()
        self._head.next = self._tail
        self._tail.prev = self._head
        self._size = 0

    def peek(self, key: Any) -> Optional[Any]:
        """
        Retrieve a value WITHOUT updating its recency.

        Useful for inspecting cache contents in tests or monitoring.

        Args:
            key: The key to look up.

        Returns:
            The cached value, or None if the key is not present.

        Time Complexity: O(1)
        """
        node = self._cache.get(key)
        return node.value if node else None

    # ------------------------------------------------------------------
    # Private helpers — doubly linked list operations
    # ------------------------------------------------------------------

    def _remove_node(self, node: Node) -> None:
        """
        Unlink a node from the doubly linked list.

        Before: ... <-> prev <-> node <-> next <-> ...
        After:  ... <-> prev <-> next <-> ...

        Time Complexity: O(1)
        """
        prev_node = node.prev
        next_node = node.next
        prev_node.next = next_node
        next_node.prev = prev_node

        # Avoid dangling pointers (aids garbage collection)
        node.prev = None
        node.next = None

    def _insert_at_front(self, node: Node) -> None:
        """
        Insert a node immediately after the HEAD sentinel (most recent position).

        Before: HEAD <-> first <-> ...
        After:  HEAD <-> node <-> first <-> ...

        Time Complexity: O(1)
        """
        node.prev = self._head
        node.next = self._head.next
        self._head.next.prev = node
        self._head.next = node

    def _move_to_front(self, node: Node) -> None:
        """
        Move an existing node to the most-recently-used position.

        Combines _remove_node + _insert_at_front.

        Time Complexity: O(1)
        """
        self._remove_node(node)
        self._insert_at_front(node)

    def _evict_lru(self) -> None:
        """
        Remove the least recently used item (node just before TAIL).

        Time Complexity: O(1)
        """
        lru_node = self._tail.prev  # Node just before the dummy tail
        if lru_node is self._head:
            return  # Cache is empty — nothing to evict (safety guard)

        del self._cache[lru_node.key]
        self._remove_node(lru_node)
        self._size -= 1

    # ------------------------------------------------------------------
    # Dunder methods for convenience
    # ------------------------------------------------------------------

    def __len__(self) -> int:
        """Return the current number of items in the cache."""
        return self._size

    def __contains__(self, key: Any) -> bool:
        """Support `key in cache` syntax (does NOT update recency)."""
        return key in self._cache

    def __repr__(self) -> str:
        """Show cache contents ordered from most to least recently used."""
        items = []
        current = self._head.next
        while current is not self._tail:
            items.append(f"{current.key!r}: {current.value!r}")
            current = current.next
        return f"LRUCache(capacity={self.capacity}, items=[{', '.join(items)}])"

---

Tests

def run_tests():
    print("=" * 60)
    print("Running LRU Cache Tests")
    print("=" * 60)

    # ------------------------------------------------------------------
    # 1. Basic put and get
    # ------------------------------------------------------------------
    print("\n1. Basic put and get")
    cache = LRUCache(3)
    cache.put("x", 10)
    cache.put("y", 20)
    cache.put("z", 30)
    assert cache.get("x") == 10
    assert cache.get("y") == 20
    assert cache.get("z") == 30
    assert len(cache) == 3
    print("   PASSED")

    # ------------------------------------------------------------------
    # 2. Cache miss returns None
    # ------------------------------------------------------------------
    print("2. Cache miss returns None")
    cache = LRUCache(2)
    assert cache.get("missing") is None
    print("   PASSED")

    # ------------------------------------------------------------------
    # 3. Eviction of LRU item
    # ------------------------------------------------------------------
    print("3. LRU eviction")
    cache = LRUCache(2)
    cache.put(1, "one")
    cache.put(2, "two")
    cache.put(3, "three")   # Should evict key=1 (oldest)
    assert cache.get(1) is None, "Key 1 should have been evicted"
    assert cache.get(2) == "two"
    assert cache.get(3) == "three"
    assert len(cache) == 2
    print("   PASSED")

    # ------------------------------------------------------------------
    # 4. get() updates recency — accessed item survives eviction
    # ------------------------------------------------------------------
    print("4. get() updates recency")
    cache = LRUCache(2)
    cache.put("a", 1)
    cache.put("b", 2)
    cache.get("a")           # "a" is now most recent; "b" becomes LRU
    cache.put("c", 3)        # Should evict "b"
    assert cache.get("b") is None, "Key 'b' should have been evicted"
    assert cache.get("a") == 1
    assert cache.get("c") == 3
    print("   PASSED")

    # ------------------------------------------------------------------
    # 5. put() on existing key updates value and recency
    # ------------------------------------------------------------------
    print("5. Updating an existing key")
    cache = LRUCache(2)
    cache.put("a", 1)
    cache.put("b", 2)
    cache.put("a", 99)       # Update "a"; "b" becomes LRU
    cache.put("c", 3)        # Should evict "b"
    assert cache.get("a") == 99
    assert cache.get("b") is None
    assert cache.get("c") == 3
    print("   PASSED")

    # ------------------------------------------------------------------
    # 6. Capacity of 1
    # ------------------------------------------------------------------
    print("6. Capacity of 1 (edge case)")
    cache = LRUCache(1)
    cache.put("only", 42)
    assert cache.get("only") == 42
    cache.put("new", 7)       # Evicts "only"
    assert cache.get("only") is None
    assert cache.get("new") == 7
    print("   PASSED")

    # ------------------------------------------------------------------
    # 7. Explicit delete
    # ------------------------------------------------------------------
    print("7. Explicit delete")
    cache = LRUCache(3)
    cache.put("a", 1)
    cache.put("b", 2)
    assert cache.delete("a") is True
    assert cache.get("a") is None
    assert cache.delete("nonexistent") is False
    assert len(cache) == 1
    print("   PASSED")

    # ------------------------------------------------------------------
    # 8. Clear cache
    # ------------------------------------------------------------------
    print("8. Clear cache")
    cache = LRUCache(3)
    cache.put("a", 1)
    cache.put("b", 2)
    cache.clear()
    assert len(cache) == 0
    assert cache.get("a") is None
    cache.put("fresh", 100)  # Should work normally after clear
    assert cache.get("fresh") == 100
    print("   PASSED")

    # ------------------------------------------------------------------
    # 9. peek() does NOT affect recency
    # ------------------------------------------------------------------
    print("9. peek() does not update recency")
    cache = LRUCache(2)
    cache.put("a", 1)
    cache.put("b", 2)
    cache.peek("a")          # Should NOT promote "a"
    cache.put("c", 3)        # "a" should be evicted (still LRU)
    assert cache.get("a") is None, "'a' should still be LRU after peek()"
    assert cache.get("b") == 2
    assert cache.get("c") == 3
    print("   PASSED")

    # ------------------------------------------------------------------
    # 10. __contains__ does NOT affect recency
    # ------------------------------------------------------------------
    print("10. `in` operator does not update recency")
    cache = LRUCache(2)
    cache.put("a", 1)
    cache.put("b", 2)
    _ = "a" in cache         # Should NOT promote "a"
    cache.put("c", 3)        # "a" should still be evicted
    assert "a" not in cache
    assert "b" in cache
    assert "c" in cache
    print("   PASSED")

    # ------------------------------------------------------------------
    # 11. Invalid capacity raises errors
    # ------------------------------------------------------------------
    print("11. Invalid capacity")
    try:
        LRUCache(0)
        assert False, "Should have raised ValueError"
    except ValueError:
        pass

    try:
        LRUCache(-5)
        assert False, "Should have raised ValueError"
    except ValueError:
        pass

    try:
        LRUCache("two")
        assert False, "Should have raised TypeError"
    except TypeError:
        pass
    print("   PASSED")

    # ------------------------------------------------------------------
    # 12. repr() shows most-to-least-recent order
    # ------------------------------------------------------------------
    print("12. repr() order")
    cache = LRUCache(3)
    cache.put("a", 1)
    cache.put("b", 2)
    cache.put("c", 3)
    cache.get("a")           # Access "a" — now most recent
    r = repr(cache)
    # Most recent first: a, c, b
    assert r.index("'a'") < r.index("'c'") < r.index("'b'"), f"Wrong order: {r}"
    print("   PASSED")

    # ------------------------------------------------------------------
    # 13. Large-scale stress test
    # ------------------------------------------------------------------
    print("13. Stress test (10,000 operations)")
    import random
    cache = LRUCache(100)
    reference = {}           # Simple dict to validate against

    for _ in range(10_000):
        op = random.choice(["put", "get"])
        key = random.randint(0, 149)   # Key space larger than capacity

        if op == "put":
            value = random.randint(0, 9999)
            cache.put(key, value)
            reference[key] = value
            # Trim reference to simulate LRU (approximate check)
        else:
            result = cache.get(key)
            if result is not None:
                # If cache returned something, it must match the last written value
                assert result == reference.get(key), (
                    f"Mismatch for key {key}: cache={result}, ref={reference.get(key)}"
                )

    assert len(cache) <= 100, "Cache exceeded capacity"
    print("   PASSED")

    print("\n" + "=" * 60)
    print("All tests passed!")
    print("=" * 60)


if __name__ == "__main__":
    run_tests()

    # Quick demo
    print("\nDemo:")
    cache = LRUCache(3)
    cache.put("a", 1)
    cache.put("b", 2)
    cache.put("c", 3)
    print(cache)                  # a, b, c → most to least recent
    cache.get("a")                # Promote "a"
    print(cache)                  # a, c, b
    cache.put("d", 4)             # Evict "b"
    print(cache)                  # d, a, c

---

Sample Output

============================================================
Running LRU Cache Tests
============================================================

1. Basic put and get
   PASSED
2. Cache miss returns None
   PASSED
3. LRU eviction
   PASSED
4. get() updates recency
   PASSED
5. Updating an existing key
   PASSED
6. Capacity of 1 (edge case)
   PASSED
7. Explicit delete
   PASSED
8. Clear cache
   PASSED
9. peek() does not update recency
   PASSED
10. `in` operator does not update recency
   PASSED
11. Invalid capacity
   PASSED
12. repr() order
   PASSED
13. Stress test (10,000 operations)
   PASSED

============================================================
All tests passed!
============================================================

Demo:
LRUCache(capacity=3, items=['c': 3, 'b': 2, 'a': 1])
LRUCache(capacity=3, items=['a': 1, 'c': 3, 'b': 2])
LRUCache(capacity=3, items=['d': 4, 'a': 1, 'c': 3])

---

Key Design Decisions

Decision	Rationale
Sentinel head/tail nodes	Eliminates if not head / boundary checks — every real node always has valid neighbours
_remove_node clears pointers	Setting .prev = .next = None prevents memory leaks via reference cycles
peek() / __contains__	Separate read-without-promote operations are critical for monitoring and testing without polluting recency state
Key stored in Node	Required to delete the key from the hash map during eviction in O(1)
Input validation	Catches bool subclass of int and negative/zero capacities at construction time

I'll create a Python implementation of an LRU cache from scratch. This implementation will use a doubly linked list for O(1) insertion/removal and a dictionary for O(1) lookups.

class LRUNode:
    """
    A node in the doubly linked list representing cache entries.
    Each node stores a key-value pair and pointers to adjacent nodes.
    """
    def __init__(self, key=None, value=None):
        self.key = key
        self.value = value
        self.prev = None
        self.next = None


class LRUCache:
    """
    Implementation of a Least Recently Used (LRU) Cache.
    
    The cache maintains a fixed capacity and ensures that when capacity is exceeded,
    the least recently used item is removed. All operations (get and put) should be O(1).
    
    Attributes:
        capacity (int): Maximum number of items the cache can hold
        size (int): Current number of items in the cache
        cache (dict): Dictionary mapping keys to their corresponding nodes
        head (LRUNode): Dummy head node of the doubly linked list
        tail (LRUNode): Dummy tail node of the doubly linked list
    """
    
    def __init__(self, capacity: int):
        """
        Initialize the LRU Cache with a specified capacity.
        
        Args:
            capacity (int): Maximum number of items the cache can hold
            
        Raises:
            ValueError: If capacity is not a positive integer
        """
        # Edge case: validate capacity
        if not isinstance(capacity, int) or capacity <= 0:
            raise ValueError("Capacity must be a positive integer")
        
        self.capacity = capacity
        self.size = 0
        self.cache = {}  # key -> LRUNode mapping
        
        # Initialize dummy head and tail nodes for the doubly linked list
        # These simplify edge cases when adding/removing nodes
        self.head = LRUNode()
        self.tail = LRUNode()
        
        # Connect head and tail to form an empty list
        self.head.next = self.tail
        self.tail.prev = self.head
    
    def _add_node_to_front(self, node: LRUNode) -> None:
        """
        Add a node to the front (most recently used position) of the linked list.
        
        Args:
            node (LRUNode): The node to add to the front
        """
        # Insert node between head and head.next
        node.prev = self.head
        node.next = self.head.next
        
        # Update surrounding nodes
        self.head.next.prev = node
        self.head.next = node
    
    def _remove_node(self, node: LRUNode) -> None:
        """
        Remove a node from the linked list.
        
        Args:
            node (LRUNode): The node to remove
        """
        # Connect the node's previous and next nodes to each other
        prev_node = node.prev
        next_node = node.next
        
        prev_node.next = next_node
        next_node.prev = prev_node
    
    def _move_to_front(self, node: LRUNode) -> None:
        """
        Move an existing node to the front (most recently used position).
        
        Args:
            node (LRUNode): The node to move to the front
        """
        # Remove from current position and add to front
        self._remove_node(node)
        self._add_node_to_front(node)
    
    def _evict_lru(self) -> None:
        """
        Remove the least recently used node (the one before the tail).
        """
        # The LRU node is right before the tail (dummy)
        lru_node = self.tail.prev
        
        # Remove from linked list
        self._remove_node(lru_node)
        
        # Remove from cache dictionary
        del self.cache[lru_node.key]
        self.size -= 1
    
    def get(self, key) -> any:
        """
        Retrieve the value associated with a key from the cache.
        
        Args:
            key: The key to look up
            
        Returns:
            The value associated with the key, or None if key is not in cache
            
        Notes:
            - If key exists, it becomes the most recently used item
            - Time complexity: O(1)
        """
        # Edge case: key is None
        if key is None:
            return None
        
        # Check if key exists in cache
        if key not in self.cache:
            return None
        
        # Get the node and update its position to most recently used
        node = self.cache[key]
        self._move_to_front(node)
        
        return node.value
    
    def put(self, key, value) -> None:
        """
        Add or update a key-value pair in the cache.
        
        Args:
            key: The key to add or update
            value: The value to associate with the key
            
        Notes:
            - If key already exists, its value is updated and it becomes most recently used
            - If key doesn't exist and cache is at capacity, the LRU item is evicted
            - Time complexity: O(1)
        """
        # Edge case: key is None
        if key is None:
            return
        
        # If key already exists, update it and move to front
        if key in self.cache:
            node = self.cache[key]
            node.value = value
            self._move_to_front(node)
            return
        
        # If cache is at capacity, evict the least recently used item
        if self.size >= self.capacity:
            self._evict_lru()
        
        # Create new node for the key-value pair
        new_node = LRUNode(key, value)
        
        # Add to front of list and to cache dictionary
        self._add_node_to_front(new_node)
        self.cache[key] = new_node
        self.size += 1
    
    def delete(self, key) -> bool:
        """
        Remove a key-value pair from the cache if it exists.
        
        Args:
            key: The key to remove
            
        Returns:
            bool: True if the key was removed, False if key was not in cache
            
        Notes:
            - Time complexity: O(1)
        """
        # Edge case: key is None
        if key is None:
            return False
        
        # Check if key exists in cache
        if key not in self.cache:
            return False
        
        # Remove node from linked list
        node = self.cache[key]
        self._remove_node(node)
        
        # Remove from cache dictionary
        del self.cache[key]
        self.size -= 1
        
        return True
    
    def clear(self) -> None:
        """
        Clear all items from the cache.
        """
        self.cache.clear()
        self.size = 0
        
        # Reset the linked list to empty state
        self.head.next = self.tail
        self.tail.prev = self.head
    
    def contains(self, key) -> bool:
        """
        Check if a key exists in the cache.
        
        Args:
            key: The key to check
            
        Returns:
            bool: True if key exists in cache, False otherwise
        """
        return key in self.cache
    
    def __len__(self) -> int:
        """
        Get the current number of items in the cache.
        
        Returns:
            int: The number of items currently in the cache
        """
        return self.size
    
    def __str__(self) -> str:
        """
        String representation of the cache contents from most to least recent.
        
        Returns:
            str: String representation of cache items
        """
        items = []
        current = self.head.next
        
        while current != self.tail:
            items.append(f"{current.key}: {current.value}")
            current = current.next
        
        return f"LRUCache({self.size}/{self.capacity}): [{', '.join(items)}]"


# Example usage and testing
if __name__ == "__main__":
    # Test 1: Basic operations
    print("Test 1: Basic operations")
    cache = LRUCache(3)
    
    cache.put(1, "A")
    cache.put(2, "B")
    cache.put(3, "C")
    print(cache)  # 3: C, 2: B, 1: A (most to least recent)
    
    print(f"Get 2: {cache.get(2)}")  # Should return "B" and make 2 most recent
    print(cache)  # 2: B, 3: C, 1: A
    
    # Test 2: Eviction when capacity exceeded
    print("\nTest 2: Eviction")
    cache.put(4, "D")  # Should evict 1 (least recent)
    print(cache)  # 4: D, 2: B, 3: C
    print(f"Get 1: {cache.get(1)}")  # Should return None (evicted)
    
    # Test 3: Update existing key
    print("\nTest 3: Update existing key")
    cache.put(2, "B-Updated")  # Should update value and move to front
    print(cache)  # 2: B-Updated, 4: D, 3: C
    
    # Test 4: Delete operation
    print("\nTest 4: Delete")
    cache.delete(4)
    print(cache)  # 2: B-Updated, 3: C
    print(f"Contains 4: {cache.contains(4)}")  # Should be False
    
    # Test 5: Clear cache
    print("\nTest 5: Clear")
    cache.clear()
    print(cache)  # Should be empty
    print(f"Length: {len(cache)}")  # Should be 0
    
    # Test 6: Edge cases
    print("\nTest 6: Edge cases")
    try:
        invalid_cache = LRUCache(0)  # Should raise ValueError
    except ValueError as e:
        print(f"Invalid capacity error: {e}")
    
    cache = LRUCache(2)
    cache.put(None, "value")  # Should handle None key gracefully
    print(f"Get None: {cache.get(None)}")  # Should return None
    cache.put(1, "value1")
    cache.put(None, "value2")  # Should not affect cache
    print(cache)  # Should only show 1: value1
    
    # Test 7: String keys and mixed types
    print("\nTest 7: Mixed key types")
    cache = LRUCache(3)
    cache.put("key1", 100)
    cache.put(2.5, "float_key")
    cache.put((1, 2), "tuple_key")
    print(cache)

Key Features of This Implementation:

1. O(1) Operations: Both get() and put() are O(1) using:

   • Doubly linked list for O(1) insertion/removal
   • Dictionary for O(1) lookups

2. Edge Cases Handled:

   • Invalid capacity (non-positive integer)
   • None keys (ignored gracefully)
   • Empty cache operations
   • Cache at capacity

3. Additional Methods:

   • delete(): Remove a specific key
   • clear(): Empty the entire cache
   • contains(): Check if key exists
   • __len__(): Get current cache size
   • __str__(): Human-readable representation

4. Proper Documentation:

   • Class and method docstrings
   • Clear parameter and return value documentation
   • Complexity analysis in comments

5. Memory Efficiency:

   • Uses only necessary data structures
   • Properly handles node creation and cleanup

The implementation follows standard LRU cache behavior where accessing or updating a key moves it to the most-recently-used position, and when capacity is exceeded, the least-recently-used item is removed.